Implement licensing

Agora utilizes a licensing system as a payment method for IoT SDK. Agora grants a device-specific license to bill for its services, with each device having its own unique license. During the licensed period, Agora does not charge for the duration of the call. Typically, IoT SDK device manufacturers predict the sales volume and usage of their devices, buy and activate licenses from Agora, and then embed the license into each device in the form of a single code.

The following figure shows the overall process of using an IoT SDK device license:

Follow the steps below to add a license to your IoT SDK devices.

To apply for a license, contact sales-us@agora.io and provide the following information:

Name	Description
Category	Device license
Company ID (CID)	A unique identifier assigned by Agora to each company or organization. You can create an Agora account and get your company ID on the Settings page of the Agora Console.
License type	Choose from the following: Trial license Commercial license Agora recommends that you use a trial license during integration testing, and switch to a commercial license before the official launch. For further details, see Trial license and commercial license.
Stock keeping unit (SKU)	Specify the capability set of the license, including the following parameters: License capabilities: Audio Video Both audio and video Upper limit of license minutes: Whether to limit the duration for using the license, which is accurate to minutes. License usage period: Whether to limit the period for using the license, which is accurate to minutes.
Validity period	The validity period of the license starts on the day of activation. Trial license: Specify the period in months. Minimum is 3 months. Commercial license: Specify the period in years. Minimum is 1 year.
Number of applications	The number of licenses you require.
List of license-enabled project IDs (App ID)	An App ID is the unique identifier of a project, which is provided by Agora and subordinate to the CID. You enable the license for a specific App ID. You can create a project and get the App ID on the Project Management page of Agora Console.
Maximum concurrent user (PCU) limit	After enabling the PCU limit, you can limit the maximum number of people who can access the SDK at the same time in the dimension of CID or App ID.

After receiving the Agora license, refer to the information in this section to activate the license. You use the IoT SDK License Activation RESTful API for activation.

Prototype

• Method: POST
• Access point: https://api.agora.io/dabiz/license/v2/active

Request parameters

The activation request requires the following query parameters:

Parameter	Type	Description
pid	String	The license identification defined by SKU, validity period, and category.
licenseKey	String	The unique ID of the device. For example, the SN number, Mac address, and so on. The string length must be less than 64 bytes.
appid	String	The unique identifier assigned by Agora to your project.

Request example

https://api.agora.io/dabiz/license/v2/active? pid=02F5xxxxxxxxxxxxxxxxxxxxxxxxEC30&licenseKey=111&appid=a6d6xxxxxxxxxxxxxxxxxxxxxxxxf75e

Response parameters If the status code is 200, the request is successful, and the response body contains the following parameters:

Parameter	Type	Description
license	String	The value of the active license.
skuView	Array	SKU capability set: product (Integer): 1: Video SDK 2: IoT SDK SDK 3: FPA name (String): The name of the SKU mediaType (Integer): 1: Audio 2: Video 3: Both audio and video minutes (Integer): The maximum duration of the license period (String): License usage time period

If the request fails, the status code is not 200. Follow the returned status code and the message field in the response body to troubleshoot errors.

Response example

The following is a response example for a successful activation request:

_13

{

_13

"code":200,

_13

"data":{

_13

"license":"1D65xxxxxxxxxxxxxxxxxxxxxxxx6016",

_13

"skuView":{

_13

"product":1,

_13

"name":"01",

_13

"mediaType":1,

_13

"minutes":100,

_13

"period":"00:00~23:59"

_13

}

_13

}

_13

}

After successfully activating a license, you write the license to the device and use it in the SDK. Take the following steps to use the license:

1. Receive an activated license from the server.
2. Write the license to the device. Ensure that the license written to each device is correct and unique. There are two common methods to write the license information to your device:
   • The license is written to a file on the device that the device reads through a program.
   • The license is burnt into the device by the manufacturer during production and the device reads it directly.
3. Device reads license:
   • If the device successfully reads the license, proceed to the next step.
   • If the device fails to read the license, troubleshoot the problem and write the license again.

4. In the , call AgoraRtcService.init and pass the license in the licenseValue parameter of RtcServiceOptions.

5. The automatically verifies the license when a user joins a channel.
   • If the license verification is successful, the user can use the functions of the SDK.
   • If the license verification fails, the SDK kicks the user out of the channel, and the user receives the ERR_CLIENT_IS_BANNED_BY_SERVER error code.

Check your license usage in Agora Console.

The content in this section completes the information on this page, or points you to documentation that explains other aspects of this product.

To import the license activation API for testing and to obtain sample code for your platform, see the Postman IoT License Activation API.

licenseValue is the ID of each license. There are two ways to query licenseValue:

• On the License Usage page of the Agora Console, click Export License Details and view the licenseValue in the License column of the exported CSV file.

• After successfully calling the activation API, you receive the activated licenseValue in the response.

licenseKey is the unique identifier of the device. For example, the SN number, or the Mac address. The string length must be less than 64 bytes. When a user calls the activation API to activate a license for a device, the user consumes the license which is passed in the licenseKey parameter. Users can perform pre-authorization operations, so that only the licenseKey in the whitelist can successfully activate the license.

To facilitate development and testing, Agora offers the following types of licenses:

• Trial license: For integration-testing and product debugging.
• Commercial license: For the launch stage of the product.

Best practice is to use a trial license before the product is officially launched. To switch to a commercial license, follow these steps:

1. Contact sales-us@agora.io to apply for a commercial license. After successfully applying for a license, you can check the PID of the license in the License Usage page of the Agora Console.
2. Call the activation API to activate a new license and pass in the PID of the new license and the licenseKey which is consistent with the old license.
3. Write and read a new license to the device.
4. Call the initialization method of the SDK with the new license.

• init()