• 开发者中心
  • >
  • 云手机
  • >
  • 技术文档
  • >
  • iOS

云手机iOS SDK开发指南

<无UI版本>

更新历史

历史版本 开发人员 更新日志 时间
V1.0.0 SDK组 初始版本 2019.04.02
V1.0.1 SDK组 1、增加获取视频帧延迟方法2、增加帧率、带宽、解码耗时回调 2020.01.13

1 引言

1.1 文档背景

CloudPlay海马云平台系统提供给用户通过浏览器或手机终端直接操作游戏的体验。所有游戏运行在云端服务器，免去了用户的下载安装等繁琐的流程，节省了用户的终端容量，并且可以将用户的游戏存盘数据保留在云端。本文档介绍IOS SDK的集成步骤，方便第三方开发者使用。

1.2 名词解释

HMCloudPhoneCore.framework: 为第三方提供的IOS SDK

CToken(Cloud Token): 第三方应用端访问云平台服务时需要根据相同的规则对参数进行加密算法并生成数字摘要得到的验证token。云平台服务接到后对参数进行相同的校验，如果得到的验证CToken与第三方应用传入的不符，则拒绝服务。

AccessKeyId: 海马云平台对第三方开发者分配的ID。

2 SDK构成

云手机SDK 为 HMCloudPhoneCore.framework

SDK 系统支持条件 iOS 8.0 及以上

SDK 接入后需使用真机运行，不支持模拟器

SDK 演示demo 请使用自己的开发者账号和bundleid 到真机演示

SDK 中使用 http 请求的，请在app demo 中 info.plist 添加App Transport Security Settings –> Allow Arbitrary Loads -> YES

示例图片

3 集成SDK

1) 将HMCloudPhoneCore.framework放到自己的工程中，并在工程目录中添加

a) 新建测试工程

示例图片

b) 测试工程名 HMCloudP

示例图片

c) 新建工程目录如下

示例图片

d) 将SDK 文件 HMCloudPhoneSDK.framework拖拽到Xcode 开发项目工程中
示例图片

e) 在弹出的弹框中选择 “Copy items if needed”“ Create groups” 以及 Add To Targets 中选择要加入的target 之后点击Finish

示例图片

f) 添加完成之后，目录图如下：

示例图片

2) 点击General->Embedded Binaries 和linked Frameworks and Libraries,确保 HMCloudPlayerSDK.framework 添加到上述路径

示例图片

4 集成SDK

4.1 注册SDK

1) 在AppDelegate 中导入头文件

#import <HMCloudPhoneCore/HMCloudPhoneCore.h>

2) 在 didFinishLaunchingWithOptions 中调用注册SDK方法

/**
 \*   @brief   生成一个SDK 单例
 *
 */
\+ (instancetype) sharedCloudPlayer;
 /**
 \*   @brief   注册SDK
 *
 */
\- (BOOL)registCloudPlayer:(NSString *)accessKeyID

​        channelId:(NSString *)channelId

​         options:(NSDictionary *)launchOptions;

各参数定义如下：

参数名称 类型 说明 选项
accessKeyId NSString 接入商唯一ID 必选
channelId NSString 渠道号，由接入商配置，可以为空 可选
options NSDictionary iOS App启动选项，在didFinishLaunching方法中由系统传入 必选

4.2 准备使用云手机

接口会返回一个UIViewController,APP需通过present或push方法将其展示在界面上。

/**
 准备云手机
  @param options 云手机参数
 @return 云手机ViewController
 */
\- (UIViewController *) prepare:(NSDictionary *)options;

参数定义如下：

参数名称 类型 说明 选项
options NSDictionary 游戏信息 必选

Options字典中，有效Key含义说明如下：

参数名称 类型 说明 选项
CloudGameOptionKeyPhoneID NSString 云手机ID 必选
CloudGameOptionKeyId NSString 游戏包名称 必选
CloudGameOptionKeyOrientation NSNumber 游戏屏幕方向 固定值为1（竖屏） 必选
CloudGameOptionKeyUserId NSString 游戏客户端用户的唯一识别码，如果没有用户登陆账号，可以随机生成长度在64以内的字符串，但需要每台客户端上的账号保证唯一性 必选
CloudGameOptionKeyUserToken NSString 用来校验userId的有效性，如果userId为随机生成，UserToken也可以随机生成 必选
CloudGameOptionKeyCToken NSString 用来校验参数的有效性 必选
CloudGameOptionKeyStasticFPSInterval NSNumber 帧数统计时⻓长，单位:秒 可选
CloudGameOptionKeyStasticBandInterval NSNumber 流量量统计时⻓长，单位:秒 可选
CloudGameOptionKeyStasticMaxFramesCount NSNumber 流量量统计周期内，最⼤大的帧的数量 可选
CloudGameOptionKeyStasticDecodeInterval NSNumber 解码耗时统计时⻓长，单位:秒 可选

4.3 开始使用云手机

  /**

   开始游戏

   */

  - (void) play;

4.4 获取视频帧延迟

/**

\* 获取视频延迟

*

\* @return 视频延迟，单位ms */

\- (NSInteger) getVideoLatency;

4.5 暂停使用云手机

/**

 暂停云手机

 */

\- (void) pause;

4.6 恢复使用云手机

/**

 恢复云手机

 */

\- (void) resume;

4.7 手动切换清晰度

/*
 \* 手动切换清晰度
 */
\- (void) switchResolution:(NSInteger)resolutionId;

参数定义如下：

参数名称 类型 说明 选项
resolutionId Int 清晰度ID 必选

4.8 停止使用云手机

/**
 停止云手机
 */
- (void) stop;
/**
停止云手机，退出云手机界面



 @param animated 和presentViewController 的 animated 值一致

 */

- (void) stopAndDismiss:(BOOL)animated;

参数定义如下：

参数名称 类型 说明 选项
resolutionId Int 清晰度ID 必选

4.9 SDK回调消息

可选则实现 代理

 \- (void) cloudPhoneSceneChangedCallback:(NSDictionary *)dict;

\- (void) cloudPhoneTouchBegan;

4.9.1 cloudPlayerTouchBegan

视频界面被点击，可用于收起已经展开的非全屏设置界面

4.9.2 cloudPhoneSceneChangedCallback

4.9.2.1 回调参数字典说明

举例

{

 "sceneId": "init",

 "extraInfo": {}

}

说明

字典Key 值类型 说明
sceneId NSString 回调场景ID，取值及含义如下：init : 初始化场景data : 配置数据场景，如清晰度列表prepare : 准备云手机场景playerState : 过程中，状态变化场景resolution : 播流清晰度场景maintance : 服务器维护场景
extraInfo NSDictionary 场景ID对应的扩展信息

4.9.2.2 初始化场景

字典Key 值类型 取值 说明 举例
state NSString success 初始化成功 { “sceneId”: “init”, “extraInfo”: { “state”: “success” }}
failed 初始化失败 { “sceneId”: “init”, “extraInfo”: { “state”: “failed”, “errorCode”: “100104001” }}
errorcode NSString 失败errorcode

4.9.3.2 配置数据场景

字典Key 值类型 取值 说明 举例
type NSString resolutions 清晰度列表 { “sceneId”: “data”,
“extraInfo”: {
“type”: “resolutions”,
“data”: [##清晰度列表##]
}
}
message 收到消息 { “sceneId”: “data”,
“extraInfo”: {
“type”: “message”,
“data”: [##消息内容##]
}
}

4.9.2.4 云手机准备场景

字典Key 值类型 取值 说明 举例
state NSString success 准备成功，之后才可以调用play方法播流 {
“sceneId”: “prepare”,
“extraInfo”: {
“state”: “success”
}
failed 准备失败 {
“sceneId”: “prepare”,
“extraInfo”: {
“state”: “failed”,
“errorCode”: “100000001”
}
}
errorcode NSString 准备失败的errorcode

4.9.2.5 状态变化场景

字典key 值类型 取值 说明 举例
prepared 实例申请完成，继续显示Loading {
“sceneId”: “playerState”,
“extraInfo”: {
“state”: “prepared”
}
}
videoVisible 视频第一帧到达 {
“sceneId”: “playerState”,
“extraInfo”: {
“state”: “videoVisible”
}
}
stopped 云游戏结束stop_reason见下表 {
“sceneId”: “playerState”,
“extraInfo”: {
“state”: “stopped”,
“stop_reason”: “”,
“errorCode”: “200211005”,
“errorMsg”: “##错误描述”,
“queues”: [#参考排队场景说明#],
}
}
timeout 游戏时间到，不结束游戏 {
“sceneId”: “playerState”,
“extraInfo”: {
“state”: “timeout”,
“tip”: “##提示内容##”
}
}
refreshSToken 刷新SToken，显示Loading {
“sceneId”: “playerState”,
“extraInfo”: {
“state”: “refreshSToken”
}
}
playfailed 调用play方法失败 {
“sceneId”: “playerState”,
“extraInfo”: {
“state”: “playFailed”,
“errorCode”: “100000001”
}
}
stop_reason取值 说明
normal 正常结束
time_limit 游戏时间到
no_operation 无操作超时
instance_err 实例出错
queue_limit 排队人数过多，禁止排队
instance_crashed 实例崩溃
in_maintance 维护中，禁止游戏
multi_inst 多开超出上限
token_expire token失效
low_bitrate 测速结果低于服务下限
url_timeout 网络连接超时
internal_error 内部错误

4.9.2.6 播流清晰度场景

字典Key 值类型 取值 说明 举例
type NSString crst 开始切换清晰度source : 当前清晰度IDdes : 目标清晰度IDmethod : 1-自动 0-手动 { “sceneId”: “resolution”, “extraInfo”: { “type”: “crst”, “source”: 1, “des”: 3, “method”: 1, “title”: “##提示##” }}
cred 清晰度切换完成cur_rate : 切换后的清晰度IDresult : 1-成功 0-失败 {
“sceneId”: “resolution”,
“extraInfo”: {
“type”: “cred”,
“cur_rate”: 1,
“result”: 1,
“title”: “##提示##”
}
}
notify 播流清晰度通知 {
“sceneId”: “resolution”,
“extraInfo”: {
“type”: “notify”,
“cur_rate”: 1
}
}

4.9.2.7 数据统计场景

字典Key 值类型 取值 说明 举例
type NSString bandwidth 带宽使⽤用数据value : 统计时段内字 节数frames : 统计时段内最 ⼤大N帧字节数 {
“sceneId”: “stastic”,
“extraInfo”: {
“type”: “bandwidth”,
“value”: 314704,
“frames”: []
}
}
frames 帧数统计数据value : 统计时段内总 帧数 {
“sceneId”: “stastic”,
“extraInfo”: {
“type”: “frames”,
“value”: 332
}
}
decode 解码耗时统计value : 统计时段内平 均解码耗时，单位ms {
“sceneId”: “stastic”,
“extraInfo”: {
“type”: “decode”,
“value”: 9
}
}

4.9.2.8 维护场景

字典Key 值类型 取值 说明 举例
soon 游戏中用户，收到即将维护的提示 {
“sceneId”: “maintance”,
“extraInfo”: {
“progress”: “soon”,
“title”: “##维护提示##”,
“timeStr”: “五分钟”
}
}
start 开始维护 {
“sceneId”: “maintance”,
“extraInfo”: {
“progress”: “start”,
“title”: “##维护提示##”
}
}
inprogress 维护中，禁止进入游戏 {
“sceneId”: “maintance”,
“extraInfo”: {
“progress”: “inprogress”,
“title”: “##维护提示##”,
“timeStr”: “五分钟”
}
}
done 维护完成 {
“sceneId”: “maintance”,
“extraInfo”: {
“progress”: “done”,
“title”: “##维护提示##”
}
}

4.10 SDK发送功能键

/** 发送功能键 
@param keycode 键值 
*/
- (void) sendKeycode:(NSInteger)keycode;

各参数定义如下：

参数名称 类型 说明 选项
keycode NSInteger 键值0x1000055：MENU36: HOME158: BACK 必选

4.11 网络状态监控

4.11.1 开启网络状态监控

/**
开始网络状态监控 
@param block 回调通知 
*/
-(void) startNetMonitor:(void (^)(CloudCorePlayerNetStatus status))block;

各参数定义如下：

参数名称 类型 说明 选项
block Block 网络状态变更回调 NetStatusUnknown : 未知NetStatusNotReachable : 不可达NetStatusReachableViaWWAN : 移动网络可达NetStatusReachableViaWiFi : Wi-Fi网络可达 必选

4.11.2 停止网络状态监控

/** 
停止网络状态监控 
*/
- (void) stopNetMonitor;