集成灵动课堂
本文详细介绍如何将灵动课堂集成到你自己的 iOS 项目中。
技术原理
灵动课堂包含以下库:
AgoraClassroomSDK
: 灵动课堂教育场景的胶水层,串联起AgoraEduUI
和AgoraEduCore
。AgoraClassroomSDK
在 GitHub 与 CocoaPods 上开源发布。AgoraEduUI
: 提供灵动课堂教育场景的交互层代码,并包含交互层所使用的文案信息和资源文件。AgoraEduCore
为该层提供灵动课堂中的能力与数据。AgoraEduUI
在 GitHub 与 CocoaPods 上开源发布。AgoraProctorSDK
: 灵动课堂监考场景的胶水层,串联起AgoraProctorUI
和AgoraEduCore
。AgoraProctorSDK
在 GitHub 与 CocoaPods 上开源发布。AgoraProctorUI
: 提供灵动课堂监考场景的交互层代码,并包含交互层所使用的文案信息和资源文件。AgoraEduCore
为该层提供灵动课堂中的能力与数据。AgoraProctorUI
在 GitHub 与 CocoaPods 上开源发布。AgoraEduCore
: 提供灵动课堂中的能力与数据。AgoraEduCore
闭源,以二进制包在 CocoaPods 上发布。Widget
: 包含界面与功能的独立插件,由AgoraClassroomSDK
或AgoraEduCore
注入灵动课堂内。Widget
与Widget
之间,以及与 UI 层中的其他组件都能进行通讯。
下图展示了灵动课堂的架构。
前提条件
下列所介绍的集成方式均需要通过 CocoaPods 进行集成,版本需要为 1.10 或更高版本。
安装后,可以在终端输入以下命令,如果终端能正常打印出版本信息,则表示安装成功:
pod --version
例如,你安装了 1.11.3 版本,则终端会打印如下信息:
1.11.3
教育场景
集成教育场景下灵动课堂(默认)
如果你使用教育场景下灵动课堂,没有修改代码的需求,可参考以下步骤通过 CocoaPods 添加远程依赖,进行集成:
-
用 Xcode 打开你的项目,在项目的
Podfile
文件中添加以下引用: -
在终端中进入到工程目录,执行
pod install
命令安装依赖包。以 2.8.20 为例,安装过程中会打印如下信息: -
通过以下代码导入头文件:
- Swift
- Objective-C
Swiftimport AgoraClassroomSDK_iOS
Objective-Cimport <AgoraClassroomSDK_iOS/AgoraClassroomSDK.h>
-
调用
AgoraClassroomSDK.launch
方法启动教育场景的灵动课堂。示例代码如下:- Swift
- Objective-C
Swiftlet launchConfig = AgoraEduLaunchConfig(userName: userName, // 用户名
userUuid: userUuid, // 用户 ID
userRole: userRole, // 用户角色: 1 为老师,2 为学生
roomName: roomName, // 房间名
roomUuid: roomUuid, // 房间 ID
roomType: roomType, // 房间类型: 0 为 一对一,2 为大班课,4 为小班课
appId: appId, // 声网 App ID
token: token, // 测试环境下,你可以使用临时 Token;生产或安全环境下,强烈建议你使用服务器生成的 Token
startTime: nil, // 课堂开始时间
duration: nil, // 课堂持续时长
region: region, // 区域
mediaOptions: mediaOptions, // 媒体相关配置
userProperties: nil) // 用户自定义属性
AgoraClassroomSDK.setDelegate(self)
AgoraClassroomSDK.launch(launchConfig,
success: successBlock,
failure: failureBlock)Objective-CAgoraEduLaunchConfig *launchConfig = [[AgoraEduLaunchConfig alloc] initWithUserName:userName // 用户名
userUuid:userUuid // 用户 ID
userRole:userRole // 用户角色: 1 为老师,2 为学生
roomName:roomName // 房间名
roomUuid:roomUuid // 房间 ID
roomType:roomType // 房间类型: 0 为 一对一,2 为大班课,4 为小班课
appId:appId // 声网 App ID
token:token // 测试环境下,你可以使用临时 Token;生产或安全环境下,强烈建议你使用服务器生成的 Token
startTime:nil // 课堂开始时间
duration:nil // 课堂持续时长
region:region // 区域
mediaOptions:mediaOptions // 媒体相关配置
userProperties:nil]; // 用户自定义属性
[AgoraClassroomSDK setDelegate:self];
[AgoraClassroomSDK launch:launchConfig
success:successBlock
failure:failureBlock];示例代码中需要传入
token
。你可以使用临时 Token,也可以参考使用 Token 鉴权从服务器生成 token。注意声网提供的客户端临时 Token 生成器仅适用于运行 App 快速测试。在正式环境中,为确保安全,你必须参考使用 Token 鉴权文档,在服务端部署并生成 Token。生成的 token 传入的
userId
需要和launch
方法中传入的参数userUuid
保持一致,否则生成的 token 无效。 -
(可选)自定义教育场景的灵动课堂界面的显示模式(明亮/暗黑)和语言(中文/英文)。
- Swift
- Objective-C
Swiftimport AgoraUIBaseViews /* 导入 AgoraUIBaseViews 库。该库提供自定义显示模式和语言的两个变量:agora_ui_mode 和 agora_ui_language。*/
agora_ui_mode = .agoraLight /* 设置界面显示模式,可设为 agoraLight 或 agoraDark,默认为 agoraLight。 */
agora_ui_language = "zh-Hans" /* 设置界面语言,可设为 "zh-Hans" 或 "en"。如果不设置,界面语言跟随系统语言。 */Objective-C/* 导入 AgoraUIBaseViews 库。该库提供自定义显示模式和语言的两个变量:agora_ui_mode 和 agora_ui_language。*/
#import <AgoraUIBaseViews/AgoraUIBaseView-Swift.h>
agora_ui_mode = AgoraUIModeAgoraLight /* 设置界面显示模式,可设为 AgoraUIModeAgoraLight 或 AgoraUIModeAgoraDark,默认为 AgoraUIModeAgoraLight。*/
agora_ui_language = @"zh-Hans" /* 设置界面语言,可设为 "zh-Hans" 或 "en"。如果不设置,界面语言跟随系统语言。*/ -
调用
AgoraClassroomSDK.exit
方法关闭教育场景的灵动课堂。示例代码如下:- Swift
- Objective-C
SwiftAgoraClassroomSDK.exit()
Objective-C[AgoraClassroomSDK exit];
集成教育场景下灵动课堂并自定义
如需自定义教育场景下灵动课堂,你需要通过 GitHub 下载源码的方式来集成灵动课堂,步骤如下:
-
运行以下命令将 CloudClass-iOS 和 apaas-extapp-ios 项目克隆至本地,可以切换你所需要版本的分支(默认为最新版本的分支):
Shellgit clone https://github.com/AgoraIO-Community/CloudClass-iOS.git
Shellgit clone https://github.com/AgoraIO-Community/apaas-extapp-ios.git
-
通过
git remote add <shortname> <url>
命令为CloudClass-iOS
和apaas-extapp-ios
仓库添加远端仓库,指向你的项目仓库,并将所需的分支推向你的仓库。 -
在你的项目的
Podfile
文件中添加如下依赖,来引用 CloudClass-iOS 仓库中的AgoraClassroomSDK_iOS.podspec
、AgoraEduUI.podspec
和 apaas-extapp-ios 项目中的AgoraWidgets.podspec
以及其它依赖的库。 -
在终端中进入到工程目录,执行
pod install
命令。安装完成后,参照自定义课堂 UI 了解灵动课堂的开源层设计思路,就可以修改源代码来自定义场景了。
监考场景
集成监考场景下灵动课堂
如果你使用监考场景下灵动课堂,没有修改代码的需求,可参考以下步骤通过 CocoaPods 添加远程依赖,进行集成:
-
用 Xcode 打开你的项目,在项目的
Podfile
文件中添加以下引用: -
在终端中进入到工程目录,执行
pod install
命令安装依赖包。以 2.8.20 为例,安装过程中会打印如下信息: -
通过以下代码导入头文件:
- Swift
- Objective-C
Swiftimport AgoraProctorSDK
Objective-Cimport <AgoraProctorSDK/AgoraProctorSDK.h>
-
调用
AgoraProctorSDK.launch
方法启动监考场景的灵动课堂。示例代码如下:- Swift
- Objective-C
Swiftlet launchConfig = AgoraProctorLaunchConfig(userName: userName, // 用户名
userUuid: userUuid, // 用户 ID
userRole: userRole, // 用户角色
roomName: roomName, // 房间名
roomUuid: roomUuid, // 房间 ID
appId: appId, // 声网 App ID
token: token, // 测试环境下,你可以使用临时 Token;生产或安全环境下,强烈建议你使用服务器生成的 Token
region: region, // 区域
mediaOptions: mediaOptions, // 媒体相关配置
userProperties: nil) // 用户自定义属性
let proctor = AgoraProctorSDK(launchConfig,
delegate: self)
proctor.launch(success: successBlock,
failure: failureBlock)Objective-CAgoraProctorLaunchConfig *launchConfig = [[AgoraProctorLaunchConfig alloc] initWithUserName:userName // 用户名
userUuid:userUuid // 用户 ID
userRole:userRole // 用户角色
roomName:roomName // 房间名
roomUuid:roomUuid // 房间 ID
appId:appId // 声网 App ID
token:token // 测试环境下,你可以使用临时 Token;生产或安全环境下,强烈建议你使用服务器生成的 Token
region:region // 区域
mediaOptions:mediaOptions // 媒体相关配置
userProperties:nil]; // 用户自定义属性
AgoraProctorSDK *proctor = [[AgoraProctorSDK alloc] init:launchConfig
delegate:self];
[proctor launch:successBlock
failure:failureBlock];示例代码中需要传入
token
。你可以使用临时 Token,也可以参考使用 Token 鉴权从服务器生成 token。注意声网提供的客户端临时 Token 生成器仅适用于运行 App 快速测试。在正式环境中,为确保安全,你必须参考使用 Token 鉴权文档,在服务端部署并生成 Token。生成的 token 传入的
userId
需要和launch
方法中传入的参数userUuid
保持一致,否则生成的 token 无效。 -
(可选)自定义监考场景的灵动课堂界面的显示模式(明亮/暗黑)和语言(中文/英文)。
- Swift
- Objective-C
Swiftimport AgoraUIBaseViews /* 导入 AgoraUIBaseViews 库。该库提供自定义显示模式和语言的两个变量:agora_ui_mode 和 agora_ui_language。*/
agora_ui_mode = .agoraLight /* 设置界面显示模式,可设为 agoraLight 或 agoraDark,默认为 agoraLight。 */
agora_ui_language = "zh-Hans" /* 设置界面语言,可设为 "zh-Hans" 或 "en"。如果不设置,界面语言跟随系统语言。 */Objective-C/* 导入 AgoraUIBaseViews 库。该库提供自定义显示模式和语言的两个变量:agora_ui_mode 和 agora_ui_language。*/
#import <AgoraUIBaseViews/AgoraUIBaseView-Swift.h>
agora_ui_mode = AgoraUIModeAgoraLight /* 设置界面显示模式,可设为 AgoraUIModeAgoraLight 或 AgoraUIModeAgoraDark,默认为 AgoraUIModeAgoraLight。*/
agora_ui_language = @"zh-Hans" /* 设置界面语言,可设为 "zh-Hans" 或 "en"。如果不设置,界面语言跟随系统语言。*/ -
通过释放 AgoraProctorSDK 对象来关闭监考场景的灵动课堂。示例代码如下:
- Swift
- Objective-C
SwiftproctorSDK = nil
Objective-CproctorSDK = nil;
集成监考场景下灵动课堂并自定义
如需自定义监考场景下灵动课堂,你需要通过下载 GitHub 仓库源码的方式来集成灵动课堂,步骤如下:
-
运行以下命令将 proctor-ios 项目克隆至本地,可以切换你所需要版本的分支(默认为最新版本的分支):
Shellgit clone https://github.com/AgoraIO-Community/proctor-ios.git
-
通过
git remote add <shortname> <url>
命令为proctor-ios
仓库添加远端仓库,指向你的项目仓库,并将所需的分支推向你的仓库。 -
在你的项目的
Podfile
文件中添加如下依赖,来引用 proctor-ios 仓库中的AgoraProctorSDK.podspec
、AgoraProctorUI.podspec
以及其它依赖的库: -
在终端中进入到工程目录,执行
pod install
命令。
安装完成后,参照自定义课堂 UI 了解灵动课堂的开源层设计思路,就可以修改源代码来自定义场景了。
注意事项
集成后在你的项目中的 info.plist
文件里增加 Privacy - Camera Usage Description
、 Privacy - Microphone Usage Description
、 Privacy - Photo Library Additions Usage Description
、 Privacy - Photo Library Usage Description
,以获取在运行灵动课堂时所必要的权限。
在 Xcode 14.0 以后,如果遇到 AgoraEduUI-AgoraEduUI
等 bundle
需要签名的错误,可以在你的 Podfile
中添加下列代码来解决这个报错:
post_install do |installer|
installer.pods_project.targets.each do |target|
target.build_configurations.each do |config|
if target.respond_to?(:product_type) and target.product_type == "com.apple.product-type.bundle"
config.build_settings['CODE_SIGNING_ALLOWED'] = 'NO'
end
end
end
end
在 Xcode 14.0 以后,如果遇到 Symbol not found: (__ZN5swift34swift50override_conformsToProtocol.../Armin.framework/Armin
等报错,可以在你的 Podfile
中添加下列代码来解决这个报错:
low_version_target_names = ["Armin", "YYModel", "Masonry", "NTLBridge", "CocoaLumberjack", "AliyunOSSiOS"]
post_install do |installer|
installer.pods_project.targets.each do |target|
target.build_configurations.each do |config|
if low_version_target_names.include?(target.name)
config.build_settings['IPHONEOS_DEPLOYMENT_TARGET'] = '10.0'
end
end
end
end