Alipay International Mini Program Development PlatformAlipay International Mini Program Development PlatformDOCS

Integrate Native SPIs

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, 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/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

Integrate Native SPIs

Native SPI

Associated JSAPI

Description

OAuthService

my.getAuthCode

The Super App integrates this SPI to provide authorization codes for mini programs. The mechanism is based on OAuth 2.0 standards and enables mini programs to securely access the resources or capabilities for proper functioning.

For more information, refer to the following sections.

MemberService

my.getOpenUserInfo

The Super App integrates this SPI to provide basic user information for both mini programs and IAPMiniProgram SDK. This integration is important for the following use cases:

  • Enable mini programs to access non-sensitive user profile information.

Note: In this use case, the Super App must integrate the OAuthService SPI first.

  • Enable IAPMiniProgram SDK to access the user ID for the following features:
    • Mini-program performance tracking: This includes the analysis of metrics such as Daily User Visits, which are displayed on the Mini Program Platform console if the Super App has enabled the feature.
    • Whitelisting: This allows mini-program developers to choose specific users to test the mini program in your Super App during pilot testing.

For more information, refer to the following sections.

PaymentService

my.tradePay

The Super App integrates this SPI to enable mini programs to process payments. For more information, refer to the following sections.

CodeService

my.scan

The Super App integrates this SPI to enable mini programs to use your scanner to scan QR codes or barcodes.

Note: To ensure this SPI activates your scanner successfully, you must implement code-scanning capabilities in your app.

For more information, refer to the following sections.

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 requests the Super App to generate authorization codes for the mini program.

Workflow

Integrate Native SPIs

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.

For the complete code samples, see Sample (Swift).

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 following caching logic:

copy
func updateCachedScopesForUser(userId: String, appId: String, scopes: Set<String>) {
    let cacheKey = getCacheKey(for: userId, appId: appId)
    guard let currentScopes = getCachedScopesForUser(userId: userId, appId: appId) else {
        defaults.set(Array(newScopes), forKey: cacheKey)
        return
    }
    let updatedScopes = currentScopes.union(newScopes)
    defaults.set(Array(updatedScopes), forKey: cacheKey)
}

private func getCacheKey(for userId: String, appId: String) -> String {
    return "MPS_scope_\(userId)_\(appId)"
}

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 to SDK

Before the SDK initialization logic, call the registerServices API to register the OAuthService interface to IAPMiniProgram SDK.

Refer to the following sample code for the registration:

copy
import UIKit
import IAPConnect
import GRVAppContainer
import IAPWalletAPI

@main
class AppDelegate: UIResponder, UIApplicationDelegate {
    func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {
        registerWalletServices()
        setupMiniProgramSDK()
        return true
    }

    func setupMiniProgramSDK() {
        let config = IAPConnectInitConfig()
        config.riverConfiguration = createConfiguration()
        config.riverExtensionDelegate = createExtensionDelegate()
        IAPConnectClient.sharedInstance().initWithContext(config) {
            debugPrint("init success")
        } failure: { code, message in
                    debugPrint("errorCode: ", code, "errorMessage: ", message as Any)
                   }
    }

    func createConfiguration() -> GRVConfiguration {
        let configuration = GRVConfiguration()
        return configuration
    }

    func createExtensionDelegate() -> GRVExtensionDelegate {
        let extensionDelegate = GRVExtensionDelegate()
        return extensionDelegate
    }

    func registerWalletServices() {
        IAPWalletServicesRegistrator.registerWalletServices(for: [
            IAPWalletServiceProtocolDefaultTypes.OAUTH
        ])
    }
}

MemberService

This section explains the workflow and integration process of the MemberService interface, which obtains the members' information for the mini program.

Workflow

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

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

For requests by mini programs

Integrate Native SPIs

For requests by IAPMiniProgram SDK

Integrate Native SPIs

Procedures

Follow the procedure to integrate the MemberService interface:

Step 1: Implement MemberService

Create a class that implements the MemberService interface. Within this class, implement the getMemberInfo method to fetch the member information according to the specified strategy.

For the complete code samples, see Sample (Swift).

Step 2: Register MemeberService to SDK

Before the SDK initialization logic, call the registerServices API to register the MemberService interface to IAPMiniProgram SDK.

Refer to the following sample code for the registration:

copy
import UIKit
import IAPConnect
import GRVAppContainer
import IAPWalletAPI

@main
class AppDelegate: UIResponder, UIApplicationDelegate {

    func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {
        registerWalletServices()
        setupMiniProgramSDK()
        return true
    }

    func setupMiniProgramSDK() {
        let config = IAPConnectInitConfig()
        config.riverConfiguration = createConfiguration()
        config.riverExtensionDelegate = createExtensionDelegate()
        IAPConnectClient.sharedInstance().initWithContext(config) {
            debugPrint("init success")
        } failure: { code, message in
                    debugPrint("errorCode: ", code, "errorMessage: ", message as Any)
                   }
    }

    func createConfiguration() -> GRVConfiguration {
        let configuration = GRVConfiguration()
        return configuration
    }

    func createExtensionDelegate() -> GRVExtensionDelegate {
        let extensionDelegate = GRVExtensionDelegate()
        return extensionDelegate
    }

    func registerWalletServices() {
        IAPWalletServicesRegistrator.registerWalletServices(for: [
            IAPWalletServiceProtocolDefaultTypes.ACCOUNT
        ])
    }
}

PaymentService

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

Workflow

Integrate Native SPIs

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.

For the complete code samples, see Sample (Swift).

Step 2: Register PaymentService to SDK

Before the SDK initialization logic, call the registerServices API to register the PaymentService interface to IAPMiniProgram SDK.

Refer to the following sample code for the registration:

copy
import UIKit
import IAPConnect
import GRVAppContainer
import IAPWalletAPI

@main
class AppDelegate: UIResponder, UIApplicationDelegate {
    func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {
        registerWalletServices()
        setupMiniProgramSDK()
        return true
    }

    func setupMiniProgramSDK() {
        let config = IAPConnectInitConfig()
        config.riverConfiguration = createConfiguration()
        config.riverExtensionDelegate = createExtensionDelegate()
        IAPConnectClient.sharedInstance().initWithContext(config) {
            debugPrint("init success")
        } failure: { code, message in
                    debugPrint("errorCode: ", code, "errorMessage: ", message as Any)
                   }
    }

    func createConfiguration() -> GRVConfiguration {
        let configuration = GRVConfiguration()
        return configuration
    }

    func createExtensionDelegate() -> GRVExtensionDelegate {
        let extensionDelegate = GRVExtensionDelegate()
        return extensionDelegate
    }

    func registerWalletServices() {
        IAPWalletServicesRegistrator.registerWalletServices(for: [
            IAPWalletServiceProtocolDefaultTypes.PAYMENT
        ])
    }
}

CodeService

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

Workflow

Integrate Native SPIs

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.

For the complete code samples, see Sample (Swift).

Step 2: Register CodeService to SDK

Before the SDK initialization logic, call the registerServices API to register the CodeService interface to IAPMiniProgram SDK.

Refer to the following sample code for the registration:

copy
import UIKit
import IAPConnect
import GRVAppContainer
import IAPWalletAPI

@main
class AppDelegate: UIResponder, UIApplicationDelegate {
    func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {
        registerWalletServices()
        setupMiniProgramSDK()
        return true
    }

    func setupMiniProgramSDK() {
        let config = IAPConnectInitConfig()
        config.riverConfiguration = createConfiguration()
        config.riverExtensionDelegate = createExtensionDelegate()
        IAPConnectClient.sharedInstance().initWithContext(config) {
            debugPrint("init success")
        } failure: { code, message in
                    debugPrint("errorCode: ", code, "errorMessage: ", message as Any)
                   }
    }

    func createConfiguration() -> GRVConfiguration {
        let configuration = GRVConfiguration()
        return configuration
    }

    func createExtensionDelegate() -> GRVExtensionDelegate {
        let extensionDelegate = GRVExtensionDelegate()
        return extensionDelegate
    }

    func registerWalletServices() {
        IAPWalletServicesRegistrator.registerWalletServices(for: [
            IAPWalletServiceProtocolDefaultTypes.CODE
        ])
    }
}

Class IAPWalletServicesRegistrator

copy
class IAPWalletServicesRegistrator {
    static func registerWalletServices(for types: [String]) {
        var serviceMap: [String: (category: IAPWalletServiceCategory, clsName: String)] = [
            IAPWalletServiceProtocolDefaultTypes.OAUTH: (.acl, NSStringFromClass(OAuthService.self)),
            IAPWalletServiceProtocolDefaultTypes.PAYMENT: (.acl, NSStringFromClass(PaymentService.self)),
            IAPWalletServiceProtocolDefaultTypes.ACCOUNT: (.acl, NSStringFromClass(MemberInfoService.self)),
            IAPWalletServiceProtocolDefaultTypes.CODE: (.foundation, NSStringFromClass(CodeService.self)),
            IAPWalletServiceProtocolDefaultTypes.DEEPLINK: (.foundation, NSStringFromClass(DeeplinkService.self))
        ]
        
        var metaInfos = types.compactMap { (type: String) -> IAPWalletBaseServiceProvider? in
            guard let (category, clsName) = serviceMap[type] else { return nil }
            
            return IAPWalletBaseServiceProvider(
                type: IAPWalletServiceType(category: category, type: type),
                name: clsName
            )
        }
        
        let walletAPIManager = IAPWalletAPIManager()
        walletAPIManager.registerServices(metaInfos: Set(metaInfos))
        IAPWalletContextManager.instance.serviceManager = walletAPIManager
    }
}