Native SPIs are a set of interfaces that bridge the interaction between the super app and mini programs. When mini programs make requests via certain JSAPIs, the IAPMiniProgram SDK calls the corresponding Native SPIs to direct the request to the super app. By integrating these SPIs, the super app grants mini programs the following services or capabilities:

• Obtaining user authorization
• Accessing user information
• Processing payments
• Scanning QR codes and barcodes

This topic mainly explains the function of each Native SPI and guides the super app to integrate these SPIs step by step.

Overview

Note: Calling a JSAPI triggers to call its associated Native SPI. Errors occur when the SPI fails to call.

OAuthService

This section explains the workflow and integration process of the OAuthService interface, which obtains user authorization and generates authorization codes for mini programs.

Workflow

Procedures

Follow the procedure to integrate the OAuthService interface:

Step 1: Implement OAuthService

Create a class that implements the OAuthService interface. Within this class, sequentially implement the following methods: getAuthorizedScopes, getAuthCode, and showAuthPage.

The following sections provide instructions for implementing the methods of this interface. For each implementation, you can optionally direct users to a Flutter page (created with a Widget) for further actions, such as an authorization page to request the user's consent. Depending on whether to open a Flutter page, the additional instructions are as follows:

• Open a Flutter page: Set the value of the result.showFlutterPage response parameter to true and specify the page route in the result.flutterPageRoute response parameter. For a code sample, see Open a Flutter page during the OAuthService calls.

Besides, you must call the parseRequest API to handle data communication between the SDK and the Flutter page. For a code samples, see Call parseRequest.

• Remain inside the mini program: Do not specify the result.showFlutterPage and result.flutterPageRoute response parameters. For a code sample, see Remain inside the mini program during the OAuthService calls.

1. (Optional) Implement the getAuthorizedScopes method

If you need to enable the my.getOpenUserInfo JSAPI, implement the getAuthorizedScopes method to provide the SDK with a list of scopes that you support for granting to mini programs. In the method's response, return an OAuthScopeQueryResult containing the auth_base and auth_user scopes.

2. Implement the getAuthCodemethod

Implement the getAuthCode method to generate authorization codes for the mini program, and handle the following outcomes of the OAuth authentication flow:

• The user's consent is required before granting the mini program access to the requested scopes. It is recommended to obtain the user's consent for scopes other than user_base.
• The OAuth process succeeds.
• The OAuth process fails.

3. Implement the showAuthPage method

Implement the showAuthPage method to show the user authorization dialog and handle the following outcomes:

• The user allows mini program to access the requested scopes.
• The user declines or cancels the permission request.

It is recommended to execute this method when the requested scopes include any scope, other than user_base, that requires the user's consent according to compliance.

Note: If the user allows mini program to access the requested scopes, the super app needs to save the scopes to prevent the authorization dialog from reappearing when the same scopes are requested again. To save the scopes, the super app can use the cacheScopes method to implement the caching logic. See the following code sample for more information:

void cacheScopes(String appId, String authClientId, Collection grantedScopes) {
  for (String scope: grantedScopes) {
    String key = appId + "_" + authClientId + "_" + scope;
    cache(key, true); 
  }
}

When caching the scopes, construct a unique key by combining appId (the mini-program ID), authClientId (the super app ID), and each of grantedScopes (the scopes that are granted to the mini program) for identification, and set the value as a simple boolean true to indicate that the scopes are granted.

Step 2: Register OAuthService with the SDK

To register the implemented OAuthService with the IAPMiniProgram SDK, pass it to the init method during initialization with the following code sample:

void initSDK() async {
  IAPMiniProgram.instance.init(
    oauthService: TestOAuthService()
  );
}

MemberInfoService

This section explains the workflow and integration process of the MemberInfoService interface, which obtains basic user information for mini programs and the SDK.

Workflow

The interaction workflow of the MemberInfoService interface differs depending on the following use cases:

• For requests by mini programs
• For requests by the IAPMiniProgram SDK

For requests by mini programs

For requests by the IAPMiniProgram SDK

Procedures

Follow the instructions to integrate the MemberInfoService interface:

Step 1: Set open ID

In the case where the SDK requests the user ID (the strategy request parameter is set to localUserIdOnly), the super app must return the ID synchronously because returning it in a different thread causes the SDK to get a null result. To return the user ID synchronously, the super app can use either of the following methods depending on whether the ID is cached locally:

• If the user ID is not cached locally, you need to retrieve it after the IAPMiniProgram SDK has been initialized and the user logs in to the super app. Then, call the setOpenId API to set the ID.
• If the user ID is cached locally, during the SDK initialization, pass the cached ID into the init method by specifying the openId key. See the following code sample for details:

void initSDK() async {
  IAPMiniProgram.instance.init(
      openId: '123***789'
  );
}

Step 2: Implement MemberInfoService

Create a class that implements the MemberInfoService interface. Within this class, implement the getMemberInfo method to fetch the user information according to the specified strategy. For a code sample, refer to MemberInfoService.

Step 3: Register MemeberInfoService with the SDK

To register the implemented MemberInfoService with the IAPMiniProgram SDK, pass it to the init method during initialization with the following code sample:

void initSDK() async {
  IAPMiniProgram.instance.init(
      memberInfoService: TestMemberInfoService()
  );
}

PaymentService

This section explains the workflow and integration process of the PaymentService interface, which enables payment processing capabilities.

Workflow

Procedures

Follow the procedure to integrate the PaymentService interface:

Step 1: Implement PaymentService

Create a class that implements the PaymentService interface. Within this class, implement the pay method to initiate the payment process and request for payment with the type of order, and handle the payment result. You can optionally direct users to a Flutter page (created with a Widget) for further actions, such as a payment page to complete transactions. Follow the corresponding instructions depending on whether to open a Flutter page:

• Open a Flutter page: Set the value of the result.showFlutterPage response parameter to true and specify the page routing address in the result.flutterPageRoute response parameter. For a code sample, see Open a Flutter page during the PaymentService calls.

Besides, you must call the parseRequest API to handle data communication between the SDK and the Flutter page. For a code sample, see Call parseRequest.

• Remain inside the mini program: Do not specify the result.showFlutterPage and result.flutterPageRoute response parameters. For a code sample, see Remain inside the mini program during the PaymentService calls.

Step 2: Register PaymentService with the SDK

To register the implemented PaymentService with the IAPMiniProgram SDK, pass it to the init method during initialization with the following code sample:

void initSDK() async {
  IAPMiniProgram.instance.init(
    paymentService: TestPaymentService(),
  );
}

CodeService

This section explains the workflow and integration process of the CodeService interface, which enables QR code or barcode scanning capabilities.

Workflow

Procedures

Follow the procedure to integrate the CodeService interface:

Step 1: Implement CodeService

Create a class that implements the CodeService interface. Within this class, implement the scan method to launch the QR code or barcode scanner and return the code. You can optionally direct users to a Flutter page (created with a Widget) for further actions, such as a code scan page to read QR codes or barcodes. Follow the corresponding instructions depending on whether to open a Flutter page:

• Open a Flutter page: Set the value of the result.showFlutterPage response parameter to true and specify the page routing address in the result.flutterPageRoute response parameter. For a code sample, see Open a Flutter page during the CodeService calls.

Besides, you must call the parseRequest API to handle data communication between the SDK and the Flutter page. For a code sample, see Call parseRequest.

• Remain inside the mini program: Do not specify the result.showFlutterPage and result.flutterPageRoute response parameters. For a code sample, see Remain inside the mini program during the CodeService calls.

Step 2: Register CodeService with the SDK

To register the implemented CodeService with the IAPMiniProgram SDK, pass it to the init method during initialization with the following code sample:

void initSDK() async {
  IAPMiniProgram.instance.init(
    codeService: TestCodeService()
  );
}