OAuthService

When the mini program requests access to specific scopes (resources or capabilities), the IAPMiniProgram SDK calls the OAuthService SPI to request the super app to obtain user authorization and generate authorization codes for the mini program. For details on how the SPI functions, refer to the OAuthService workflow.

This SPI provides the following three methods:

getAuthCode

IAPMiniProgram calls the getAuthCode method to request the super app to generate authorization codes for the mini program.

Method signature

copy
func getAuthCode(
    clientId: String, 
    scopes: Set<String>, 
    type: IAPWalletOAuthCodeFlowType = .standard, 
    extendedInfo: [String : String] = [:], 
    in context: IAPWalletAPIContext? = nil, 
    callback: @escaping (IAPWalletOAuthResult) -> Void
) -> Void

Request parameters

Field

Data type

Description

Required

clientId

String

The unique ID that is assigned by Mini Program Platform to identify a mini program.

Yes

scopes

Set<String>

The authorization scopes, which represent the resources or capabilities that are requested by the mini program. For more information about the valid values, refer to the Scopes section.

Yes

type

IAPWalletOAuthCodeFlowType

The type of the mini program. Valid values are:

  • alipayConnect: The mini program is published from the Alipay connect mini program workspace.
  • localMiniProgram: The mini program is published to the local Super App workspace only.

Yes

extendedInfo

Dictionary<String, String>

An extended attribute that is used to provide additional information if necessary.

No

context

IAPWalletAPIContext

A context object, carries the mini program runtime metadata.

Yes

callback

Callback

The callback that is executed when request processing is completed. For details, see the following section.

Yes

Callback

Field

Data type

Description

Required

result

IAPWalletOAuthResult

The result of the getAuthCode request.

Yes

Response parameters

N/A

showAuthPage

The super app calls the showAuthPage method to display an authorization dialog to the user when the requested scopes require the user's agreement before being granted to mini programs.

Method signature

copy
func showAuthPage(
    clientId: String,
    name: String,
    logo: String,
    scopes: Set<String>,
    extendedInfo: [String: String]? = [:],
    in context: IAPWalletAPIContext? = nil,
    callback: @escaping (IAPWalletAuthPageConfirmResult) -> Void
) -> Void

Request parameters

Field

Data type

Description

Required

clientId

String

The unique ID that is assigned by Mini Program Platform to identify a mini program.

Yes

scopes

Set<String>

The authorization scopes that require the user's agreement. The values fall within those specified in the scopes request parameter of getAuthCode.

Yes

name

String

The name of the mini program that requests the scopes.

Yes

logo

String

The logo URL of the mini program that requests the scopes.

No

extendedInfo

Dictionary<String, String>

An extended attribute that is used to provide additional information if necessary.

No

context

IAPWalletAPIContext

A context object, carries the mini program runtime metadata.

Yes

callback

Callback

The callback that is executed when request processing is complete. For details, see the following section.

Yes

Callback

Field

Data type

Description

Required

result

IAPWalletAuthPageConfirmResult

The result of the showAuthPage request.

Yes

Response parameters

N/A

getAuthorizedScopes

IAPMiniProgram calls this method to retrieve a list of scopes that the super app supports for granting to mini programs.

Method signature

copy
func getAuthorizedScopes(
    clientId: String, 
    extendedInfo: [String: String] = [:], 
    in context: IAPWalletAPIContext? = nil, 
    callback: @escaping (IAPWalletOAuthScopeQueryResult) -> Void
) -> Void

Request parameters

Field

Data type

Description

Required

clientId

String

The unique ID that is assigned by Mini Program Platform to identify a mini program.

Yes

extendedInfo

Dictionary<String, String>

An extended attribute that is used to provide additional information if necessary.

No

context

IAPWalletAPIContext

A context object, carries the mini program runtime metadata.

Yes

callback

Callback

The callback that is executed when request processing is complete. For details, see the following section.

Yes

Callback

Field

Data type

Description

Required

scopeQueryResult

IAPWalletOAuthScopeQueryResult

The result of the getAuthorizedScopes request.

Yes

Response parameters

N/A

Scopes

The following table lists the scopes that are defined by Mini Program Platform:

Scope

Description

auth_base

The unique ID that is assigned by the super app to identify a user.

Note:

  • The super app must support this scope because most mini programs might request it for basic user identification.
  • It is recommended that the super app grant this scope silently without requesting the user's agreement.

auth_user

The basic user profile information, including the user ID, avatar, etc.

Note:

  • The super app must support this scope because most mini programs might require it.
  • This scope is requested when IAPMiniProgram SDK calls the MemberInfoService SPI to obtain the basic user information.
  • It is recommended that the super app request the user's agreement before granting this scope.

Error codes

Error code

Error message

1000

ERROR_CODE_UNKNOWN_ERROR

Unknown error

1001

ERROR_CODE_USER_CANCEL

The user cancels the operation.

1002

ERROR_CODE_APP_SERVICE_ERROR

The app service is wrong.

1003

ERROR_CODE_TIMEOUT

Timeout

2001

ERROR_CODE_AUTH_PENDING_AGREEMENT

Authorization is not finished or is pending.

1005

ERROR_CODE_SYSTEM_ERROR

System error

Sample

The following sample shows how to implement the OAuthService SPI to generate authorization codes for mini programs:

  1. Create a class that implements the OAuthService interface.
  2. Implement the getAuthorizedScopes method to provide a list of the supported scopes.
  3. Implement the getAuthCode method to generate authorization codes for the mini program.
  4. Implement the showAuthPage method to show the user authorization dialog.

Swift

copy
final class OAuthService: IAPWalletOAuthServiceSignature {

    // MARK: getAuthCode
    override func getAuthCode(
        clientId: String, scopes: Set<String>, 
        type: IAPWalletOAuthCodeFlowType = .standard, 
        extendedInfo: [String : String] = [:], 
        in context: IAPWalletAPIContext? = nil, 
        callback: @escaping (IAPWalletOAuthResult) -> Void
    ) {
        //The logic to be executed if the requested scopes require the user's consent
        let oAuthSuccessful: Bool = xxx
        if (oAuthSuccessful) { //The logic to be executed if OAuth is successful 
            let oAuthResult = IAPWalletOAuthResult(
                authCode: "AUTH_CODE",
                authErrorScopes: [:],
                authSuccessScopes: []
            )
            callback(oAuthResult)
        } else { //The logic to be executed if Oauth fails
            let oAuthResult = IAPWalletOAuthResult()
            oAuthResult.error = NSError(
                domain: "OAuthError",
                code: IAPWalletBaseServiceResult.ERROR_CODE_AUTH_PENDING_AGREEMENT,
                userInfo: [NSLocalizedDescriptionKey: "OAuth Params invalid"]
            )
            callback(oAuthResult)
        }
    }

    // MARK: getAuthorizedScopes
    override func getAuthorizedScopes(
        clientId: String, 
        extendedInfo: [String : String] = [:], 
        in context: IAPWalletAPIContext? = nil, 
        callback: @escaping (IAPWalletOAuthScopeQueryResult) -> Void
    ) {
        //The logic to retrieve a list of the authorized scopes
        let authorizedScopes = ["xxx"]
        let oAuthResult = IAPWalletOAuthScopeQueryResult(authorizedScopes: authorizedScopes)
        callback(oAuthResult)
    }

    // MARK: showAuthPage
    override func showAuthPage(
        clientId: String, 
        name: String, 
        logo: String, 
        scopes: Set<String>, 
        extendedInfo: [String : String]? = [:], 
        in context: IAPWalletAPIContext? = nil, 
        callback: @escaping (IAPWalletAuthPageConfirmResult) -> Void
    ) {
        //Show user authorization dialog
        let alertController = UIAlertController(
            title: "xxx auth page", 
            message: "Do you allow this service to get your auth code?", 
            preferredStyle: .alert
        )

        let cancelAction = UIAlertAction(title: "NO", style: .cancel) { _ in
            let oAuthResult = IAPWalletAuthPageConfirmResult()
            oAuthResult.error = NSError(
                domain: "OAuthError", 
                code: IAPWalletBaseServiceResult.ERROR_CODE_USER_CANCEL, 
                userInfo: [NSLocalizedDescriptionKey: "USER CANCEL"]
            )
            callback(oAuthResult)
        }

        let confirmAction = UIAlertAction(title: "YES", style: .default) { _ in
            let cacheAuthKey = "xxx"
            UserDefaults.standard.set(true, forKey: cacheAuthKey)
            callback(IAPWalletAuthPageConfirmResult(referenceAgreementId: "AGREEMENT_ID"))
        }

        alertController.addAction(cancelAction)
        alertController.addAction(confirmAction)

        DispatchQueue.main.async {
            UIApplication.shared.keyWindow?.rootViewController?.dismiss(animated: true, completion: {
                UIApplication.shared.keyWindow?.rootViewController?.present(alertController, animated: true)
            })
        }
    }
}