H5产品SDK接入说明
1.文档说明
- 1.1 功能描述
- 1.2 阅读对象
2.接入准备
3.特别说明
- 3.1 H5游戏访问地址
4.引入掌趣JSSDK
5.JSSDK功能接入
6 JSSDK回调接口
附1 校验码生成规则
- 校验码介绍
- 生成示例
附2 货币类型

H5产品SDK接入说明

1.文档说明

1.1 功能描述

此文档主要是用于在H5游戏及应用开发商需要接入掌趣JSSDK时，了解JSSDK如何接入，以及接入过程中需注意的事项等。

1.2 阅读对象

接入掌趣JSSDK的游戏及应用的H5开发者。

2.接入准备

服务端接入：请参考通用接入文档—> 《SDK服务端接入说明文档》

3.特别说明

3.1 H5游戏访问地址

接入掌趣JSSDK后，游戏的访问地址必须由掌趣平台生成，不可单独访问游戏的地址。接入前需要在掌趣平台进行配置游戏访问地址，配置后即可生成该产品对应的平台地址。也可联系平台技术支持人员获取产品的平台地址。

4.引入掌趣JSSDK

重要性:必接
在游戏主HTML页面必须引入掌趣 ourpalm-sdk-agent.js，后续接口都由该js提供。
示例：

<script type="text/javascript" src="https://gscservice.gamebean.net/h5sdk/v1/js/ourpalm-sdk-agent.js"></script>

建议放置到页面顶部，优先加载 ourpalm-sdk-agent.js
上线后必须使用https；

5.JSSDK功能接入

5.1 初始化接口 ready

重要性:必接 游戏 -> JSSDK

5.1.1 接入时间

在游戏主页面dom加载完毕后立即调用，接入代码可以放到body底部。
示例：

window.ourpalmSdk.ready(gameInfo, gameCallBackInfo);

5.1.2 请求参数

游戏版本信息 gameInfo

参数名称	类型	限制策略	说明
version	字符串	必填	游戏版本号
resVersion	字符串	选填	游戏资源版本号；无，则传空字符串
title	字符串	必填	默认分享标题；个别渠道需要提前设置；
content	字符串	必填	默认分享内容；个别渠道需要提前设置；
imageURL	字符串	必填	默认分享图片地址；个别渠道需要提前设置；注意：图片推荐使用正方形，图片最小需要200 * 200；
signKey	字符串	必填	校验码，`需要在服务端生成校验码`. 校验码生成规则见`附1`

示例

{
    "version":"1.0",
    "resVersion":"1.0.1",
    "title":"分享标题",
    "content":"分享内容",
    "imageURL":"分享图片地址",
    "signKey":"2f4e6d659d29c9cb6979a395516aa705"
}

游戏回调接口信息 gameCallback

参数名称	类型	限制策略	说明
readyCallback	JS函数	必填	掌趣平台初始化完成后的回调函数，具体回调参数详见`6.1 初始化回调接口`
userLoginCallback	JS函数	必填	掌趣平台用户登录完成后的回调函数，具体回调参数详见`6.2 用户登录回调接口`
userLogoutCallback	JS函数	必填	掌趣平台用户登出完成后的回调函数，具体回调参数详见`6.3 用户登出回调接口`
payCallback	JS函数	必填	掌趣平台用户支付结果后的回调函数，具体回调参数详见`6.4 用户支付回调接口`
shareCallback	JS函数	选填	分享成功后回调函数，具体回调参数详见`6.5 分享回调接口`

示例

{
    "readyCallback":function(){},
    "userLoginCallback":function(){},
    "userLogoutCallback":function(){},
    "payCallback":function(){}
}

5.2 角色登录接口 roleLogin

重要性:必接 游戏 -> JSSDK

5.2.1 接入时间

在游戏完成角色登录后立即调用。
示例：

window.ourpalmSdk.roleLogin(roleInfo);

5.2.2 请求参数

角色信息 roleInfo

参数名称	类型	限制策略	说明
type	字符串	必填	1：角色注册，2：角色登陆
gameServerId	字符串	必填	逻辑服ID
gameServerName	字符串	必填	逻辑服名称
roleId	字符串	必填	角色ID
roleName	字符串	必填	角色名称
roleLevel	字符串	必填	角色等级；无等级可传空字符串
roleVipLevel	字符串	必填	角色VIP等级；无vip等级可传空字符串
signKey	字符串	必填	校验码，`需要在服务端生成校验码`. 校验码生成规则见`附1`

示例

{
    "type":"2",
    "gameServerId":"1",
    "gameServerName":"未来之城",
    "roleId":"5f438152-258d-47ff-82bf-c7ba314a4fce",
    "roleName":"doublinglee_微信",
    "roleLevel":"0",
    "roleVipLevel":"0",
    "signKey":"e11a571fffc78737b1154aead7bcef46"
}

5.3 下单接口 pay

重要性:必接 游戏 -> JSSDK

5.3.1 接入时间

游戏在商城或其他需要支付的场景发起支付时调用。
示例：

window.ourpalmSdk.pay(payInfo);

5.3.2 请求参数

支付信息 payInfo

参数名称	类型	限制策略	说明
propId	字符串	必填	商品ID
propName	字符串	必填	商品名称
propDes	字符串	必填	商品描述，无可传空
currencyType	字符串	必填	货币类型，具体货币类型参见`附2`
chargeCash	字符串	必填	商品金额；单位（分）
propCount	字符串	必填	商品数量；
roleLevel	字符串	必填	角色等级；无等级可传空字符串
roleVipLevel	字符串	必填	角色VIP等级；无VIP等级可传空字符串
extendParams	字符串	选填	游戏自定义数据，支付成功后，计费中心会将此字段数据回传给游戏服务器。
gameUrl	字符串	必填	游戏发放道具服务器地址，用户支付成功后掌趣计费中心会回调此地址告知游戏进行道具发放
signKey	字符串	必填	校验码，`需要在服务端生成校验码`. 校验码生成规则见`附1`

示例

{
    "propId":"1001",
    "propName":"2钻复活",
    "propDes":"",
    "currencyType":"1",
    "chargeCash":"1",
    "propCount":"1",
    "roleLevel":"",
    "roleVipLevel":"",
    "extendParams":"",
    "gameUrl":"http://testplatform.gamebean.net/activity/s/h5planechargecallback.htm",
    "signKey":"06345232c45310b4f9dad446394df7e3"
}

5.4 客户端日志接口 log

重要性:选接 游戏 -> JSSDK

5.4.1 接入时间

在需要发送日志的时机进行调用。
示例：

window.ourpalmSdk.log(logInfo);

5.4.2 请求参数

日志信息 logInfo

参数名称	类型	限制策略	说明
id	字符串	必填	日志ID
key	字符串	必填	日志KEY
content	字符串	必填	日志内容;json格式

示例玩家虚拟货币变更日志

{
    "id":"91",
    "key":"role-income-update",
    "content":{
        "roleLevel":"10",
        "roleVipLevel":"2",
        "updateType":"1",
        "itemId":"10002",
        "itemName":"钻石",
        "isPrecious":"0",
        "itemCount":"200",
        "remains":"300",
        "custom":"购买xx"
    }
}

5.5 打开客服 openKfCenter

重要性:选接 游戏 -> JSSDK

5.5.1 接入时间

在游戏页面需要引导用户打开客服界面时调用。注意：游戏需要先对初始化返回参数中的是否可以启动客服进行判断，只有当允许拉起客服时，才建议进行展示拉起客服按钮，否则不建议展示拉起客服按钮；（有个别渠道不允许有游戏内自己的客服，所以需要根据初始化返回的状态动态显示客服按钮）
示例：

window.ourpalmSdk.openKfCenter();

5.5.2 请求参数

无

重要性:选接，需要根据初始化返回状态动态显示分享按钮 游戏 -> JSSDK

5.6.1 接入时间

在游戏页面需要分享的地方，并根据初始化返回状态动态显示分享按钮。
示例：

window.ourpalmSdk.share(shareMsg);

5.6.2 请求参数

分享数据 shareMsg

参数名称	类型	限制策略	说明
title	字符串	必填	分享标题
content	字符串	必填	分享内容
imageURL	字符串	必填	分享图片地址

5.7 收藏 collect

重要性:选接，需要根据初始化返回状态动态显示收藏按钮 游戏 -> JSSDK

5.7.1 接入时间

在游戏页面需要收藏的地方，并根据初始化返回状态动态显示收藏按钮。
示例：

window.ourpalmSdk.collect();

5.7.2 请求参数

无

5.8 关注 subscript

重要性:选接，需要根据初始化返回状态动态显示关注按钮 游戏 -> JSSDK

5.8.1 接入时间

在游戏页面需要关注的地方，并根据初始化返回状态动态显示关注按钮。
示例：

window.ourpalmSdk.subscript();

5.8.2 请求参数

无

5.9 获取用户扩展信息 getUserExtendInfo

重要性:选接，主要提供用户头像地址等信息，根据渠道不同可能为空，需要游戏进行判断 游戏 -> JSSDK

5.9.1 接入时间

在需要获取用户扩展信息的地方调用。
示例：

window.ourpalmSdk.getUserExtendInfo(function(userExtendInfo) {
    console.log(userExtendInfo);
});

5.9.2 请求参数

无

5.9.3 回调userExtendInfo参数

参数名称	类型	限制策略	说明
imageURL	字符串	选填	用户头像，注意根据渠道不同可能为空
wanba_platform	字符串	选填	玩吧渠道平台类型（2-IOS，1-安卓），其他渠道无该参数；如何确认玩吧渠道？`根据初始化回调（4.6）结果中的serviceid进行判断，serviceid以31033349000结尾表示玩吧渠道`，玩吧渠道要求游戏商城中显示的商品价格`单位`需要根据平台类型进行不同的展示（1元=10星币），具体详见`https://wiki.qzone.qq.com/doc/before/pay`

5.10 选服事件 selectServer

重要性:必接，角色登陆前的任意一次选服事件，都需要调用 游戏 -> JSSDK

5.10.1 接入时间

在游戏选服页进行选服时调用。
示例：

window.ourpalmSdk.selectServer(serverInfo);

5.10.2 请求参数

游戏服信息 serverInfo

参数名称	类型	限制策略	说明
gameServerId	字符串	必填	游戏服Id
gameServerName	字符串	必填	游戏服名称gameServerName	字符串	必填	游戏服名称

5.11 背景音乐播放[个别渠道可用] play_bg_music

重要性:选接，华为渠道背景音乐播放可调用该方法，不支持其他渠道 游戏 -> JSSDK

5.11.1 接入时间

在播放背景音乐或切换背景音乐播放时调用。该方法会自动循环播放此背景音乐
示例：

window.ourpalmSdk.play_bg_music(url);

5.11.2 请求参数

url：音乐在线播放地址（必须HTTPS）

5.12 其他音乐播放[个别渠道可用] play_other_music

重要性:选接，华为渠道非背景音乐播放可调用该方法，不支持其他渠道 游戏 -> JSSDK

5.12.1 接入时间

在需要播放特效音时调用。该方法只播放一次，播放完后自动继续播放背景音乐（若之前已经在进行播放背景音乐）; 因为华为渠道目前不支持多音频同时播放，在进行背景音和特效音切换时会有2-3秒左右停顿；
示例：

window.ourpalmSdk.play_other_music(url);

5.12.2 请求参数

url：音乐在线播放地址（必须HTTPS）

5.13 音乐播放状态变更[个别渠道可用] music_status

重要性:选接，华为渠道改变音乐播放状态时可调用该方法，不支持其他渠道 游戏 -> JSSDK

5.13.1 接入时间

在需要静音或关闭静音时调用该方法；注意：静音状态需要游戏方自己保存，默认进入游戏是非静音状态，如果用户设置为静音需要游戏在进入后【播放音乐前】调用该方法设置为静音。
示例：

window.ourpalmSdk.music_status(status);

5.13.2 请求参数

status：1:非静音模式； 0：静音模式

5.14 页面重新加载接口 refresh

重要性:选接, 仅初始化回调返回supportRefresh为1时才支持，使用时需要进行判断 游戏 -> JSSDK

5.14.1 接入时间

游戏内在需要进行重新加载游戏页面时使用，注意：仅初始化回调返回supportRefresh为1时才支持，使用时需要进行判断。
示例：

window.ourpalmSdk.refresh();

5.14.2 请求参数

无

5.15 角色数据变更接口 roleInfoChange

重要性:必接 游戏 -> JSSDK

5.15.1 接入时间

游戏角色名、等级、VIP等级发生变化时立即调用。
示例：

window.ourpalmSdk.roleInfoChange(roleInfoChange);

5.15.2 请求参数

角色数据变更信息 roleInfoChange
注意：如果等级数据存在转生，则等级新旧值均使用：转生次数-等级数据 来表示

参数名称	类型	限制策略	说明
type	字符串	必填	1：角色名修改，2：角色等级变化， 3：角色VIP等级变化
oldValue	字符串	必填	变更之前值；
newValue	字符串	必填	变更之后值；

示例

{
    "type":"2",
    "oldValue":"25",
    "newValue":"26"
}

6 JSSDK回调接口

6.1 初始化回调接口 readyCallback

重要性:必接 JSSDK -> 游戏

6.1.1 触发时间

掌趣平台完成初始化后回调游戏，通知游戏SDK初始化结果信息。通过初始化接口传递的readyCallback函数进行回调游戏。
示例：

readyCallback(readyInfo);

6.1.2 请求参数

初始化结果信息 readyInfo

参数名称	类型	限制策略	说明
h5deviceid	字符串	必填	掌趣平台H产品中的设备标识符
servicecode	字符串	必填	掌趣平台服务端日志使用的servicecode（已经base64）
opid	字符串	必填	掌趣平台渠道产品唯一短串
serviceid	字符串	必填	掌趣平台渠道产品标识符
devicegroupid	字符串	必填	掌趣平台机型组标识
channelid	字符串	必填	掌趣平台推广渠道标识符
localeid	字符串	必填	掌趣平台当前语言标识符
status	字符串	必填	掌趣平台初始化结果状态，固定为0
supportLogout	字符串	必填	是否支持游戏内进行用户登出；0：不支持； 1：支持
supportKF	字符串	必填	是否支持游戏内进行打开客服；0：不支持； 1：支持
supportRefresh	字符串	必填	是否支持游戏内进行页面刷新；0：不支持； 1：支持
supportShare	字符串	必填	是否支持游戏内使用渠道的分享功能；该值不影响调用初始化时传递的分享标题、内容、图片地址；0：不支持； 1：支持
supportCollect	字符串	必填	是否支持游戏内使用渠的道收藏功能；0：不支持； 1：支持
supportSubscribe	字符串	必填	是否支持游戏内使用渠道的关注功能；0：不支持； 1：支持
signKey	字符串	必填	校验码，`需要在服务端完成校验码校验`. 校验码生成规则见`附1`

示例

{
    "h5deviceid":"fbd996919976f1d0d6023ed4c2f1f272",
    "servicecode":"MjAwMDAwMDIzMTAxNDMwMDAwMDMxMDE0MzAwMzEwMTQzMDAwMDAwMDF8fHx8fHwxOTIwKjEwODB8fHx8fDEuMC4yLjAwYjFhM3wxLjAuMXwxLjAuMXx8fHx8fHx8ZmJkOTk2OTE5OTc2ZjFkMGQ2MDIzZWQ0YzJmMWYyNzJ8TW96aWxsYS81LjAgKFdpbmRvd3MgTlQgMTAuMDsgV09XNjQpIEFwcGxlV2ViS2l0LzUzNy4zNiAoS0hUTUwsIGxpa2UgR2Vja28pIENocm9tZS83MC4wLjM1MzguNzcgU2FmYXJpLzUzNy4zNnx8aHR0cDovL3Rlc3RwbGF0Zm9ybS5nYW1lYmVhbi5uZXQvZ2FtZS9wbGFuZTIvaW5kZXguaHRtbA==",
    "supportLogout":"1",
    "opid":"",
    "signKey":"7b3987d36e4ff42ce37958099d6b7cb6",
    "supportKF":"0",
    "serviceid":"2000000231014300000",
    "devicegroupid":"0000",
    "channelid":"3101430031014300",
    "localeid":"01",
    "status":"0"
}

6.2 登录回调接口 userLoginCallBack

重要性:必接 JSSDK -> 游戏

6.2.1 触发时间

掌趣平台完成登录后回调游戏，通知游戏登录成功。通过初始化接口传递的userLoginCallBack函数进行回调游戏。
示例：

userLoginCallBack(userInfo);

6.2.2 请求参数

用户信息 userInfo

参数名称	类型	限制策略	说明
sessionId	字符串	必填	掌趣平台用户中心sessionId；具体详细信息通过sessionId在服务端接入接口[登录验证接口]中获取
userId	字符串	必填	掌趣平台用户中心用户ID
nickName	字符串	选填	用户昵称，可能为空；如果游戏需要用到昵称，必须通过`http://sdk.0708.com/t3/192/3955/1500006359.html`的`4.1`章节进行获取
signKey	字符串	必填	校验码，`需要在服务端完成校验码校验`. 校验码生成规则见`附1`

示例

{
    "sessionId":"3897bfbb237ae-486c-97cd-85c1e03d6601",
    "userId":"0102830000000olrL101pbniKue_PuI_ITMcIo7U",
    "nickName":"玩家olrL101pbniKue_PuI_ITMcIo7U",
    "signKey":"6b5e71a321f7d6773930d7f6537733a5"
}

6.3 登出回调接口 userLogoutCallBack

重要性:必接 JSSDK -> 游戏

6.3.1 触发时间

掌趣平台完成用户注销后回调游戏，通知游戏注销成功。通过初始化接口传递的 userLogoutCallBack 函数进行回调游戏。
示例：

userLogoutCallBack(userInfo);

6.3.2 请求参数

用户信息 userInfo

参数名称	类型	限制策略	说明
sessionId	字符串	必填	掌趣平台用户中心sessionId
userId	字符串	必填	掌趣平台用户中心用户ID
nickName	字符串	必填	掌趣平台用户中心用户昵称，无则传空
signKey	字符串	必填	校验码，`需要在服务端完成校验码校验`. 校验码生成规则见`附1`

示例

{
    "sessionId":"3897bfbb237ae-486c-97cd-85c1e03d6601",
    "userId":"0102830000000olrL101pbniKue_PuI_ITMcIo7U",
    "nickName":"玩家olrL101pbniKue_PuI_ITMcIo7U",
    "signKey":"6b5e71a321f7d6773930d7f6537733a5"
}

6.4 支付结果回调接口 payCallBack

重要性:必接 JSSDK -> 游戏

6.4.1 触发时间

掌趣平台支付流程结束后回调游戏，通知游戏支付结果。通过初始化接口传递的 payCallBack 函数进行回调游戏。注意：该回调属于客户端回调，仅用于客户端支付结果提示，最终发货需要依赖掌趣计费中心的服务端回调通知。
示例：

payCallBack(payResult);

6.4.2 请求参数

支付信息 payResult

参数名称	类型	限制策略	说明
status	字符串	必填	0:下单失败,1:下单成功, 2:支付失败, 3:支付成功; 该状态仅作为客户端参考使用，具体发货必须以服务端的支付通知为准
code	字符串	必填	失败详细错误码，参照错误码表
ssid	字符串	必填	掌趣订单号
pbid	字符串	必填	游戏商品ID
signKey	字符串	必填	校验码，`需要在服务端完成校验码校验`. 校验码生成规则见`附1`

示例

{
    "status":"3",
    "code":"",
    "ssid":"0992018090513344444700",
    "pbid":"1001",
    "signKey":"34d9dcfc4dbfc76cd2421f5aa0d75b27"
}

6.5 分享回调 shareCallback

重要性:选接，分享成功后回调游戏，回调函数在初始化接口进行设置 JSSDK -> 游戏

6.5.1 接入时间

分享成功后回调游戏，回调函数在初始化接口进行设置。

6.5.2 请求参数

无

附1 校验码生成规则

校验码介绍

校验码：校验码是为了防止在通信过程中交换数据被篡改的一种通用校验方式，由交换数据按照某种格式拼装在一起，再追加上双方协商好的秘钥[需要通过运营人员获取]，生成校验码明文，通过对明文进行hash处理得到校验码。接受数据方需要比较自己生成的校验码和交换数据中传递的校验码是否一致，来确定该数据是否合法。

校验码明文生成：对交换数据按key进行字典排序（ASCII码从小到大排序），只取value值，进行拼接，不同值之间使用&符号进行分割，最后再追加上约定秘钥，得出校验码明文。

参数key区分大小写。
按字典排序，即ASCII码从小到大排序。
参数值为空或不传时，按空字符串进行拼接。
接口协议中定义的不包含 signKey 不参与签名。

校验码hash算法：MD5，注意取32位md5，并转小写。

生成示例

假设交换数据如下（不包含signKey）

{
    "type":"2",
    "gameServerId":"1",
    "gameServerName":"未来之城",
    "roleId":"5f438152-258d-47ff-82bf-c7ba314a4fce",
    "roleName":"doublinglee_微信",
    "roleLevel":"0",
    "roleVipLevel":""
}

假设约定秘钥如下

b306ab1d0421ad3c73ad2c409621669c

生成校验码明文如下

1&未来之城&5f438152-258d-47ff-82bf-c7ba314a4fce&0&doublinglee_微信&&2&b306ab1d0421ad3c73ad2c409621669c

生成校验码如下

67dcc59acaa6220214c81d6aa43bf9cf

附2 货币类型

currencyType（货币类型）说明：

货币类型值	货币名称	货币单位
1	人民币	分
2	美元	美分
3	日元	円
4	港币	分
5	英镑	便士
6	新加坡币	分
7	越南盾	盾
8	台币	元
9	韩元	分
10	泰铢	萨当

Table of Contents

H5产品SDK接入说明

1.文档说明

1.1 功能描述

1.2 阅读对象

2.接入准备

3.特别说明

3.1 H5游戏访问地址

4.引入掌趣JSSDK

5.JSSDK功能接入

5.1 初始化接口 ready

5.1.1 接入时间

5.1.2 请求参数

5.2 角色登录接口 roleLogin

5.2.1 接入时间

5.2.2 请求参数

5.3 下单接口 pay

5.3.1 接入时间

5.3.2 请求参数

5.4 客户端日志接口 log

5.4.1 接入时间

5.4.2 请求参数

5.5 打开客服 openKfCenter

5.5.1 接入时间

5.5.2 请求参数

5.6 分享 share

5.6.1 接入时间

5.6.2 请求参数

5.7 收藏 collect

5.7.1 接入时间

5.7.2 请求参数

5.8 关注 subscript

5.8.1 接入时间

5.8.2 请求参数

5.9 获取用户扩展信息 getUserExtendInfo

5.9.1 接入时间

5.9.2 请求参数

5.9.3 回调userExtendInfo参数

5.10 选服事件 selectServer

5.10.1 接入时间

5.10.2 请求参数

5.11 背景音乐播放[个别渠道可用] play_bg_music

5.11.1 接入时间

5.11.2 请求参数

5.12 其他音乐播放[个别渠道可用] play_other_music

5.12.1 接入时间

5.12.2 请求参数

5.13 音乐播放状态变更[个别渠道可用] music_status

5.13.1 接入时间

5.13.2 请求参数

5.14 页面重新加载接口 refresh

5.14.1 接入时间

5.14.2 请求参数

5.15 角色数据变更接口 roleInfoChange

5.15.1 接入时间

5.15.2 请求参数

6 JSSDK回调接口

6.1 初始化回调接口 readyCallback

6.1.1 触发时间

6.1.2 请求参数

6.2 登录回调接口 userLoginCallBack

6.2.1 触发时间

6.2.2 请求参数

6.3 登出回调接口 userLogoutCallBack

6.3.1 触发时间

6.3.2 请求参数

6.4 支付结果回调接口 payCallBack

6.4.1 触发时间

6.4.2 请求参数

6.5 分享回调 shareCallback

6.5.1 接入时间

6.5.2 请求参数

附1 校验码生成规则

校验码介绍

生成示例

附2 货币类型