Merge branch 'staging' of https://github.com/AgoraIO/Docs-Source

assets/code/signaling/authentication-workflow/handle-expire-event.mdx

@@ -0,0 +1,47 @@
+A token expires after the `tokenExpiryTime` specified in the call to the token server. If the expiry time is not specified the default timeout is 24 hours. The  `TokenPrivilegeWillExpire` event receives a callback when the current token is about to expire so that a fresh token may be retrieved and used.
+
+<PlatformWrapper platform='android'>
+
+    ```kotlin
+    override fun onTokenPrivilegeWillExpire(token: String) {
+        handleTokenExpiry()
+        super.onTokenPrivilegeWillExpire(token)
+    }
+    ```
+
+    * <Link to="{{Global.API_REF_SIG_ANDROID}}#event-listeners">Event Listeners</Link>
+
+
+</PlatformWrapper>
+
+<PlatformWrapper platform={['ios','macos']}>
+    ```swift
+    public func rtmKit(_ rtmClient: RtmClientKit, tokenPrivilegeWillExpire channel: String?) {
+        // token will expire soon
+    }
+    ```
+    <PlatformWrapper platform="ios">
+    - <Link to="{{Global.SIG2_SDK_API_IOS}}/rtmclientdelegate/rtmkit(_:tokenprivilegewillexpire:)-3d6ke">rtmKit(_:tokenPrivilegeWillExpire:)</Link>
+    </PlatformWrapper>
+    <PlatformWrapper platform="macos">
+    - <Link to="{{Global.SIG2_SDK_API_MACOS}}/rtmclientdelegate/rtmkit(_:tokenprivilegewillexpire:)-3d6ke">rtmKit(_:tokenPrivilegeWillExpire:)</Link>
+    </PlatformWrapper>
+</PlatformWrapper>
+
+<PlatformWrapper platform = 'web'>
+
+    ``` javascript
+    // When token-privilege-will-expire occurs, fetch a new token from the server and call renewToken to renew the token.
+      const handleSignalingEvents = (event, eventArgs) => {
+        switch (event) {
+          case "TokenPrivilegeWillExpire":
+            renewToken(uid);
+            break;
+        }
+      }
+    ```
+
+    * <Link to="{{Global.API_REF_SIG_WEB}}#event-listeners">Event Listeners</Link>
+
+</PlatformWrapper>
+

assets/code/signaling/authentication-workflow/join-stream-channel.mdx

@@ -0,0 +1,99 @@
+Create a stream channel using the channel name and call `join` with the RTC token.
+
+<PlatformWrapper platform='android'>
+
+    ```kotlin
+    fun joinStreamChannel(channelName: String): Int {
+        fetchRTCToken(channelName, 1, object : TokenCallback {
+            override fun onTokenReceived(token: String?) {
+                // Use the received token to log in
+                if (token != null) {
+                    streamChannel = signalingEngine!!.createStreamChannel(channelName)
+                    streamChannel.join(
+                        JoinChannelOptions(token, true, true, true),
+                        object : ResultCallback<Void?> {
+                            override fun onFailure(errorInfo: ErrorInfo?) {
+                                notify("Join stream channel failed:\n" + errorInfo.toString())
+                                isStreamChannelJoined = false
+                            }
+
+                            override fun onSuccess(responseInfo: Void?) {
+                                isStreamChannelJoined = true
+                                mListener?.onSubscribeUnsubscribe(true)
+                                notify("Joined stream channel: $channelName")
+                            }
+                        })
+                }
+            }
+
+            override fun onError(errorMessage: String) {
+                // Handle the error
+                notify("Error fetching token: $errorMessage")
+            }
+        })
+        return 0
+    }
+    ```
+
+    * <Link to="{{Global.API_REF_SIG_ANDROID}}##channeljoinpropsag_platform">join</Link>
+
+</PlatformWrapper>
+
+<PlatformWrapper platform={['ios','macos']}>
+    ```swift
+    func loginStreamChannel(tokenUrl: String, username: String, streamChannel: String) async throws {
+        let token = try await self.fetchToken(
+            from: tokenUrl, username: username,
+            channelName: streamChannel
+        )
+
+        let channel = try self.signalingEngine.createStreamChannel(streamChannel)
+        let joinOption = RtmJoinChannelOption(token: token, features: [.presence])
+        try await channel?.join(with: joinOption)
+    }
+    ```
+    <PlatformWrapper platform="ios">
+    - <Link to="{{Global.SIG2_SDK_API_IOS}}/rtmclientkit/createstreamchannel(_:)">createStreamChannel(_:)</Link>
+    </PlatformWrapper>
+    <PlatformWrapper platform="macos">
+    - <Link to="{{Global.SIG2_SDK_API_MACOS}}/rtmclientkit/createstreamchannel(_:)">createStreamChannel(_:)</Link>
+    </PlatformWrapper>
+</PlatformWrapper>
+
+<PlatformWrapper platform = 'web'>
+
+    ```javascript
+    const streamChannelJoinAndLeave = async function (
+      isStreamChannelJoined,
+      uid,
+      streamChannelName
+    ) {
+      const token = await fetchRTCToken(uid, streamChannelName);
+      if (getSignalingStreamChannel() === null) {
+        streamChannel = await signalingManager
+          .getSignalingEngine()
+          .createStreamChannel(streamChannelName); // creates a stream channel
+      }
+
+      if (isStreamChannelJoined === false) {
+        await streamChannel
+          .join({
+            token: token,
+            withPresence: true,
+          })
+          .then((response) => {
+            console.log(response);
+          });
+      } else {
+        streamChannel.leave().then((response) => {
+          console.log(response);
+          messageCallback("Left the channel: " + streamChannelName);
+          streamChannel = null;
+        });
+      }
+    };
+    ```
+
+    * <Link to="{{Global.API_REF_SIG_WEB}}##channeljoinpropsag_platform">join</Link>
+</PlatformWrapper>
+

assets/code/signaling/authentication-workflow/login.mdx

@@ -0,0 +1,61 @@
+<PlatformWrapper platform='android'>
+
+    ```kotlin
+    fun loginWithToken(uid: Int): Int {
+        return if (isValidURL(serverUrl)) { // A valid server url is available
+            // Fetch a token from the server for the specified uid
+            fetchRTMToken(uid, object : TokenCallback {
+                override fun onTokenReceived(token: String?) {
+                    // Use the received token to log in
+                    if (token != null) login(uid, token)
+                }
+
+                override fun onError(errorMessage: String) {
+                    // Handle the error
+                    notify("Error fetching token: $errorMessage")
+                }
+            })
+            0
+        } else { // use the uid and token from the config.json file
+            val defaultUid = config!!.optString("uid").toInt()
+            val token = config!!.optString("token")
+            login(defaultUid, token)
+        }
+    }
+    ```
+
+    * <Link to="{{Global.API_REF_SIG_ANDROID}}#configloginpropsag_platform">login</Link>
+</PlatformWrapper>
+
+<PlatformWrapper platform={['ios','macos']}>
+    ```swift
+    func loginMessageChannel(tokenUrl: String, username: String) async throws {
+        let token = try await self.fetchToken(
+            from: tokenUrl, username: username
+        )
+
+        try await self.signalingEngine.login(byToken: token)
+    }
+    ```
+
+    <PlatformWrapper platform="ios">
+    - <Link to="{{Global.SIG2_SDK_API_IOS}}/rtmclientkit/login(bytoken:)">login(byToken:)</Link>
+    - <Link to="{{Global.SIG2_SDK_API_IOS}}/rtmclientkit/login(bytoken:completion:)">login(byToken:completion:)</Link>
+    </PlatformWrapper>
+    <PlatformWrapper platform="macos">
+    - <Link to="{{Global.SIG2_SDK_API_MACOS}}/rtmclientkit/login(bytoken:)">login(byToken:)</Link>
+    - <Link to="{{Global.SIG2_SDK_API_MACOS}}/rtmclientkit/login(bytoken:completion:)">login(byToken:completion:)</Link>
+    </PlatformWrapper>
+</PlatformWrapper>
+<PlatformWrapper platform = 'web'>
+
+    ``` javascript
+    const fetchTokenAndLogin = async (uid) => {
+      const token = await fetchToken(uid);
+      signalingManager.login(uid, token);
+    };
+    ```
+
+    * <Link to="{{Global.API_REF_SIG_WEB}}#configloginpropsag_platform">login</Link>      
+</PlatformWrapper>
+

assets/code/signaling/authentication-workflow/renew-token.mdx

@@ -0,0 +1,67 @@
+    You persist the existing session by retrieving a fresh token and calling `renewToken`.
+<PlatformWrapper platform='android'>
+
+    ```kotlin
+    protected fun handleTokenExpiry() {
+        notify("Token is about to expire")
+        // Fetch a new token
+        fetchToken(object : TokenCallback {
+            override fun onTokenReceived(token: String?) {
+                // Use the token to renew authentication
+                signalingEngine!!.renewToken(token, object: ResultCallback<Void?> {
+                    override fun onFailure(errorInfo: ErrorInfo?) {
+                        notify("Failed to renew token")
+                    }
+
+                    override fun onSuccess(responseInfo: Void?) {
+                        notify("Token renewed")
+                    }
+                })
+            }
+
+            override fun onError(errorMessage: String) {
+                // Handle the error
+                notify("Error fetching token: $errorMessage")
+            }
+        })
+    }
+    ```
+
+</PlatformWrapper>
+
+<PlatformWrapper platform={['ios','macos']}>
+    ```swift
+    public func rtmKit(_ rtmClient: RtmClientKit, tokenPrivilegeWillExpire channel: String?) {
+        Task {
+            let token = try await self.fetchToken(from: self.tokenUrl, username: self.userId)
+            try await signalingEngine.renewToken(token)
+        }
+    }
+    ```
+
+    <PlatformWrapper platform="ios">
+    - <Link to="{{Global.SIG2_SDK_API_IOS}}/rtmclientdelegate/rtmkit(_:tokenprivilegewillexpire:)-3d6ke">rtmKit(_:tokenPrivilegeWillExpire:)</Link>
+    - <Link to="{{Global.SIG2_SDK_API_IOS}}/rtmclientkit/renewtoken(_:)">renewToken(_:)</Link>
+    - <Link to="{{Global.SIG2_SDK_API_IOS}}/rtmclientkit/renewtoken(_:completion:)">renewToken(_:completion:)</Link>
+    </PlatformWrapper>
+    <PlatformWrapper platform="macos">
+    - <Link to="{{Global.SIG2_SDK_API_MACOS}}/rtmclientdelegate/rtmkit(_:tokenprivilegewillexpire:)-3d6ke">rtmKit(_:tokenPrivilegeWillExpire:)</Link>
+    - <Link to="{{Global.SIG2_SDK_API_MACOS}}/rtmclientkit/renewtoken(_:)">renewToken(_:)</Link>
+    - <Link to="{{Global.SIG2_SDK_API_MACOS}}/rtmclientkit/renewtoken(_:completion:)">renewToken(_:completion:)</Link>
+    </PlatformWrapper>
+</PlatformWrapper>
+
+<PlatformWrapper platform = 'web'>
+
+    ``` javascript
+      const renewToken = async (uid) => {
+        const token = await fetchToken(uid);
+        const result = await signalingManager
+          .getSignalingEngine()
+          .renewToken(token);
+        messageCallback("Token was about to expire so it was renewed...");
+      };
+    ```
+
+</PlatformWrapper>
+

assets/code/signaling/authentication-workflow/retrieve-rtc-token.mdx

@@ -0,0 +1,80 @@
+<PlatformWrapper platform='android'>
+
+    ```kotlin
+    fun fetchRTCToken(channelName: String, role: Int, callback: TokenCallback) {
+        // Fetches the RTC token for stream channels
+        val urlString = "$serverUrl/rtc/$channelName/$role/uid/$localUid/?expiry=$tokenExpiryTime"
+        fetchToken(urlString, callback)
+    }
+    ```
+
+</PlatformWrapper>
+
+<PlatformWrapper platform={['ios','macos']}>
+    ```swift
+    func loginStreamChannel(
+        tokenUrl: String, username: String, streamChannel: String
+    ) async throws {
+        let token = try await self.fetchToken(
+            from: tokenUrl, username: username, channelName: streamChannel
+        )
+
+        let channel = try self.signalingEngine.createStreamChannel(streamChannel)
+        let joinOption = RtmJoinChannelOption(token: token, features: [.presence])
+        try await channel?.join(with: joinOption)
+    }
+    ```
+
+    <PlatformWrapper platform="ios">
+    - <Link to="{{Global.SIG2_SDK_API_IOS}}/rtmclientkit/createstreamchannel(_:)">createStreamChannel(_:)</Link>
+    - <Link to="{{Global.SIG2_SDK_API_IOS}}/rtmjoinchanneloption">RtmJoinChannelOption</Link>
+    - <Link to="{{Global.SIG2_SDK_API_IOS}}/rtmstreamchannel/join(with:)">join(with:)</Link>
+    - <Link to="{{Global.SIG2_SDK_API_IOS}}/rtmstreamchannel/join(with:completion:)">join(with:completion:)</Link>
+    </PlatformWrapper>
+    <PlatformWrapper platform="macos">
+    - <Link to="{{Global.SIG2_SDK_API_MACOS}}/rtmclientkit/createstreamchannel(_:)">createStreamChannel(_:)</Link>
+    - <Link to="{{Global.SIG2_SDK_API_MACOS}}/rtmjoinchanneloption">RtmJoinChannelOption</Link>
+    - <Link to="{{Global.SIG2_SDK_API_MACOS}}/rtmstreamchannel/join(with:)">join(with:)</Link>
+    - <Link to="{{Global.SIG2_SDK_API_MACOS}}/rtmstreamchannel/join(with:completion:)">join(with:completion:)</Link>
+    </PlatformWrapper>
+</PlatformWrapper>
+
+<PlatformWrapper platform = 'web'>
+
+    ```javascript
+    // Fetches an RTC token for stream channels
+    async function fetchRTCToken(uid, channelName) {
+      if (config.serverUrl !== "") {
+        try {
+          const res = await fetch(
+            config.proxyUrl +
+              config.serverUrl +
+              "/rtc/" +
+              channelName +
+              "/" +
+              role +
+              "/uid/" +
+              uid +
+              "/?expiry=" +
+              config.tokenExpiryTime,
+            {
+              headers: {
+                "X-Requested-With": "XMLHttpRequest",
+              },
+            }
+          );
+          const data = await res.text();
+          const json = await JSON.parse(data);
+          console.log("RTC token fetched from server: ", json.rtcToken);
+          return json.rtcToken;
+        } catch (err) {
+          console.log(err);
+        }
+      } else {
+        return config.rtcToken;
+      }
+    }
+    ```
+
+</PlatformWrapper>
+