iOS SDK 开发指南
版本号:master-4.8.1
1 文档概述
欢迎使用海马云游戏服务,本文档主要介绍云游戏iOS端SDK的接入流程及提供支持的API详情,开发者通过接入海马云游戏SDK,可以实现云游戏的播放、停止、状态回调等各类控制操作和数据交互,在海马云游戏端到端全栈云服务能力基础上,为用户带来顺畅的云游戏体验。在开始接入SDK前,请确认您已经拥有海马云游戏平台接入商ID并创建了渠道号,并已经完成了在海马云游戏平台上传游戏包等相关准备工作。
2 集成 SDK
云玩 SDK 为 HMCloudPlayerCore.framework
- SDK 系统支持条件 iOS 8.0 及以上
- SDK 接入后需使用真机运行,不支持模拟器
- SDK 演示demo 请使用自己的开发者账号和bundleid 到真机演示
- SDK 中使用 http 请求的,请在 App Demo 中 info.plist 添加 App Transport Security Settings –> Allow Arbitrary Loads -> YES
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
- 将 HMCloudPlayerCore.framework 复制到项目文件夹下。
- 打开 Xcode(以 Xcode 11.0 为例),进入 TARGETS > Project Name > General > Frameworks, Libraries, and Embedded Content 菜单,点击 +,再点击 Add Other… 添加 HMCloudPlayerCore.framework 。添加完成后,项目会自动链接其他系统库。为保证动态库的签名和 app 的签名一致,你需要将动态库的 Embed 属性设置为 Embed & Sign。
3 快速入门
3.1 导入头文件
#import <HMCloudPlayerCore/HMCloudPlayer.h>
3.2 创建单例
/**
* 生成一个单例
*/
+ (instancetype) sharedCloudPlayer;
3.3 配置SDK连接地址接口
在调用注册SDK接口前,调用该接口,可以指定 SDK 连接地址信息;在调用注册SDK接口后,调用该接口,会返回失败。
/**
配置云游戏连接信息;该方法在创建单例后第一时间调用
@param info 连接信息 AUTH / Countly / Link
@return 是否成功 //参数类型非法,或者已经请求过SAAS地址,均返回失败。
*/
- (BOOL) config:(NSDictionary *)info;
参数说明
参数 | 类型 | 说明 |
---|---|---|
info | NSDictionary | 连接地址信息 |
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;
参数 | 类型 | 说明 |
---|---|---|
accessKeyID | NSString | 接入商唯一ID |
channelId | NSString | 渠道号,由接入商配置。如果应用本身不区分渠道,可以设置为一个随机值的字符串 |
options | NSDictionary | iOS App启动选项,在 didFinishLaunching 方法中由系统传入 |
3.5 准备游戏
接口会返回一个UIViewController, APP 需通过 present 或 push 方法将其展示在界面上。
/**
准备游戏
@param options 游戏参数
@return 云游戏ViewController
*/
- (UIViewController *) prepare:(NSDictionary *)options;
参数说明
参数 | 类型 | 说明 |
---|---|---|
options | NSDictionary | 游戏信息 |
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 | 游戏渠道 | 可选 |
CloudGameOptionKeyProtoData | NSString | 数据透传字段 | 可选 |
CloudGameOptionKeyBitrate | NSNumber | 开始播放的码率,单位KB | 可选 |
CloudGameOptionKeyIPV6Supported | NSNumber | 是否查询IPV6地址,0-否 1-是,默认为0 | 可选 |
CloudGameOptionKeyStasticFPSInterval | NSNumber | 帧数统计时长,单位:秒 | 可选 |
CloudGameOptionKeyStasticBandInterval | NSNumber | 流量统计时长,单位:秒 | 可选 |
CloudGameOptionKeyStasticMaxFramesCount | NSNumber | 流量统计周期内,最大的帧的数量 | 可选 |
CloudGameOptionKeyStasticDecodeInterval | NSNumber | 解码耗时统计时长,单位:秒 | 可选 |
CloudGameOptionKeyCid | NSString | 继续未完成游戏实例时(必选) | 可选 |
3.6 开始游戏
/**
开始游戏
*/
- (void) play;
4 API 接口
4.1 暂停游戏
/**
暂停游戏
*/
- (void) pause;
4.2 恢复游戏
/**
恢复云游戏
@param playingTime 恢复后的时长,单位:ms
*/
- (void) resume:(NSInteger)playingTime;
参数说明
参数 | 类型 | 说明 |
---|---|---|
playingTime | NSInteger | 恢复后的游戏时长,单位:ms |
4.3 停止游戏
/**
停止游戏
*/
- (void) stop;
/**
停止游戏,退出游戏界面
@param animated 和presentViewController 的 animated 值一致
*/
- (void) stopAndDismiss:(BOOL)animated;
4.4 设置背景图
/*
* 设置背景图
*/
- (void)setBackgroundImage:(UIImage *)bgImage;
参数说明
参数 | 类型 | 说明 |
---|---|---|
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;
参数说明
参数 | 类型 | 说明 |
---|---|---|
cmd | HMCloudPlayerKeyCommand | 要发送的按键 |
updateUserOperationTime | BOOL | 是否更新用户最后操作时间 |
枚举值 | 说明 |
---|---|
CloudPlayerKeyCommandBackGame | 在非游戏界面发送该指令,返回游戏 |
CloudPlayerKeyCommandEmptyTouch | 发送空操作指令,重置用户无操作定时器 |
4.6 游戏维度清晰查询接口
/**
查询游戏配置信息(目前版本仅支持清晰度查询)
@param pkgName 必填,不能为NULL
@param appChannel 选填,可为NULL
@param success 游戏配置的清晰度列表
@param fail 查询失败回调
@return 是否开始查询
*/
- (BOOL) gameParamsQuery:(NSString *)pkgName
appChannel:(NSString *)appChannel
success:(void (^)(NSArray<HMCloudPlayerResolution *> *))success
fail:(void (^)(NSString *errorCode))fail;
参数说明
参数 | 类型 | 说明 | 选项 |
---|---|---|---|
pkgName | NSString | 游戏包名称 | 必选 |
appChannel | NSString | 游戏渠道 | 可选 |
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;
参数说明
参数 | 类型 | 说明 | 选项 |
---|---|---|---|
fail | Block | 查询失败后的回调 | 可选 |
success | Block | 查询成功后的回调 返回测速文件地址、路由IP |
可选 |
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;
参数说明
参数 | 类型 | 说明 |
---|---|---|
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;
参数说明
参数 | 类型 | 说明 | 选项 |
---|---|---|---|
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;
参数说明
参数名称 | 类型 | 说明 | 选项 | |
---|---|---|---|---|
message | NSString | 消息内容 | 必选 |
4.13 手动切换清晰度
/**
手动切换清晰度
@param resolutionId 目标清晰度ID
*/
- (void) switchResolution:(NSInteger)resolutionId;
参数说明
参数名称 | 类型 | 说明 | 选项 | |
---|---|---|---|---|
resulotionId | NSString | 清晰度ID | 必选 |
4.14 进入排队
/**
确认进入排队队列
*/
- (void) confirmQueue;
4.15 开启网络监控
/**
开始网络状态监控
@param block 回调通知
*/
- (void) startNetMonitor:(void (^)(CloudCorePlayerNetStatus status))block;
参数说明
参数名称 | 类型 | 说明 |
---|---|---|
block | Block | 网络状态变更回调 NetStatusUnknown : 未知 NetStatusNotReachable : 不可达 NetStatusReachableViaWWAN : 移动网络可达 NetStatusReachableViaWiFi : Wi-Fi网络可达 |
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;
参数说明
参数 | 类型 | 说明 | 选项 |
---|---|---|---|
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;
参数说明
参数 | 类型 | 说明 | 选项 |
---|---|---|---|
userId | NSString | 游戏客户端用户的唯一识别码,如果没有用户登陆账号, 可以随机生成长度在64以内的字符串,但需要每台客户端上的账号保证唯一性 |
必选 |
userToken | NSString | 用来校验userId的有效性,如果userId为随机生成,UserToken也可以随机生成 | 必选 |
pkgName | NSString | 游戏包名称 | 必选 |
appChannel | NSString | 游戏渠道 | 可选 |
success | Block | 查询成功后的回调 finished - YES:存档完成; NO:存档中 |
可选 |
fail | Block | 查询失败后的回调 | 可选 |
5.3 获取未释放的游戏实例
/**
查询是否有上次未完成的游戏实例
@param options 游戏参数 {@"CloudGameOptionKeyUserId":@"...", @"CloudGameOptionKeyUserToken":"...",}
@param reservedIncetance 查询驻留机回调方法,包含驻留机数组
*/
- (void) getReservedInstance:(NSDictionary *)options ReservedIncetance:(HMReservedIncetanceCallback)reservedIncetance;
5.4 获取延迟检测信息
/**
获取某一秒延迟检测信息
@return 包含延迟信息的HMDelayInfoModel
*/
- (HMDelayInfoModel *) getDelayInfo;
参数说明
参数名称 | 类型 | 说明 |
---|---|---|
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;
参数说明
参数 | 类型 | 说明 |
---|---|---|
cid | NSString | 要释放的cid |
cToken | NSString | 用来校验参数的有效性 |
userId | NSString | 用户登录信息 userId |
userToken | NSString | 用户登录信息 userToken |
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;
参数说明
参数 | 类型 | 说明 |
---|---|---|
livingId | NSString | 直播ID |
livingUrl | NSString | 直播地址 |
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
@return 是否开始获取控制权
*/
- (BOOL) gainControlWithMasterCid:(NSString *)cid authCode:(NSString *)authCode extraInfo:(NSString *)extraInfo;
参数说明
参数 | 类型 | 说明 |
---|---|---|
cid | NSString | cid |
authCode | NSString | 授权码 |
5.10 查询是否支持直播
/**
查询是否支持直播的方法,建议APP调用时机为收到第一帧回调之后
@return 是否支持直播枚举结果
*/
- (ELivingCapabilityStatus) getLivingCapabilityStatus;
返回值定义
枚举返回值类型 | 返回值 | 说明 |
---|---|---|
ELivingCapabilityStatus | LivingUnknown | |
LivingUnSupported | 不支持直播 | |
LivingSupported | 支持直播 |
6 SDK 消息回调
可选则实现 HMCloudPlayerDelegate 代理
- (void) cloudPlayerSceneChangedCallback:(NSDictionary *)dict;
- (void) cloudPlayerTouchBegan;
6.1 cloudPlayerTouchBegan
游戏视频界面被点击,可用于收起已经展开的非全屏设置界面
6.2 cloudPlayerSceneChangedCallback
回调参数字典说明:
{
"sceneId": "init",
"extraInfo": {}
}
6.2.1 参数说明
字典Key | 值类型 | 说明 |
---|---|---|
sceneId | NSString | 回调场景ID,取值及含义如下: init : 初始化场景 data : 配置数据场景,如清晰度列表 prepare : 准备云游戏场景 playerState : 游戏过程中,状态变化场景 queue : 排队场景 playingtime : 游戏时长场景 resolution : 播流清晰度场景 stastic : 数据统计场景 maintance : 服务器维护场景 |
extraInfo | NSDictionary | 场景ID对应的扩展信息 |
6.2.2 初始化场景说明
字典Key | 值类型 | 说明 | 举例 |
---|---|---|---|
state = success | NSString | 初始化成功 | { “sceneId”: “init”, “extraInfo”: { “state”: “success” } } |
state = failed | NSString | 初始化失败 | { “sceneId”: “init”, “extraInfo”: { “state”: “failed”, “errorCode”: “100104001” } } |
errorCode | NSString | 失败 errorCode |
6.2.3 配置数据场景
字典Key | 值类型 | 说明 | 举例 |
---|---|---|---|
type = titleVideo | NSString | 片头信息 | { “sceneId”: “data”, “extraInfo”: { “type”: “titleVideo”, “data”: { “name”: “…”, “url”: “…”, “version”: “…” } } } |
type = resolutions | NSString | 清晰度列表 | { “sceneId”: “data”, “extraInfo”: { “type”: “resolutions”, “data”: [##清晰度列表##] } } |
type = loadingTips | NSString | Loading界面Tips revolveTime为轮播时间,单位ms |
{ “sceneId”: “data”, “extraInfo”: { “type”: “loadingTips”, “data”: { “revolveTime”: 4000, “tips”: [##Tips列表##] } } } |
type = message | NSString | 收到消息 | { “sceneId”: “data”, “extraInfo”: { “type”: “message”, “data”: “##消息内容##” } } |
type = speed | NSString | 测速信息配置 time为最大测速时长,单位:秒 |
{ “sceneId”: “data”, “extraInfo”: { “type”: “speed”, “data”: { “url”: “…”, “time”: 5, “rateCoef”: 1.0, “standCoef”: 0.8, “skip”: 0 } } } |
6.2.4 准备云游戏场景
字典Key | 值类型 | 说明 | 举例 |
---|---|---|---|
state = success | NSString | 准备成功, 之后才可以调用play方法播流 |
{ “sceneId”: “prepare”, “extraInfo”: { “state”: “success” } } |
state = failed | NSString | 准备失败 | { “sceneId”: “prepare”, “extraInfo”: { “state”: “failed”, “errorCode”: “100000001” } } |
errorCode | NSString | 准备失败 errorCode | / |
6.2.5 云游戏状态变化场景
字典Key | 值类型 | 说明 | 举例 |
---|---|---|---|
state = prepared | NSString | 实例申请完成, 继续显示Loading |
{ “sceneId”: “playerState”, “extraInfo”: { “state”: “prepared” } } |
state = videoVisible | NSString | 视频第一帧到达 | { “sceneId”: “playerState”, “extraInfo”: { “state”: “videoVisible” } } |
state = stopped | NSString | 云游戏结束 stop_reason见下表 |
{ “sceneId”: “playerState”, “extraInfo”: { “state”: “stopped”, “stop_reason”: “”, “errorCode”: “200211005”, “errorMsg”: “##错误描述”, “queues”: [#参考排队场景说明#], } } |
state = timeout | NSString | 游戏时间到,结束游戏 | { “sceneId”: “playerState”, “extraInfo”: { “state”: “timeout”, “tip”: “##提示内容##” } } |
state = refreshSToken | NSString | 刷新SToken,显示Loading | { “sceneId”: “playerState”, “extraInfo”: { “state”: “refreshSToken” } } |
state = playFailed | NSString | 调用play方法失败 | { “sceneId”: “playerState”, “extraInfo”: { “state”: “playFailed”, “errorCode”: “100000001” } } |
errorCode | NSString | 失败时 errorCode | / |
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 | NSString | 游戏剩余时长提示 countdown==1,表示为倒计时显示 title中占位符为”|”,否则title为显示内容 second为游戏剩余时长,单位秒 |
{ “sceneId”: “playingtime”, “extraInfo”: { “state”: “prompt”, “second”: 12000, “title”: “##时长提示##”, “countdown”: 1 } } |
state = totaltime | NSString | 游戏总时长提示 second 为游戏总时长秒数 |
{ “sceneId”: “playingtime”, “extraInfo”: { “state”: “totaltime”, “second”: 12000, “title”: “##总时长提示##” } } |
state = update | NSString | 游戏过程中,时长更新 | { “sceneId”: “playingtime”, “extraInfo”: { “state”: “update”, “title”: “##时长更新提示##” } } |
6.2.7 播流清晰度场景
字典Key | 值类型 | 说明 | 举例 |
---|---|---|---|
type = crst | NSString | 开始切换清晰度 source : 当前清晰度ID des : 目标清晰度ID method : 1-自动 0-手动 |
{ “sceneId”: “resolution”, “extraInfo”: { “type”: “crst”, “source”: 1, “des”: 3, “method”: 1, “title”: “##提示##” } } |
type = cred | NSString | 清晰度切换完成 cur_rate : 切换后的清晰度ID result : 1-成功 0-失败 |
{ “sceneId”: “resolution”, “extraInfo”: { “type”: “cred”, “cur_rate”: 1, “result”: 1, “title”: “##提示##” } } |
type = crtp | NSString | 游戏卡断,建议用户切换清晰度 minimum : 是否已经在最低码率 1-是 0-否 |
{ “sceneId”: “resolution”, “extraInfo”: { “type”: “crtp”, “minimum”: 1, “delay_less_minimum”: 1, “title”: “##提示##” } } |
type = notify | NSString | 播流清晰度通知 | { “sceneId”: “resolution”, “extraInfo”: { “type”: “notify”, “cur_rate”: 1 } } |
6.2.8 数据统计场景
字典Key | 值类型 | 说明 | 举例 |
---|---|---|---|
type = bandwidth | NSString | 带宽使用数据 value : 统计时段内字节数 frames : 统计时段内最大N帧字节数 |
{ “sceneId”: “playingtime”, “extraInfo”: { “state”: “prompt”, “second”: 12000, “title”: “##时长提示##”, “countdown”: 1 } } |
type = frames | NSString | 帧数统计数据 value : 统计时段内总帧数 |
{ “sceneId”: “stastic”, “extraInfo”: { “type”: “frames”, “value”: 332 } } |
type = decode | NSString | 解码耗时统计 value : 统计时段内平均解码耗时,单位ms |
{ “sceneId”: “stastic”, “extraInfo”: { “type”: “decode”, “value”: 9 } } |
6.2.9 排队场景
字典Key | 值类型 | 说明 | 举例 |
---|---|---|---|
state = confrim | NSString | 提醒用户需要排队 index : 当前排队人数 queues : 多队列排队信息 |
{ “sceneId”: “queue”, “extraInfo”: { “state”: “confrim”, “title”: “##排队提示##”, “index”: 3, “queues”: [] } } |
state = update | NSString | 排队进度更新 index : 当前排队人数 second : 预计剩余秒数 queues : 多队列排队信息 |
{ “sceneId”: “queue”, “extraInfo”: { “state”: “update”, “title”: “##排队提示##”, “index”: 3, “second”: 300, “timeStr”: “五分钟”, “queues”: [] } } |
state = entering | NSString | 排队成功,即将进入游戏 | { “sceneId”: “queue”, “extraInfo”: { “state”: “entering”, “title”: “##排队提示##” } } |
多队列排队数据项说明
字典Key | 值类型 | 说明 |
---|---|---|
rank | NSInteger | 队列等级 |
index | NSInteger | 当前排队人数 |
second | NSInteger | 预计剩余秒数 |
timeStr | NString | 预计排队描述格式化的字符串 |
priorities | NSArray<NSNumber *> | 当前队列包含的用户优先级列表 |
6.2.10 维护场景
字典Key | 值类型 | 举例 | 说明 |
---|---|---|---|
progress = soon | NSString | { “sceneId”: “maintance”, “extraInfo”: { “progress”: “soon”, “title”: “##维护提示##”, “timeStr”: “五分钟” } } |
游戏中用户, 收到即将维护的提示 |
progress = start | NSString | { “sceneId”: “maintance”, “extraInfo”: { “progress”: “start”, “title”: “##维护提示##” } } |
排队进度更新 index : 当前排队人数 second : 预计剩余秒数 queues : 多队列排队信息 |
progress = inprogress | NSString | { “sceneId”: “maintance”, “extraInfo”: { “progress”: “inprogress”, “title”: “##维护提示##”, “timeStr”: “五分钟” } } |
排队成功,即将进入游戏 |
progress = done | NSString | { “sceneId”: “maintance”, “extraInfo”: { “progress”: “done”, “title”: “##维护提示##” } } |
维护完成 |
6.2.11 无输入提示场景
字典Key | 值类型 | 说明 | 举例 |
---|---|---|---|
state = remindtime | NSString | 在无输入情况下游戏剩余时长提示, title中占位符为 | ;否则title为显示内容 second为游戏剩余时长,单位秒 |
{ “sceneId”: “noinput”, “extraInfo”: { “state”: “remindtime”, “second”: 12000, “title”: “##剩余时长提示##”, } } |