Documentation
AI Effects
Getting started
Online privilege authentication

Online authentication

Last updated：2024-12-26 18:54

Only SDK versions below 2.1.0 support online authentication using this document.
For version 2.1.0 and above, you can directly call the create interface to create Effects objects using AppID and AppSign authentication, and there's no need to worry about authentication logic as it's already implemented inside the SDK.

This document describes how to obtain the license file and the implementation steps of online authentication.

The license file refers to the software license and contains the following:

Authorized time
Authorized Platform
Authorized SDK version
Authorized features

To implement the AI features provided by the ZegoEffects SDK, an online user privilege authentication is required.

Online user privilege authentication refers to the process in which a client accesses the ZegoEffects Server, applies for a license file, and performs network authentication.

Understand the process

We now provide two online authentication methods for you to implement the online authentication:

Send requests from your app client to the ZegoEffects Server
Send requests from your own business server to the ZegoEffects Server

Method	Send requests from your app client	Send requests from your business server
Process	The app client accesses to the ZegoEffects SDK to get the AuthInfo. The ZegoEffects SDK returns the AuthInfo to app client. The app client sends an URL request to ZegoEffects Server with the AppID and AuthInfo. The ZegoEffects Server returns the license file (as License parameter) to app client. Import the resource and model files. The app client creates a ZegoEffects object with the License file. Enables the AI Effects feature to start implementing image processing.	The business server directly sends an URL request to the ZegoEffects Server through the public gateway interface. The ZegoEffects Server returns the license file (as License parameter) to the business server. The business server distributes the license file to app client.（this must be implemented by your own.） Import the resource and model files. The app client creates a ZegoEffects object with the license file. Enables the AI Effects feature to start implementing image processing.
Diagram
Advantages	Easy to use and integrate. You don't need to build your own business server or manage your authentication file.	Using your own business backend server, the request network will be relatively stable. And the probability of hitting the DNS cache increases because the server is relatively stable. You can set authentication capabilities and manage authentication files on your own app client, providing high flexibility.

Get the license

Before you start to implement user privilege authentication in your app, contact the ZEGO team to apply for the AppID and AppSign for online user privilege validation.

Method 1: Send requests from your app client

1. Get the authentication info from the `ZegoEffects SDK`

To get the authentication information, call the getAuthInfo method with the AppSign you get in the previous step.

String encryptInfo = ZegoEffects.getAuthInfo(AppSign,context);

2. Request for a license file from ZegoEffects Server

To get the license file after you get the authentication information, construct a message body that meets the following, and send the request to the ZegoEffects Server.

URL: https://aieffects-api.zego.im?Action=DescribeEffectsLicense&AppId=xxxxxxxx&AuthInfo=xxxxxxxx
Method: GET
Content format: JSON
Parameter:

Parameter	Type	Required	Description
AppId	unsigned int	Yes	The unique identifier of the user privilege authentication, which can be obtained by contacting the ZEGO team.
AuthInfo	string	Yes	Encrypted data, device-related identifiers generated by the SDK, which can be obtained by calling the `getAuthInfo` method.

Sample message:

curl -X GET --data https://aieffects-api.zego.im?Action=DescribeEffectsLicense&AppId=xxxxxxxx&AuthInfo=xxxxxxxx

Method 2: Send requests from your business server

Your business server constructs a message body through the public gateway interface and directly sends a request to the ZegoEffects Server to apply for an license file. The message body structure is as follows:

URL: https://aieffectscgi-api.zego.im?Action=CgiDescribeEffectsLicense
Method: GET
Content format: JSON
Parameter:

Parameter	Type	Required	Description
AppId	unsigned int	Yes	The unique identifier of the user privilege authentication, which can be obtained by contacting the ZEGO team.
Signature	string	Yes	The API request signature. For more details, see Signing the requests.
SignatureNonce	string	Yes	A random string.
SignatureVersion	string	Yes	The version of the signature. Default value: 2.0.
Timestamp	string	Yes	Unix timestamp in seconds. A maximum error of 10 minutes is allowed.

Sample message:

curl -X GET https://aieffectscgi-api.zego.im?Action=CgiDescribeEffectsLicense?AppId=1&Signature=1302668869d55ab3f6114af4ba6e5580&SignatureNonce=3f15d0b95f6e480b&SignatureVersion=2.0&Timestamp=1635940599

ZegoEffects Server returns a message

The following is the sample message returned by the ZegoEffects Server:

{
    "Code": 0,
    "Message": <message>,
    "Data": {
        "License": <license>
    }
}

If the license file is successfully obtained, the license file shows in the returned License field.
If the request fails, the return field Code returns an error code, and the Message is the corresponding error message.

The code value in the returned filed varies based on the online authentication methods:

Parameter	Type	Description
Code	unsigned int32	When you send the request from the app client, the error code returned is as follows: 0: Successful. 1: Invalid parameter. 2: Invalid authentication information. 3: Invalid license. AppId or Bundle ID is invalid. 4: Internal server error.	When you send the request from the business server the error code returned is as follows: 0: Successful. 910001: Invalid parameter. 910002: Invalid license. 910003: Internal server error. 910004: Invalid authentication information.
Message	string	The returned message corresponds to the `Code` value.
Data	object	The license file is returned when `Code` is 0.

Among which, the returned field Data:

Parameter	Type	Description
License	string	Contains the license file.

Import the license

To activate the features you want, you need to import the license file to the ZegoEffects SDK.
To import the license file, do the following:

Get the license file from the returned field Data > License.
Call the create method, pass the license file to the ZegoEffects SDK.
Create a ZegoEffects SDK object.

// Before create a ZegoEffects SDK obejct, call the setResources method and import related resources and models.
// Pass the license file, create a ZegoEffects SDK object.
String license = "xxxxxxx";
ZegoEffects mEffects = ZegoEffects.create(license, applicationContext);

Before you create a ZegoEffects SDK object (create), you will need to import the resources and models (setResources) first.