• 
• 开发者中心
• >
• 云游戏
• >
• SDK开发指南
• >
• 云游戏基础SDK
• >
• iOS
• >
• v5.2

版本号：master-5.2

1 文档概述

欢迎使用海马云游戏服务，本文档主要介绍云游戏iOS端SDK的接入流程及提供支持的API详情，开发者通过接入海马云游戏SDK，可以实现云游戏的播放、停止、状态回调等各类控制操作和数据交互，在海马云游戏端到端全栈云服务能力基础上，为用户带来顺畅的云游戏体验。

在开始接入SDK前，请确认您已经拥有海马云游戏平台接入商ID并创建了渠道号，并已经完成了在海马云游戏平台上传游戏包等相关准备工作。

2 集成 SDK

云游戏 SDK 为 HMCloudPlayerCore.framework
集成依赖库HMWebRTC.framework

• SDK 系统支持条件 iOS 9.0 及以上
• SDK 接入后需使用真机运行，不支持模拟器
• SDK 演示demo 请使用自己的开发者账号和bundleid 到真机演示
• 在 App 的 info.plist 添加 App Transport Security Settings –> Allow Arbitrary Loads -> YES
• SDK 支持webrtc流，请在自己的应用中增加麦克风，照相机权限。info.plist 添加Privacy->Camera Usage Description, Privacy->Microphone Usage Description
• 建议客户端申请云游戏SDK的参数从自己的服务器端动态获取

2.1 创建 iOS 项目

1. 打开 Xcode 并点击 Create a new Xcode project；
2. 选择项目类型为 Single View App，并点击 Next；；
3. 输入项目信息，如项目名称、开发团队信息、组织名称和语言，并点击 Next；
4. 选择项目存储路径，并点击 Create ；
5. 将你的 iOS 设备连接至电脑；
6. 进入 TARGETS > Project Name > General > Signing 菜单，选择 Automatically manage signing，并在弹出菜单中点击 Enable Automatic；

2.2 下载集成 SDK

1. 前往 SDK 下载页面，获取最新版的 海马云 SDK，然后解压出 HMCloudPlayerCore.framework,HMWebRTC.framework
2. 将 HMCloudPlayerCore.framework (不要修改SDK名字) 复制到项目文件夹下；
3. HMWebRTC为webrtc流依赖库，将 HMWebRTC.framework 复制项目文件夹下；
4. 打开 Xcode（以 Xcode 11.0 为例），进入 TARGETS > Project Name > General > Frameworks, Libraries, and Embedded Content 菜单，点击 +，再点击 Add Other… 添加 HMCloudPlayerCore.framework HMWebRTC.framework。添加完成后，项目会自动链接其他系统库。为保证动态库的签名和 app 的签名一致，你需要将动态库的 Embed 属性设置为 Embed & Sign。

3 快速入门

3.1 导入头文件

#import <HMCloudPlayerCore/HMCloudPlayer.h>

3.2 创建单例

/**
 *  生成一个单例
 */
+ (instancetype) sharedCloudPlayer;

3.3 配置SDK连接地址接口

在调用注册SDK接口前，调用该接口可以指定 SDK 连接地址信息；在调用注册SDK接口后，调用该接口，会返回失败。

无特殊说明，接入方无需调用该接口。

/**
 配置云游戏连接信息；该方法在创建单例后第一时间调用

 @param info 连接信息
 @return 是否成功 //参数类型非法，或者已经请求过SAAS地址，均返回失败。
 */
- (BOOL) config:(NSDictionary *)info;

参数说明

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

3.4 注册 SDK

/**
 向海马云端注册

 @param accessKeyID 接入商ID
 @param channelId 接入商渠道ID
 @param launchOptions AppLauchuOptions
 @return 是否正常进行注册，最终注册结果异步返回
 */
- (BOOL) registCloudPlayer:(NSString *)accessKeyID 
                            channelId:(NSString *)channelId 
                            options:(NSDictionary *)launchOptions;

3.5 准备游戏

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

/**
 准备游戏

 @param options 游戏参数
 @return 云游戏ViewController
 */
- (UIViewController *) prepare:(NSDictionary *)options;

参数说明

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

特殊类型定义如下：

3.6 开始游戏

/**
 开始游戏
 */
- (void) play;

4 API 接口

4.1 暂停游戏

/**
 暂停游戏
 */
- (void) pause;

4.2 恢复游戏

/**
 恢复云游戏

 @param playingTime 恢复后的时长，单位：ms
 */
- (void) resume:(NSInteger)playingTime;

参数说明

4.3 停止游戏

/**
 停止游戏
 */
- (void) stop;

/**
 停止游戏，退出游戏界面

 @param animated 和presentViewController 的 animated 值一致
 */
- (void) stopAndDismiss:(BOOL)animated;

4.4 设置背景图

/*
 * 设置背景图
 */

- (void)setBackgroundImage:(UIImage *)bgImage;

参数说明

4.5 发生按键指令

typedef NS_ENUM(NSInteger, HMCloudPlayerKeyCommand){
    CloudPlayerKeyCommandBackGame = 0x01,
    CloudPlayerKeyCommandEmptyTouch
};


/**
 发送特定键值指令，更新用户操作时间

 @param cmd 键值
 @return 是否发送
 */
- (BOOL) sendKeyCommand:(HMCloudPlayerKeyCommand)cmd;

/**
发送特定键值指令

@param cmd 键值
@param updateUserOperationTime  是否更新用户操作时间
@return 是否发送
*/
- (BOOL) sendKeyCommand:(HMCloudPlayerKeyCommand)cmd updateUserOperationTime:(BOOL)updateUserOperationTime;

参数说明

4.6 游戏维度清晰查询接口

/**
 查询游戏配置信息（目前版本仅支持清晰度查询）

 @param pkgName 必填，不能为NULL
 @param appChannel 选填，可为NULL
 @param streamingType 必填
 @param success 游戏配置的清晰度列表
 @param fail 查询失败回调
 @return 是否开始查询
 */

- (BOOL) gameParamsQuery:(NSString *)pkgName
  appChannel:(NSString *)appChannel
  streamingType:(CloudCoreStreamingType)streamingType
  success:(void (^)(NSArray<HMCloudPlayerResolution *> *))success
  fail:(void (^)(NSString *errorCode))fail;

参数说明

4.7 路由节点查询接口

/**
 IDC路由查询

 @param success 查询成功回调
 @param fail 查询失败回调
 @return 是否开始查询
 */
- (BOOL) idcQuery:(void (^)(NSString *url, NSString *ipAddress))success 
  fail:(void (^)(NSString *errorCode))fail;

参数说明

4.8 获取用户最后操作时间戳

/**
获取用户最后一次操作时间

@return 用户最后操作时间戳，单位ms
*/
- (long long) getLastUserOperationTimestamp;

4.9 获取云游戏延迟信息

通过该接口会返回当前云游戏的网络延迟信息，该算法的准确性基于App和实例的时钟校准。

/**
 *  获取云游戏延迟信息
 *
 *  @return 云游戏延迟，单位ms
 */

- (NSInteger) getVideoLatency;

4.10 测速接口

/**
 IDC节点测速

 @param seconds 最大测速时长，单位：秒
 @param success 测速成功回调
 @param fail 测速失败回调
 @return 是否开始测速
 */
- (BOOL) speedTest:(NSInteger)seconds 
  success:(void (^)(int))success 
  fail:(void (^)(NSString *errorCode))fail;

参数说明

4.11 更新UID和游戏时长

/**
  游戏过程中，更新UID和游戏时长

 @param userId 必填，不能为NULL
 @param userToken 必填，不能为NULL
 @param ctoken 必填，不能为NULL
 @param playingTime 必填，不能小于0，单位: ms
 @param tip 选填
 @param protoData 选填
 @param success 更新成功回调
 @param fail 更新失败回调
 @return 是否开始更新
 */
- (BOOL) updateGameUID:(NSString *)userId 
  userToken:(NSString *)userToken 
  ctoken:(NSString *)ctoken 
  playingTime:(NSInteger)playingTime 
  tip:(NSString *)tip 
  protoData:(NSString *)protoData 
  success:(void (^)(BOOL successed))success 
  fail:(void (^)(NSString *errorCode))fail;

参数说明

4.12 SDK 发生消息

/**
 发送消息

 @param message 消息内容
 */
- (void) sendMessage:(NSString *)message;

参数说明

4.13 手动切换清晰度

/**
 手动切换清晰度

 @param resolutionId 目标清晰度ID
 */
- (void) switchResolution:(NSInteger)resolutionId;

参数说明

4.14 进入排队

/**
 确认进入排队队列
 */
- (void) confirmQueue;

4.15 开启网络监控

/**
 开始网络状态监控

 @param block 回调通知
 */
- (void) startNetMonitor:(void (^)(CloudCorePlayerNetStatus status))block;

参数说明

4.16 停止网络监控

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

4.17 静音功能

/**
 视频静音开关
 @param mute; true为静音，false恢复声音
 */
- (void) setAudioMute:(BOOL)mute;

5 进阶 API

5.1 存档进度查询

/**
 游戏存档进度查询

 @param userId 必填，不能为NULL
 @param userToken 必填，不能为NULL
 @param pkgName 必填，不能为NULL
 @param appChannel 选填，可为NULL
 @param success 查询成功的回调
 @param fail 查询失败的回调
 @return 是否开始查询
 */
- (BOOL) gameArchiveQuery:(NSString *)userId
    userToken:(NSString *)userToken
    pkgName:(NSString *)pkgName
    appChannel:(NSString *)appChannel
    success:(void (^)(BOOL finished))success
    fail:(void (^)(NSString *errorCode))fail;

参数说明

5.2 查询游戏是否有存档

/**
 游戏是否有存档查询

 @param userId 必填，不能为NULL
 @param userToken 必填，不能为NULL
 @param pkgName 必填，不能为NULL
 @param appChannel 选填，可为NULL
 @param success 查询成功的回调
 @param fail 查询失败的回调
 @return 是否开始查询
 */
- (BOOL) gameArchived:(NSString *)userId 
  userToken:(NSString *)userToken
  pkgName:(NSString *)pkgName
  appChannel:(NSString *)appChannel
  success:(void (^)(BOOL archived))success
  fail:(void (^)(NSString *errorCode))fail;

参数说明

5.3 获取未释放的游戏实例

/**
 查询是否有上次未完成的游戏实例
 @param options 游戏参数  {@"CloudGameOptionKeyUserId":@"...", @"CloudGameOptionKeyUserToken":"...",}
 @param reservedIncetance 查询驻留机回调方法，包含驻留机数组
 */
- (void) getReservedInstance:(NSDictionary *)options ReservedIncetance:(HMReservedIncetanceCallback)reservedIncetance;

5.4 获取延迟检测信息

/**
 获取某一秒延迟检测信息
 @return 包含延迟信息的HMDelayInfoModel
 */
- (HMDelayInfoModel *) getDelayInfo;

参数说明

5.5 根据CID立即释放实例

/**
 根据cid立即释放实例
 @param cid 必填，不能为NULL
 @param cToken 必填，不能为NULL,并且必须与之前播放的实例传入的cToken一致
 @param userId 必填，不能为NULL
 @param userToken 必填，不能为NULL
 @param pkgName 必填，不能为NULL
 @param appChannel 选填，可为NULL
 @param success 释放成功回调
 @param fail 释放失败回调
 @return 是否开始释放实例
*/

- (BOOL)gameReleaseInstanceWithCid:(NSString *)cid 
  Ctoken:(NSString *)cToken 
  UserId:(NSString *)userId 
  UserToken:(NSString *)userToken 
  PkgName:(NSString *)pkgName 
  AppChannel:(NSString *)appChannel 
  Success:(void(^)(BOOL released))success 
  Fail:(void (^)(NSString *errorCode))fail;

参数说明

5.6 开启直播

/**
 游戏过程中，开启直播

 @param livingId 直播唯一标识，必填，不能为NULL
 @param pushStreamUrl 第三方推流地址，必填，不能为NULL
 @return 是否开始开启直播
 */
- (BOOL) startLivingWithLivingId:(NSString *)livingId pushStreamUrl:(NSString *)pushStreamUrl;

参数说明

5.7 停止直播

/**
 游戏过程中，关闭直播

 @param livingId 直播间ID，必填，不能为NULL
 @return 是否开始结束直播
 */
- (BOOL) stopLivingWithLivingId:(NSString *)livingId;

5.8 获取授权码

/**
 获取授权码，控制端同意转让控制权后调用
 @return 是否开始获取授权码
 */
- (BOOL) getAuthCode;

5.9 获取控制权

/**
 获取控制权（即移屏），申请端调用

 @param cid 控制端cid，必填，不能为NULL
 @param authCode 授权码，必填，不能为NULL
 @param streamType 流类型，可选
 @param accessKeyID 控制端bid，必填
 @param clientISP 运营商，可选
 @param clientProvince 省份，可选
 @param clientCity 城市，可选
 @return 是否开始获取控制权
 */
- (BOOL) gainControlWithMasterCid:(NSString *)cid
                         authCode:(NSString *)authCode
                       streamType:(CloudCoreStreamingType)streamType
                      accessKeyID:(NSString *)accessKeyID
                        clientISP:(NSString *)clientISP
                   clientProvince:(NSString *)clientProvince
                       clientCity:(NSString *)clientCity
                        extraInfo:(NSString *)extraInfo;

参数说明

5.10 查询是否支持直播

/**
 查询是否支持直播的方法，建议APP调用时机为收到第一帧回调之后

 @return 是否支持直播枚举结果
 */
- (ELivingCapabilityStatus) getLivingCapabilityStatus;

返回值定义

5.11 停止云游戏，支持配置最小云玩存档时间

/**
 停止云游戏

 @param seconds 存档时长，必填 单位：秒
 */
- (void) stop:(int)seconds;

5.12 停止云游戏带动画，支持配置最小云玩存档时间

/**
 停止云游戏带动画

 @param archiveMinSeconds 存档时长，必填 单位：秒
 */
- (void) stopAndDismiss:(BOOL)animated archiveMinSeconds:(int)seconds；

6 SDK 消息回调

可选则实现 HMCloudPlayerDelegate 代理

- (void) cloudPlayerSceneChangedCallback:(NSDictionary *)dict;
- (void) cloudPlayerTouchBegan;
- (void) cloudPlayerUsageAuthorization:(HMCloudPlayerUsageAuthorization)type success:(void (^)(BOOL authorization))success;

6.1 cloudPlayerTouchBegan

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

6.2 cloudPlayerSceneChangedCallback

回调参数字典说明：

{
  "sceneId": "init",
  "extraInfo": {}
}

6.2.1 参数说明

6.2.2 初始化场景说明

6.2.3 配置数据场景

6.2.4 准备云游戏场景

6.2.5 云游戏状态变化场景

6.2.6 游戏时长场景

6.2.7 播流清晰度场景

6.2.8 数据统计场景

6.2.9 排队场景

多队列排队数据项说明

6.2.10 维护场景

6.2.11 无输入提示场景

6.2.12 直播场景

6.2.13 控制权转移场景

6.3 系统隐私权限判断cloudPlayerUsageAuthorization

/**
系统隐私权限判断

@param type 隐私权限类型；
@param success 授权情况回调；
*/

• (void) cloudPlayerUsageAuthorization:(HMCloudPlayerUsageAuthorization)type success:(void (^)(BOOL authorization))success;