U8SDK—聚合SDK文档

Appearance

小游戏接口调用 ​

接入准备 ​

U8SDK将不同平台的小游戏开放能力API（登录、支付、广告等）封装成统一的接口，游戏层在使用U8SDK接入时，直接调用U8SDK提供的API进行调用即可，而无需单独去接入。

但不同平台的小游戏开发工具内置支持的Javascript规范有所差异，比如有些只支持ESM规范、有些只支持CommonJS规范、有些两者都支持、有些两者都不支持。

所以， 不同平台的小游戏配置和代码引入方式有所区别，具体可以查看对应小游戏平台的配置说明：

微信小游戏

1、 拷贝文件

将u8-demo-wehcat/js/u8sdk目录，拷贝到游戏工程目录下；

2、 添加依赖

在游戏的接入文件中，添加u8sdk类的引用：

js
import u8sdk from './u8sdk/u8sdk-adapter-wechat'

如果游戏同时存在原生平台官网包，并使用了U8SDK旗下的官网SDK用于游戏的官网包， 也可以按下面方式引入互通版本的脚本，这样玩家在原生平台使用微信登录的账号，在小游戏版本中享有相同的游戏进度：

js
import u8sdk from './u8sdk/u8sdk-adapter-wechat-with-xsdk'
抖音小游戏

1、 拷贝文件

将u8-demo-douyin/u8sdk目录，拷贝到游戏工程目录下；

2、 添加依赖

在游戏的接入文件中，添加u8sdk类的引用：

js
const { u8sdk, U8DouYinApi } = require('./u8sdk/u8sdk-adapter-douyin.js')
快手小游戏

1、 拷贝文件

将u8-demo-kuaishou/u8sdk目录，拷贝到游戏工程目录下；

2、 添加依赖

在游戏的接入文件中，添加u8sdk类的引用：

js
const u8sdk = require('./u8sdk/u8sdk-adapter-kuaishou.js')
支付宝小游戏

1、 拷贝文件

将u8-demo-zhifubao/u8sdk目录，拷贝到游戏工程目录下；

2、 添加依赖

在游戏的接入文件中，添加u8sdk类的引用：

js
const u8sdk = require('./u8sdk/u8sdk-adapter-zhifubao.js')
华为快游戏

1、 拷贝文件

将u8-demo-huawei/src/u8sdk目录，拷贝到游戏工程src目录下；

2、 添加依赖

在游戏的接入文件中，添加u8sdk类的引用：

js
require('src/u8sdk/u8sdk-adapter-huawei.js')

初始化 ​

初始化应尽快调用，其他后续其他接口，需要在初始化完成后，才能调用：

js

//初始化聚合SDK（在其他接口调用之前初始化）
const initParams = {
appID: '1',
appKey: '855237c757b7420bb932110efa41263b',
channelID: '5107',
useAD: true,
}

u8sdk.init(initParams).then(()=>{
console.log('init success.')

testLogin()
}).catch(err=>{
console.log('init failed with err:', err)
})

参数说明：

参数名称说明
AppIDU8聚合SDK后台，该游戏的AppID参数
AppKeyU8聚合SDK后台，该游戏的AppKey参数
ChannelID渠道号在U8聚合后台-》渠道配置中查看（对应小游戏渠道的渠道号）
userAD是否使用广告变现，如果游戏内有广告变现的需求，设置为true；否则设置为false

登录 ​

1、接口调用

当玩家进入游戏登录界面、 或玩家手动点击【进入游戏】按钮并且此时玩家是未登录状态时， 游戏层可以调用登录接口。

js

u8sdk.login().then(user=>{
    console.log('sdk login success.', user)

}).catch(err=>{
    console.log('sdk login failed with err:', err)
})

2、处理登录回调

当渠道SDK登录成功或失败时， 聚合SDK会通过login接口中传入的回调函数，通知给游戏层：

js
.then(user=>{
    console.log('sdk login success.', user)
})

在then回调中，U8聚合SDK会返回当前玩家的账号， 其中包含了当前玩家的账号ID等信息。 user结构如下：

参数名称参数类型参数说明
userIDlong玩家唯一ID，游戏层可以用该字段绑定游戏账号或角色
sdkUserIDString渠道平台返回的玩家唯一ID，不同渠道之间可能不唯一
usernameString聚合SDK生成的用户名，无意义
sdkUsernameString渠道平台那边玩家的用户名，可能为空
tokenString此次登录的token，游戏客户端传给游戏服务器，游戏服务器登录认证需要使用
timestampString当前时间戳
newAccountNumber当前账号是否是新账号（首次登录）, 1：新用户；0：老用户
signString当前签名，游戏服务器如果使用本地校验签名，可以使用该字段

3、服务端登录验证

客户端登录成功后， 会返回user对象给游戏层。 游戏层收到user后， 可以将里面userID、 token等数据， 传给游戏服务器。

游戏服务器通过调用服务端->登录认证API，验证token的合法性。

验证通过后， 才能让玩家进入游戏。

支付 ​

1、 接口调用

当玩家点击游戏内商品充值项时，调用支付接口:

js
var productPrice = 1            //当前道具金额（单位元）
var cpOrderID = parseInt("" + new Date().getTime() / 1000)          // 游戏自己的订单号
var cpPayNotifyUrl = "http://172.16.0.109:12201/game/pay/callback"  // 支付完成后， 游戏服务器接收SDK服务器回调通知地址

var orderData = {
    price: productPrice,
    productId: '1',
    productName: '微信小游戏测试商品',
    productDesc: '充值10元送50钻石',
    serverID: '1',
    serverName: '微信服务器',
    roleID: '100',
    roleName: '角色_&#@!%^_+·~|{}[]',
    roleLevel: 1,
    vip: '1',
    cpOrderID: cpOrderID,
    extension: "自定义数据，回调通知时原样返回",
    payNotifyUrl: cpPayNotifyUrl
};
U8SDKApi.pay(orderData).then(()=>{
    // 支付成功回调
    console.log('sdk pay success')
}).catch(err=>{
    // 支付失败回调
    console.log('sdk pay failed with err:', err)
})

orderData对象的结构说明如下：

参数名称参数类型参数说明
productIDString充值商品ID，游戏内的商品ID，
productNameString商品名称，比如100元宝，500钻石等，
productDescString商品描述，比如 充值100元宝，赠送20元宝，
priceint充值金额(单位：元)，
serverIDString玩家所在服务器的ID，
serverNameString玩家所在服务器的名称，
roleIDString玩家角色ID，
roleNameString玩家角色名称，
roleLevelString玩家角色等级，
vipString玩家vip等级
payNotifyUrlString玩家支付成功，U8聚合SDK会优先通过该地址，通知游戏服务器，给玩家发货。 如果该地址没设置， 会使用后台配置的地址
cpOrderIDString游戏自己的订单号，最大长度64字符；支付成功之后，U8聚合SDK原样返回给游戏服务器
extensionString自定义数据，最大长度：64字符；支付成功之后，U8聚合SDK原样返回给游戏服务器

2、处理服务端发货通知

玩家在客户端支付成功后， 小游戏平台会通知给U8聚合SDK服务端。 接着， U8聚合SDK服务端会按统一的协议通知给游戏服务器。

游戏服务器需要实现服务端->支付回调通知协议，用来接收U8聚合SDK的发货通知请求。

收到请求并验证通过后， 才能给玩家发放道具。

提交角色信息 ​

1、 接口调用

当玩家创建角色成功、进入游戏内、角色等级升级时，需要调用角色上报接口。 每次调用，角色对象中的必选参数都需要全部设置。

js
var roleData = {
    serverID: '1',
    serverName: 'H5演示服务器',
    roleID: '100',
    roleName: '角色_&#@!%^_+·~|{}[]',
    roleLevel: '1',
    vip: '1',
    moneyNum: 0,
    roleCreateTime: parseInt("" + new Date().getTime()/1000),
    roleLevelUpTime: parseInt("" + new Date().getTime()/1000)
};

roleData.dataType = 2       // 2: 创建角色 3: 进入游戏 4： 等级升级 5：退出游戏
U8SDKApi.submit(roleData).then(()=>{
    console.log('submit success')
}).catch(err=>{
    console.log('submit failed with err:', err)
})

dataType主要有如下几种调用时机：

调用时机dataType值
创建角色成功2
进入游戏内3
角色等级升级后4
玩家点击退出游戏（可选）5

也就是在创建角色的时候，dataType为2；进入游戏时，dataType为3；等级提升时，dataType为4；退出游戏时，dataType为5。

UserExtraData 数据结构:

参数名称参数类型参数说明
dataTypeint调用时机，值为2、3、4或5，
serverIDString玩家所在服务器的ID，
serverNameString玩家所在服务器的名称，
roleIDString玩家角色ID，
roleNameString玩家角色名称，
roleLevelString玩家角色等级，
roleCreateTimelong角色创建时间，从1970年到现在的时间，单位秒,必须传入真实的数据，
roleLevelUpTimelong角色等级变化时间，从1970年到现在的时间，单位秒，
moneyNumString当前角色身上拥有的游戏币数量
vipString玩家VIP等级

2、 补充说明

为了最小化接口调用， 聚合SDK内部的一些功能逻辑， 会依赖角色上报接口。 依赖的功能见下表：

功能依赖时机说明
自动补单进入游戏部分小游戏平台需要在进入游戏时查询丢单记录，该行为依赖进入游戏时机的角色上报接口，在这里进行补单逻辑的检查
后台角色查询/统计创建角色/进入游戏U8SDK后台提供了角色查询和统计等功能，该功能依赖客户端的角色上报接口

广告接口 ​

WARNING

目前小游戏支持的广告类型： 【Banner广告】、 【插屏广告】、 【激励视频广告】

1、 激励视频广告
  1. 创建广告
JS
const rewardedAd = u8sdk.createRewardedVideoAd({
	adUnitId: "1163989897326174230"
})

参数说明：

参数名称参数类型参数说明
adUnitIdstringU8SDK后台创建的激励视频类型的广告位ID

2）设置回调

js

// 广告加载成功时，回调
rewardedAd.onLoad(()=>{
	console.log('reward ad on loaded.')
rewardedAd.show() //主动展示广告
})

// 广告加载失败时，回调
rewardedAd.onError((res)=>{
	console.log('reward ad on error.', JSON.stringify(res))
})

// 广告关闭时，回调
rewardedAd.onClose(()=>{
	console.log('reward ad on closed.', res)
})

广告回调说明：

回调名称参数类型参数说明
onLoadFunction广告加载成功时，回调
onErrorFunction广告加载失败时，回调
onCloseFunction广告关闭时回调，可以在这个回调中继续调用load提前加载下一次展示的广告
  1. 加载广告

创建广告后， 可以调用load方法，加载广告：

js
rewardedAd.load()
  1. 展示广告

在需要展示广告的时机，调用show方法，展示广告：

js
rewardedAd.show()
  1. 销毁广告

销毁广告时，可以调用：

js
rewardedAd.destroy()
2、 插屏广告
  1. 创建广告
JS
const interstitialAd = u8sdk.createInterstitialAd({
	adUnitId: "879620241503559681"
})

参数说明：

参数名称参数类型参数说明
adUnitIdstringU8SDK后台创建的插屏类型的广告位ID

2）设置回调

js

interstitialAd.onLoad(()=>{
	console.log('interstitial ad on loaded.')
	interstitialAd.show() //主动展示广告
})
interstitialAd.onError((res)=>{
	console.log('interstitial ad on error.', res)
})
interstitialAd.onClose(()=>{
	console.log('interstitial ad on closed.')
})

广告回调说明：

回调名称参数类型参数说明
onLoadFunction广告加载成功时，回调
onErrorFunction广告加载失败时，回调
onCloseFunction广告关闭时回调，可以在这个回调中继续调用load提前加载下一次展示的广告
  1. 加载广告

创建广告后， 可以调用load方法，加载广告：

js
interstitialAd.load()
  1. 展示广告

在需要展示广告的时机，调用show方法，展示广告：

js
interstitialAd.show()
  1. 销毁广告

销毁广告时，可以调用：

js
interstitialAd.destroy()
3、 Banner广告
  1. 创建广告
JS
const bannerAd = u8sdk.createBannerAd({
	adUnitId: "879620241503559682",
	adIntervals: 30,
	style: {
	  left: 10,
	  top: 76,
	  width: 320,
	  height: 100
	}
})

参数说明：

参数名称参数类型参数说明
adUnitIdstringU8SDK后台创建的Banner类型的广告位ID
adIntervalsnumberBanner自动刷新的时间间隔，大于等于30s
styleobjectBanner广告的位置和尺寸

2）设置回调

js

bannerAd.onLoad(()=>{
	console.log('banner ad on loaded.')
	bannerAd.show() //主动展示广告
})

bannerAd.onError((res)=>{
	console.log('banner ad on error.', res)
})

bannerAd.onResize((res)=>{
	console.log('banner ad on resize.', res)
})

广告回调说明：

回调名称参数类型参数说明
onLoadFunction广告加载成功时，回调
onErrorFunction广告加载失败时，回调
onCloseFunction广告关闭时，回调
onResizeFunction广告尺寸变化时，回调
  1. 展示广告

在需要展示广告的时机，调用show方法，展示广告：

js
bannerAd.show()
  1. 关闭广告

在需要关闭广告的时机，调用hide方法，隐藏广告：

js
bannerAd.hide()
  1. 销毁广告

销毁广告时，可以调用：

js
bannerAd.destroy()

版权所有© 2021-2030 上海丞诺网络科技有限公司

沪ICP备17007891号-3 沪公网安备 31011202012782号