This article describes how to integrate the Agora Cocos Creator SDK and implement the basic interactive live audio streaming in your app.
Cocos Creator 2.3.4 or later (the interface description in this article is based on Cocos Creator 2.4.3).
Operating system and IDE requirements:
Target platform | Operating system version | IDE version |
---|---|---|
Android | Android 4.1 or later |
|
iOS | iOS 8.0 or later | Xcode 9.0 or later |
A valid Cocos account and a Cocos App ID.
Use the following steps to build a project from scratch:
Open a Cocos Creator project, and click Service on the right to open the Service panel.
Click the button following AppID, and click Set Cocos AppID.
Click the drop-down box, select a game, and click Association to associate your project with your game.
On the Service panel, scroll down to find and click Agora RTC.
Click the button following Agora RTC, read the prompts carefully, and click Open Service.
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.
To ensure communication security, Agora uses tokens (dynamic keys) to authenticate users joining a channel.
Agora Console supports generating temporary tokens for testing purposes. The following steps show how to generate a temporary token:
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:
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:
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);
}
}
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);
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:
BROADCASTER
or AUDIENCE
.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);
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 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);
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();
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();
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: 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.
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.