iOS 集成方法

1 前言

在您阅读此文档时，我们假定您已经具备了基础的 iOS 应用开发经验，并能够理解相关基础概念。

1.1 环境准备

请到拓课官方网站下载 TKLiveSDK iOS 版。 如果您打算使用拓课公网服务器，使用 DEMO 里填写的默认参数即可进入教室；

1.2 版本兼容

兼容 iOS 12 及以上版本。

2 工程设置

2.1 Xcode Version 13+

2.2 导入 Framework:

添SDK 到 TARGETS -> Framework,Lbraries,and Embedded Content 下的 Embed 属性都设置为 Embed&Sign。 TKRoomSDK.framework、 TKWhiteBoard.framework、 TKLiveSDK.framework、 TKExtension.framework(V1.7.0及之后版本) 。

2.3 Info.plist 文件的设置

添加权限申请及相应文本

Privacy - Camera Usage Description
Privacy - Microphone Usage Description
Privacy - Photo Library Additions Usage Description
Privacy - Photo Library Usage Description
Privacy - Location When In Use Usage Description

2.4 添加第三方库

必要(V1.7.0及之后) 
#腾讯播放器 //需注册腾讯播放器licence,否则无法使用
pod 'TXLiteAVSDK_Player'

2.5 http 请求

App Transport Security Settings Allow Arbitrary Loads YES

2.6 uild Settings 设置项

Enable Bitcode : NO
User-Defined : arm64
OTHER_LDFLAGS : 加入 -ObjC

2.7 外部链接打开

app 的 url schemes
targets -> info -> URL Types
添加 协议头 enterroomnew（添加此协议头后 在浏览器点击特定链接才可以打开 app，此协议头可和后端协商自定义，enterroomnew 为拓客云默认协议头）

3 AppDelegate.m 文件的配置

3.1 引入头文件

# import <TKLiveSDK/TKLiveSDK.h>

3.2 回调方法里加入对应的方法：

- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
    // 加载自定义的loadingGIF图，key值为 企业的authkey。
    // 不调用此方法，或者key值传空，加载默认的GIF图。
    [[TLAPPSetConfig shareInstance] roomLoadingImageWithPath:@""];
    //注册腾讯播放器Licence (V1.7.0之后)
    [[TLTxLiveSetting shareInstance] registerTxLicenceKey:@"LicenceKEY" licenceURL:@"licenceURL"];
    详见DEMO
}
- (BOOL)application:(UIApplication *)app openURL:(NSURL *)url options:(NSDictionary<UIApplicationOpenURLOptionsKey,id> *)options {
    // 添加通过链接跳转APP的方法
    [[TLEduClassManager shareInstance] joinRoomWithUrl:url.relativeString];
}
-(void)applicationWillTerminate:(UIApplication *)application {
    // 在程序被kill的时候，添加退出房间的方法
    [[TLEduClassManager shareInstance] leaveRoom];
}
-(void)applicationDidBecomeActive:(UIApplication *)application {
    // 添加用于恢复数据的方法
    [[TLEduClassManager shareInstance] applicationDidBecomeActive];
}

4 SDK 使用说明

TKLiveSDK.framework提供了所有的直播间功能;

TKWhiteBoard.framework 提供了所有的白板功能;

TKRoomSDK.framework 提供音视频流的传输、信令的传递以及重要功能逻辑的实现。

TKExtension.framework 为工具类;

将以上 framework 引入工程

5 TKLiveSDK.framework

5.1 TLAPPSetConfig 类主要提供了进入教室前的配置信息的接口。

5.2 TLEduRoomDelegate 类提供了进入教室的一些回调，可根据自己的需求使用。

5.3 TLEduClassManager 类提供了以下的方法:

a.进入房间的方法:

/// 进入房间的函数
/// @param paramDic NSDictionary类型，键值需要传递
/// serial（NSString * 课堂号）、
/// userrole(NSNumber * 学生 2,老师 0,旁听生 6, 巡课 4)、
/// nickname（NSString * 用户昵称）、
/// userid(NSString * 用户ID，选填)、
/// password(NSString * 密码 有则传)、
/// norecord(是否不录制当前用户视频 0,录制 1,不录制),
/// 桌面共享:bundleid (桌面共享进程的bundleid,为空视为无共享功能) 、groupid (桌面共享的appGroupid)
/// @param controller 当前页面的控制器，通常与下边delegate相同
/// @param delegate 遵循TKEduEnterClassRoomDelegate代理，供给用户进行处理
/// @param isFromWeb 是否是从网址链接进入进入
/// @return 是否成功 0 成功 其他失败

- (int)joinRoomWithParamDic:(NSDictionary*)paramDic ViewController:(UIViewController*)controller Delegate:(id<TLEduRoomDelegate>)delegate isFromWeb:(BOOL)isFromWeb;

b.进入 mp4 回放 :

/// 播放MP4回放
/// @param vc 控制器用于弹出播放页面
/// @param path 视频路径
-(void)playVideo:(UIViewController *)vc path:(NSString *)path;

/// MP4续播
/// @param path MP4回放地址
/// @param controller 代理
/// @param skipTime 时间点 (选填 可传" ")
/// @param breakurl breakurl (选填 可传" ")
- (void)joinRoomWithPlaybackPath:(NSString*)path ViewController:(UIViewController*)controller skipTime:(NSString *)skipTime breakurl:(NSString *)breakurl;

c.展示设备检测页面:

/// 展示设备检测页面
/// @param vc 控制器用于弹出设备检测页面
-(void)showDeviceStatusCheck:(UIViewController *)vc;

*TKWhiteBoard.framework 和 TKRoomSDK.framework 已在 TKLiveSDK.framework 中调用,除非有特定需求,否则无需额外调用。

6 插件-友盟分享（可选）

添加分享功能（友盟）

（1） pod 集成友盟插件

pod 'UMCommon', '7.2.5'
pod 'UMShare/UI', '6.10.1'
# 微信完整版
pod 'UMShare/Social/WeChat', '6.10.1'

/// QQ 新浪 暂未开通
# 集成QQ/QZone/TIM(完整版7.6M)
pod 'UMShare/Social/QQ', '6.10.1'
# 集成新浪微博(完整版25.3M)
pod 'UMShare/Social/Sina', '6.10.1'

（2）添加文件 将 demo 中 TKUIDEMO -> PluginClass 文件夹添加到工程中

（3）添加代码（需要提前准备 友盟、微信等平台账号，并填写相关信息获取 相关参数）（相关问题可以自行百度）

- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {

    // 添加
    [self addTKSharePlugin];

    return YES;
}

- (void) addTKSharePlugin {

    // 友盟分享（如果使用需要完成以下内容）
    // 1 pod 集成相关UM库（参考podfile）
    // 2 在 UM 和 微信 平台创建账号并申请权限（当前版本只支持分享到微信好友和朋友圈）并完成相关配置
    // 3 填写 TKUMShareSettings 分享内相关宏定义的值.   APP启动时调用 [TKUMShareSettings UMShareSettings] 初始化分享，
    [TKUMShareSettings UMShareSettings];

    // 进入教室前 设置分享回调
    _sharePlugin = [[TK_SharePlugin alloc] init];
    [[TKAPPSetConfig shareInstance] registerSharePlusin:_sharePlugin];
}

-(BOOL)application:(UIApplication *)app openURL:(NSURL *)url options:(NSDictionary<UIApplicationOpenURLOptionsKey,id> *)options{

    if ([url.relativeString containsString:@"enterroomnew://"]) {
        [[TKEduClassManager shareInstance] joinRoomWithUrl:url.relativeString];
        [TKEduClassManager shareInstance].isUrlOpen = YES;//记录外部链接打开
    } else {
#if __has_include(<UMShare/UMShare.h>)
        //6.3的新的API调用，是为了兼容国外平台(例如:新版facebookSDK,VK等)的调用[如果用6.2的api调用会没有回调],对国内平台没有影响
        BOOL result = [[UMSocialManager defaultManager]  handleOpenURL:url options:options];
        if (result == NO) {

        }
        return result;
#else
#endif
    }
    return YES;
}

#if __has_include(<UMShare/UMShare.h>)
- (BOOL)application:(UIApplication *)application continueUserActivity:(NSUserActivity *)userActivity restorationHandler:(void (^)(NSArray<id<UIUserActivityRestoring>> * _Nullable))restorationHandler {

    if (![[UMSocialManager defaultManager] handleUniversalLink:userActivity options:nil]) {
        // 其他SDK的回调
    }
    return YES;
}
#else
#endif

（4）工程配置 配置 Universal Link （有疑问可自行百度）

（5） 拓课云后台配置分享内容 （icon、url、text 等），配置好后创建的教室将携带相关信息，原有教室不携带。

7 屏幕旋转问题处理

一、原 app 仅支持竖屏模式

TARGETS -> General -> Deployment Info -> Device Orientation 勾选 Portrait、 Landscape Left、Landscape Right。

二、 原 app 支持旋转

1、AppDelegate.h 中添加

+ (AppDelegate *) appDelegate;

@property (nonatomic, assign) BOOL isTalkCloudTimes;

2、AppDelegate.m 中添加

+ (AppDelegate *) appDelegate {
  return (AppDelegate *)[UIApplication sharedApplication].delegate;
}

- (UIInterfaceOrientationMask)application:(UIApplication *)application supportedInterfaceOrientationsForWindow:(UIWindow *)window {

  if (self.isTalkCloudTimes == YES) {
    return UIInterfaceOrientationMaskLandscapeRight | UIInterfaceOrientationMaskLandscapeLeft;
  }

  // demo 登陆页 支持左右横屏(此处根据自己工程实际需要做本地化修改)
    return UIInterfaceOrientationMaskAll;
}

3、进入教室处 添加

（1）调用 joinRoomWithParamDic 方法前添加代码

[AppDelegate appDelegate].isTalkCloudTimes = YES;

（2） TLEduRoomDelegate 代理中加入代码

- (void)onEnterRoomFailed:(int)result Description:(NSString*)desc {

  if (result == 0 && [desc isEqualToString:@"取消"]) {
        [AppDelegate appDelegate].isTalkCloudTimes = NO;
    }
}

- (void)leftRoomComplete {
  [AppDelegate appDelegate].isTalkCloudTimes = NO;
}

4、添加后测试过程中，如果退出教室后页面方向错误：

（1）检测 appdelegate 中 自行根据本身项目配置的部分是否正确。

（2）晃动手机。看能使屏幕方向恢复正常。

5、需要晃一下手机才能恢复正常时：（这个和项目有关，不是必须的）

在 代码：

[AppDelegate appDelegate].isTalkCloudTimes = NO;

后调用下面方法：

- (void) setOrientations {
  [[UIDevice currentDevice] setValue:[NSNumber numberWithInt:UIInterfaceOrientationUnknown] forKey:@"orientation"];
  [[UIDevice currentDevice] setValue:[NSNumber numberWithInt:UIInterfaceOrientationPortrait] forKey:@"orientation"];
}

注：第二行的方向为当前页面支持的某一方向

6、本方案 需要所有页面都做页面方向处理

// New Autorotation support.
@property(nonatomic, readonly) BOOL shouldAutorotate API_AVAILABLE(ios(6.0)) API_UNAVAILABLE(tvos);
@property(nonatomic, readonly) UIInterfaceOrientationMask supportedInterfaceOrientations API_AVAILABLE(ios(6.0)) API_UNAVAILABLE(tvos);
// Returns interface orientation masks.
@property(nonatomic, readonly) UIInterfaceOrientation preferredInterfaceOrientationForPresentation API_AVAILABLE(ios(6.0)) API_UNAVAILABLE(tvos);

7 常见问题描述

7.1 进入教室出现错误码

(TLEduRoomDelegate -> - (void)onEnterRoomFailed:(int)result Description:(NSString*)desc;)

错误码	说明
3001	服务器过期
3002	公司被冻结
3003	课堂被删除或过期
4007	课堂不存在
4008	课堂密码错误
4103	课堂人数超限
4110	该课堂需要密码，请输入密码

(在此只列举部分错误码，更详细错误码请参考 TKRoomSDK.framwork 中的 TKRoomDefines 类。)

7.2 获取录制件接口(回放 path 参数获取方式): getrecordlist

请求 URL： https://global.talk-cloud.net/WebAPI/getrecordlist 请求方式：POST

参数：

参数	必选	类型	说明
key	是	String	企业 key
serial	是	String	房间号
thirdroomid	是	String	第三方教室号：和 serial 二选一必填
starttime	否	int	开始时间（时间截：1597852800）
endtime	否	int	结束时间（时间截：1597852800）
recordtype	否	int	返回录制件类型(0 常规，1mp4,2 所有)，默认只返回常规

返回示例

{
    "result": 0,
    "recordlist": [
        {
            "recordid": "1000610044773851543565780miarfiuv",
            "serial": "10044277385",
            "companyid": "100026",
            "recordtitle": "1543565779986",
            "starttime": "1543565780",
            "duration_ms": 1394883,
            "size": "432722377",
            "webhost": "https://local.global.com",
            "recordpath": "/0904754e-f255-4070-8075-c99f517adbb8-1004477385/",
            "state": "0",
            "playpath": "http://local.global.com/replay/1004477385/10006/1543565779986/",
            "https_playpath": "https://local.global.com/replay/1004477385/10006/1543565779986/"
        },
        {
            "recordid": "10108013994234561603071801rtvsdgju",
            "serial": "10044277385",
            "companyid": "100026",
            "recordtitle": "1603071800847",
            "starttime": "1603071801",
            "duration_ms": 2234,
            "size": "1368886",
            "webhost": "https://local.global.com",
            "recordpath": "/700ef742-f37a-4932-a85c-be5e4dcf09bf-1399423456/",
            "state": "0",
            "playpath": "",
            "https_playpath": "",
            "playpath_mp4": "http://record.talk-cloud.net/700ef742-f37a-4932-a85c-be5e4dcf09bf-1399423456/record.mp4",
            "https_playpath_mp4": "https://record.talk-cloud.net/700ef742-f37a-4932-a85c-be5e4dcf09bf-1399423456/record.mp4",
            "playpath_m4a": "",
            "https_playpath_m4a": "",
            "videoplayback_m4a": "",
            "videoplayback_mp4": "https://global.talk-cloud.net/media/1399423456/101080/1603071800847/1/"
        }
    ]
}

返回参数说明

参数	类型	说明
recordlist.recordid	String	录制件 ID
recordlist.serial	String	房间号
recordlist.companyid	String	企业 ID
recordlist.recordtitle	String	录制标题
recordlist.starttime	String	开始时间
recordlist.duration_ms	Int	时长(毫秒)
recordlist.size	String	录制件大小
recordlist.webhost	String	访问域名
recordlist.recordpath	String	录制件路径
recordlist.state	String	录制件状态
recordlist.playpath	String	常规播放地址
recordlist.https_playpath	String	https 常规播放地址
recordlist.playpath_mp4 String	String	MP4 播放地址
recordlist.https_playpath_mp4	String	httpsMP4 播放地址
recordlist.playpath_m4a String	String	M4A 播放地址
recordlist.https_playpath_m4a	String	httpsM4A 播放地址
recordlist.videoplayback_mp4	String	视频播放地址
recordlist.videoplayback_m4a	String	音频播放地址

常规录制件 path 参数拼接方法

获取录制件，生成录制件（recordtype=0 convert = 1） 的时候。调用 getrecordlist 接口去获取 recordpath 播放回放的参数 path global.talk-cloud.net:8081 + recordpath 例： global.talk-cloud.net:8081/bb3ae4f7-1242-4752-a7bb-afe8f3f1ab87-1695310935/

7.3 通过 Cocoapods 导入的第三方库：参考 Podfile 文件. 如果使用到友盟，

SDK 版本需要一致（当前:UMCommon 7.2.5 UMShare 6.10.1）否则会版本冲突导致闪退 SDK 名称需要一致（UMCommon / UMCCommon）

  pod 'UMCommon', '7.2.5'

  pod 'UMShare/UI', '6.10.1'
  # 微信完整版
  pod 'UMShare/Social/WeChat', '6.10.1'
  # 集成QQ/QZone/TIM(完整版7.6M)
  pod 'UMShare/Social/QQ', '6.10.1'
  # 集成新浪微博(完整版25.3M)
  pod 'UMShare/Social/Sina', '6.10.1'

7.4 本地语言简体中文 地区中国大陆 进入教室显示英文问题 添加本地支持支持语言

targets -> Info -> Custom iOS Target Properties
添加 Localizations（类型：Array）
内容： Chinese（traditional）、Chinese(simplified)、English 三项