当前版本：V1.2.9

苏州必捷网络有限公司

1 概述

1.1 目的

用于指导使用必捷SDK开发iOS发送端应用程序。

1.2 读者对象

本文档适用于iOS发送端应用程序的开发人员和测试人员。

1.3 缩略语定义

缩写名称	英文	中文
BJCast		必捷无线投屏协议

2 范围

2.1 功能

本SDK为BJCast发射端SDK，和BJCast接收端SDK配合进行无线投屏。

本SDK为标准的iOS framework模块，提供objective-c接口供应用集成。

2.2 SDK框架

总体框架分为两层：

SDK层： SDK包含用于Host App SDK和extension App SDK,共计4个framework包。分别为：CocoaAsyncSocket、BJCastFramework、BJCastLiveKitHost和BJCastLiveKitExt。其中BJCastLiveKitHost和CocoaAsyncSocket用于Host App集成，BJCastLiveKitExt、CocoaAsyncSocket和BJCastFramework用于Extension App集成。其中BJCastLiveKitHostframework依赖CocoaAsyncSocket，BJCastLiveKitExtframework依赖CocoaAsyncSocket和 BJCastFramework。
应用层：开发的具体APP应用部分，我司交付的是DEMO APP，具体与客户应用集成，可做针对性开发。用户可用于参考。

2.3 SDK交付物

SDK库
DEMO APP源代码，Demo APP基于最新SDK，作为参考实现提供给客户
SDK接口文档

2.4 版本要求

支持的操作系统： iOS 12 及以上版本

3 接口

3.1 BJCastLiveKitHost接口说明

3.1.1 初始化接口

objectivec

-(BOOL)setupWIthAppGroup:(NSString *)appGroup andConfig:(BJCastLiveHostConfig *_Nullable)config;

描述

设置SDK的初始化参数，在启动时调用。

参数

名称	描述
appGroup	用于Host App和Extension App之间通信的App Group ID
config	初始化参数配置信息，该值可以为空

其中BJCastLiveHostConfig支持以下常用属性的设置：

属性名	描述	必填
hostListenPort	Host App与Extension App通信的Server端监听的端口号，默认为0，在默认值情况下，SDK内部会分配一个随机端口号。	否

返回值：

如果初始化成功，返回YES，否则返回NO。

3.1.2 探测接口

objectivec

-(void)probeDeviceWithIP:(NSString *)deviceIP completion:(void (^)(BJCastRenderInfo * _Nullable deviceInfo,BJCastLiveKitHostProbeError error))completion;

描述

该接口用于探测IP地址对应的接收端是否存在。

参数

名称	描述
deviceIP	接收端IP地址
completion	探测回调block

completionblock将探测结果返回，其中deviceInfo为接收端设备信息，error为探测失败错误码枚举值。deviceInfo和error定义如下：

deviceInfo：

属性名称	描述	类型
deviceName	设备名称	NSString
deviceID	设备ID	NSString
ft	设备能力集	NSString
ipArray	设备IP列表	NSArray<NSString *>

error：

属性名称	描述
BJCastLiveHostProbeError_NonError	探测成功时error返回该值
BJCastLiveHostProbeError_ProbeTimeout	探测超时返回该值，超时时间为5s
BJCastLiveHostProbeError_NoDeviceInfo	探测返回的URL中未包含接收端有效信息时返回该值
BJCastLiveHostProbeError_ProbeFailed	探测失败时返回该值

注意事项：

completion块代码的运行线程不是UI线程，若使用者想要在其中进行UI相关操作请务必将UI相关操作放入主队列中运行。

3.1.3 设置投屏参数接口

objectivec

-(int)setStartRecordConfig:(BJCastLiveHostCastConfig *)config;

描述

设置Externsion App创建投屏会话所需的相关参数。

参数

名称	描述
config	投屏会话相关初始化参数

BJCastLiveHostCastConfig定义如下：

属性名称	描述	类型
ip	接收端IP	NSString
port	接收端会话端口，固定为8190	NSInteger

返回值

如果成功，返回BJCastLiveError_NonError,失败返回负值。返回值的具体含义参见BJCastLiveErrorCode枚举值：

错误码	描述
BJCastLiveError_NonError	函数执行成功的返回值
BJCastLiveError_BuildServerFailed	Host App Server启动失败

参考样例

objectivec

int ret=[[BJCastLiveKitHostInterface shareInstance] setStartRecordConfig:castConfig];
if(ret){
    switch (ret) {
        case BJCastLiveError_BuildServerFailed:
        {
            UIAlertController *alertControl= [UIAlertController alertControllerWithTitle:@"warning" message:@"Failed to build server" preferredStyle:UIAlertControllerStyleAlert];
        }
            break;
                    
        default:
            reak;
    }
    return;
}

注意事项：

该接口必须在Host App启动Extension App之前被调用。启动Extension App的代码如下：

objectivec

 if(@available(iOS 13.0,*)){
    RPSystemBroadcastPickerView *recordView=[[RPSystemBroadcastPickerView alloc] initWithFrame:(CGRect){0, 0, 70, 70}];

    //preferredExtension为Extension的BundleID
    recordView.preferredExtension=@"com.bj.BJNativeLiveIOS.BJNativeLiveIOSBroadcastExtension";
    recordView.showsMicrophoneButton=YES;
    UIButton* recordbutton=[recordView findRecordButton];
    [recordbutton sendActionsForControlEvents:UIControlEventTouchUpInside];
    [recordView setHidden:YES];
}else{
    [self.navigationController pushViewController:self.userGuideController animated:YES];
}

这部分代码应该在主队列中调用。

3.1.4 BJCastLiveKitHost通知接口

objectivec

extern NSString * const BJCastLiveCastSessionConnStatusNotification;
extern NSString * const BJCastLiveHostServerDisconnectedNotification;

extern NSString * const BJCastLiveCastSessionConnStatusKey;

描述

BJCastLiveCastSessionConnStatusNotification为投屏会话连接状态通知。 BJCastLiveHostServerDisconnectedNotification为Host App与Extension App Socket连接断开通知。 BJCastLiveCastSessionConnStatusKey为投屏连接状态userInfo中连接状态的key值。

参考样例

objectivec

//注册通知
[[NSNotificationCenter defaultCenter] addObserver:self selector:@selector(getConnStatus:) name:BJCastLiveCastSessionConnStatusNotification object:nil];
[[NSNotificationCenter defaultCenter] addObserver:self selector:@selector(connServerDisconnect) name:BJCastLiveHostServerDisconnectedNotification object:nil];

//通知处理函数

//处理连接状态方法
-(void)getConnStatus:(NSNotification *)notification
{
    NSDictionary *userInfo=notification.userInfo;
    if(!userInfo){
        return;
    }
    //获取投屏会话连接状态
    BJCastLiveCastSessionConnStatus status=[[userInfo objectForKey:BJCastLiveCastSessionConnStatusKey] longValue];
    NSLog(@"Get Conn status key:%ld",status);
    //处理连接状态，通常是更改UI显示
    if(status==BJCastLiveCastSession_Conn_Connected){
        if(self.selectDeviceModel){
            self.selectDeviceModel.isLive=YES;
        }
        self.recordState=BJRecordStartRecord;
        [self saveSelectDeviceInfo];
    }else{
        if(self.selectDeviceModel){
            self.selectDeviceModel.isLive=NO;
        }
        self.recordState=BJRecordStopRecord;
        [self removeSelectDeviceInfo];
    }
    dispatch_async(dispatch_get_main_queue(), ^{
        [self.deviceListView reloadData];
    });
}

//处理HostApp与Extension App socket连接断开方法，通常此时Extension App已结束其生命周期，Host APP做相应的UI状态修改
-(void)connServerDisconnect
{
    if(self.selectDeviceModel){
        self.selectDeviceModel.isLive=NO;
    }
    self.recordState=BJRecordStopRecord;
    [self removeSelectDeviceInfo];
    
    dispatch_async(dispatch_get_main_queue(), ^{
        [self.deviceListView reloadData];
    });
}

3.2 BJCastLiveKitExt接口说明

3.2.1 setup接口

objectivec

-(void)setupWithAppGroup:(NSString *)appGroup delegate:(id<BJCastLiveKitDelegate>)delegate;

描述

该接口在SampleHandler的- (void)broadcastStartedWithSetupInfo:(NSDictionary<NSString *,NSObject *> *)setupInfo 方法中被调用，用于初始化Extension SDK。

参数

名称	描述
appGroup	用于Host App和Extension App之间通信的App Group ID
delegate	Extension委托对象，使用者应在`SampleHandler`实现该委托并将`SampleHandler`作为参数传入，有关`BJCastLiveKitDelegate`相关信息请参照`BJCastLiveKitDelegate`委托接口说明

3.2.2 暂停接口

objectivec

-(void)broadcastPaused;

描述

该接口在SampleHandler的- (void)broadcastPaused方法中被调用。

3.2.3 恢复接口

objectivec

-(void)broadcastResumed;

描述

该接口在SampleHandler的- (void)broadcastResumed方法中被调用。

3.2.4 结束接口

objectivec

-(void)broadcastFinished;

描述

该接口在SampleHandler的- (void)broadcastFinished方法中被调用。

3.2.5 处理录制数据接口

objectivec

-(void)processSampleBuffer:(CMSampleBufferRef)sampleBuffer withType:(RPSampleBufferType)type;

描述

该接口在SampleHandler的-- (void)processSampleBuffer:(CMSampleBufferRef)sampleBuffer withType:(RPSampleBufferType)sampleBufferType方法中被调用，用于处理ReplayKit录制到的媒体数据。

3.2.6 `BJCastLiveKitDelegate`委托结束接口

objectivec

-(void)broadcastFinishedWithReason:(BJCastLiveKitReason)reason;
@optional

描述

该接口在投屏会话结束时被调用，告知委托方投屏结束的原因。

参数

名称	描述
reason	投屏会话结束原因code

BJCastLiveKitReason的定义如下：

名称	描述
BJCastLiveKitReasonDisconnectedWithMain	Host App与Extension App soeckt连接中断
BJCastLiveKitReasonEndByMain	Host App 主动关闭投屏会话
BJCastLiveKitReasonEncodeFrameFailed	视频编码失败
BJCastLiveKitReasonEncodeSessionFailed	视频编码会话出现错误
BJCastLiveKitReasonSessionNetworkFailed	投屏会话结束，网络异常
BJCastLiveKitReasonSessionKickedOut	投屏会话结束，接收端踢出投屏
BJCastLiveKitReasonSessionFailed	投屏会话失败
BJCastLiveKitReasonSessionInitFailed	投屏会话创建失败
BJCastLiveKitReasonSessionEnd	投屏会话正常结束
BJCastLiveKitReasonSessionNoScreenReasource	投屏会话结束，超出接收端投屏数量上限
BJCastLiveKitReasonSessionHeartbeatLost	投屏会话结束,投屏会话心跳丢失严重
BJCastConnectSessionFailedCallReject	投屏会话结束，接收端拒绝投屏，在接收端投屏显示路数设置为1时发射端会收到该错误码

4 客户如何使用SDK

4.1 集成简要说明

iOS 端基于苹果提供的 Replaykit 框架实现屏幕录制，可以分享整个系统的屏幕内容。但由于苹果的隐私设置，不同 App 之间数据无法互通，因此需要当前 App（主 App 进程）额外提供一个 Extension 扩展组件（Extension 进程），并且把 App 和 Extension 配置为同一 App Group（有关 app group的相关配置请参考文档Configuring App Groups | Apple Developer Documentation），让 Extension 录屏进程可以同主 App 进程进行跨进程通信，实现屏幕内容分享。以下是简要集成步骤，详细配置请参考demo代码工程。

步骤一：创建 App Group

为使 Extension 录屏进程可以和主 App 进程进行跨进程通信，需要将 Extension 和 App 配置为同一 App Group。

步骤二：创建 Extension 扩展组件

新建 Broadcast Upload Extension 组件并进行相关配置。

在 Xcode 中，点击 File > New > Target...，在弹出对话框中选择 Broadcast Upload Extension，点击 Next。

步骤三：在 Extension 组件集成`BJCastLiveKitExt`SDK

集成BJCastLiveKitExt、CocoaAsyncSocket和BJCastFramework并在SampleHandler中调用BJCastLiveKitExt接口,实现屏幕采集和投屏相关逻辑。

步骤四：在Host App工程中集成`BJCastLiveKitHost`SDK

Host APP工程集成BJCastLiveKitHost和CocoaAsyncSocket,将ios_enc_scene_def.json文件作为资源文件集成。Host App调用BJCastLiveKitHost接口，实现与Extension App进行通信的目的。

1 概述 ​

1.1 目的 ​

1.2 读者对象 ​

1.3 缩略语定义 ​

2 范围 ​

2.1 功能 ​

2.2 SDK框架 ​

2.3 SDK交付物 ​

2.4 版本要求 ​

3 接口 ​

3.1 BJCastLiveKitHost接口说明 ​

3.1.1 初始化接口 ​

3.1.2 探测接口 ​

3.1.3 设置投屏参数接口 ​

3.1.4 BJCastLiveKitHost通知接口 ​

3.2 BJCastLiveKitExt接口说明 ​

3.2.1 setup接口 ​

3.2.2 暂停接口 ​

3.2.3 恢复接口 ​

3.2.4 结束接口 ​

3.2.5 处理录制数据接口 ​

3.2.6 BJCastLiveKitDelegate委托 结束接口 ​

4 客户如何使用SDK ​

4.1 集成简要说明 ​

步骤一：创建 App Group ​

步骤二：创建 Extension 扩展组件 ​

步骤三：在 Extension 组件集成BJCastLiveKitExtSDK ​

步骤四：在Host App工程中集成BJCastLiveKitHostSDK ​

1 概述

1.1 目的

1.2 读者对象

1.3 缩略语定义

2 范围

2.1 功能

2.2 SDK框架

2.3 SDK交付物

2.4 版本要求

3 接口

3.1 BJCastLiveKitHost接口说明

3.1.1 初始化接口

3.1.2 探测接口

3.1.3 设置投屏参数接口

3.1.4 BJCastLiveKitHost通知接口

3.2 BJCastLiveKitExt接口说明

3.2.1 setup接口

3.2.2 暂停接口

3.2.3 恢复接口

3.2.4 结束接口

3.2.5 处理录制数据接口

3.2.6 `BJCastLiveKitDelegate`委托结束接口

4 客户如何使用SDK

4.1 集成简要说明

步骤一：创建 App Group

步骤二：创建 Extension 扩展组件

步骤三：在 Extension 组件集成`BJCastLiveKitExt`SDK

步骤四：在Host App工程中集成`BJCastLiveKitHost`SDK