logo
ConsoleSign Up
FAQ
Overview
On this page

How to upgrade ZIM from AppSign authentication to Token authentication?

2025-01-09
Products / Plugins:In-app chat
Platform / Framework:iOS / Android / macOS / Windows / Flutter / ReactNative / uni-app / Unity3D

Document Guide

To improve project security, for developers using AppSign authentication, you can use Token authentication, and you can only use related services after authentication passes (if you don't need it, you can continue using AppSign authentication). You can refer to this document to understand the implementation process.

Note
  • Platform SDK support for "AppSign authentication":
    • Web and mini programs: Not supported (including Web applications developed with various framework SDKs).
    • Remaining platforms: Supported, but ZIM SDK versions for iOS, Android, macOS, Windows, uni-app, React Native and other platforms need to be 2.3.0 or above.
  • All platform SDKs support "Token authentication".

Solution Description

ZIM SDK provides the following "Token authentication" integration solution:

In this solution, you need to implement the following business logic through your own business system:

  • Build user management logic for the client and issue user IDs for client login.
  • Authentication Token, it is recommended to be implemented by your business backend to ensure authentication data security.

Authentication Methods

Authentication MethodFunction DescriptionSecurity Level
AppSign AuthenticationPass AppSign when creating a ZIM instance. After authentication passes, you can use ZIM functions.
Please pass an empty string or not pass Token when logging into ZIM.		Very low security level.
Reason: If AppSign is leaked, attackers will steal your cloud service traffic, and AppSign has no expiration mechanism. It is recommended that you upgrade to Token authentication as soon as possible.
Token Authentication (Recommended)Token authentication requires passing Token when logging into ZIM. After authentication passes, you can use real-time audio and video functions.
Please pass an empty string or not pass AppSign when creating a ZIM instance.
High security level.
Reason: Token is issued by the developer's self-built server and authenticated on the client, and the issued Token has time validity. Therefore, we recommend using Token authentication.
Note

When you pass both AppSign and Token (not recommended to pass both), AppSign will be verified first. If AppSign verification passes, Token will not be verified. If AppSign verification fails, Token will be verified.

Upgrade Guide

Service Activation

  • SDK version 2.3.3 and above supports independent switching of authentication methods without contacting ZEGOCLOUD Technical Support.
  • For the following SDK versions, when you need to switch to "Token authentication", please contact ZEGOCLOUD Technical Support.
    • iOS/Android/macOS/Windows: Version 2.3.0 ~ 2.3.1.
    • uni-app/React Native/Flutter: Version 2.3.0.
  • SDK version 2.3.0 and below defaults to "Token authentication" and does not support "AppSign authentication", no additional activation is needed.

Generate Token

The developer client sends a request to the developer server to apply for Token. The developer server generates Token and returns it to the corresponding client.

ZEGO provides an open-source zego_server_assistant plugin on GitHub/Gitee, supporting Go, C++, Java, Python, PHP, .NET, Node.js languages to deploy and generate Token on the developer's server or client (not recommended for client generation).

For detailed introduction on generating Token, please refer to the following documents:

ProductReference Document
Instant Messaging

Use Token

This chapter mainly introduces how to use Token functionality after upgrading the SDK.

ProductPlatform
Instant Messaging

The implementation process for each platform is as follows:

iOS/macOS

  1. Download and integrate the latest version of SDK. For details, please refer to Integrate SDK.

  2. When calling the createWithAppConfig interface to create a ZIM instance, pass an empty string or not pass "AppSign" in ZIMAppConfig.

    // Create ZIM object, pass appID, appSign
// Note: ZIM supports AppSign authentication starting from version 2.3.0, and SDK defaults to AppSign authentication. If you need to switch authentication methods:
// (1) SDK version 2.3.3 and above supports independent switching of authentication methods; (2) SDK version 2.3.0 ~ 2.3.1, please contact ZEGOCLOUD Technical Support to switch to "Token authentication"
ZIMAppConfig *appConfig = [[ZIMAppConfig alloc] init];
appConfig.appID = (unsigned int)appID;     //Replace with your applied AppID
appConfig.appSign = @"appSign";     //Pass empty string or not pass AppSign
self.zim = [ZIM createWithAppConfig: appConfig];

  3. When calling the loginWithUserInfo interface to log into ZIM, you need to fill in the Token generated by the developer server.

    // userID is a string with a maximum of 32 bytes. Only supports numbers, English characters and '!', '#', '$', '%', '&', '(', ')', '+', '-', ':', ';', '<', '=', '.', '>', '?', '@', '[', ']', '^', '_', '{', '}', '|', '~'.
// userName is a string with a maximum of 64 bytes, with no special character restrictions.
ZIMUserInfo *userInfo = [[ZIMUserInfo alloc]init];
userInfo.userID = @"zegoUser1"; //Fill in NSString type value
userInfo.userName = @"zegotest";//Fill in NSString type value

// When logging in:
// Using Token authentication, developers need to fill in the Token generated by the "Use Token Authentication" document. For details, please refer to [Use Token Authentication]
[zim loginWithUserInfo:userInfo token:token callback:^(ZIMError * _Nonnull errorInfo) {
    //Fill in the login callback here
}];

  4. After receiving the tokenWillExpire callback, call the renewToken interface to update Token and pass it to the SDK.

    - (void)zim:(ZIM *)zim tokenWillExpire:(unsigned int)second {
    NSString *token = [MyToken getToken]; // Re-request Token from developer server
    [self.zim renewToken:token callback:^(ZIMError * _Nonnull errorInfo) {
        // Developers can determine whether Token update is successful based on ZIMErrorCode.
        ......
    }];
}
Android

  1. Download and integrate the latest version of SDK. For details, please refer to Integrate SDK.

  2. When calling the create interface to create a ZIM instance, pass an empty string or not pass "AppSign" in ZIMAppConfig.

    // Create ZIM object, pass appID, appSign and Application in Android
// Note: ZIM supports AppSign authentication starting from version 2.3.0, and SDK defaults to AppSign authentication. If you need to switch authentication methods:
// (1) SDK version 2.3.3 and above supports independent switching of authentication methods; (2) SDK version 2.3.0 ~ 2.3.1, please contact ZEGOCLOUD Technical Support to switch to "Token authentication"
ZIMAppConfig appConfig = new ZIMAppConfig();
appConfig.appID = 12345;  //Replace with your applied AppID
appConfig.appSign = "appSign";   //Pass empty string or not pass AppSign
zim = ZIM.create(appConfig, application);

  3. When calling the login interface to log into ZIM, you need to fill in the Token generated by the developer server.

    // userID is a string with a maximum of 32 bytes. Only supports numbers, English characters and '!', '#', '$', '%', '&', '(', ')', '+', '-', ':', ';', '<', '=', '.', '>', '?', '@', '[', ']', '^', '_', '{', '}', '|', '~'.
// userName is a string with a maximum of 64 bytes, with no special character restrictions.
ZIMUserInfo zimUserInfo = new ZIMUserInfo();
zimUserInfo.userID = userID;
zimUserInfo.userName = userName;

// When logging in:
// Using Token authentication, developers need to fill in the Token generated by the "Use Token Authentication" document. For details, please refer to [Use Token Authentication]
zim.login(zimUserInfo, token, new ZIMLoggedInCallback() {
    @Override
    public void onLoggedIn(ZIMError error) {
        // Developers can determine whether login is successful based on ZIMError.
    }
});

  4. After receiving the onTokenWillExpire callback, call the renewToken interface to update Token and pass it to the SDK.

    @Override
public void onTokenWillExpire(int second){
    String token = getToken(); // Re-request Token from developer server;
    engine.renewToken(token, new ZIMTokenRenewedCallback {
        @Override
        public void onTokenRenewed(String token, ZIMError error) {
            // Developers can determine whether Token update is successful based on ZIMError
        }
    });
}
Windows

  1. Download and integrate the latest version of SDK. For details, please refer to Integrate SDK.

  2. When calling the create interface to create a ZIM instance, pass an empty string or not pass "AppSign" in ZIMAppConfig.

    // Create ZIM object, pass appID, appSign. Currently, it is recommended to create only one zim instance per client
// Note: ZIM supports AppSign authentication starting from version 2.3.0, and SDK defaults to AppSign authentication. If you need to switch authentication methods:
// (1) SDK version 2.3.3 and above supports independent switching of authentication methods; (2) SDK version 2.3.0 ~ 2.3.1, please contact ZEGOCLOUD Technical Support to switch to "Token authentication"
zim::ZIMAppConfig app_config;
app_config.appID = 12345;     //Replace with your applied AppID
app_config.appSign = "appSign";   //Pass empty string or not pass AppSign
zim_ = zim::ZIM::create(app_config);

  3. When calling the login interface to log into ZIM, you need to fill in the Token generated by the developer server.

    // userID is a string with a maximum of 32 bytes. Only supports numbers, English characters and '!', '#', '$', '%', '&', '(', ')', '+', '-', ':', ';', '<', '=', '.', '>', '?', '@', '[', ']', '^', '_', '{', '}', '|', '~'.
// userName is a string with a maximum of 64 bytes, with no special character restrictions.
zim::ZIMUserInfo user_info;
user_info.userID = user_id;
user_info.userName = user_name;

// When logging in:
// Using Token authentication, developers need to fill in the Token generated by the "Use Token Authentication" document. For details, please refer to [Use Token Authentication]
zim_->login(user_info, token, [=](zim::ZIMError errorInfo){
    // Here you can get the login result return value and execute user code based on the error code
});

  4. After receiving the onTokenWillExpire callback, call the renewToken interface to update Token and pass it to the SDK.

    void onTokenWillExpire(ZIM * zim, unsigned int second) override {
    std::string token = getToken(); // Re-request Token from developer server
    zim->renewToken(token, [=](const std::string &token, zim::ZIMError errorInfo) {
        // Developers can determine whether Token update is successful based on the code in errorInfo
        ......
    });
}
uni-app

  1. Download and integrate the latest version of SDK. For details, please refer to Integrate SDK.

  2. When calling the create interface to create a ZIM instance, pass an empty string or not pass "AppSign" in ZIMAppConfig.

    // Note: ZIM supports AppSign authentication starting from version 2.3.0, and SDK defaults to AppSign authentication. If you need to switch authentication methods:
// (1) SDK version 2.3.3 and above supports independent switching of authentication methods; (2) SDK version 2.3.0, please contact ZEGOCLOUD Technical Support to switch to "Token authentication"

// Static synchronous method to create zim instance, pass AppID and AppSign
// The create method only creates a ZIM instance on the first call, subsequent calls return null.
ZIM.create({ appID: 0, appSign: '' });
// Get single instance through getInstance to avoid hot updates causing multiple create calls to return null.
var zim = ZIM.getInstance();

  3. When calling the login interface to log into ZIM, you need to fill in the Token generated by the developer server.

    // userID is a string with a maximum of 32 bytes. Only supports numbers, English characters and '!', '#', '$', '%', '&', '(', ')', '+', '-', ':', ';', '<', '=', '.', '>', '?', '@', '[', ']', '^', '_', '{', '}', '|', '~'.
// userName is a string with a maximum of 64 bytes, with no special character restrictions.
var userInfo = { userID: 'xxxx', userName: 'xxxx' };

// When logging in:
// Using Token authentication, developers need to fill in the Token generated by the "Use Token Authentication" document. For details, please refer to [Use Token Authentication]
var token = '';
zim.login(userInfo, token)
    .then(function () {
        // Login successful
    })
    .catch(function (err) {
        // Login failed
    });

  4. After receiving the tokenWillExpire callback, call the renewToken interface to update Token and pass it to the SDK.

    // Register listener for "token will expire" callback
zim.on('tokenWillExpire', function(zim, second) {
    var token = ''; // Re-request Token from developer server
    zim.renewToken(token)
        .then(function({ token }) {
            // Update successful
        })
        .catch(function(err) {
            // Update failed
        });
})
React Native

  1. Download and integrate the latest version of SDK. For details, please refer to Integrate SDK.

  2. When calling the create interface to create a ZIM instance, pass an empty string or not pass "AppSign" in ZIMAppConfig.

    // Note: ZIM supports AppSign authentication starting from version 2.3.0, and SDK defaults to AppSign authentication. If you need to switch authentication methods:
// (1) SDK version 2.3.3 and above supports independent switching of authentication methods; (2) SDK version 2.3.0, please contact ZEGOCLOUD Technical Support to switch to "Token authentication"

// Static synchronous method to create zim instance, pass AppID and AppSign
// The create method only creates a ZIM instance on the first call, subsequent calls return null.
ZIM.create({ appID: 0, appSign: '' });
// Get single instance through getInstance to avoid hot updates causing multiple create calls to return null.
var zim = ZIM.getInstance();

  3. When calling the login interface to log into ZIM, you need to fill in the Token generated by the developer server.

    // userID is a string with a maximum of 32 bytes. Only supports numbers, English characters and '!', '#', '$', '%', '&', '(', ')', '+', '-', ':', ';', '<', '=', '.', '>', '?', '@', '[', ']', '^', '_', '{', '}', '|', '~'.
// userName is a string with a maximum of 64 bytes, with no special character restrictions.
var userInfo = { userID: 'xxxx', userName: 'xxxx' };

// When logging in:
// Using Token authentication, developers need to fill in the Token generated by the "Use Token Authentication" document. For details, please refer to [Use Token Authentication]
var token = '';
zim.login(userInfo, token)
    .then(function () {
        // Login successful
    })
    .catch(function (err) {
        // Login failed
    });

  4. After receiving the tokenWillExpire callback, call the renewToken interface to update Token and pass it to the SDK.

    // Register listener for "token will expire" callback
zim.on('tokenWillExpire', function(zim, second) {
    var token = ''; // Re-request Token from developer server
    zim.renewToken(token)
        .then(function({ token }) {
            // Update successful
        })
        .catch(function(err) {
            // Update failed
        });
})
Flutter

  1. Download and integrate the latest version of SDK. For details, please refer to Integrate SDK.

  2. When calling the create interface to create a ZIM instance, pass an empty string or not pass "AppSign" in ZIMAppConfig.

    // Create
// Create ZIM single instance through plugin, pass APPID, AppSign
// Note: ZIM supports AppSign authentication starting from version 2.3.0, and SDK defaults to AppSign authentication. If you need to switch authentication methods, please contact ZEGOCLOUD Technical Support to switch configuration
ZIMAppConfig appConfig = ZIMAppConfig();
appConfig.appID = appID;
appConfig.appSign = appSign;  //Pass empty string or not pass AppSign

ZIM.create(appConfig);

  3. When calling the login interface to log into ZIM, you need to fill in the Token generated by the developer server.

    // userID is a string with a maximum of 32 bytes. Only supports numbers, English characters and '!', '#', '$', '%', '&', '(', ')', '+', '-', ':', ';', '<', '=', '.', '>', '?', '@', '[', ']', '^', '_', '{', '}', '|', '~'.
// userName is a string with a maximum of 64 bytes, with no special character restrictions.
ZIMUserInfo userInfo = ZIMUserInfo();
userInfo.userID = "userID"; //Fill in string type value
userInfo.userName = "userName";//Fill in string type value

// When logging in:
// Using Token authentication, developers need to fill in the Token generated by the "Use Token Authentication" document. For details, please refer to [Use Token Authentication]

ZIM
.getInstance()
!.login(userInfo, "token")
.then((value) {
    //Login successful triggers here
})
.catchError((onError) {
    switch (onError.runtimeType) {
        // Login failed triggers here
        case PlatformException:
            log(onError.code); //Login failed error code
            log(onError.message!);//Login failed error message
            break;
        default:
    }
});

  4. After receiving the onTokenWillExpire callback, call the renewToken interface to update Token and pass it to the SDK.

    ZIMEventHandler.onTokenWillExpire = (zim, second) {
    ZIM.getInstance().renewToken('new token');
};

Previous

Why does building a project with iOS simulator fail in Xcode 12.3 and above?

Next

How to set landscape orientation when publishing streams in mini programs?

On this page

Back to top