本文档描述了云手机 iOS 客户端 SDK 提供的接口。

接口概览 #

生命周期相关接口 #

云手机进程相关接口 #

音视频控制相关接口 #

传感器开关参数 #

快速接入 #

初始化 VePhoneManager 配置 #

参考示例：

- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions
{
    // 初始化SDK，设置全局配置信息
    // accountId：火山引擎账号ID
    // 建议在程序一启动的时候就调用
    [[VePhoneManager sharedInstance] initWithAccountId: accountId];
}

创建 VePhoneManager 实例 #

描述：配置 VePhoneConfigObject 配置参数，然后调用 startWithConfig: configObj 接口，启动云机实例。
参考示例：

// 设置回调代理
[VePhoneManager sharedInstance].delegate = self;
// 设置容器视图
[VePhoneManager sharedInstance].containerView = self.containerView;
// 配置参数
VePhoneConfigObject *configObj = [VePhoneConfigObject new];
configObj.ak = @"";
configObj.sk = @"";
configObj.token = @"";
configObj.podId = @"";
configObj.userId = @"";
configObj.productId = @"";
// 启动云手机
[[VePhoneManager sharedInstance] startWithConfig: configObj];

#pragma mark - VePhoneManagerDelegate
- (void)phoneManager:(VePhoneManager *)manager startSucceedResult:(NSInteger)streamProfileId reservedId:(NSString *)reservedId extra:(NSDictionary *)extra
{
    // 启动成功，收到首帧画面回调
}

- (void)phoneManager:(VePhoneManager *)manager changedDeviceRotation:(NSInteger)rotation
{
    // 横竖屏方向回调，注意：SDK只负责横竖屏方向回调，不负责横竖屏的旋转，接入时需根据rotation自行处理
}

- (void)phoneManager:(VePhoneManager *)manager onWarning:(VePhoneWarningCode)warnCode
{
    // 警告回调
}

- (void)phoneManager:(VePhoneManager *)manager onError:(VePhoneErrorCode)errCode
{
    // 错误回调
}

配置参数
VePhoneConfigObject 配置参数如下：

参考示例：

@interface VePhoneConfigObject : NSObject

/**--------------------------必选参数----------------------------------*/
/** 鉴权参数 */
@property (nonatomic, copy) NSString *ak;
/** 鉴权参数 */
@property (nonatomic, copy) NSString *sk;
/** 鉴权参数 */
@property (nonatomic, copy) NSString *token;
/** 自定义客户端用户 ID */
@property (nonatomic, copy) NSString *userId;
/** 业务 ID */
@property (nonatomic, copy) NSString *productId;

/**--------------------------可选参数----------------------------------*/
/** 指定实例 ID */
@property (nonatomic, copy) NSString *podId;
/** 指定启动的应用 ID */
@property (nonatomic, copy) NSString *appId;
/** 当次启动的生命周期标识 */
@property (nonatomic, copy) NSString *roundId;
/** 火山侧套餐 ID */
@property (nonatomic, copy) NSString *planId;
/** 火山账号ID */
@property (nonatomic, copy) NSString *accountId;
/** 退出后，是否还原，默认：NO */
@property (nonatomic, assign) BOOL reset;
/** 本地键盘开关 */
@property (nonatomic, assign) BOOL localKeyboardEnable;
/** 无操作保活时长 */
@property (nonatomic, assign) NSInteger autoRecycleTime;
/** 清晰度 ID，不传使用默认档位 */
@property (nonatomic, assign) NSInteger videoStreamProfileId;
/** 用户标签，业务方指定 */
@property (nonatomic, copy) NSString *userTag;
/** 远端虚拟定位信息 */ 
@property (nonatomic, strong) VeBaseLocationInfo *remoteMockLocation;
/** 设置远端推流分辨率 */
@property (nonatomic, assign) CGSize remoteWindowSize;
/** 画面渲染模式 */
@property (nonatomic, assign) VeBaseVideoRenderMode videoRenderMode;
/** 画面旋转模式，默认：VeBaseRotationModeAutoRotation */
@property (nonatomic, assign) VeBaseRotationMode rotationMode;
/** 根据业务需要，自定义附加参数 */
@property (nonatomic, strong) NSDictionary<NSString *, NSString *> *extraDict;
/** 云手机实例等待客户端加入房间的最大允许时长 */
@property (nonatomic, assign) NSInteger waitTime;

@end

订阅音视频流 #

在调用 startWithConfig: 启动云手机之前，指定启动云手机时拉取音视频流类型（如不指定，则正常拉取音视频流）：

• VeBaseStreamTypeVideo（仅拉取视频流，不拉取音频流）
• VeBaseStreamTypeAudio（仅拉取音频流，不拉取视频流）
• VeBaseStreamTypeBoth（启动后正常拉取音视频流，默认）

/**
 * 设置“媒体流”订阅类型
 * 默认：VeBaseStreamTypeBoth
 * 在调用 startWithConfig: 之前设置，不支持拉流过程中修改
 * 收到首帧之后，可通过调用 muteAudio:、muteVideo:、switchPaused: 接口恢复
 */
@property (nonatomic, assign) VeBaseStreamType streamType;

设置音频采集方式 #

在调用 startWithConfig: 启动云手机之前，指定“音频”的采集方式：

• VeBaseMediaSourceTypeInternal（SDK 内部采集，默认）
• VeBaseMediaSourceTypeExternal（外部自定义采集）

/**
 * 设置“音频“采集方式
 * 默认：VeBaseMediaSourceTypeInternal
 * 在调用 startWithConfig: 之前设置，不支持拉流过程中修改
 */
@property (nonatomic, assign) VeBaseMediaSourceType audioSourceType;

设置视频采集方式 #

在调用 startWithConfig: 启动云手机之前，指定“视频”的采集方式：

• VeBaseMediaSourceTypeInternal（SDK 内部采集，默认）
• VeBaseMediaSourceTypeExternal（外部自定义采集）

/**
 * 设置“视频”采集方式
 * 默认：VeBaseMediaSourceTypeInternal
 * 在调用 startWithConfig: 之前设置，不支持拉流过程中修改
 */
@property (nonatomic, assign) VeBaseMediaSourceType videoSourceType;

设置定位模式 #

在调用 startWithConfig: 启动云手机之前，指定“定位”的模式：

• VeBaseLocationModeAuto（自动模式，默认）
• VeBaseLocationModeManual（手动模式）

/**
 * 设置”定位“模式
 * 默认：VeBaseLocationModeAuto
 * 在调用 startWithConfig: 之前设置，不支持拉流过程中修改
 * VeBaseLocationModeAuto：会触发“phoneManager:onSentLocalLocation:”回调
 * VeBaseLocationModeManual：会触发“phoneManager:onReceivedRemoteLocationRequest:minTime:minDistance:numUpdates:、“phoneManager:onRemoteLocationRequestEndedFromPhoneManager:”回调
 */
@property (nonatomic, assign) VeBaseLocationMode locationServiceMode;

接口说明 #

初始化 SDK #

描述：初始化 SDK，设置全局配置信息（建议在程序启动的时候调用，时机越早越好）。

- (void)initWithAccountId:(NSString *)accountId;

获取管理器实例 #

描述：获取管理器实例（返回 VePhoneManager 对象）。

+ (VePhoneManager *)sharedInstance;

获取 SDK 版本信息 #

描述：获取 vePhoneSDK 的当前版本号。

+ (NSString *)currentVersion;

获取本地设备 ID #

描述：获取 SDK 生成的本地设备 ID，用于后台查询 SDK 日志，进行调试和问题排查。格式要求为 16 位，纯数字；（建议接入方在需要问题排查时，提供给火山引擎技术支持）。

+ (NSString *)currentDeviceId;

获取服务端设备 ID #

描述：获取 SDK 生成的服务端设备 ID，用于后台查询 SDK 日志，进行调试和问题排查。格式要求为 32 位，字母和数字组合；（建议接入方在需要问题排查时，提供给火山引擎技术支持）。

+ (NSString *)serviceDeviceId;

开启调试日志 #

描述：开启调试日志信息。

- (void)setDebugInfoEnable:(BOOL)enable;

启动云手机 #

描述：启动云手机接口。

调用此接口，会触发“phoneManager:startSucceedResult:reservedId:extra:”回调

- (void)startWithConfig:(VePhoneConfigObject *)configObj;

退出 #

描述：停止从云机拉流，并且退出，但不会回收客户端本地资源。

- (void)stop;

云手机进程相关接口 #

设置保活时间 #

描述：在应用运行中动态设置客户端切后台之后，云机服务的保活时间（如不设置，则使用默认保活时长 300 秒；支持设置的上限值为 7200 秒，即 2 小时；如需设置更长时间，可联系火山引擎云手机技术支持）。

当客户端切后台时开始计时。如用户在设置的保活时间到达时未切回前台，服务端将断开连接。
调用此接口，会异步触发 phoneManager:onIdleTimeChanged:callUserId:code: 回调

- (void)setIdleTime:(NSInteger)time;

查询保活时间 #

描述：在应用运行中，查询已设置的云端保活服务时间。

调用此接口，会异步触发 phoneManager:onGetIdleTime:code: 回调

- (void)getIdleTime;

设置无操作推流服务回收时长 #

描述：在应用运行中动态设置无操作推流服务回收时长。
该接口用于设定一个时长，如果在这个时长内客户端没有任何操作，云手机实例将停止推流并自动退出。
如不设置或设置为 0，则使用默认时长 300 秒；支持设置的上限值为 864000 秒，即 24 小时。
如需设置更长时间，可联系火山引擎云手机技术支持。

• 如果已在 VePhoneConfigObject 配置参数中通过 autoRecycleTime 参数设置，动态设置的时长优先级高。
• 调用此接口，会触发 phoneManager:onAutoRecycleTimeChanged:callUserId:code: 回调。

- (void)setAutoRecycleTime:(NSInteger)time;

获取无操作推流服务回收时长 #

描述：获取已设置的无操作推流服务回收时长。

调用此接口，会触发 phoneManager:onGetAutoRecycleTime:code: 回调。

- (void)getAutoRecycleTime;

清晰度切换 #

描述：在云手机运行过程中，可通过指定清晰度 ID，切换视频流的清晰度。

调用此接口，会触发 phoneManager:onVideoStreamProfileChanged:fromStreamProfileId:callUserId:targetParams:result: 回调。

- (void)setVideoStreamProfile:(NSInteger)streamProfileId;

查询当前清晰度 #

描述：在应用运行中，查询已设置的云机清晰度 ID。

调用此接口，会触发 phoneManager:onGetVideoStreamProfile:result: 回调。

- (void)getVideoStreamProfileId;

客户端前后台切换 #

描述：设置客户端应用切换前后台的状态。

调用此接口，会触发 phoneManager:onBackgroundSwitched: 回调。

- (void)switchBackground:(BOOL)enable;

云机应用切换前台 #

描述：将指定云机应用切换到前台。

调用此接口，会触发 phoneManager:onRemoteAppSwitchedForeground:switchType 和phoneManager:onRemoteAppSwitchedBackground:switchType: 回调。

- (void)setRemoteAppForeground:(NSString *)packageName;

获取云机后台应用列表 #

描述：获取已切换到后台的云机应用列表（客户端退出实例重新拉流后，也可调用该接口获取客户端退出之前已切换后台的应用列表）。

调用此接口，会触发 phoneManager:onRevicedRemoteAppList: 回调。

- (void)getRemoteBackgroundAppList;

云手机画面截图 #

描述：对当前云手机画面进行截图，并获取在云手机实例中保存截图文件的路径以及下载录屏文件的地址。

调用此接口，会触发 phoneManager:onScreenShot:savePath:downloadUrl: 回调。

- (void)screenShot:(BOOL)savedOnPod;

云手机画面录屏 #

描述：对当前云手机画面进行录屏，并获取在云手机实例中保存录屏文件的路径以及下载录屏文件的地址。

调用此接口，会触发 phoneManager:status:savePath:msg:downloadUrl: 回调。

- (void)startRecording:(NSInteger)duration saveOnPod:(BOOL)saveOnPod;

停止画面录屏 #

描述：主动停止对当前云手机画面进行录屏。

- (void)stopRecording;

查询屏幕当前焦点应用 #

描述：查询屏幕当前的焦点窗口应用名称。

调用此接口，会触发 phoneManager:getFocusedWindowApp:packageName: 回调。

- (void) getFocusedWindowApp;

设置导航栏开关状态 #

描述：设置云手机当前导航栏开关状态（打开/隐藏）。

- (void)setNavBarStatus:(NSInteger)status;

获取导航栏开关状态 #

描述：获取云手机当前导航栏开关状态（打开/隐藏）。

调用此接口，会触发 phoneManager:onNavBarStatus: 回调。

- (void)getNavBarStatus;

切换本地/云机输入法类型 #

描述：拉流过程中，切换本地/云机输入法类型。

调用此接口，会触发 phoneManager:onKeyboardTypeChanged: 回调。

- (NSInteger)setKeyboardType:(VePhoneKeyboardType)type;

查询输入法类型 #

描述：查询当前使用的本地/云机输入法类型。

调用此接口，会触发 phoneManager:onGetKeyboardTypeResult: 回调。

- (NSInteger)getKeyboardType;

设置用户的操控权 #

描述：当多个用户通过不同客户端连接到同一云手机实例时，支持开启或关闭用户对云手机的操控权。

调用此接口，会触发 phoneManager:onEnableControlResult:state:message: 回调。

- (void)enableControl:(VePhoneControlState *)state;

/** ------------ 用户操控权 ------------- */
@interface VePhoneControlState : NSObject
/**
 * 目标用户ID
 */
@property (nonatomic, copy) NSString *userId;
/**
 * 目标用户是否具有操控权
 */
@property (nonatomic, assign) BOOL enable;

@end

查询指定用户的操控权 #

描述：异步查询指定用户是否具有云手机操控权。

调用此接口，会触发 phoneManager:onHasControlResult:state:message: 回调。

- (void)hasControl:(NSString *)userId;