This article describes how to integrate the Agora Cocos Creator SDK and implement the basic interactive live audio streaming in your app.

Understand the tech

The following figure shows the workflow to integrate into your app in order to add Interactive Live Streaming Premium functionality.

As shown in the figure, the workflow for adding Interactive Live Streaming Premium in your project is as follows:

1. Set the client role
   Each user in an Interactive Live Streaming Premium channel is either a host or an audience member. Hosts publish streams to the channel, and the audience subscribe to the streams.

2. Retrieve a token
   A token is the credential that authenticates a user when your app client joins a channel. In a test or production environment, your app client retrieves tokens from a server in your security infrastructure.

3. Join a channel
   Call joinChannel to create and join a channel. App clients that pass the same channel name join the same channel.

4. Publish and subscribe to audio and video in the channel
   After joining a channel, app clients with the role of the host can publish audio and video. For an auidence memeber to send audio and video, you can call setClientRole to switch the client role.

For an app client to join a channel, you need the following information:

• The App ID: A randomly generated string provided by Agora for identifying your app. You can get the App ID from Agora Console.
• The user ID: The unique identifier of a user. You need to specify the user ID yourself, and ensure that it is unique in the channel.
• A token: In a test or production environment, your app client retrieves tokens from a server in your security infrastructure. For this page, you use a temporary token with a validity period of 24 hours that you retrieve from Agora Console.
• The channel name: A string that identifies the channel for the live stream.

Prerequisites

• Cocos Creator 2.3.4 or later (the interface description in this article is based on Cocos Creator 2.4.3).

• CocoaPods.

• Operating system and IDE requirements:

  Target platform	Operating system version	IDE version
  Android	Android 4.1 or later	Android Studio 3.0 or later Android SDK API 16 or later Android NDK 17 or later
  iOS	iOS 8.0 or later	Xcode 9.0 or later

• A valid Cocos account and a Cocos App ID.

  If your network has a firewall, follow the instructions in Firewall Requirements to access Agora services.

Create a Cocos Creator project

Use the following steps to build a project from scratch:

1. Open Cocos Creator, and navigate to New Project.
2. Choose an example (Hello World shown here), choose a storage path, and enter a project name.
3. Click Create.

Integrate the SDK

1. Open a Cocos Creator project, and click Service on the right to open the Service panel.

2. Click the button following AppID, and click Set Cocos AppID.
   

3. Click the drop-down box, select a game, and click Association to associate your project with your game.

4. On the Service panel, scroll down to find and click Agora RTC.

5. Click the button following Agora RTC, read the prompts carefully, and click Open Service.

6. On the bottom of the Agora RTC panel, select Audio as the SDK type, and click Save to integrate the Agora Cocos Creator SDK.

After integrating the Agora Cocos Creator SDK, Cocos Creator automatically adds codes in your project for obtaining device permissions, so you do not need to write these codes yourself.

Cocos Creator also uses your Cocos Creator account to automatically register an Agora account and create an Agora project. You can click Dashboard on the Agora RTC panel to visit Agora Console.

Configure the Agora project

1. Get an Agora App ID

Agora automatically assigns each project an App ID as a unique identifier.

To copy this App ID, find your project on the Project Management page in Agora Console, and click the copy icon to the right of the App ID.

2. Generate an Agora temporary token

To ensure communication security, Agora recommends using tokens to authenticate users joining a channel.

For testing purposes, Agora Console supports generating RTC temporary tokens. To generate an RTC temporary token:

1. On the Project Management page, click the icon for your project.
2. On the Token page, enter the name of the channel that you want to join, and click Generate Temp Token. When joining the channel later, ensure that the channel name is the same with the one that you use to generate the temporary token.

Implementation

Once the project is set up, create a component script and a scene based on your requirements, and add the script into the scene node. See Creating and using component script.

You can use core APIs of the Agora Cocos Creator SDK in a component script to implement the basic interactive live audio streaming function. The following figure shows the API call sequence:

1. Create a user interface

Create a user interface (UI) for the interactive live audio streaming in your project. If you already have a UI in your project, skip to Initialize the Agora engine.

Agora recommends adding the following elements to the UI:

• A select role button
• An exit button

2. Initialize the Agora engine

Initialize the Agora engine before calling any other Agora APIs. You need to pass in the App ID of your Agora project in this step. See Get the Agora App ID.

Call init and pass in the App ID to initialize the Agora engine.

According to your requirements, you can also listen for callback events in this step, such as when the local user joins or leaves the channel.

// Initialize the Agora engine. You need to use your Agora App ID to replace YOUR_APPID.
agora.init("YOUR_APPID");
// Listen for callback events.
initAgoraEvents: function () {
    if (agora) {
        agora.on('joinChannelSuccess', this.onJoinChannelSuccess, this);
        agora.on('leaveChannel', this.onLeaveChannel, this);
        agora.on('warning', this.onWarning, this);
        agora.on('error', this.onError, this);
        agora.on('userJoined', this.onUserJoined, this);
        agora.on('userOffline', this.onUserOffline, this);
        agora.on('clientRoleChanged', this.onClientRoleChanged, this);
    }
}

3. Set the channel profile

After initializing the Agora engine, call setChannelProfile to set the channel profile as LIVE_BROADCASTING.

If you want to switch to another profile, destroy the current Agora engine with the release method and reinitialize the Agora engine before calling setChannelProfile.

agora.setChannelProfile(CHANNEL_PROFILE_TYPE.CHANNEL_PROFILE_LIVE_BROADCASTING);

4. Set the client role

An interactive streaming channel has two client roles: BROADCASTER and AUDIENCE; and the default role is AUDIENCE. After setting the channel profile to LIVE_BROADCASTING, your app may use the following steps to set the client role:

1. Allow the user to set the role as BROADCASTER or AUDIENCE.
2. Call setClientRole and pass in the client role set by the user.

Note that during the interactive live audio streaming, only the host can be heard. If you want to switch the client role after joining the channel, call the setClientRole method.

agora.setClientRole(CLIENT_ROLE_TYPE.CLIENT_ROLE_BROADCASTER);

5. Join a channel

After setting the client role, you can call joinChannel to join a channel. You need to generate a token to replace YOUR_TOKEN in the code sample below.

• For testing, you can generate a temporary token in Agora Console.
• For production, Agora recommends using a token generated at your server. See Generate a Token.

// For SDKs earlier than v3.1.2, call this method to enable interoperability between the Agora Cocos Creator SDK and the Agora Web SDK if the Agora Web SDK is in the channel.
// As of v3.1.2, the Agora Cocos Creator SDK enables the interoperability with the Agora Web SDK by default, so you do not need to call this method.
agora.enableWebSdkInteroperability(true);
// Join a channel with a token.
agora.joinChannel("YOUR_TOKEN", “channel5”, "Extra Optional Data", 0);

6. Leave the channel

According to your scenario, such as when the interactive live audio streaming ends and when you need to close the app, call leaveChannel to leave the current channel.

agora.leaveChannel();

7. Destroy the Agora engine

After leaving the channel, if you want to exit the app or release the memory of the Agora engine, call release to destroy the Agora engine.

agora.release();

Run the project

Agora recommends running and debugging your project through a real Android or iOS device. See Compile and preview.

When the interactive live audio streaming starts successfully, audience members can hear the voice of hosts in the app.

Q&A

Q: I set a correct build path. Why do I receive the xxx.o:No such file or directory error message?
A: The cause of this problem is that the bulild path is too long. You need to shorten the bulild path. For example, change the bulild path to the disk root.

Reference

Agora provide an open-source Voice-Call-for-Mobile-Gaming sample project on GitHub that implements the basic one-to-one voice call. You can refer to this sample project and the sample code in this article to implement the interactive live audio streaming.