Class: Agora::AgoraDynamicKey2::RtcTokenBuilder

Inherits:
Object
  • Object
show all
Defined in:
lib/agora/dynamic_key2/rtc_token_builder.rb

Constant Summary collapse

ROLE_PUBLISHER =

RECOMMENDED. Use this role for a voice/video call or a live broadcast, if your scenario does not require authentication for [Co-host](docs.agora.io/en/video-calling/get-started/authentication-workflow?#co-host-token-authentication).

1
ROLE_SUBSCRIBER =
Note:

In order for this role to take effect, please contact our support team

Only use this role if your scenario require authentication for [Co-host](docs.agora.io/en/video-calling/get-started/authentication-workflow?#co-host-token-authentication). to enable authentication for Hosting-in for you. Otherwise, Role_Subscriber still has the same privileges as Role_Publisher.

2

Class Method Summary collapse

Class Method Details

.build_token_with_rtm(app_id, app_certificate, channel_name, account, role, token_expire, privilege_expire = 0) ⇒ Object

Build the RTC and RTM token with account.

app_id: The App ID issued to you by Agora. Apply for a new App ID from Agora Dashboard if it is missing

from your kit. See Get an App ID.

app_certificate: Certificate of the application that you registered in the Agora Dashboard.

See Get an App Certificate.

channel_name: Unique channel name for the AgoraRTC session in the string format. uid: User ID. A 32-bit unsigned integer with a value ranging from 1 to (2^32-1).

uid must be unique.

role: ROLE_PUBLISHER: A broadcaster/host in a live-broadcast profile.

ROLE_SUBSCRIBER: An audience(default) in a live-broadcast profile.

token_expire: represented by the number of seconds elapsed since now. If, for example,

you want to access the Agora Service within 10 minutes after the token is generated,
set token_expire as 600(seconds).

privilege_expire: represented by the number of seconds elapsed since now. If, for example,

you want to enable your privilege for 10 minutes, set privilege_expire as 600(seconds).

return: The RTC and RTM token.



195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
 
# File 'lib/agora/dynamic_key2/rtc_token_builder.rb', line 195

def self.build_token_with_rtm(app_id, app_certificate, channel_name, , role, token_expire, privilege_expire = 0)
  access_token = Agora::AgoraDynamicKey2::AccessToken.new(app_id, app_certificate, token_expire)
  service_rtc = Agora::AgoraDynamicKey2::ServiceRtc.new(channel_name, )

  service_rtc.add_privilege(Agora::AgoraDynamicKey2::ServiceRtc::PRIVILEGE_JOIN_CHANNEL, privilege_expire)
  if role == ROLE_PUBLISHER
    service_rtc.add_privilege(Agora::AgoraDynamicKey2::ServiceRtc::PRIVILEGE_PUBLISH_AUDIO_STREAM, privilege_expire)
    service_rtc.add_privilege(Agora::AgoraDynamicKey2::ServiceRtc::PRIVILEGE_PUBLISH_VIDEO_STREAM, privilege_expire)
    service_rtc.add_privilege(Agora::AgoraDynamicKey2::ServiceRtc::PRIVILEGE_PUBLISH_DATA_STREAM, privilege_expire)
  end
  access_token.add_service(service_rtc)

  service_rtm = Agora::AgoraDynamicKey2::ServiceRtm.new()

  service_rtm.add_privilege(Agora::AgoraDynamicKey2::ServiceRtm::, token_expire)
  access_token.add_service(service_rtm)

  access_token.build
end

.build_token_with_uid(app_id, app_certificate, channel_name, uid, role, token_expire, privilege_expire = 0) ⇒ Object

Build the RTC token with uid.

app_id: The App ID issued to you by Agora. Apply for a new App ID from Agora Dashboard if it is missing

from your kit. See Get an App ID.

app_certificate: Certificate of the application that you registered in the Agora Dashboard.

See Get an App Certificate.

channel_name: Unique channel name for the AgoraRTC session in the string format. uid: User ID. A 32-bit unsigned integer with a value ranging from 1 to (2^32-1).

uid must be unique.

role: ROLE_PUBLISHER: A broadcaster/host in a live-broadcast profile.

ROLE_SUBSCRIBER: An audience(default) in a live-broadcast profile.

token_expire: represented by the number of seconds elapsed since now. If, for example,

you want to access the Agora Service within 10 minutes after the token is generated,
set token_expire as 600(seconds).

privilege_expire: represented by the number of seconds elapsed since now. If, for example,

you want to enable your privilege for 10 minutes, set privilege_expire as 600(seconds).

return: The RTC token.



32
33
34
 
# File 'lib/agora/dynamic_key2/rtc_token_builder.rb', line 32

def self.build_token_with_uid(app_id, app_certificate, channel_name, uid, role, token_expire, privilege_expire = 0)
  (app_id, app_certificate, channel_name, uid, role, token_expire, privilege_expire)
end

.build_token_with_uid_and_privilege(app_id, app_certificate, channel_name, uid, token_expire, join_channel_privilege_expire, pub_audio_privilege_expire, pub_video_privilege_expire, pub_data_stream_privilege_expire) ⇒ Object

Note:

Generates an RTC token with the specified privilege.

This method supports generating a token with the following privileges:

  • Joining an RTC channel.

  • Publishing audio in an RTC channel.

  • Publishing video in an RTC channel.

  • Publishing data streams in an RTC channel.

The privileges for publishing audio, video, and data streams in an RTC channel apply only if you have enabled co-host authentication.

A user can have multiple privileges. Each privilege is valid for a maximum of 24 hours. The SDK triggers the onTokenPrivilegeWillExpire and onRequestToken callbacks when the token is about to expire or has expired. The callbacks do not report the specific privilege affected, and you need to maintain the respective timestamp for each privilege in your app logic. After receiving the callback, you need to generate a new token, and then call renewToken to pass the new token to the SDK, or call joinChannel to re-join the channel.

Agora recommends setting a reasonable timestamp for each privilege according to your scenario. Suppose the expiration timestamp for joining the channel is set earlier than that for publishing audio. When the token for joining the channel expires, the user is immediately kicked off the RTC channel and cannot publish any audio stream, even though the timestamp for publishing audio has not expired.

  • All lowercase English letters: a to z.

  • All uppercase English letters: A to Z.

  • All numeric characters: 0 to 9.

  • The space character.

  • “!”, “#”, “$”, “%”, “&”, “(”, “)”, “+”, “-”, “:”, “;”, “<”, “=”, “.”, “>”, “?”, “@”, “[”, “]”, “^”, “_”, “ “”, “|”, “~”, “,”.

Agora Service within 10 minutes after the token is generated, set token_expire as 600(seconds). If, for example, you want to join channel and expect stay in the channel for 10 minutes, set join_channel_privilege_expire as 600(seconds). If, for example, you want to enable publish audio privilege for 10 minutes, set pub_audio_privilege_expire as 600(seconds). If, for example, you want to enable publish video privilege for 10 minutes, set pub_video_privilege_expire as 600(seconds). If, for example, you want to enable publish data stream privilege for 10 minutes, set pub_data_stream_privilege_expire as 600(seconds).

Parameters:

  • app_id —

    The App ID of your Agora project.

  • app_certificate —

    The App Certificate of your Agora project.

  • channel_name —

    The unique channel name for the Agora RTC session in string format. The string length must be less than 64 bytes. The channel name may contain the following characters:

  • uid —

    The user ID. A 32-bit unsigned integer with a value range from 1 to (2^32 - 1). It must be unique. Set uid as 0, if you do not want to authenticate the user ID, that is, any uid from the app client can join the channel.

  • token_expire —

    represented by the number of seconds elapsed since now. If, for example, you want to access the

  • join_channel_privilege_expire —

    represented by the number of seconds elapsed since now.

  • pub_audio_privilege_expire —

    represented by the number of seconds elapsed since now.

  • pub_video_privilege_expire —

    represented by the number of seconds elapsed since now.

  • pub_data_stream_privilege_expire —

    represented by the number of seconds elapsed since now.

Returns:

  • The RTC Token



111
112
113
114
115
116
117
118
 
# File 'lib/agora/dynamic_key2/rtc_token_builder.rb', line 111

def self.build_token_with_uid_and_privilege(app_id, app_certificate, channel_name, uid, token_expire,
                                            join_channel_privilege_expire, pub_audio_privilege_expire,
                                            pub_video_privilege_expire, pub_data_stream_privilege_expire)
  (
    app_id, app_certificate, channel_name, uid, token_expire, join_channel_privilege_expire,
    pub_audio_privilege_expire, pub_video_privilege_expire, pub_data_stream_privilege_expire
  )
end

.build_token_with_user_account(app_id, app_certificate, channel_name, account, role, token_expire, privilege_expire = 0) ⇒ Object

Build the RTC token with account.

app_id: The App ID issued to you by Agora. Apply for a new App ID from Agora Dashboard if it is missing

from your kit. See Get an App ID.

app_certificate: Certificate of the application that you registered in the Agora Dashboard.

See Get an App Certificate.

channel_name: Unique channel name for the AgoraRTC session in the string format. uid: User ID. A 32-bit unsigned integer with a value ranging from 1 to (2^32-1).

uid must be unique.

role: ROLE_PUBLISHER: A broadcaster/host in a live-broadcast profile.

ROLE_SUBSCRIBER: An audience(default) in a live-broadcast profile.

token_expire: represented by the number of seconds elapsed since now. If, for example,

you want to access the Agora Service within 10 minutes after the token is generated,
set token_expire as 600(seconds).

privilege_expire: represented by the number of seconds elapsed since now. If, for example,

you want to enable your privilege for 10 minutes, set privilege_expire as 600(seconds).

return: The RTC token.



53
54
55
56
57
58
59
60
61
62
63
64
65
 
# File 'lib/agora/dynamic_key2/rtc_token_builder.rb', line 53

def self.(app_id, app_certificate, channel_name, , role, token_expire, privilege_expire = 0)
  access_token = Agora::AgoraDynamicKey2::AccessToken.new(app_id, app_certificate, token_expire)
  service_rtc = Agora::AgoraDynamicKey2::ServiceRtc.new(channel_name, )

  service_rtc.add_privilege(Agora::AgoraDynamicKey2::ServiceRtc::PRIVILEGE_JOIN_CHANNEL, privilege_expire)
  if role == ROLE_PUBLISHER
    service_rtc.add_privilege(Agora::AgoraDynamicKey2::ServiceRtc::PRIVILEGE_PUBLISH_AUDIO_STREAM, privilege_expire)
    service_rtc.add_privilege(Agora::AgoraDynamicKey2::ServiceRtc::PRIVILEGE_PUBLISH_VIDEO_STREAM, privilege_expire)
    service_rtc.add_privilege(Agora::AgoraDynamicKey2::ServiceRtc::PRIVILEGE_PUBLISH_DATA_STREAM, privilege_expire)
  end
  access_token.add_service(service_rtc)
  access_token.build
end

.build_token_with_user_account_and_privilege(app_id, app_certificate, channel_name, account, token_expire, join_channel_privilege_expire, pub_audio_privilege_expire, pub_video_privilege_expire, pub_data_stream_privilege_expire) ⇒ Object

Note:

Generates an RTC token with the specified privilege.

This method supports generating a token with the following privileges:

  • Joining an RTC channel.

  • Publishing audio in an RTC channel.

  • Publishing video in an RTC channel.

  • Publishing data streams in an RTC channel.

The privileges for publishing audio, video, and data streams in an RTC channel apply only if you have enabled co-host authentication.

A user can have multiple privileges. Each privilege is valid for a maximum of 24 hours. The SDK triggers the onTokenPrivilegeWillExpire and onRequestToken callbacks when the token is about to expire or has expired. The callbacks do not report the specific privilege affected, and you need to maintain the respective timestamp for each privilege in your app logic. After receiving the callback, you need to generate a new token, and then call renewToken to pass the new token to the SDK, or call joinChannel to re-join the channel.

Agora recommends setting a reasonable timestamp for each privilege according to your scenario. Suppose the expiration timestamp for joining the channel is set earlier than that for publishing audio. When the token for joining the channel expires, the user is immediately kicked off the RTC channel and cannot publish any audio stream, even though the timestamp for publishing audio has not expired.

  • All lowercase English letters: a to z.

  • All uppercase English letters: A to Z.

  • All numeric characters: 0 to 9.

  • The space character.

  • “!”, “#”, “$”, “%”, “&”, “(”, “)”, “+”, “-”, “:”, “;”, “<”, “=”, “.”, “>”, “?”, “@”, “[”, “]”, “^”, “_”, “ “”, “|”, “~”, “,”.

Agora Service within 10 minutes after the token is generated, set token_expire as 600(seconds). If, for example, you want to join channel and expect stay in the channel for 10 minutes, set join_channel_privilege_expire as 600(seconds). If, for example, you want to enable publish audio privilege for 10 minutes, set pub_audio_privilege_expire as 600(seconds). If, for example, you want to enable publish video privilege for 10 minutes, set pub_video_privilege_expire as 600(seconds). If, for example, you want to enable publish data stream privilege for 10 minutes, set pub_data_stream_privilege_expire as 600(seconds).

Parameters:

  • app_id —

    The App ID of your Agora project.

  • app_certificate —

    The App Certificate of your Agora project.

  • channel_name —

    The unique channel name for the Agora RTC session in string format. The string length must be less than 64 bytes. The channel name may contain the following characters:

  • account —

    The user account.

  • token_expire —

    represented by the number of seconds elapsed since now. If, for example, you want to access the

  • join_channel_privilege_expire —

    represented by the number of seconds elapsed since now.

  • pub_audio_privilege_expire —

    represented by the number of seconds elapsed since now.

  • pub_video_privilege_expire —

    represented by the number of seconds elapsed since now.

  • pub_data_stream_privilege_expire —

    represented by the number of seconds elapsed since now.

Returns:

  • The RTC Token



164
165
166
167
168
169
170
171
172
173
174
175
176
 
# File 'lib/agora/dynamic_key2/rtc_token_builder.rb', line 164

def self.(app_id, app_certificate, channel_name, , token_expire,
                                                      join_channel_privilege_expire, pub_audio_privilege_expire,
                                                      pub_video_privilege_expire, pub_data_stream_privilege_expire)
  access_token = Agora::AgoraDynamicKey2::AccessToken.new(app_id, app_certificate, token_expire)
  service_rtc = Agora::AgoraDynamicKey2::ServiceRtc.new(channel_name, )

  service_rtc.add_privilege(Agora::AgoraDynamicKey2::ServiceRtc::PRIVILEGE_JOIN_CHANNEL, join_channel_privilege_expire)
  service_rtc.add_privilege(Agora::AgoraDynamicKey2::ServiceRtc::PRIVILEGE_PUBLISH_AUDIO_STREAM, pub_audio_privilege_expire)
  service_rtc.add_privilege(Agora::AgoraDynamicKey2::ServiceRtc::PRIVILEGE_PUBLISH_VIDEO_STREAM, pub_video_privilege_expire)
  service_rtc.add_privilege(Agora::AgoraDynamicKey2::ServiceRtc::PRIVILEGE_PUBLISH_DATA_STREAM, pub_data_stream_privilege_expire)
  access_token.add_service(service_rtc)
  access_token.build
end