Agora RTC Objective-C API Reference  Refactor
<AgoraRtcEngineDelegate> Protocol Reference

Inherits <NSObject>.

Core Delegate Methods


(void) - rtcEngineRequestToken:
 
(void) - rtcEngine:tokenPrivilegeWillExpire:
 
(void) - rtcEngineConnectionDidLost:
 
(void) - rtcEngine:connectionStateChanged:reason:
 
(void) - rtcEngine:reportRtcStats:
 
(void) - rtcEngine:lastmileProbeTestResult:
 
(void) - rtcEngine:didApiCallExecute:api:result:
 

Local User Core Delegate Methods


(void) - rtcEngine:didJoinChannel:withUid:elapsed:
 
(void) - rtcEngine:didRejoinChannel:withUid:elapsed:
 
(void) - rtcEngine:didClientRoleChanged:newRole:
 
(void) - rtcEngine:didLeaveChannelWithStats:
 

Local User Audio Delegate Methods


(void) - rtcEngine:audioMixingStateChanged:errorType:
 
(void) - rtcEngine:firstLocalAudioFramePublished:
 
(void) - rtcEngine:localAudioStats:
 
(void) - rtcEngine:localAudioStateChanged:error:
 

Remote User Core Delegate Methods


(void) - rtcEngine:didJoinedOfUid:elapsed:
 
(void) - rtcEngine:didOfflineOfUid:reason:
 

Remote User Audio Delegate Methods


(void) - rtcEngine:remoteAudioStats:
 
(void) - rtcEngine:reportAudioVolumeIndicationOfSpeakers:totalVolume:
 
(void) - rtcEngineIntraRequestReceived:
 
(void) - rtcEngine:bandwidthEstimationUpdate:
 

Remote User Video Delegates Methods


(void) - rtcEngine:localVideoStateChangedOfState:error:
 
(void) - rtcEngine:remoteVideoStateChangedOfUid:state:reason:elapsed:
 
(void) - rtcEngine:remoteAudioStateChangedOfUid:state:reason:elapsed:
 
(void) - rtcEngine:remoteVideoStats:
 

Stream Publish Delegate Methods


(void) - rtcEngine:streamStateChanged:state:errCode:
 
(void) - rtcEngine:audioMixingStateChanged:errorCode:
 

Detailed Description

The AgoraRtcEngineDelegate protocol enables callback event notifications to your application.

The SDK uses delegate callbacks in the AgoraRtcEngineDelegate protocol to report runtime events to the application. From v1.1, some block callbacks in the SDK are replaced with delegate callbacks. The old block callbacks are therefore deprecated, but can still be used in the current version. However, Agora recommends replacing block callbacks with delegate callbacks. The SDK calls the block callback if a callback is defined in both the block and delegate callbacks.

Method Documentation

◆ rtcEngineRequestToken:

- (void) rtcEngineRequestToken: (AgoraRtcEngineKit *_Nonnull)  engine

Occurs when the token has expired.

If a token is specified when calling joinChannelByToken, the token expires after a certain period of time and you need a new token to reconnect to the server.

Upon receiving this callback, generate a new token at your app server and call renewToken to pass the new token to the SDK.

Parameters
engineThe AgoraRtcEngineKit object.
See also
How to generate a token.

◆ rtcEngine:tokenPrivilegeWillExpire:

- (void) rtcEngine: (AgoraRtcEngineKit *_Nonnull)  engine
tokenPrivilegeWillExpire: (NSString *_Nonnull)  token 

Occurs when the token will expire in 30 seconds.

If the token you specified when calling joinChannelByToken expires, the user drops offline. This callback is triggered 30 seconds before the token expires, to remind you to renew the token. Upon receiving this callback, generate a new token at your app server and call renewToken to pass the new token to the SDK.

Parameters
engineThe AgoraRtcEngineKit object.
tokenThe token that will expire in 30 seconds.

◆ rtcEngineConnectionDidLost:

- (void) rtcEngineConnectionDidLost: (AgoraRtcEngineKit *_Nonnull)  engine

Occurs when the SDK cannot reconnect to Agora's edge server 10 seconds after its connection to the server is interrupted.

The SDK triggers this callback when it cannot connect to the server 10 seconds after calling joinChannelByToken, regardless of whether it is in the channel or not.

Parameters
engineThe AgoraRtcEngineKit object.

◆ rtcEngine:connectionStateChanged:reason:

- (void) rtcEngine: (AgoraRtcEngineKit *_Nonnull)  engine
connectionStateChanged: (AgoraConnectionState)  state
reason: (AgoraConnectionChangedReason)  reason 

Occurs when the connection state of the SDK to the server is changed.

Parameters
engineThe AgoraRtcEngineKit object.
stateSee AgoraConnectionState.
reasonSee AgoraConnectionChangedReason.

◆ rtcEngine:reportRtcStats:

- (void) rtcEngine: (AgoraRtcEngineKit *_Nonnull)  engine
reportRtcStats: (AgoraChannelStats *_Nonnull)  stats 

Reports the statistics of the current call.

This callback is triggered once every two seconds after the user joins the channel.

Parameters
engineThe AgoraRtcEngineKit object.
statsThe statistics on the current call: AgoraChannelStats.

◆ rtcEngine:lastmileProbeTestResult:

- (void) rtcEngine: (AgoraRtcEngineKit *_Nonnull)  engine
lastmileProbeTestResult: (AgoraLastmileProbeResult *_Nonnull)  result 

Reports the last-mile network probe result.

The SDK triggers this callback within 30 seconds after the app calls the startLastmileProbeTest method.

Parameters
engineThe AgoraRtcEngineKit object.
resultThe uplink and downlink last-mile network probe test result, see AgoraLastmileProbeResult.

◆ rtcEngine:didApiCallExecute:api:result:

- (void) rtcEngine: (AgoraRtcEngineKit *_Nonnull)  engine
didApiCallExecute: (NSInteger)  error
api: (NSString *_Nonnull)  api
result: (NSString *_Nonnull)  result 

The API call was executed successfully.

Parameters
engineThe AgoraRtcEngineKit object.
errorAgoraErrorCode
apiThe method executed by the SDK.
resultThe result of the method call.

◆ rtcEngine:didJoinChannel:withUid:elapsed:

- (void) rtcEngine: (AgoraRtcEngineKit *_Nonnull)  engine
didJoinChannel: (NSString *_Nonnull)  channel
withUid: (NSUInteger)  uid
elapsed: (NSInteger)  elapsed 

Occurs when the local user successfully joins a specified channel.

Parameters
engineAgoraRtcEngineKit object
channelThe channel name.
uidThe user ID.
elapsedThe time elapsed (ms) from the local user calling joinChannelByToken until this event occurs.

◆ rtcEngine:didRejoinChannel:withUid:elapsed:

- (void) rtcEngine: (AgoraRtcEngineKit *_Nonnull)  engine
didRejoinChannel: (NSString *_Nonnull)  channel
withUid: (NSUInteger)  uid
elapsed: (NSInteger)  elapsed 

Occurs when the local user rejoins a channel.

If the client loses connection with the server because of network problems, the SDK automatically attempts to reconnect and then triggers this callback upon reconnection, indicating that the user rejoins the channel with the assigned channel ID and user ID.

Parameters
engineThe AgoraRtcEngineKit object.
channelThe channel name.
uidThe user ID.
elapsedTime elapsed (ms) from the local user calling joinChannelByToken until this event occurs.

◆ rtcEngine:didClientRoleChanged:newRole:

- (void) rtcEngine: (AgoraRtcEngineKit *_Nonnull)  engine
didClientRoleChanged: (AgoraClientRole)  oldRole
newRole: (AgoraClientRole)  newRole 

Occurs when the local user role switches in a live broadcast.

Parameters
engineThe AgoraRtcEngineKit object.
oldRoleThe role that the user switches from: AgoraClientRole.
newRoleThe role that the user switches to: AgoraClientRole.

◆ rtcEngine:didLeaveChannelWithStats:

- (void) rtcEngine: (AgoraRtcEngineKit *_Nonnull)  engine
didLeaveChannelWithStats: (AgoraChannelStats *_Nonnull)  stats 

Occurs when the local user leaves a channel.

When the user successfully leaves the channel after calling leaveChannel method, this callback notifies the app that a user leaves a channel.

This callback also reports information such as the call duration and the statistics of data received or transmitted by the SDK.

Parameters
engineThe AgoraRtcEngineKit object.
statsThe statistics of the call. See AgoraChannelStats.

◆ rtcEngine:audioMixingStateChanged:errorType:

- (void) rtcEngine: (AgoraRtcEngineKit *_Nonnull)  engine
audioMixingStateChanged: (AgoraAudioMixingStateType)  stateType
errorType: (AgoraAudioMixingErrorType)  errorType 

Occurs when the playback state of the local user's audio mixing file changes.

  • When the audio mixing file plays, pauses playing, or stops playing, this callback returns 710, 711, or 713 in state, and 0 in errorCode.
  • When exceptions occur during playback, this callback returns 714 in state and an error code in errorCode.
Parameters
engineThe AgoraRtcEngineKit object.
stateAgoraAudioMixingStateType
errorCodeAgoraAudioMixingErrorType

◆ rtcEngine:firstLocalAudioFramePublished:

- (void) rtcEngine: (AgoraRtcEngineKit *_Nonnull)  engine
firstLocalAudioFramePublished: (NSInteger)  elapsed 

Occurs when the first local audio frame is published.

Parameters
engineThe AgoraRtcEngineKit object.
elapsedThe time elapsed (ms) from calling joinChannelByToken until the SDK triggers this callback.

◆ rtcEngine:localAudioStats:

- (void) rtcEngine: (AgoraRtcEngineKit *_Nonnull)  engine
localAudioStats: (AgoraRtcLocalAudioStats *_Nonnull)  stats 

Reports the statistics of the local audio stream.

The SDK triggers this callback once every two seconds.

Parameters
engineThe AgoraRtcEngineKit object.
statsThe statistics of the local audio stream. See AgoraRtcLocalAudioStats.

◆ rtcEngine:localAudioStateChanged:error:

- (void) rtcEngine: (AgoraRtcEngineKit *_Nonnull)  engine
localAudioStateChanged: (AgoraAudioLocalState)  state
error: (AgoraAudioLocalError)  error 

Occurs when the local audio stream state changes.

This callback indicates the state change of the local audio stream, including the state of the audio recording and encoding, and allows you to troubleshoot issues when exceptions occur.

Note
When the state is AgoraAudioLocalStateFailed(3), see the error parameter for details.
Parameters
engineAgoraRtcEngineKit object
stateThe state of the local audio. See AgoraAudioLocalState.
errorThe error information of the local audio. See AgoraAudioLocalError.

◆ rtcEngine:didJoinedOfUid:elapsed:

- (void) rtcEngine: (AgoraRtcEngineKit *_Nonnull)  engine
didJoinedOfUid: (NSUInteger)  uid
elapsed: (NSInteger)  elapsed 

Occurs when a remote user or user joins the channel.

If other users or hosts are already in the channel, the SDK also reports to the app on the existing users/hosts.

The SDK triggers this callback under one of the following circumstances:

  • A remote user/host joins the channel by calling joinChannelByToken.
  • A remote user switches the user role to the host by calling setClientRole method after joining the channel.
  • A remote user/host rejoins the channel after a network interruption.
    Note
    When a web user joins the channel, this callback is triggered as long as the user publishes a stream.
    Parameters
    engineThe AgoraRtcEngineKit object.
    uidThe user ID.
    elapsedTime elapsed (ms) from calling joinChannelByToken until this callback is triggered.

◆ rtcEngine:didOfflineOfUid:reason:

- (void) rtcEngine: (AgoraRtcEngineKit *_Nonnull)  engine
didOfflineOfUid: (NSUInteger)  uid
reason: (AgoraUserOfflineReason)  reason 

Occurs when a remote user or host goes offline.

There are two reasons for a user to go offline:

  • Leave the channel: When the user leaves the channel, the user sends a goodbye message. When this message is received, the SDK determines that the user leaves the channel.
  • Drop offline: When no data packet of the user is received for a certain period of time, the SDK assumes that the user drops offline. A poor network connection may lead to false detection, so we recommend using the RTM SDK for reliable offline detection.
Parameters
engineThe AgoraRtcEngineKit object.
uidThe ID of the user who goes offline.
reasonThe reason why the user goes offline: AgoraUserOfflineReason.

◆ rtcEngine:remoteAudioStats:

- (void) rtcEngine: (AgoraRtcEngineKit *_Nonnull)  engine
remoteAudioStats: (AgoraRtcRemoteAudioStats *_Nonnull)  stats 

Reports the statistics of the remote audio stream.

The SDK triggers this callback once every two seconds for each remote user or broadcaster. If a channel has multiple remote users, the SDK triggers this callback as many times.

Parameters
engineThe AgoraRtcEngineKit object.
statsThe statistics of the received audio. See AgoraRtcRemoteAudioStats.

◆ rtcEngine:reportAudioVolumeIndicationOfSpeakers:totalVolume:

- (void) rtcEngine: (AgoraRtcEngineKit *_Nonnull)  engine
reportAudioVolumeIndicationOfSpeakers: (NSArray< AgoraRtcAudioVolumeInfo * > *_Nonnull)  speakers
totalVolume: (NSInteger)  totalVolume 

This callback reports the IDs and volumes of the loudest speakers at the moment in the channel, and whether the local user is speaking.

Once enabled, this callback is triggered at the set interval, regardless of whether a user speaks or not.

The SDK triggers two independent reportAudioVolumeIndicationOfSpeakers callbacks at one time, which separately report the volume information of the local user and all the remote speakers.

Parameters
engineThe AgoraRtcEngineKit object.
speakersAn array containing the user ID and volume information for each speaker: AgoraRtcAudioVolumeInfo.
  • In the local user's callback, this array contains the following members:
    • uid = 0,
    • volume = totalVolume, which reports the sum of the voice volume and audio-mixing volume of the local user.
  • In the remote users' callback, this array contains the following members:
    • uid of each remote speaker.
    • volume, which reports the sum of the voice volume and audio-mixing volume of each remote speaker. An empty speakers array in the callback indicates that no remote user is speaking at the moment.
totalVolumeThe total volume after audio mixing. The value ranges between 0 (the lowest volume) and 255 (the highest volume).
  • In the local user's callback, totalVolume is the sum of the voice volume and audio-mixing volume of the local user.
  • In the remote users' callback, totalVolume is the sum of the voice volume and audio-mixing volume of all the remote speakers.

◆ rtcEngineIntraRequestReceived:

- (void) rtcEngineIntraRequestReceived: (AgoraRtcEngineKit *_Nonnull)  engine

Intra request received.

Parameters
engineThe AgoraRtcEngineKit object.

◆ rtcEngine:bandwidthEstimationUpdate:

- (void) rtcEngine: (AgoraRtcEngineKit *_Nonnull)  engine
bandwidthEstimationUpdate: (AgoraNetworkInfo *_Nonnull)  networkInfo 

Target bitrate updated.

Parameters
engineThe AgoraRtcEngineKit object.
networkInfoThe suggested network info, including target bitrate bps.

◆ rtcEngine:localVideoStateChangedOfState:error:

- (void) rtcEngine: (AgoraRtcEngineKit *_Nonnull)  engine
localVideoStateChangedOfState: (AgoraVideoLocalState)  state
error: (AgoraLocalVideoStreamError)  error 

Occurs when the local video stream state changes

This callback indicates the state of the local video stream, including camera capturing and video encoding, and allows you to troubleshoot issues when exceptions occur.

Note
For some device models, the SDK will not trigger this callback when the state of the local video changes while the local video capturing device is in use, so you have to make your own timeout judgment.
Parameters
engineAgoraRtcEngineKit object
stateState type AgoraVideoLocalState. When the state is AgoraVideoLocalStateFailed (3), see the error parameter for details.
errorThe detailed error information: AgoraLocalVideoStreamError.

◆ rtcEngine:remoteVideoStateChangedOfUid:state:reason:elapsed:

- (void) rtcEngine: (AgoraRtcEngineKit *_Nonnull)  engine
remoteVideoStateChangedOfUid: (NSUInteger)  uid
state: (AgoraVideoRemoteState)  state
reason: (AgoraVideoRemoteReason)  reason
elapsed: (NSInteger)  elapsed 

A remote video stream state changed.

Parameters
engineAgoraRtcEngineKit object
uidID of the user whose video state has changed.
stateState of the remote video: Running: the remote video is normal Frozen: the remote video is frozen
reasonInteral: Internal reasons. NetworkCongestion: Network congestion. NetworkRecovery: Network recovery. LocalMuted: The local user stops receiving the remote audio stream or disables the audio module. LocalUnmuted: The local user resumes receiving the remote audio stream or enables the audio module. RemoteMuted: The remote user stops sending the audio stream or disables the audio module. RemoteUnmuted: The remote user resumes sending the audio stream or enables the audio module. Offline: The remote user leaves the channel. AudioFallback: The remote media stream falls back to the audio-only stream due to poor network conditions. AudioFallbackRecovery: The remote media stream switches back to the video stream after the network conditions improve.
elapsedThe time elapsed (ms) from the local user calling ref "joinChannel" until this callback is triggered.

◆ rtcEngine:remoteAudioStateChangedOfUid:state:reason:elapsed:

- (void) rtcEngine: (AgoraRtcEngineKit *_Nonnull)  engine
remoteAudioStateChangedOfUid: (NSUInteger)  uid
state: (AgoraAudioRemoteState)  state
reason: (AgoraAudioRemoteReason)  reason
elapsed: (NSInteger)  elapsed 

Occurs when the state of a remote audio stream changes.

Parameters
engineThe AgoraRtcEngineKit object.
uidThe ID of the user whose audio state has changed.
stateThe state of the remote audio. See AgoraAudioRemoteState.
reasonThe reason of the remote audio state change. See AgoraAudioRemoteReason.
elapsedThe time elapsed (ms) from calling joinChannelByToken until the SDK triggers this callback.

◆ rtcEngine:remoteVideoStats:

- (void) rtcEngine: (AgoraRtcEngineKit *_Nonnull)  engine
remoteVideoStats: (AgoraRtcRemoteVideoStats *_Nonnull)  stats 

Reports the statistics of the video stream from each remote user/host.

The SDK triggers this callback once every two seconds for each remote user or host. If a channel includes multiple remote users, the SDK triggers this callback as many times.

This callback reports the statistics more closely linked to the real-user experience of the video transmission quality.

Schemes such as FEC (Forward Error Correction) or retransmission counter the frame loss rate. Hence, users may find the overall video quality acceptable even when the packet loss rate is high.

Parameters
engineThe AgoraRtcEngineKit object.
statsThe statistics of the received remote video streams. See AgoraRtcRemoteVideoStats.

◆ rtcEngine:streamStateChanged:state:errCode:

- (void) rtcEngine: (AgoraRtcEngineKit *_Nonnull)  engine
streamStateChanged: (NSString *_Nonnull)  url
state: (AgoraRtmpStreamPublishState)  state
errCode: (AgoraRtmpStreamPublishError)  errCode 

Occurs when the state of the RTMP streaming changes.

Parameters
engineThe AgoraRtcEngineKit object.
urlAddress to which the publisher publishes the stream.
state[AgoraRtmpStreamPublishState]([AgoraRtmpStreamPublishState])
errCode[AgoraRtmpStreamPublishError]([AgoraRtmpStreamPublishError])

◆ rtcEngine:audioMixingStateChanged:errorCode:

- (void) rtcEngine: (AgoraRtcEngineKit *_Nonnull)  engine
audioMixingStateChanged: (AgoraAudioMixingStateType)  state
errorCode: (AgoraAudioMixingErrorType)  errorCode 

Audio mixing state changed.

Parameters
engineThe AgoraRtcEngineKit object.
stateAgoraAudioMixingStateType
errorCodeAgoraAudioMixingErrorType