Merge pull request #85 from AgoraIO-Community/410-update

DocC Tutorial and 4.1.0 Update

AgoraUIKit_iOS.podspec

@@ -26,7 +26,7 @@ Use this Pod to create a video UIKit view that can be easily added to your iOS a
 
   s.static_framework = true
   s.source_files = 'Sources/Agora-Video-UIKit/*'
-  s.dependency 'AgoraRtcEngine_iOS', '~> 4.0.1'
+  s.dependency 'AgoraRtcEngine_iOS', '~> 4.1.0'
   s.dependency 'AgoraRtmControl_iOS', "#{s.version.to_s}"
 
 end

Package.swift

@@ -15,7 +15,7 @@ let package = Package(
         .package(
             name: "AgoraRtcKit",
             url: "https://github.com/AgoraIO/AgoraRtcEngine_iOS",
-            .upToNextMinor(from: Version(4, 0, 1))
+            .upToNextMinor(from: Version(4, 1, 0))
         ),
         .package(
             name: "AgoraRtmKit",

Sources/Agora-Video-UIKit/AgoraUIKit.docc/.swiftlint.yml

@@ -0,0 +1,2 @@
+disabled_rules: 
+  - todo

Sources/Agora-Video-UIKit/AgoraUIKit.docc/AgoraUIKit.md

@@ -29,4 +29,5 @@ agoraView.join(channel: "test", as: .broadcaster)
 
 ### Getting Started
 
+- <doc:/tutorials/TOC>
 - <doc:Quickstart-UIKit>

Sources/Agora-Video-UIKit/AgoraUIKit.docc/Custom Camera.md

@@ -22,7 +22,7 @@ If you want the above code to fallback on other cameras, simply add more cases t
 
 ## Set Video UI Kit Properties
 
-Now you need to add some external video settings with Video UI Kit.
+Now you need to add some external video settings with Video UI Kit, using ``AgoraSettings`` and ``AgoraSettings/externalVideoSettings-swift.property``.
 
 ```swift
 var agSettings = AgoraSettings()

Sources/Agora-Video-UIKit/AgoraUIKit.docc/Resources/code/quickstart-swiftui-01.swift

@@ -0,0 +1,16 @@
+//
+//  quickstart-swiftui.swift
+//  
+//
+//  Created by Max Cobb on 15/12/2022.
+//
+
+import SwiftUI
+import AgoraRtcKit
+import AgoraUIKit
+
+struct ContentView: View {
+
+    var body: some View {
+    }
+}

Sources/Agora-Video-UIKit/AgoraUIKit.docc/Resources/code/quickstart-swiftui-02.swift

@@ -0,0 +1,26 @@
+//
+//  quickstart-swiftui.swift
+//  
+//
+//  Created by Max Cobb on 15/12/2022.
+//
+
+import SwiftUI
+import AgoraRtcKit
+import AgoraUIKit
+
+struct ContentView: View {
+
+    static var agview = AgoraViewer(
+        connectionData: AgoraConnectionData(
+            appId: <#Agora App ID#>
+        ),
+        style: .floating
+    )
+
+    var body: some View {
+        ZStack {
+            ContentView.agview
+        }
+    }
+}

Sources/Agora-Video-UIKit/AgoraUIKit.docc/Resources/code/quickstart-swiftui-03.swift

@@ -0,0 +1,41 @@
+//
+//  quickstart-swiftui.swift
+//  
+//
+//  Created by Max Cobb on 15/12/2022.
+//
+
+import SwiftUI
+import AgoraRtcKit
+import AgoraUIKit
+
+struct ContentView: View {
+
+    static var agview = AgoraViewer(
+        connectionData: AgoraConnectionData(
+            appId: <#Agora App ID#>
+        ),
+        style: .floating
+    )
+
+    @State private var connectedToChannel = false
+
+    var body: some View {
+        ZStack {
+            ContentView.agview
+            if !connectedToChannel {
+                Button(
+                    action: {
+                        // TODO: Add Join Channel Logic
+                        connectedToChannel = true
+                    }, label: {
+                        Text("Connect")
+                            .padding(3.0)
+                            .background(Color.green)
+                            .cornerRadius(3.0)
+                    }
+                )
+            }
+        }
+    }
+}

Sources/Agora-Video-UIKit/AgoraUIKit.docc/Resources/code/quickstart-swiftui-04.swift

@@ -0,0 +1,45 @@
+//
+//  quickstart-swiftui.swift
+//  
+//
+//  Created by Max Cobb on 15/12/2022.
+//
+
+import SwiftUI
+import AgoraRtcKit
+import AgoraUIKit
+
+struct ContentView: View {
+
+    static var agview = AgoraViewer(
+        connectionData: AgoraConnectionData(
+            appId: <#Agora App ID#>
+        ),
+        style: .floating
+    )
+
+    @State private var connectedToChannel = false
+
+    var body: some View {
+        ZStack {
+            ContentView.agview
+            if !connectedToChannel {
+                Button(
+                    action: {
+                        ContentView.agview.join(
+                            channel: "channel-name",
+                            with: <#Temporary Token#>,
+                            as: .broadcaster
+                        )
+                        connectedToChannel = true
+                    }, label: {
+                        Text("Connect")
+                            .padding(3.0)
+                            .background(Color.green)
+                            .cornerRadius(3.0)
+                    }
+                )
+            }
+        }
+    }
+}

Sources/Agora-Video-UIKit/AgoraUIKit.docc/Tutorials/TOC.tutorial

@@ -0,0 +1,13 @@
+@Tutorials(name: "Agora Video UI Kit") {
+    @Intro(title: "Video UI Kit Tutorials") {
+        These tutorials will show you how to use Agora's Video UI Kit.
+    }
+
+    @Chapter(name: "Getting Started with SwiftUI") {
+        @Image(source: agora-x-swiftui, alt: "Agora + SwiftUI Logo")
+
+        The basics of using Agora Video UI Kit with a SwiftUI Application
+
+        @TutorialReference(tutorial: "doc:UsingSwiftUI")
+    }
+}

Sources/Agora-Video-UIKit/AgoraUIKit.docc/Tutorials/UsingSwiftUI.tutorial

@@ -0,0 +1,60 @@
+@Tutorial(time: 5) {
+    @Intro(title: "Agora UI Kit + SwiftUI") {
+        How to get started with Agora's Video UI Kit in SwiftUI
+
+        @Image(source: agora-uikit-banner, alt: "Video UI Kit Banner Image")
+    }
+
+    @Section(title: "Create a Video Viewer") {
+        @ContentAndMedia {
+            Let's make a SwiftUI Video Call App!
+
+            After creating a new SwiftUI project with Xcode, you must add the Swift Package of Agora Video UI Kit using this URL:
+            `https://github.com/AgoraIO-Community/VideoUIKit-iOS`
+
+            And add camera and microphone permissions to your Info.plist:
+
+            @Image(source: quickstart-swiftui-permissions, alt: "A screenshot showing the Camera and Microphone permissions in Info.plist")
+
+        }
+
+        @Steps {
+            @Step {
+                Import Agora's Video UI Kit, as well as the core RTC Kit. 
+
+                @Code(name: Quickstart-SwiftUI.swift, file: quickstart-swiftui-01.swift)
+            }
+
+            @Step {
+                Create an ``AgoraUIKit/AgoraViewer`` as a static variable on your ContentView struct. This uses the initialisers, ``AgoraUIKit/AgoraViewer/init(connectionData:style:agoraSettings:delegate:)`` and ``AgoraUIKit/AgoraConnectionData/init(appId:rtcToken:rtmToken:idLogic:)``, with the App ID from your [Agora Console](https://console.agora.io).
+
+                Add the newly created ``AgoraUIKit/AgoraViewer`` to your body inside of a ZStack.
+
+                @Code(name: Quickstart-SwiftUI.swift, file: quickstart-swiftui-02.swift) {
+                    @Image(source: quickstart-swiftui-button.png, alt: "A screenshot of the SwiftUI View with just a button visible")
+                }
+            }
+
+            @Step {
+                We still need to call the method ``AgoraUIKit/AgoraViewer/join(channel:with:as:mediaOptions:)`` in order to join an Agora Channel. To do so, let's first add a button to the ZStack.
+
+                The button appears ontop of the ``AgoraUIKit/AgoraViewer``, and once tapped will disappear from the view
+
+                @Code(name: Quickstart-SwiftUI.swift, file: quickstart-swiftui-03.swift) {
+                    @Image(source: quickstart-swiftui-button.png, alt: "A screenshot of the SwiftUI View with just a button visible")
+                }
+            }
+
+            @Step {
+                Finally, call the ``AgoraUIKit/AgoraViewer/join(channel:with:as:mediaOptions:)`` function in the Button action to join the Agora Video Channel.
+
+                For the temporary token, you can put `nil` in there if your project is still in testing and does not require a token. Otherwise create a temporary token from the [Agora Console](https://console.agora.io).
+
+                @Code(name: Quickstart-SwiftUI.swift, file: quickstart-swiftui-04.swift) {
+                    @Image(source: quickstart-swiftui-videoview, alt: "A screenshot of the SwiftUI View with just a button visible")
+                }
+            }
+
+        }
+    }
+}

Sources/Agora-Video-UIKit/AgoraUIKit.swift

@@ -22,7 +22,7 @@ public struct AgoraUIKit: Codable {
     /// Framework type of UIKit. "native", "flutter", "reactnative"
     public fileprivate(set) var framework: String
     /// Version of UIKit being used
-    public static let version = "4.0.3"
+    public static let version = "4.0.5"
     /// Framework type of UIKit. "native", "flutter", "reactnative"
     public static let framework = "native"
     #if os(iOS)

Sources/Agora-Video-UIKit/AgoraVideoViewer+AgoraRtcEngineDelegate.swift

@@ -13,10 +13,12 @@ extension AgoraVideoViewer: AgoraRtcEngineDelegate {
     ///   - engine: AgoraRtcEngine of this session.
     ///   - oldRole: Previous role of the user.
     ///   - newRole: New role of the user.
+    ///   - newRoleOptions: The client role option of the new role.
     open func rtcEngine(
         _ engine: AgoraRtcEngineKit,
         didClientRoleChanged oldRole: AgoraClientRole,
-        newRole: AgoraClientRole
+        newRole: AgoraClientRole,
+        newRoleOptions: AgoraClientRoleOptions?
     ) {
         let isHost = newRole == .broadcaster
         if !isHost {
@@ -31,7 +33,11 @@ extension AgoraVideoViewer: AgoraRtcEngineDelegate {
         #if canImport(AgoraRtmControl)
         self.broadcastPersonalData()
         #endif
-        self.agoraSettings.rtcDelegate?.rtcEngine?(engine, didClientRoleChanged: oldRole, newRole: newRole)
+
+        self.agoraSettings.rtcDelegate?.rtcEngine?(
+            engine, didClientRoleChanged: oldRole,
+            newRole: newRole, newRoleOptions: newRoleOptions
+        )
     }
 
     /// New User joined the channel

Sources/Agora-Video-UIKit/AgoraVideoViewer+JoinChannel.swift

@@ -79,8 +79,9 @@ extension AgoraVideoViewer {
     ///   - role: [AgoraClientRole](https://docs.agora.io/en/Video/API%20Reference/oc/Constants/AgoraClientRole.html) to join the channel as. Default: `.broadcaster`
     ///   - uid: UID to be set when user joins the channel, default will be 0.
     ///   - mediaOptions: Media options such as custom audio/video tracks, subscribing options etc.
-    /// - Returns: `Int32?` representing Agora's joinChannelByToken response. If response is `nil`,
-    ///            that means it has continued on another thread, or you area already in the channel.
+    /// - Returns: An integer representing Agora's joinChannelByToken response. If response is `nil`,
+    ///            that means it has continued on another thread due to requesting camera/mic permissions,
+    ///            or you area already in the channel. If the response is 0, everything is fine.
     @discardableResult
     public func join(
         channel: String, with token: String?,

Sources/Agora-Video-UIKit/AgoraVideoViewer+RtcEngineDelegateOverflow.swift

@@ -138,8 +138,14 @@ extension AgoraVideoViewer {
     open func rtcEngine(_ engine: AgoraRtcEngineKit, rtmpStreamingChangedToState url: String, state: AgoraRtmpStreamingState, errCode: AgoraRtmpStreamingErrorCode) {
         self.agoraSettings.rtcDelegate?.rtcEngine?(engine, rtmpStreamingChangedToState: url, state: state, errCode: errCode)
     }
-    open func rtcEngine(_ engine: AgoraRtcEngineKit, didApiCallExecute error: Int, api: String, result: String) {
-        self.agoraSettings.rtcDelegate?.rtcEngine?(engine, didApiCallExecute: error, api: api, result: result)
+//    open func rtcEngine(_ engine: AgoraRtcEngineKit, didApiCallExecute error: Int, api: String, result: String) {
+//        self.agoraSettings.rtcDelegate?.rtcEngine?(engine, didApiCallExecute: error, api: api, result: result)
+//    }
+    open func rtcEngine(_ engine: AgoraRtcEngineKit, licenseValidationFailure error: AgoraLicenseVerifyCode) {
+        self.agoraSettings.rtcDelegate?.rtcEngine?(engine, licenseValidationFailure: error)
+    }
+    open func rtcEngine(_ engine: AgoraRtcEngineKit, audioMixingPositionChanged position: Int) {
+        self.agoraSettings.rtcDelegate?.rtcEngine?(engine, audioMixingPositionChanged: position)
     }
     open func rtcEngine(_ engine: AgoraRtcEngineKit, didRejoinChannel channel: String, withUid uid: UInt, elapsed: Int) {
         self.agoraSettings.rtcDelegate?.rtcEngine?(engine, didRejoinChannel: channel, withUid: uid, elapsed: elapsed)

Sources/Agora-Video-UIKit/AgoraViewer.swift

@@ -53,15 +53,20 @@ public struct AgoraViewer: UIViewRepresentable {
         )
     }
 
+    @discardableResult
     /// Join the Agora channel
     /// - Parameters:
     ///   - channel: Channel name to join.
     ///   - token: Valid token to join the channel.
     ///   - role: AgoraClientRole to join the channel as. Default: .broadcaster.
     ///   - mediaOptions: Media options such as custom audio/video tracks, subscribing options etc.
+    /// - Returns: An integer representing Agora's joinChannelByToken response. If response is `nil`,
+    ///            that means it has continued on another thread due to requesting camera/mic permissions,
+    ///            or you area already in the channel. If the response is 0, everything is fine.
     public func join(
         channel: String, with token: String?, as role: AgoraClientRole,
-        mediaOptions: AgoraRtcChannelMediaOptions? = nil) {
+        mediaOptions: AgoraRtcChannelMediaOptions? = nil
+    ) -> Int32? {
         self.viewer.join(channel: channel, with: token, as: role, mediaOptions: mediaOptions)
     }
 }