OAuthService

When the mini program requests access to specific scopes (resources or capabilities), IAPMiniProgram SDK calls the OAuthService SPI to request the Super App to generate authorization codes for the mini program.

getAuthCode

Method signature

Call the getAuthCode method to request the Super App to generate authorization codes for the mini program.

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. Valid values are:

  • auth_base: The user ID.

Notes:

    • The Super App must support this scope because most mini programs might use 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, which can include the user ID, gender, avatar, etc.

Notes:

    • The Super App must support this scope because most mini programs might require it.
    • When this scope is used, it's recommended that the user needs to manually click to agree the authorization.

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.

No

callback

Callback (For details, see the following section)

The callback that is executed when request processing is completed.

Yes

Callback

Field

Data type

Description

Required

result

IAPWalletOAuthResult

The result of the getAuthCode request.

Yes

Response parameters

N/A

showAuthPage

Method signature

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.

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, which represent the resources or capabilities that are requested by the mini program.

Yes

name

String

Auth client name

Yes

logo

String

Auth client logo

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.

No

callback

Callback (For details, see the following section)

The callback that is executed when request processing is complete.

Yes

Callback

Field

Data type

Description

Required

result

IAPWalletAuthPageConfirmResult

The result of the showAuthPage request.

Yes

Response parameters

N/A

getAuthorizedScopes

Method signature

The Super App calls this method to retrieve a list of scopes that are granted to the mini program.

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.

NO

callback

Callback (For details, see the following section)

The callback that is executed when request processing is complete.

Yes

Callback

Field

Data type

Description

Required

scopeQueryResult

IAPWalletOAuthScopeQueryResult

The result of the getAuthorizedScopes request.

Yes

Response parameters

N/A

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

Samples

The following samples show how to call the OAuthService SPI to generate authorization codes for the mini program:

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

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)
            })
        }
    }
}