Guide for upgrading the authentication mode from using the AppSign to Token

Introduction

To improve your project security, you will need to change the way you implement the user privilege control feature after you upgrade the Video Call/Voice Call SDK (ZEGO Express SDK) version to the following:

• iOS/Android/macOS/Windows/Unity3D: 2.17.0 or later
• Flutter: 2.17.1 or later
• React Native: 0.17.0 or later

That is, you will need to use the Token for authentication in the future and can continue to use the service only after the authentication passes (If you have been using AppSign for authentication, you will also need to use the Token for authentication, and the AppSign is no longer provided from the ZEGOCLOUD Admin Console). For how to upgrade the authentication mode, check this document.

Authentication modes

The differences of different authentication modes are as follows:

Compatibility

We now have three modes to control user privileges: AppSign mode, Token-preferred mode, and Token-only mode, and the compatibility of the three authentication modes varies. If you have been using AppSign for authentication, then:

Disable the Token-only authentication mode (by default): You can use both the AppSign and Token for authentication with the new version of the SDK. Enable the Token-only authentication mode: Both the new and old versions of the SDK use Token for authentication only, and the way to use the AppSign for authentication will no longer be compatible.

Upgrade guide

Service subscription

The user privilege control feature (using the Token for authentication) is enabled by default.

1. If you want to use Token authentication as the only way to control user privileges (the Token-only mode), contact ZEGOCLOUD Technical Support.
2. If you have been using the AppSign for authentication and want to continue using it with the new SDK version, you will need to contact ZEGOCLOUD Technical Support to obtain the AppSign (The AppSign field is no longer available on the ZEGOCLOUD Admin Console).

Generate a Token

Upon request from your app clients, your app server generates Tokens and sends the Tokens to the corresponding app clients.

ZEGOCLOUD provides an open-source Token generator plug-in on GitHub, which you can use to generate Tokens on your app server using different programming languages such as Go, C++, Java, Python, PHP,.NET, and Node.js. (For business security, you must generate Tokens on your app server.)

Note: The Token generator we provide contains two versions of plug-in for generating Tokens. And the plug-in supports different versions of the SDK:

• token03: Supports ZEGO Express SDK 2.8.0 or later.
• token04: Only supports ZEGO Express SDK 2.17.0 or later.

For details on how to generate a Token, see the following documents:

Use a Token

This section describes how to use a Token after the SDK upgrade.

Video Call/Voice Call

The implementation steps for different platforms are as follows:

iOS

1. Download the integrate the latest version of the SDK. For SDK integration, see Integrate the SDK.

2. Pass null to the AppSign parameter of the ZegoEngineProfile or leave it empty when calling the createEngine method to create a singleton instance of the ZegoExpressEngine.

ZegoEngineProfile *profile = [[ZegoEngineProfile alloc] init];
// The AppID value you get from the ZEGOCLOUD Admin console. AppID format: 1234567890
profile.appID = appID; 
// Use a general scenario.
profile.scenario = ZegoScenarioGeneral; 
// Create a ZegoExpressEngine instance and set eventHandler to [self]. If eventHandler is set to [nil], no callback will be received. You can set up the event handler later by calling the [-setEventHandler:] method.
[ZegoExpressEngine createEngineWithProfile:profile eventHandler:self];

3. Pass the Token you get from your app server to the room configuration parameter ZegoRoomCofig when calling the loginRoom method to log in to a room.

NSString *roomID = @"xxx"; // The ID of the room to log in to.
ZegoUser *user = [ZegoUser userWithUserID:@"xxxx"];
ZegoRoomConfig *config = [[ZegoRoomConfig alloc] init];
config.token = @"xxxxxxxx"; // The Token you get from your app server. 

[[ZegoExpressEngine sharedEngine] loginRoom:roomID user:user config:config];

4. Before a Token expires, the SDK sends out a notification through the onRoomTokenWillExpire callback. Upon receiving this callback, you will need to get a new Token from your app server first, and then pass the new Token to the renewToken method.

NSString *token = [MyToken getToken]; // Request a new Token from app server.
[[ZegoExpressEngine sharedEngine] renewToken:token roomID:roomID];

Android

1. Download the integrate the latest version of the SDK. For SDK integration, see quick start.
2. Pass null to the AppSign parameter of the ZegoEngineProfile or leave it empty when calling the createEngine method to create a singleton instance of the ZegoExpressEngine.

// Create a ZegoExpressEngine instance and set eventHandler to [self]. 
// If eventHandler is set to [null], no callback will be received. You can set up the event handler later by calling the [-setEventHandler:] method.
ZegoEngineProfile profile = new ZegoEngineProfile();
profile.appID = ;  // The AppID value you get from the ZEGOCLOUD Admin console. AppID format: 1234567890
profile.scenario = ZegoScenario.GENERAL;  // Use a general scenario.
profile.application = getApplication();
engine = ZegoExpressEngine.createEngine(profile, null);

3. Pass the Token you get from your app server to the room configuration parameter ZegoRoomCofig when calling the loginRoom method to log in to a room.

String roomID = "xxx" // The ID of the room to log in to.
ZegoUser user = new ZegoUser("xxxx");
ZegoRoomConfig config = new ZegoRoomConfig();
config.token = "xxxxxxxxxx"; // The Token you get from your app server. 
engine.loginRoom(roomID, user, config);

4. Before a Token expires, the SDK sends out a notification through the onRoomTokenWillExpire callback. Upon receiving this callback, you will need to get a new token from your app server first, and then pass the new Token to the renewToken method.

String token = getToken(); // Request a new Token from app server.
engine.renewToken(roomID, token);

macOS

• If you are using Objective-C: Refer to iOS.
• If you are using C++: Refer to Windows.

Windows

1. Download the integrate the latest version of the SDK. For SDK integration, see Integrate the SDK.
2. Pass null to the AppSign parameter of the ZegoEngineProfile or leave it empty when calling the createEngine method to create a singleton instance of the ZegoExpressEngine.

ZegoEngineProfile profile;
// The AppID value you get from the ZEGOCLOUD Admin console. 
profile.appID = appID;
profile.scenario = ZegoScenario::ZEGO_SCENARIO_GENERAL;
// Create a ZegoExpressEngine instance.
auto engine = ZegoExpressSDK::createEngine(profile, nullptr);

3. Pass the Token you get from your app server to the room configuration parameter ZegoRoomCofig when calling the loginRoom method to log in to a room.

std::string roomID = 'xxx'; // The ID of the room to log in to.
ZegoUser user;
user.userID = 'xxxx';
user.userName = 'xxxx';
ZegoRoomConfig config;
config.token = 'xxxxxxxxxx' // The Token you get from your app server. 
engine->loginRoom(roomID, user, config);

4. Before a Token expires, the SDK sends out a notification through the onRoomTokenWillExpire callback. Upon receiving this callback, you will need to get a new token from your app server first, and then pass the new Token to the renewToken method.

std::string token = getToken(); // Request a new Token from app server.
engine->renewToken(token);

Unity3D

1. Download the integrate the latest version of the SDK. For SDK integration, see Integrate the SDK.
2. Pass null to the AppSign parameter of the ZegoEngineProfile or leave it empty when calling the createEngine method to create a singleton instance of the ZegoExpressEngine.

// Define a ExpressEngine object.
ZegoExpressEngine engine;

ZegoEngineProfile profile = new ZegoEngineProfile();
profile.appID = appID; // The AppID value you get from the ZEGOCLOUD Admin console. AppID format: 123456789
profile.scenario = ZegoScenario.General; // Use a general scenario.
// Initialize the SDK.
engine = ZegoExpressEngine.CreateEngine(profile);

3. Pass the Token you get from your app server to the room configuration parameter ZegoRoomCofig when calling the loginRoom method to log in to a room.

string roomID = "xxx"; // The ID of the room to log in to.
ZegoUser user = new ZegoUser();
user.userID = "xxxx";
user.userName = "xxxx";
ZegoRoomConfig config = new ZegoRoomConfig();
config.token = "xxxxxxxxxx"; // The Token you get from your app server. 
engine.LoginRoom(roomID, user, config);

4. Before a Token expires, the SDK sends out a notification through the onRoomTokenWillExpire callback. Upon receiving this callback, you will need to get a new token from your app server first, and then pass the new Token to the renewToken method.

void OnRoomTokenWillExpire(string roomID, int remainTimeInSecond){
    string token = getToken(); // Request a new Token from app server.
    engine.RenewToken(roomID, token);
}

Flutter

1. Download the integrate the latest version of the SDK. For SDK integration, see quick start.
2. Pass null to the AppSign parameter of the ZegoEngineProfile or leave it empty when calling the createEngineWithProfile method to create a singleton instance of the ZegoExpressEngine.

ZegoEngineProfile profile = ZegoEngineProfile(
    appID, // The AppID value you get from the ZEGOCLOUD Admin console. AppID format: 123456789
    ZegoScenario.General, // Use a general scenario.
    enablePlatformView: true);
// Create a ZegoExpressEngine instance.
ZegoExpressEngine.createEngineWithProfile(profile);

3. Pass the Token you get from your app server to the room configuration parameter ZegoRoomCofig when calling the loginRoom method to log in to a room.

// Create a ZegoUser ovject
ZegoUser user = ZegoUser.id('user1');
// To receive the [onRoomUserUpdate] callback, you must set the [isUserStatusNotify] property of the room configuration parameter [ZegoRoomConfig] to [true].
ZegoRoomConfig config = ZegoRoomConfig.defaultConfig();
config.isUserStatusNotify = true;
// We recommend you generate the token on your app server. While for a more faster integration, you can also go to the ZEGOCLOUD Admin Console to get a temporary Token. 
config.token = "xxxx";
// Log in to a room
ZegoExpressEngine.instance.loginRoom('room1', user, config: config);

4. Before a Token expires, the SDK sends out a notification through the onRoomTokenWillExpire callback. Upon receiving this callback, you will need to get a new token from your app server first, and then pass the new Token to the renewToken method.

ZegoExpressEngine.onRoomTokenWillExpire = (String roomID, int remainTimeInSecond) {
    String token = getToken(); // Request a new Token from app server.
    ZegoExpressEngine.instance.renewToken(roomID, token);
  };

React Native

1. Download the integrate the latest version of the SDK. For SDK integration, see quick start.
2. Pass null to the AppSign parameter of the ZegoEngineProfile or leave it empty when calling the createEngineWithProfile method to create a singleton instance of the ZegoExpressEngine.

// Import the ZegoExpressEngine.
import ZegoExpressEngine from 'zego-express-engine-reactnative';

// Use a general scenario.
const profile = {
appID : xxx,
scenario : 0
};

ZegoExpressEngine.createEngineWithProfile(profile)

3. Pass the Token you get from your app server to the room configuration parameter ZegoRoomCofig when calling the loginRoom method to log in to a room.

let roomConfig = {};
//We recommend you generate the token on your app server. While for a more faster integration, you can also go to the ZEGOCLOUD Admin Console to get a temporary Token. 
roomConfig.token = "xxxx";
// To receive the [onRoomUserUpdate] callback, you must set the [isUserStatusNotify] property of the room configuration parameter [ZegoRoomConfig] to [true].
roomConfig.isUserStatusNotify = true;
// Log in to a room
// Start logging in to a room
ZegoExpressEngine.instance().loginRoom('room1', {'userID': 'id1', 'userName': 'user1'}, roomConfig);

4. Before a Token expires, the SDK sends out a notification through the roomTokenWillExpire callback. Upon receiving this callback, you will need to get a new token from your app server first, and then pass the new Token to the renewToken method.

ZegoExpressEngine.instance().on("roomTokenWillExpire", (roomID, remainTimeInSecond){
    let token = getToken(); // Request a new Token from app server.
    ZegoExpressEngine.instance().renewToken(roomID, token);
});