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 React Native page for further actions, such as an authorization page to request the user's consent. Depending on whether to open a React Native page, the additional instructions are as follows:

• Open a React Native page: Specify the following response parameters:

• result.showReactNativePage: Set the value to true.
• result.moduleName: Set the value to the name of the module that contains the React Native page to be opened. The value corresponds to the string that is specified in the AppRegistry.registerComponent method.
• result.jsMainModulePath: Set the value to the name of the main module that contains the registerComponent call.
• result.bundleURLPath: Set the value to the name of the bundle that contains all the JavaScript code for the application to run.

For a code sample, see Open a React Native page during the OAuthService calls.

In this case, the SDK passes an object to the React Native page. The object contains request parameters from the method call and an additional traceId parameter, which identifies a specific method call. You must call the handlePageResult API on the React Native page to send traceId (used to correlate the request and response) and the processing result back to the SDK. For a code sample, see Call handlePageResult.

• Remain inside the mini program: Do not specify the following response parameters:

• result.showReactNativePage
• result.moduleName
• result.jsMainModulePath
• result.bundleURLPath

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:

function cacheScopes(appId: string, authClientId: string, grantedScopes: Array<String>) {
 for (let index = 0; index < grantedScopes.length; index++) {
  const element = grantedScopes[index];
  let key = appId + "_" + authClientId + "_" + element;
  try {
    await AsyncStorage.setItem(key, "true");
    } catch (error) {
         // Error saving data
    }
  }   
}

When caching the scopes, construct a unique key by combining appId (the mini-program ID), authClientId (the super app ID), and each of the grantedScopes (the scopes that are granted to the mini program) for identification, and set the value as a string "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:

import { init } from 'iapminiprogram-rn';

import type { BaseSuccess, BaseError } from 'iapminiprogram-rn';

  function initSDK() {
    init({
      oauthService: new TestOAuthService(),
      success: (success: BaseSuccess) => {
        console.log(success.msg);
      },
      error: (error: BaseError) => {
        console.log(error.errorMsg);
      },
    });
  }

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 procedure 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:

import { init } from 'iapminiprogram-rn';
import type { BaseSuccess, BaseError } from 'iapminiprogram-rn';
 function initSDK() {
    init({
      openId: '123***789'
      success: (success: BaseSuccess) => {
         console.log(success.msg);
      },
      error: (error: BaseError) => {
        console.log(error.errorMsg);
      },
    });
  }

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:

import { init } from 'iapminiprogram-rn';

import type { BaseSuccess, BaseError } from 'iapminiprogram-rn';

  function initSDK() {
    init({
      memberInfoService: new TestMemberInfoService(),
      success: (success: BaseSuccess) => {
        console.log(success.msg);
      },
      error: (error: BaseError) => {
        console.log(error.errorMsg);
      },
    });
  }

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 React Native page for further actions, such as a payment page to complete transactions. Follow the corresponding instructions depending on whether to open a React Native page:

• Open a React Native page: Specify the following response parameters:

• result.showReactNativePage: Set the value to true.
• result.moduleName: Set the value to the name of the module that contains the React Native page to be opened. The value corresponds to the string that is specified in the AppRegistry.registerComponent method.
• result.jsMainModulePath: Set the value to the name of the main module that contains the registerComponent call.
• result.bundleURLPath: Set the value to the name of the bundle that contains all the JavaScript code for the application to run.

For a code sample, see Open a React Native page during the PaymentService calls.

In this case, the SDK passes an object to the React Native page. The object contains request parameters from the method call and an additional traceId parameter, which identifies a specific method call. You must call the handlePageResult API on the React Native page to send traceId (used to correlate the request and response) and the processing result back to the SDK. For a code sample, see Call handlePageResult.

• Remain inside the mini program: Return result.resultCode and result.resultMessage and do not specify the following response parameters:

• result.showReactNativePage
• result.moduleName
• result.jsMainModulePath
• result.bundleURLPath

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:

import { init } from 'iapminiprogram-rn';

import type { BaseSuccess, BaseError } from 'iapminiprogram-rn';

  function initSDK() {
    init({
      paymentService: new TestPaymentService(),
      success: (success: BaseSuccess) => {
        console.log(success.msg);
      },
      error: (error: BaseError) => {
        console.log(error.errorMsg);
      },
    });
  }

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 React Native page 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 React Native page:

• Open a React Native page: Specify the following response parameters:

• result.showReactNativePage: Set the value to true.
• result.moduleName: Set the value to the name of the module that contains the React Native page to be opened. The value corresponds to the string that is specified in the AppRegistry.registerComponent method.
• result.jsMainModulePath: Set the value to the name of the main module that contains the registerComponent call.
• result.bundleURLPath: Set the value to the name of the bundle that contains all the JavaScript code for the application to run.

For a code sample, see Open a React Native page during the CodeService calls.

In this case, the SDK passes an object to the React Native page. The object contains request parameters from the method call and an additional traceId parameter, which identifies a specific method call. You must call the handlePageResult API on the React Native page to send traceId (used to correlate the request and response) and the processing result back to the SDK. For a code sample, see Call handlePageResult.

• Remain inside the mini program: Do not specify the following response parameters:

• result.showReactNativePage
• result.moduleName
• result.jsMainModulePath
• result.bundleURLPath

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:

import { init } from 'iapminiprogram-rn';

import type { BaseSuccess, BaseError } from 'iapminiprogram-rn';

  function initSDK() {
    init({
      codeService: new TestCodeService(),
      success: (success: BaseSuccess) => {
        console.log(success.msg);
      },
      error: (error: BaseError) => {
        console.log(error.errorMsg);
      },
    });
  }