tencent cloud

Open APIs V3
Last updated: 2025-09-24 15:24:54
Open APIs V3
Last updated: 2025-09-24 15:24:54
The mini program SDK provides some open APIs for implementing features that are provided by superapps, such as login, user information retrieval, and payment.
Note:
The open APIs currently provide three implementation solutions:
v1: Fully customized by the superapp, and all open APIs must be implemented by superapp developers.
v2: Starting from SDK version 2.1.0, the SDK provides default implementations for login (wx.login), user information (wx.getPhoneNumber, wx.getEmail, wx.chooseAvatar, wx.getNickName), and session checks (wx.checkSession). Users can easily configure these to link the mini program user login with superapp user information.
v3: Starting from SDK version 2.2.11, the SDK APIs support the mutual trust mode based on the default v2 implementation. The default implementation of wx.login and user information-related APIs will first trigger the call for the open API getAuthCode to obtain authCode from the superapp for authorizing subsequent processes.

v2 and v3 are only supported in the public cloud version. Starting from version 2.2.11, if the superapp implements the TMFMiniAppSDKDelegate.getAuthCode API, developers can configure version compatibility through the mini program's apiVersion setting or the TMFMiniAppSDKDelegate.openApiVersion delegate API.

API description

Mini program method
TMFMiniAppSDKDelegate implementation method
Description
Default implementation
wx.login
login
Login API SDK
The default implementation (v2) is available starting from version 2.1.0.
Starting from version 2.2.11, the mutual trust mode (v3) is provided, which requires the superapp to implement getAuthCode.
wx.getPhoneNumber
getPhoneNumber
Retrieves phone number
The default implementation (v2) is available starting from version 2.1.0.
Starting from version 2.2.11, the mutual trust mode (v3) is provided, which requires the superapp to implement getAuthCode.
wx.getEmail
getEmail
Retrieves the user email
The default implementation (v2) is available starting from version 2.1.0.
Starting from version 2.2.11, the mutual trust mode (v3) is provided, which requires the superapp to implement getAuthCode.

getAuthCode
Retrieves authCode (v3)
No default implementation is available, and it needs to be implemented by the superapp.
Scope information can be obtained from the request parameters. The supported scopes include:
SCOPE_PHONE_NUMBER：wx.getPhoneNumber
SCOPE_EMAIL: wx.getEmail
SCOPE_AVATAR:wx.chooseAvatar
SCOPE_NICKNAME: wx.getNickName
wx.checkSession
checkSession
Checks if the login session is expired
The default implementation (v2) is available starting from version 2.1.0.
wx.chooseAvatar
chooseAvatar
Retrieves the user profile photo
The default implementation (v2) is available starting from version 2.1.0.
wx.getNickName
getNickName
Retrieves the user nickname
The default implementation (v2) is available starting from version 2.1.0.
wx.getUserInfo
getUserInfo
Retrieves the basic user information
No default implementation
wx.getUserProfile
getUserProfile
Retrieves the user profile information
No default implementation
wx.requestPayment
requestPayment
Initiates a payment
No default implementation
wx.requestMidasPaymentGameItem
requestMidasPaymentGameItem
Mini game payment
No default implementation

Related APIs in the proxy class

// Initiates a payment
// @param app Mini program/mini game instance 
// @param params Parameters
// @param completionHandler A callback to handle the result 
- (void)requestPayment:(TMFMiniAppInfo *)app params:(NSDictionary *)params completionHandler:(MACommonCallback)completionHandler;

// Initiate a payment for a direct virtual item purchase 
// @param app Mini game instance 
// @param params Parameters 
// @param completionHandler A callback to handle the result 
- (void)requestMidasPaymentGameItem:(TMFMiniAppInfo *)app params:(NSDictionary *)params completionHandler:(MACommonCallback)completionHandler;

// login
// @param app Mini program/mini game instance 
// @param params Parameters 
// @param completionHandler A callback to handle the result 
- (void)login:(TMFMiniAppInfo *)app params:(NSDictionary *)params completionHandler:(MACommonCallback)completionHandler;

// checkSession
// @param app Mini program/mini game instance 
// @param params Parameters 
// @param completionHandler A callback to handle the result 
- (void)checkSession:(TMFMiniAppInfo *)app params:(NSDictionary *)params completionHandler:(MACommonCallback)completionHandler;

// getUserProfile
// @param app Mini program/mini game instance 
// @param params Parameters 
// @param completionHandler A callback to handle the result 
- (void)getUserProfile:(TMFMiniAppInfo *)app params:(NSDictionary *)params completionHandler:(MACommonCallback)completionHandler;


// getPhoneNumber
// @param app Mini program/mini game instance 
// @param params Parameters 
// @param completionHandler A callback to handle the result 
- (void)getPhoneNumber:(TMFMiniAppInfo *)app params:(NSDictionary *)params completionHandler:(MACommonCallback)completionHandler;

// getUserInfo
// @param app Mini program/mini game instance 
// @param params Parameters 
// @param completionHandler A callback to handle the result 
- (void)getUserInfo:(TMFMiniAppInfo *)app params:(NSDictionary *)params completionHandler:(MACommonCallback)completionHandler;

// OpenAPI version
// @param app Mini program/mini game instance
// @reutn v1/v2/v3
- (NSString *)openApiVersion:(TMFMiniAppInfo *)app;

// getAuthCode
// @param app Mini program/mini game instance
// @param params Parameters
// @param completionHandler A callback to handle the result
- (void)getAuthCode:(TMFMiniAppInfo *)app params:(NSDictionary *)params completionHandler:(MACommonCallback)completionHandler;

Implementation description

Superapp developers can implement the open API logic by overriding the MiniOpenApiProxy proxy implementation.

Implementation description for v1

All APIs in v1 must be implemented by superapp developers.

Example


- (void)getUserInfo:(TMFMiniAppInfo *)app params:(NSDictionary *)params completionHandler:(MACommonCallback)completionHandler {
    if (completionHandler) {
        completionHandler(@{
            @"nickName": [DemoUserInfo sharedInstance].nickName,
            @"avatarUrl": [DemoUserInfo sharedInstance].avatarUrl,
            @"gender": [NSNumber numberWithUnsignedInt:[DemoUserInfo sharedInstance].gender],
            @"country": [DemoUserInfo sharedInstance].country,
            @"province": [DemoUserInfo sharedInstance].province,
            @"city": [DemoUserInfo sharedInstance].city,
            @"language": @"zh_CN"
        },nil);
    }
}

- (void)getUserProfile:(TMFMiniAppInfo *)app params:(NSDictionary *)params completionHandler:(MACommonCallback)completionHandler {
    if (completionHandler) {
        completionHandler(@{
            @"nickName": [DemoUserInfo sharedInstance].nickName,
            @"avatarUrl": [DemoUserInfo sharedInstance].avatarUrl,
            @"gender": [NSNumber numberWithUnsignedInt:[DemoUserInfo sharedInstance].gender],
            @"country": [DemoUserInfo sharedInstance].country,
            @"province": [DemoUserInfo sharedInstance].province,
            @"city": [DemoUserInfo sharedInstance].city,
            @"language": @"zh_CN"
        },nil);
    }
}

Implementation description for v2

After logging in to the superapp, the obtained UID (the current user account identifier of the host platform) should be returned to the SDK engine through the proxy interface. For example, after logging in to the superapp, the UID is set in [DemoUserInfo sharedInstance].userId, and the implementation of the proxy interface is as follows:
- (NSString *)getAppUID {
    return [DemoUserInfo sharedInstance].userId;
}

Implementation description for v3

Starting from SDK version 2.2.11, the SDK APIs support the mutual trust mode based on the default v2 implementation. The default implementation of wx.login and user information-related APIs will first trigger the call for the open API getAuthCode to obtain authCode from the superapp for authorizing subsequent processes. Superapp developers need to implement getAuthCode on the basis of the v2 implementation.
- (void)getAuthCode:(TMFMiniAppInfo *)app params:(NSDictionary *)params completionHandler:(MACommonCallback)completionHandler {
    NSString *token = [DemoUserInfo sharedInstance].token;
    if(token.length <= 0) {
        if(completionHandler) {
            NSDictionary *userInfo = @{NSLocalizedDescriptionKey: @"app not login"};
            completionHandler(nil,[NSError errorWithDomain:@"TCMPPLoginErrorDomain" code:-1001 userInfo:userInfo]);
        }
        return;
    }

    NSString *appId = [[TMFMiniAppSDKManager sharedInstance] getConfigAppKey];
    NSArray *selectedScopes = [[[DemoUserInfo sharedInstance] scopeList] allKeys];
            [[LoginManager sharedInstance] getAuthCode:token appId:appId scopes:selectedScopes completionHandler:^(NSError * _Nullable err, NSDictionary* _Nullable datas) {
                if(err) {
                    if(completionHandler) completionHandler(nil,err);
                } else {
                    if(datas) {
                        NSString *authCode = datas[@"authCode"];
                        NSArray *authSuccessScopes = datas[@"authSuccessScopes"];
                        NSString *code = datas[@"code"];
                        if(completionHandler) {
                            if(authCode.length <=0 && code.length <= 0) {
                                completionHandler(@{@"authCode":authCode,@"authSuccessScopes":authSuccessScopes?:@[]},nil);
                            } else {
                                if(authCode.length >0) {
                                    completionHandler(@{@"authCode":authCode,@"authSuccessScopes":authSuccessScopes?:@[]},nil);
                                } else {
                                    completionHandler(@{@"code":code,@"authSuccessScopes":authSuccessScopes?:@[]},nil);
                                }
                            }
                        }
                    } else {
                        if(completionHandler) {
                            NSDictionary *userInfo = @{NSLocalizedDescriptionKey: @"authCode is null"};
                            completionHandler(nil,[NSError errorWithDomain:@"TCMPPLoginErrorDomain" code:-1002 userInfo:userInfo]);
                        }
                    }
                }
            }];
}

Compatibility of custom login logic

Starting from SDK version 2.2.11, the SDK APIs support the mutual trust mode based on the default v2 implementation. The default implementation of wx.login and user information-related APIs will first trigger the call for the open API getAuthCode to obtain authCode from the superapp for authorizing subsequent processes. Superapp developers need to implement getAuthCode on the basis of the v2 implementation.
// OpenAPI version
// @param app Mini program/mini game instance
// @reutn v1/v2/v3
- (NSString *)openApiVersion:(TMFMiniAppInfo *)app;
Note:
Mini program developers can use the apiVersion field in app.json to control versions for APIs that are implemented by default in SDK versions later than 2.1.0. When this field is unconfigured, the version follows the value returned by the delegate API's openApiVersion method. Once configured, the API version matches the configured one. That means,
the priority of apiVersion configuration is higher than the value returned by the openApiVersion delegate API.
(For example, if apiVersion is configured as v2, all APIs will use the v2 implementation without version mixing. Even if openApiVersion returns other values, the v2 implementation will be used.)

Example:

- (NSString *)openApiVersion:(TMFMiniAppInfo *)app {
    // This app uses version 2 of the OpenAPI
    return @"v2";
}



Was this page helpful?
You can also Contact Sales or Submit a Ticket for help.
Yes
No

Feedback