iOS SDK 开发指南
文档版本号:20220302-100
变更说明:
SDK版本号 | 日期 | 更新内容 |
---|---|---|
Master-5.24.1 | 2022年2月22日 | 新增功能: 1、优化网络连接。SDK内部在网络上出现异常时实现内部重连。 |
Master-5.22.1 | 2022年2月21日 | bug fixed 1、优化WebRTC播流最后一帧画面展示效果 |
Master-5.22 | 2022年2月14日 | 新增功能: 1、支持旋转适配非刘海区域,参考参数CloudGameOptionKeyResetPlayerFrame |
Master-5.20.3 | 2022年1月7日 | 新增功能: 1、增加收起游戏内本地键盘方法hiddenKeyboard bugfix: 1、解决游戏内弹出本地键盘,游戏内输入框焦点被抢夺后,本地键盘落下黑屏显示问题 2、优化WebRTC播流最后一帧画面展示效果 |
master-5.20 | 2021年12月8日 | 新增功能: 1、在cloudPlayerSceneChangedCallback场景回调返回错误时,增加errorCodeWithoutCid字段,此字段对应值不包含cid |
master-5.18 | 2021年11月23日 | 新增功能: 1、新增GPS开启回调通知,参考 cloudPlayerDidReceiveWSMessage 回调方法 2. 扩展实例类型消息回调,参考idcInfo场景回调 |
master-5.17 | 2021年11月15日 | 1、新增功能: 自定义画面位置尺寸,参见CloudGameOptionKeyShowPoint、CloudGameOptionKeyShowSize参数 |
master-5.4.1 | 2021年6月25日 | 新增功能: 1、通过后台参数配置优化云游戏音效 bug fixed: 1、优化addSubView加载云游戏方式横竖屏适配 |
1 产品简介
欢迎使用海马云游戏服务,本文档主要介绍海马云游戏iOS端SDK的接入流程及提供支持的API详情,开发者通过接入海马云游戏SDK,可以实现云游戏的播放、停止、状态回调等各类控制操作和数据交互,在海马云游戏端到端全栈云服务能力基础上,为用户带来顺畅的云游戏体验。
在开始接入SDK前,请确认已经拥有海马云游戏平台接入方ID、创建了渠道号,并已经完成了在海马云游戏平台上传游戏包等相关准备工作。
2 集成 SDK
云游戏SDK为HMCloudPlayerCore.framework,集成的依赖库为HMWebRTC.framework。
集成条件:
- 系统支持条件为iOS 9.0及以上。
- SDK接入后需使用真机运行,不支持模拟器。
- 请使用自己的开发者账号和bundleid到真机演示SDK demo。
- 在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 项目
- 打开Xcode并点击Create a new Xcode project。
- 选择项目类型为Single View App,并点击Next。
- 输入项目信息,如项目名称、开发团队信息、组织名称和语言,并点击Next。
- 选择项目存储路径,并点击Create 。
- 将iOS设备连接至电脑。
- 进入TARGETS→Project Name→General→Signing菜单,选择Automatically manage signing,并在弹出菜单中点击Enable Automatic。
2.2 下载集成 SDK
- 前往SDK下载页面,获取最新版的海马云SDK,然后解压出HMCloudPlayerCore.framework,HMWebRTC.framework。
- 将HMCloudPlayerCore.framework(不要修改SDK名字)复制到项目文件夹下。
- HMWebRTC为webrtc流依赖库,将HMWebRTC.framework复制项目文件夹下。
- 打开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;
表3-1 参数说明
参数 | 类型 | 说明 |
---|---|---|
info | NSDictionary | 连接地址信息 |
表3-2 Info 字典中有效 Key 含义
参数 | 类型 | 说明 |
---|---|---|
CloudGameConfigKeyAuthURL | NSString | SAAS AUTH请求地址 |
CloudGameConfigKeyLinkURL | NSString | SAAS WS长连接地址 |
CloudGameConfigKeyCountlyURL | NSString | 数据上报地址 |
3.4 注册 SDK
函数原型:
/**
向海马云端注册
@param accessKeyID 接入方ID
@param channelId 接入方渠道ID
@param launchOptions AppLauchuOptions
@return 是否正常进行注册,最终注册结果异步返回
*/
- (BOOL) registCloudPlayer:(NSString *)accessKeyID
channelId:(NSString *)channelId
options:(NSDictionary *)launchOptions;
表3-3 参数说明
参数 | 类型 | 说明 |
---|---|---|
accessKeyID | NSString | 接入方唯一ID |
channelId | NSString | 渠道号,由接入方配置。如果应用本身不区分渠道,可以设置为一个随机值的字符串。此参数由接入方自己定义与海马云无关,请注意不要跟appChannel混淆 |
options | NSDictionary | iOS APP启动选项,在didFinishLaunching方法中由系统传入 |
3.5 准备游戏
接口会返回一个UIViewController, APP需通过present或push方法将其展示在界面上。
如使用addSubView接入,需根据云游戏方向设置rootViewController的取向。可参考接入Demo。
函数原型:
/**
准备游戏
@param options 游戏参数
@return 云游戏ViewController
*/
- (UIViewController *) prepare:(NSDictionary *)options;
表3-4 参数说明
参数 | 类型 | 说明 |
---|---|---|
options | NSDictionary | 游戏信息 |
表3-5 options字典中有效Key含义
参数 | 类型 | 必填项 | 说明 |
---|---|---|---|
CloudGameOptionKeyId | NSString | 是 | 游戏包名称 |
CloudGameOptionKeyOrientation | NSNumber | 是 | 游戏屏幕方向。 0:横屏 1:竖屏 |
CloudGameOptionKeyUserId | NSString | 是 | 游戏客户端用户的唯一识别码,如果没有用户登录账号,可以随机生成长度在64以内的字符串,但需要每台客户端上的账号保证唯一性 |
CloudGameOptionKeyUserToken | NSString | 是 | 用来校验userId的有效性,如果userId为随机生成,UserToken也可以随机生成 |
CloudGameOptionKeyUserType | NSString | 是 | 用户类型。 超级账号用户:5 其他:0 默认为0 |
CloudGameOptionKeyConfigInfo | NSString | 是 | 免登使用,如果不需要免登功能,传任意非空字符串 |
CloudGameOptionKeyCToken | NSString | 是 | 用来校验参数的有效性 |
CloudGameOptionKeyPriority | NSNumber | 是 | 用户申请游戏服务的优先级,默认写0;数值越大,优先级越高 |
CloudGameOptionKeyPlayingTime | NSNumber | 是 | 用户可以玩游戏的时长,单位为ms |
CloudGameOptionKeyExtraId | NSString | 否 | 预留参数 |
CloudGameOptionKeyArchive | NSNumber | 否 | 是否存档。 0:否 1:是 |
CloudGameOptionKeyAppChannel | NSString | 否 | 游戏渠道。此参数由海马云配置且与accessKey、accessKeyID相对应,否则会返回“游戏已下架”的错误。需要注意:此参数不要与channelId(接入方自己定义,与海马云无关)混淆。 |
CloudGameOptionKeyProtoData | NSString | 否 | 数据透传字段 |
CloudGameOptionKeyBitrate | NSNumber | 否 | 开始播放的码率,单位KB |
CloudGameOptionKeyIPV6Supported | NSNumber | 否 | 是否查询IPV6地址。 0:否 1:是 默认为0 |
CloudGameOptionKeyStasticFPSInterval | NSNumber | 否 | 帧数统计时长,单位为s |
CloudGameOptionKeyStasticBandInterval | NSNumber | 否 | 流量统计时长,单位为s |
CloudGameOptionKeyStasticMaxFramesCount | NSNumber | 否 | 流量统计周期内,最大的帧的数量 |
CloudGameOptionKeyStasticDecodeInterval | NSNumber | 否 | 解码耗时统计时长,单位为s |
CloudGameOptionKeyCid | NSString | 否 | 继续未完成游戏实例(必选) |
CloudGameOptionKeyShowPoint | NSString | 否 | 自定义展示位置,例:30x0 |
CloudGameOptionKeyShowSize | NSString | 否 | 自定义展示尺寸,例:782x375 |
CloudGameOptionKeyUserType | NSString | 否 | 用户类型 |
CloudGameOptionKeyIPV6Supported | NSString | 否 | 是否支持IPV6网络,即是否需要SDK查询IPV4地址 |
CloudGameOptionKeyCidCacheInterval | NSString | 否 | 缓存cid超时时间,单位为s,默认2小时 |
CloudGameOptionKeyStreamType | CloudCoreStreamingType | 否 | 播流类型 |
CloudGameOptionKeyArchiveFromUserId | NSString | 否 | 被读取存档用户userId |
CloudGameOptionKeyarchiveFromBid | NSString | 否 | 被读取存档用户BId |
CloudGameOptionKeyComponentType | NSNumber | 否 | 组件类型:0-activity 1-service 2-broadcast 默认为0 |
CloudGameOptionKeyComponentAction | NSString | 否 | 组件对应的action |
CloudGameOptionKeyComponentName | NSString | 否 | 组件名:游戏包名 |
CloudGameOptionKeyIntentExtraData | HMIntentExtraData | 否 | 免登对象:透传参数 |
CloudGameOptionKeyResetPlayerFrame | NSString | 否 | 根据设备方向重置PlayerFrame |
特殊类型定义如下:
表3-6 CloudCoreStreamingType说明
CloudCoreStreamingType | 说明 |
---|---|
CloudCoreStreamingTypeRTMP | RTMP播流 |
CloudCoreStreamingTypeRTC | WebRtc播流 |
表3-7 HMIntentExtraData说明
HMIntentExtraData | 类型 | 必填项 | 说明 |
---|---|---|---|
booleanExtra | NSDictionary | 否 | 添加Boolean |
integerExtra | NSDictionary | 否 | 添加Integer |
integerArrayExtra | NSDictionary | 否 | 添加Integer数组 |
integerListExtra | NSDictionary | 否 | 添加Integer List |
stringExtra | NSDictionary | 否 | 添加String |
stringArrayExtra | NSDictionary | 否 | 添加String数组 |
stringListExtra | NSDictionary | 否 | 添加String List |
floatExtra | NSDictionary | 否 | 添加Float |
floatArrayExtra | NSDictionary | 否 | 添加Float数组 |
floatListExtra | NSDictionary | 否 | 添加Float List |
longExtra | NSDictionary | 否 | 添加Long |
longArrayExtra | NSDictionary | 否 | 添加Long数组 |
longListExtra | NSDictionary | 否 | 添加Long List |
componentNameExtra | NSDictionary | 否 | 添加组件名componentName |
uriExtra | NSDictionary | 否 | 添加uri |
appLink | NSString | 否 | 添加appLink |
函数原型:
/**
HMIntentExtraData对象赋值
*/
HMIntentExtraData *intentExtraData = [[HMIntentExtraData alloc] init];
NSDictionary *dic = @{@"Viable":@(1), @"Enable":@(0)};
intentExtraData.booleanExtra = dic;
[options setObject:intentExtraData forKey:CloudGameOptionKeyIntentExtraData];
3.6 开始游戏
函数原型:
/**
开始游戏
*/
- (void) play;
4 API 接口
4.1 暂停游戏接口
函数原型:
/**
暂停游戏
*/
- (void) pause;
4.2 继续游戏接口
函数原型:
/**
继续云游戏
@param playingTime 恢复后的时长,单位:ms
*/
- (void) resume:(NSInteger)playingTime;
表4-1 参数说明
参数 | 类型 | 说明 |
---|---|---|
playingTime | NSInteger | 恢复后的游戏时长,单位为ms |
4.3 停止游戏接口
函数原型:
/**
停止游戏
*/
- (void) stop;
/**
停止游戏,退出游戏界面
@param animated 和presentViewController 的 animated 值一致
*/
- (void) stopAndDismiss:(BOOL)animated;
4.4 设置背景图接口
函数原型:
/**
设置背景图
*/
- (void)setBackgroundImage:(UIImage *)bgImage;
表4-2 参数说明
参数 | 类型 | 说明 |
---|---|---|
bgImage | UIImage | 要显示的背景图 |
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-3 参数说明
参数 | 类型 | 说明 |
---|---|---|
cmd | HMCloudPlayerKeyCommand | 要发送的按键 |
updateUserOperationTime | BOOL | 是否更新用户最后操作时间 |
表4-4 HMCloudPlayerKeyCommand说明
HMCloudPlayerKeyCommand | 说明 |
---|---|
CloudPlayerKeyCommandBackGame | 在非游戏界面发送该指令,返回游戏 |
CloudPlayerKeyCommandEmptyTouch | 发送空操作指令,重置用户无操作定时器 |
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-5 参数说明
参数 | 类型 | 必填项 | 说明 |
---|---|---|---|
pkgName | NSString | 是 | 游戏包名称 |
appChannel | NSString | 否 | 游戏渠道 |
streamingType | CloudCoreStreamingType | 是 | 流类型 |
success | Block | 否 | 查询成功后的回调 返回游戏配置的清晰度列表 |
fail | Block | 否 | 查询失败后的回调 |
4.7 路由节点查询接口
函数原型:
/**
IDC路由查询
@param success 查询成功回调
@param fail 查询失败回调
@return 是否开始查询
*/
- (BOOL) idcQuery:(void (^)(NSString *url, NSString *ipAddress))success
fail:(void (^)(NSString *errorCode))fail;
表4-6 参数说明
参数 | 类型 | 必填项 | 说明 |
---|---|---|---|
fail | Block | 否 | 查询失败后的回调 |
success | Block | 否 | 查询成功后的回调 返回测速文件地址、路由IP |
4.8 获取用户最后操作时间戳接口
函数原型:
/**
获取用户最后一次操作时间
@return 用户最后操作时间戳,单位ms
*/
- (long long) getLastUserOperationTimestamp;
4.9 获取云游戏延迟信息接口
通过该接口会返回当前云游戏的网络延迟信息,该算法的准确性基于APP和实例的时钟校准。
函数原型:
/**
获取云游戏延迟信息
@return 云游戏延迟,单位ms
*/
- (NSInteger) getVideoLatency;
4.10 测速接口
检测实例到云端的速度。
函数原型:
/**
IDC节点测速
@param seconds 最大测速时长,单位为s
@param success 测速成功回调
@param fail 测速失败回调
@return 是否开始测速
*/
- (BOOL) speedTest:(NSInteger)seconds
success:(void (^)(int))success
fail:(void (^)(NSString *errorCode))fail;
表4-7 参数说明
参数 | 类型 | 说明 |
---|---|---|
seconds | NSInteger | 最大测速时长,单位为 |
success | Block | 测速成功后的回调,单位为KB/s |
fail | Block | 测速失败后的回调 |
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-8 参数说明
参数 | 类型 | 必填项 | 说明 |
---|---|---|---|
userId | NSString | 是 | 游戏客户端用户的唯一识别码,如果没有用户登录账号, 可以随机生成长度在64以内的字符串,但需要每台客户端上的账号保证唯一性 |
userToken | NSString | 是 | 用来校验userId的有效性,如果userId为随机生成,UserToken也可以随机生成 |
ctoken | NSString | 是 | 用来校验参数的有效性 |
playingTime | NSNumber | 是 | 游戏时长,单位:ms |
tip | NSString | 否 | 游戏时长更新提示话术 |
protoData | NSString | 否 | 数据透传字段 |
success | Block | 是 | 更新成功后的回调。 successed:YES表示“更新成功“, NO表示“更新失败” |
fail | Block | 是 | 更新失败后的回调 |
4.12 SDK发送消息接口
向云端发送消息。
函数原型:
/**
发送消息
@param message 消息内容
*/
- (void) sendMessage:(NSString *)message;
表4-9 参数说明
参数 | 类型 | 必填项 | 说明 |
---|---|---|---|
message | NSString | 是 | 消息内容 |
4.13 手动切换清晰度接口
函数原型:
/**
手动切换清晰度
@param resolutionId 目标清晰度ID
*/
- (void) switchResolution:(NSInteger)resolutionId;
表4-10 参数说明
参数 | 类型 | 必填项 | 说明 |
---|---|---|---|
resulotionId | NSString | 是 | 清晰度ID |
4.14 进入队列接口
函数原型:
/**
确认进入排队队列
*/
- (void) confirmQueue;
4.15 开启网络监控接口
函数原型:
/**
开始网络状态监控
@param block 回调通知
*/
- (void) startNetMonitor:(void (^)(CloudCorePlayerNetStatus status))block;
表4-11 参数说明
参数 | 类型 | 说明 |
---|---|---|
block | Block | 网络状态变更回调 。 NetStatusUnknown:未知 NetStatusNotReachable:不可达 NetStatusReachableViaWWAN:移动网络可达 NetStatusReachableViaWiFi:Wi-Fi网络可达 |
4.16 停止网络监控接口
函数原型:
/**
停止网络状态监控
*/
- (void) stopNetMonitor;
4.17 静音功能接口
函数原型:
/**
视频静音开关
@param mute; true为静音,false恢复声音
*/
- (void) setAudioMute:(BOOL)mute;
4.18 关闭游戏内本地键盘功能接口
函数原型:
/**
关闭本地键盘
*/
- (void)hiddenKeyboard;
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-1 参数说明
参数 | 类型 | 必填项 | 说明 |
---|---|---|---|
userId | NSString | 是 | 游戏客户端用户的唯一识别码,如果没有用户登录账号,可以随机生成长度在64以内的字符串,但需要每台客户端上的账号保证唯一性 |
userToken | NSString | 是 | 用来校验userId的有效性,如果userId为随机生成,UserToken也可以随机生成 |
pkgName | NSString | 是 | 游戏包名称 |
appChannel | NSString | 否 | 游戏渠道 |
success | Block | 否 | 查询成功后的回调。 finished:YES表示“存档完成“, NO表示“存档中” |
fail | Block | 否 | 查询失败后的回调 |
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-2 参数说明
参数 | 类型 | 必填项 | 说明 |
---|---|---|---|
userId | NSString | 是 | 游戏客户端用户的唯一识别码,如果没有用户登录账号,可以随机生成长度在64以内的字符串,但需要每台客户端上的账号保证唯一性 |
userToken | NSString | 是 | 用来校验userId的有效性,如果userId为随机生成,UserToken也可以随机生成 |
pkgName | NSString | 是 | 游戏包名称 |
appChannel | NSString | 否 | 游戏渠道 |
success | Block | 否 | 查询成功后的回调。 finished:YES表示“存档完成“, NO表示“存档中” |
fail | Block | 否 | 查询失败后的回调 |
5.3 检测未释放游戏实例接口
函数原型:
/**
查询是否有上次未释放的游戏实例
@param (NSArray <HMCloudPlayerReservedSingleIncetance*>*) 未释放游戏实例数组
*/
typedef void (^HMReservedIncetanceCallback)(NSArray <HMCloudPlayerReservedSingleIncetance*>*);
/**
@param options 游戏参数
{@"CloudGameOptionKeyUserId":@"...", @"CloudGameOptionKeyUserToken":"...",}
@param reservedIncetance 查询驻留机回调方法,包含驻留机数组
*/
- (void) getReservedInstance:(NSDictionary *)options ReservedIncetance:(HMReservedIncetanceCallback)reservedIncetance;
表5-3 HMCloudPlayerReservedSingleIncetance说明
参数 | 类型 | 说明 |
---|---|---|
cid | NSString | 用户使用云游戏服务的唯一标识 |
pkgName | NSString | 游戏包名 |
gameName | NSString | 游戏名称 |
appChannel | NSString | 渠道号 |
5.4 获取延迟信息接口
获取某一秒的延迟信息。
函数原型:
/**
获取某一秒延迟信息
@return 包含延迟信息的HMDelayInfoModel
*/
- (HMDelayInfoModel *) getDelayInfo;
表5-3 参数说明
参数 | 类型 | 说明 |
---|---|---|
HMDelayInfoModel | HMDelayInfoModel | HMDelayInfoModel 属性的含义。 collectTime:收集延迟信息时的时间戳,单位:ms netDelayTime:网络延迟时间,单位:ms decodeDelayTime:解码耗时,单位:ms renderDelayTime:渲染耗时,单位:ms aFrameDelayTime:单帧耗时,单位:ms nowDelayTime:采集某一帧到当前时间的耗时,单位:ms frameNowSize:帧大小 showFps:展示帧率 gameFps:推流帧率 bitRate:码率 pingpongCostTime:pingpong耗时,单位:ms |
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-4 参数说明
参数 | 类型 | 说明 |
---|---|---|
cid | NSString | 要释放的cid |
cToken | NSString | 用来校验参数的有效性 |
userId | NSString | 用户登录ID |
userToken | NSString | 用户登录令牌 |
pkgName | NSString | 游戏包名称 |
appChannel | NSString | 如果存在多款游戏同包名的情况,可以通过appChannel区分。如果不存在则可以忽略。 |
success | Block | 释放成功回调 |
fail | Block | 释放失败回调 |
5.6 开启直播接口
函数原型:
/**
游戏过程中,开启直播
@param livingId 直播唯一标识,必填,不能为NULL
@param pushStreamUrl 第三方推流地址,必填,不能为NULL
@return 请求调用“开启直播”是否成功
*/
- (BOOL) startLivingWithLivingId:(NSString *)livingId pushStreamUrl:(NSString *)pushStreamUrl;
返回值YES/NO仅表示请求调用的结果,由于开启直播是个异步过程,最终开启直播成功与否请参见直播场景回调。
表5-5 参数说明
参数 | 类型 | 说明 |
---|---|---|
livingId | NSString | 直播ID |
livingUrl | NSString | 直播地址 |
5.7 停止直播接口
函数原型:
/**
游戏过程中,关闭直播
@param livingId 直播间ID,必填,不能为NULL
@return 请求调用“停止直播”是否成功
*/
- (BOOL) stopLivingWithLivingId:(NSString *)livingId;
返回值YES/NO仅表示请求调用的结果,由于停止直播是个异步过程,最终停止成功与否请参见直播场景回调。
5.8 获取授权码接口
函数原型:
/**
获取授权码,控制端同意转让控制权后调用
@return 是否开始获取授权码
*/
- (BOOL) getAuthCode;
返回值YES/NO仅表示请求调用的结果,由于获取授权码是个异步过程,最终获取授权码成功与否请参见控制权转移场景回调。
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;
返回值YES/NO仅表示请求调用的结果,由于获取控制权是个异步过程,最终获取控制权成功与否请参见控制权转移场景回调。
表5-6 参数说明
参数 | 类型 | 说明 |
---|---|---|
cid | NSString | 控制端cid |
authCode | NSString | 授权码 |
streamType | CloudCoreStreamingType | 流类型 |
accessKeyID | NSString | 控制端bid |
clientISP | NSString | 运营商 |
clientProvince | NSString | 省份 |
clientCity | NSString | 城市 |
5.10 查询是否支持直播接口
函数原型:
/**
查询是否支持直播的方法,建议APP调用时机为收到第一帧回调之后
@return 是否支持直播枚举结果
*/
- (ELivingCapabilityStatus) getLivingCapabilityStatus;
表5-7 返回值定义
枚举返回值类型 | 返回值 |
---|---|
ELivingCapabilityStatus | LivingUnknown |
LivingUnSupported | 不支持直播 |
LivingSupported | 支持直播 |
5.11 停止云游戏接口
此接口支持配置最小云玩存档时间。
无动画停止云游戏,函数原型:
/** 停止云游戏 @param seconds 存档时长,必填 单位为s */ - (void) stop:(int)seconds;
停止云游戏带动画,函数原型:
/** 停止云游戏带动画 @param archiveMinSeconds 存档时长,必填 单位为s */ - (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,游戏视频界面被点击,可用于收起已经展开的非全屏设置界面。
函数原型:
(void) cloudPlayerTouchBegan;
6.2 场景切换回调
方法名为cloudPlayerSceneChangedCallback,回调参数字典说明:
{
"sceneId": "init",
"extraInfo": {}
}
6.2.1 参数说明
表6-1 字典Key说明
字典Key | 类型 | 说明 |
---|---|---|
sceneId | NSString | 回调场景ID,取值及含义如下。 init:初始化场景 data:配置数据场景,如清晰度列表 prepare:准备云游戏场景 playerState:游戏过程中,状态变化场景 queue:排队场景 playingtime:游戏时长场景 resolution:播流清晰度场景 stastic:数据统计场景 maintance:服务器维护场景 |
extraInfo | NSDictionary | 场景ID对应的扩展信息 |
6.2.2 初始化场景说明
字典Key示例:
/**
state = success
*/
{
"sceneId": "init",
"extraInfo":
{
"state": "success"
}
}
/**
state = failed
*/
{
"sceneId": "init",
"extraInfo":
{
"state": "failed",
"errorCode": "100104001",
"errorCodeWithoutCid": "100104001"
}
}
表6-2 字典Key说明
字典Key | 类型 | 说明 |
---|---|---|
state = success | NSString | 初始化成功 |
state = failed | NSString | 初始化失败 |
errorCode | NSString | 失败的errorCode |
errorCodeWithoutCid | NSString | 不包含cid的errorCode |
6.2.3 配置数据场景
字典Key示例:
/**
type = titleVideo
*/
{
"sceneId": "data",
"extraInfo":
{
"type": "titleVideo",
"data":
{
"name": "...",
"url": "...",
"version": "..."
}
}
}
/**
type = resolutions
*/
{
"sceneId": "data",
"extraInfo":
{
"type": "resolutions",
"data":
[
##清晰度列表##
]
}
}
/**
type = loadingTips
*/
{
"sceneId": "data",
"extraInfo":
{
"type": "loadingTips",
"data":
{
"revolveTime": 4000,
"tips":
[
##Tips列表##
]
}
}
}
/**
type = message
*/
{
"sceneId": "data",
"extraInfo":
{
"type": "message",
"data": "##消息内容##"
}
}
/**
type = speed
*/
{
"sceneId": "data",
"extraInfo":
{
"type": "speed",
"data":
{
"url": "...",
"time": 5,
"rateCoef": 1.0,
"standCoef": 0.8,
"skip": 0
}
}
}
表6-3 字典Key说明
字典Key | 类型 | 说明 |
---|---|---|
type = titleVideo | NSString | 片头信息 |
type = resolutions | NSString | 清晰度列表 |
type = loadingTips | NSString | Loading界面Tips revolveTime为轮播时间,单位为ms |
type = message | NSString | 收到消息 |
type = speed | NSString | 测速信息配置 time为最大测速时长,单位为s |
6.2.4 准备云游戏场景
字典Key示例:
/**
state = success
*/
{
"sceneId": "prepare",
"extraInfo":
{
"state": "success"
}
}
/**
state = success
*/
{
"sceneId": "prepare",
"extraInfo":
{
"state": "failed",
"errorCode": "100000001",
"errorCodeWithoutCid": "100104001"
}
}
表6-4 字典Key说明
字典Key | 类型 | 说明 |
---|---|---|
state = success | NSString | 准备成功,之后才可以调用play方法播流 |
state = failed | NSString | 准备失败 |
errorCode | NSString | 准备失败的errorCode |
errorCodeWithoutCid | NSString | 不包含cid的errorCode |
6.2.5 云游戏状态变化场景
字典Key示例:
/**
state = prepared
*/
{
"sceneId": "playerState",
"extraInfo":
{
"state": "prepared"
}
}
/**
state = videoVisible
*/
{
"sceneId": "playerState",
"extraInfo":
{
"state": "videoVisible"
}
}
/**
state = stopped
*/
{
"sceneId": "playerState",
"extraInfo":
{
"state": "stopped",
"stop_reason": "",
"open_api_release_instance" : "",
"errorCode": "200211005-716971087",
"errorCodeWithoutCid" :"200211005",
"errorMsg": "##错误描述",
"queues":
[
#参考排队场景说明#
],
}
}
/**
state = timeout
*/
{
"sceneId": "playerState",
"extraInfo":
{
"state": "timeout",
"tip": "##提示内容##"
}
}
/**
state = refreshSToken
*/
{
"sceneId": "playerState",
"extraInfo":
{
"state": "refreshSToken"
}
}
/**
state = playFailed
*/
{
"sceneId": "playerState",
"extraInfo":
{
"state": "playFailed",
"errorCode": "100000001-716971087",
"errorCodeWithoutCid" :"100000001"
}
}
/**
state = idcInfo
*/
{
"sceneId": "playerState",
"extraInfo":
{
"state": "idcInfo",
"idcId": "",
"idcName": "",
"instanceTag":"",
"instanceTagName":""
}
}
表6-5 字典Key说明
字典Key | 类型 | 说明 |
---|---|---|
state = prepared | NSString | 实例申请完成,继续显示Loading |
state = videoVisible | NSString | 视频第一帧到达 |
state = stopped | NSString | 云游戏结束。 stop_reason见下表。 当stop_reason为time_limit时,返回的extralInfo参数里会增加open_api_release_instance字段,此字段value为APP端调用openAPI释放实例时的原因,此value可能为空 |
state = timeout | NSString | 游戏时间到,结束游戏 |
state = refreshSToken | NSString | 刷新SToken,显示Loading |
state = playFailed | NSString | 调用play方法失败 |
state = idcInfo | NSString | IDC信息回调 |
errorCode | NSString | 失败时的errorCode |
errorCodeWithoutCid | NSString | 不包含cid的errorCode |
表6-6 stop_reason取值说明
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 | 内部错误 |
6.2.6 游戏时长场景
字典Key示例:
/**
state = prompt
*/
{
"sceneId": "playingtime",
"extraInfo":
{
"state": "prompt",
"second": 12000,
"title": "##时长提示##",
"countdown": 1
}
}
/**
state = totaltime
*/
{
"sceneId": "playingtime",
"extraInfo":
{
"state": "totaltime",
"second": 12000,
"title": "##总时长提示##"
}
}
/**
state = update
*/
{
"sceneId": "playingtime",
"extraInfo":
{
"state": "update",
"title": "##时长更新提示##"
}
}
表6-7 字典Key说明
字典Key | 类型 | 说明 |
---|---|---|
state = prompt | NSString | 游戏剩余时长提示 countdown==1,表示为倒计时显示 title中占位符为”|”,否则title为显示内容 second为游戏剩余时长,单位为s |
state = totaltime | NSString | 游戏总时长提示 second 为游戏总时长秒数 |
state = update | NSString | 游戏过程中,时长更新 |
6.2.7 播流清晰度场景
字典Key示例:
/**
type = crst
*/
{
"sceneId": "resolution",
"extraInfo":
{
"type": "crst",
"source": 1,
"des": 3,
"method": 1,
"title": "##提示##"
}
}
/**
type = cred
*/
{
"sceneId": "resolution",
"extraInfo":
{
"type": "cred",
"cur_rate": 1,
"result": 1,
"title": "##提示##"
}
}
/**
type = crtp
*/
{
"sceneId": "resolution",
"extraInfo":
{
"type": "crtp",
"minimum": 1,
"delay_less_minimum": 1,
"title": "##提示##"
}
}
/**
type = notify
*/
{
"sceneId": "resolution",
"extraInfo":
{
"type": "notify",
"cur_rate": 1
}
}
表6-8 字典Key说明
字典Key | 类型 | 说明 |
---|---|---|
type = crst | NSString | 开始切换清晰度。 source:当前清晰度ID des:目标清晰度ID method:1表示“自动“,0表示“手动” |
type = cred | NSString | 清晰度切换完成。 cur_rate:切换后的清晰度ID result:1表示“成功”,0表示“失败” |
type = crtp | NSString | 游戏卡断,建议用户切换清晰度。 minimum:是否已经在最低码率,1表示“是”, 0表示“否” |
type = notify | NSString | 播流清晰度通知 |
6.2.8 数据统计场景
字典Key示例:
/**
type = bandwidth
*/
{
"sceneId": "playingtime",
"extraInfo":
{
"state": "prompt",
"second": 12000,
"title": "##时长提示##",
"countdown": 1
}
}
/**
type = frames
*/
{
"sceneId": "stastic",
"extraInfo":
{
"type": "frames",
"value": 332
}
}
/**
type = frames
*/
{
"sceneId": "stastic",
"extraInfo":
{
"type": "decode",
"value": 9
}
}
表6-9 字典Key说明
字典Key | 类型 | 说明 |
---|---|---|
type = bandwidth | NSString | 带宽使用数据。 value : 统计时段内字节数 frames : 统计时段内最大N帧字节数 |
type = frames | NSString | 帧数统计数据。 value : 统计时段内总帧数 |
type = decode | NSString | 解码耗时统计。 value : 统计时段内平均解码耗时,单位ms |
6.2.9 排队场景
字典Key示例:
/**
state = confrim
*/
{
"sceneId": "queue",
"extraInfo":
{
"state": "confrim",
"title": "##排队提示##",
"index": 3,
"queues": []
}
}
/**
state = update
*/
{
"sceneId": "queue",
"extraInfo":
{
"state": "update",
"title": "##排队提示##",
"index": 3,
"second": 300,
"timeStr": “五分钟”,
"queues": []
}
}
/**
state = entering
*/
{
"sceneId": "queue",
"extraInfo":
{
"state": "entering",
"title": "##排队提示##"
}
}
表6-10 字典Key说明
字典Key | 类型 | 说明 |
---|---|---|
state = confrim | NSString | 提醒用户需要排队。 index : 当前排队人数 queues : 多队列排队信息 |
state = update | NSString | 排队进度更新。 index : 当前排队人数 second : 预计剩余秒数 queues : 多队列排队信息 |
state = entering | NSString | 排队成功,即将进入游戏 |
表6-11 多队列排队数据项说明
字典Key | 类型 | 说明 |
---|---|---|
rank | NSInteger | 队列等级 |
index | NSInteger | 当前排队人数 |
second | NSInteger | 预计剩余秒数 |
timeStr | NString | 预计排队描述格式化的字符串 |
priorities | NSArray<NSNumber *> | 当前队列包含的用户优先级列表 |
6.2.10 维护场景
字典Key示例:
/**
progress = soon
*/
{
"sceneId": "maintance",
"extraInfo":
{
"progress": "soon",
"title": "##维护提示##",
"timeStr": "五分钟"
}
}
/**
progress = start
*/
{
"sceneId": "maintance",
"extraInfo":
{
"progress": "start",
"title": "##维护提示##"
}
}
/**
progress = inprogress
*/
{
"sceneId": "maintance",
"extraInfo":
{
"progress": "inprogress",
"title": "##维护提示##",
"timeStr": "五分钟"
}
}
/**
progress = inprogress
*/
{
"sceneId": "maintance",
"extraInfo":
{
"progress": "inprogress",
"title": "##维护提示##",
"timeStr": "五分钟"
}
}
/**
progress = done
*/
{
"sceneId": "maintance",
"extraInfo":
{
"progress": "done",
"title": "##维护提示##"
}
}
表6-12 字典Key说明
字典Key | 类型 | 说明 |
---|---|---|
progress = soon | NSString | 游戏中用户,收到即将维护的提示 |
progress = start | NSString | 开始维护 |
progress = inprogress | NSString | 维护中 |
progress = done | NSString | 维护完成 |
6.2.11 无输入提示场景
字典Key示例:
/**
state = remindtime
*/
{
"sceneId": "noinput",
"extraInfo":
{
"state": "remindtime",
"second": 12000,
"title": "##剩余时长提示##",
}
}
表6-13 字典Key说明
字典Key | 类型 | 说明 |
---|---|---|
state = remindtime | NSString | 在无输入情况下游戏剩余时长提示,title中占位符为 | ;否则title为显示内容。 second为游戏剩余时长,单位为s |
6.2.12 直播场景
字典Key示例:
/**
state = startSuccess
*/
{
"sceneId": "living",
"extraInfo":
{
"state": "startSuccess",
}
}
/**
state = startFailed
*/
{
"sceneId": "living",
"extraInfo":
{
"state": "startFailed",
"errorCode": "100000001",
"errorCodeWithoutCid":"100000001"
}
}
/**
state = stopSuccess
*/
{
"sceneId": "living",
"extraInfo":
{
"state": "startFailed",
}
}
/**
state = stopFailed
*/
{
"sceneId": "living",
"extraInfo":
{
"state": "startFailed",
"errorCode": "100000001",
"errorCodeWithoutCid":"100000001"
}
}
表6-14 字典Key说明
字典Key | 类型 | 说明 |
---|---|---|
state = startFailed | NSString | 直播开始失败 |
state = stopSuccess | NSString | 停止成功 |
state = stopFailed | NSString | 停止失败 |
6.2.13 控制权转移场景
字典Key示例:
/**
state = authcodeSuccess
*/
{
"sceneId": "control",
"extraInfo":
{
"state": "authcodeSuccess",
"authcode":"skjdksd"
"masterCid:"ijsdhkk"
}
}
/**
state = authcodeFailed
*/
{
"sceneId": "control",
"extraInfo":
{
"state": "authcodeFailed",
"errorCode": "200217001" ,
"errorCodeWithoutCid":"200217001",
"errorMsg":"服务异常,未生成授权码"
}
}
/**
state = loseControl
*/
{
"sceneId": "control",
"extraInfo":
{
"state": "loseControl",
"followCid":"d2434e",
"uid":"h33333"
}
}
/**
state = gainControlSuccess
*/
{
"sceneId": "control",
"extraInfo":
{
"state": "gainControlSuccess"
}
}
/**
state = gainControlFailed
*/
{
"sceneId": "control",
"extraInfo":
{
"state": "gainControlFailed",
"errorCode":"200217001",
"errorCodeWithoutCid":"200217001",
"errorMsg":"服务异常,未生成授权码"
}
}
表6-15 字典Key说明
字典Key | 类型 | 说明 |
---|---|---|
state = authcodeSuccess | NSString | 获取授权码成功 |
state = authcodeFailed | NSString | 获取授权码失败 |
state = loseControl | NSString | 失去控制 |
state = gainControlSuccess | NSString | 获取控制权成功 |
state = gainControlFailed | NSString | 获取控制权失败 |
6.3 系统隐私权限判断
方法名cloudPlayerUsageAuthorization,函数原型:
/**
系统隐私权限判断
@param type 隐私权限类型;
@param success 授权情况回调;
*/
- typedef NS_ENUM(NSInteger, HMCloudPlayerUsageAuthorization){
HMCloudPlayerUsageAuthorizationMicrophone = 0, //麦克风权限回调
};
(void) cloudPlayerUsageAuthorization:(HMCloudPlayerUsageAuthorization)type success:(void (^)(BOOL authorization))success;
表6-16 参数说明
参数 | 类型 | 必填项 | 说明 |
---|---|---|---|
HMCloudPlayerUsageAuthorization | HMCloudPlayerUsageAuthorization | 是 | HMCloudPlayerUsageAuthorizationMicrophone:麦克风权限 |
success | Block | 是 | if(success){ success(isGranted); } isGranted为设备隐私权限授权结果,回调SDK |