1 文档修订记录
| 文档版本 | 文档更新日期 | 文档更新内容 |
|---|---|---|
| 3.3.81 | 2024.12.26 | 登录返回是否首次登录标识 |
| 3.3.64 | 2024.09.11 | 新增打开客服会话方法 |
| 3.3.62 | 2024.08.14 | 新增游戏圈、广告、订阅、问卷、分享功能 |
| 3.3.58 | 2024.06.19 | 支持获取渠道参数配置 |
2 接入准备
1.微信小游戏支撑服务介绍， 点击进入
2.微信小游戏接入配置指引，点击进入
3.下载 SDK 拷贝到工程目录，点我下载
4.服务端文档请查阅，点击进入
3 项目接入
3.1 项目引入
1.将下载的 SDK 导入到项目
import NebulaSDK from "./nebula-sdk.js";2.导入星云对接中心渠道配置下载的配置文件，星云开放平台 → 游戏中心 → 选择游戏 → 对接中心 → 渠道打包 → 渠道配置，下载小游戏渠道配置文件fy-config.json
import nebulaConfigJson from "./fy-config.json";3.SDK 属性设置和方法调用
// 属性设置
NebulaSDK.debug = true;
// 方法调用
NebulaSDK.init({ version: "1.0.0", config: nebulaConfigJson });4.方法调用都使用Promise风格进行调用，返回值统一格式
调用示例
async function test() {
// 方法调用统一返回数据格式：{ status, code, msg, data }
const { status, code, msg, data } = await NebulaSDK.init({
version: "1.0.0",
config: nebulaConfigJson,
});
if (status === "success") {
// 初始化成功，进行下一步操作
} else {
// 初始化失败，进行错误处理
}
}数据格式
| 属性名 | 类型 | 说明 |
|---|---|---|
| status | string | 请求状态，成功success、失败error |
| code | string | 状态码，根据不同状态进行处理和错误原因排查 |
| msg | string | 消息，返回响应结果消息，错误返回对应错误描述 |
| data | unknow | 返回值，响应结果不同请求数据格式参照方法说明文档 |
3.2 代码示例
// 导入下载好的星云微信SDK
import NebulaSDK from "./nebula-sdk.js";
// 导入星云对接中心渠道配置下载的配置文件
import configJson from "./fy-config.json";
class Game {
constructor() {
// 1.开启调试模式，查看星云对接中心调试状态
// 2.完成调试后上线前请关闭调试模式
// 3.调试模式初始化前进行开启和关闭
// 4.开发者工具调试尽量开启方便错误排查
NebulaSDK.debug = false;
}
// 游戏初始化
async init() {
// 启动游戏调用初始化方法
const { status, data } = await NebulaSDK.init({
version: "1.0.0", // 游戏版本号
config: nebulaConfig, // 星云对接中心渠道配置
});
if (status === "success") {
// 初始化成功
data.nbAppId; // 星云游戏 AppId
data.nbChannelId; // 星云渠道 ChannelId
} else {
// 初始化失败
}
}
// 游戏登录
async login() {
// 账号登录
const { status, data } = await NebulaSDK.login();
if (status === "success") {
// 登录成功
data.nbOpenId; //聚合渠道用户openId,可作为游戏内玩家的唯一用户标识
data.openId; // 微信小游戏openId,可作为用户扩展属性值使用
} else {
// 登录失败
}
}
async pay() {
const { status, data } = await NebulaSDK.Pay({
tradeNo: "2024010100001", // 游戏订单号
goodsId: "1", // 商品 ID，直购原生支付商品ID和商品价格必须与微信后台一致
goodsPrice: 100, // 商品价格，单位分，直购原生支付商品ID和商品价格必须与微信后台一致
goodsName: "100钻石", // 商品名称
playerId: "1", // 玩家 ID
playerName: "1号玩家", // 玩家名称
playerLevel: "1", // 玩家等级
serverId: "1", // 服务器 ID
vipLevel: "1", // VIP 等级
zoneId: "1", // 分区 ID
sandbox: 0, // 沙箱支付
});
if (status === "success") {
// 支付成功，不同的支付方式最终结果都以服务端通知为基准
// 1.安卓和PC端的原生支付：返回值可代表微信支付的状态
// 2.iOS和PC扫码支付：由于这两种模式已脱离了SDK，所以返回值无法代表支付状态
data.payType; // 支付类型：1=原生支付、2=客服支付、3=二维码支付
data.orderNo; // 星云订单号
} else {
// 支付失败
}
}
}
// 实例化游戏
const game = new Game();
// 游戏初始化
game.init();
// 游戏登录
game.logn();
// 商品支付
game.pay();3.3 属性
| 属性 | 类型 | 默认值 | 说明 |
|---|---|---|---|
| version | string | - | SDK 版本号，建议更新到最新版本 |
| debug | boolean | false |
是否开启调试模式，对应结果查看星云对接中心调试状态，上线后请务必将调试状态关闭！！！ |
3.3.1 调试模式
1.属性
debug: boolean
2.说明
可以进行对接问题排查和检测功能是否完整接入，上线后请务必将调试状态关闭！！！
调试模式开启情况进入，星云开放平台 → 游戏中心 → 选择游戏 → 对接中心 → SDK 对接 → SDK 调试 → H5 → 微信小游戏 SDK → SDK 调试，进行调试结果查看
3.4 方法
3.4.1 初始化(必接)
1.方法
function init(args: SDKOptions): Promise<InitResult>
2.说明
- 作用：用来加载 SDK 的初始化配置
- 调用时机：游戏需要在刚启动游戏的时候调用
- 返回值说明：初始化完成后会回调初始化回调，并返回星云配置参数，包括星云平台 AppID、渠道 ID 等
3.调用
const { status, code, data } = await NebulaSDK.({ version: "1.0.0", config: config });
if (status === "success") {
// 初始化成功
data.nbAppId; //星云游戏AppId
data.nbChannelId; // 星云游戏渠道Id
data.nbChannelTemplateCode; // 星云游戏渠道模板标识
data.passportCode; // 星云通行证标识
data.paymentCode; // 星云游戏支付标识
}else{
// 初始化失败
}4.参数
| 属性 | 类型 | 默认值 | 必填 | 说明 |
|---|---|---|---|---|
| version | string | - | 是 | 游戏版本号 |
| config | object | - | 是 | 星云对接中心渠道配置文件对象 |
5.调用返回值
| 属性 | 类型 | 说明 |
|---|---|---|
| nbAppId | string | 星云游戏 AppId |
| nbChannelId | string | 星云渠道 ChannelId |
| nbChannelTemplateCode | string | 星云渠道标识 |
| passportCode | string | 星云通行证标识 |
| paymentCode | string | 星云支付标识 |
3.4.2 登录(必接)
1.方法
function login(): Promise<LoginResult>
2.说明
- 作用：获取用户信息
- 调用时机：初始化完成后，玩家需要登录时调用
- 登录流程：点我查看
- 返回值说明：星云 nbOpenId 和微信 OpenId 等
3.调用
const { status, data } = await NebulaSDK.login();
if (status === "success") {
// 登录成功
data.nbOpenId; //聚合渠道用户openId,可作为游戏内玩家的唯一用户标识
data.openId; // 微信小游戏openId,可作为用户扩展属性值使用
} else {
// 登录失败
}4.参数
无
5.返回值
| 属性 | 类型 | 说明 |
|---|---|---|
| nbOpenId | string | 聚合渠道用户 openId,可作为游戏内玩家的唯一用户标识 |
| openId | string | 微信小游戏 openId,可作为用户扩展属性值使用 |
| token | string | 登录票据，有效期为7天 |
| firstLogin | boolean | 是否首次登录 |
3.4.3 支付(必接)
1.方法
function pay(args: PayArgs): Promise<PayResult>
2.说明
- 作用：拉起支付界面
- 调用时机：玩家进行商品购买时调用
- 支付流程：点我查看
- 服务端回调：需配置游戏服务端的支付回调地址，支付完成后会通过此地址回调支付结果，配置路径：星云开放平台 → 游戏中心 → 选择游戏 → 对接中心 → SDK 对接 → SDK 列表 → 基础接入参数 → 游戏支付回调地址
- 注意事项：客户端的支付回调不能作为支付成功的依据，不能在此处发放道具，客户端的支付回调只可以用来控制游戏界面显示，例如 loading 框的关闭、遮罩层的关闭。
判断支付是否成功要根据服务端的支付回调。具体的服务端回调请看服务端接入文档
3.调用
const { status, code, msg, data } = await NebulaSDK.pay({
tradeNo: "2024010100001", // 游戏订单号
goodsId: "1", // 商品 ID，直购原生支付商品ID和商品价格必须与微信后台一致
goodsPrice: 100, // 商品价格，单位分，直购原生支付商品ID和商品价格必须与微信后台一致
goodsName: "100钻石", // 商品名称
playerId: "1", // 玩家 ID
playerName: "1号玩家", // 玩家名称
playerLevel: "1", // 玩家等级
serverId: "1", // 服务器 ID
vipLevel: "1", // VIP 等级
zoneId: "1", // 分区 ID
sandbox: 0, // 沙箱支付
});
if (status === "success") {
// 支付成功
} else {
// 支付失败
}4.参数
| 属性 | 类型 | 默认值 | 必填 | 说明 |
|---|---|---|---|---|
| tradeNo | string | - | 是 | 游戏订单号，由游戏生成并管理。服务端支付回调会回传，游戏需进行唯一性校验，防止重复下发商息给玩家，50 个字符内。 对应服务端支付回调的 out_trade_no 参数 |
| goodsId | string | - | 是 | 商品 ID,对应服务端支付回调的 goods_id 参数 |
| goodsPrice | number | - | 是 | 商品价格，单位：分，对应服务端支付回调的 total_amount 参数 |
| goodsName | string | - | 是 | 商品名称 |
| playerId | string | - | 是 | 角色 ID，对应服务端支付回调的 player_id 参数 |
| playerName | string | - | 是 | 角色名称 |
| playerLevel | string | - | 是 | 角色等级 |
| serverId | string | - | 是 | 服务器 ID,对应服务端支付回调的 server_id 参数 |
| vipLevel | number | 0 |
否 | VIP 等级 |
| zoneId | string | 1 |
否 | 分区 ID，对应小游戏平台的支付分区 |
| sandbox | number | 0 |
否 | 沙箱支付，0=正式支付、1=沙箱支付，微信直购商品未发布必须使用 1，正式环境请务必调整为0值！！！ |
| notifyExt | string | - | 否 | 额外参数，游戏的透传参数可通过此参数传递，支付完成后平台服务端会回调此参数给游戏服务端。对应服务端支付回调的 notify_ext 参数 |
| notifyUrl | string | - | 否 | 1.通过该值能在客户端动态传递服务端支付回调地址； 2.若您在客户端传递了该地址，则支付完成后会通过此地址回调支付结果； 3.若您同时也在星云后台配置了支付回调地址，会优先回调客户端传递的地址； 4.需要先配置支付回调可信域名，请前往"星云后台->对接中心->回调配置->支付回调可信域名"进行配置，否则无法回调成功； 5.若您在客户端传递了该地址，在游戏包体发布之前，建议您仔细检查该参数是否配置正确，以防止包体发布后支付出现问题 |
5.返回值
| 属性 | 类型 | 说明 |
|---|---|---|
| payType | number | 支付方式，1=原生支付、2=客服支付、3=二维码支付，支付成功状态success下，不同的支付方式最终结果都以服务端通知为基准1.安卓和 PC 端的原生支付：返回值可代表微信支付的状态 2.iOS 客服和 PC 扫码支付：由于这两种模式已脱离了 SDK，所以返回值无法代表支付状态, 仅代表成功唤起 |
| orderNo | string | 星云订单号 |
3.4.4 问卷(选接)
1.方法
function createSurvey(args: CreateSurveyArgs): Promise<CreateSurveyResult>
2.说明
- 作用：通过传入星云平台的问卷 ID，来确定问卷是否有效，并打开相应的问卷界面
- 配置问卷：需先在腾讯问卷创建问卷，获取问卷链接，然后在星云开放平台配置好问卷链接、标题等，配置路径：：星云开放平台 → 游戏中心 → 选择游戏 → GM 系统 → 微信小游戏运营工具 → 腾讯问卷 → 获取问卷 ID
- 调用创建问卷方法返回问卷实例对象，返回实例为空，则不展示问卷入口，调用
survey.show方法，用户填写问卷后，会回调给游戏客服端，可以根据下发结果判断是否给予奖励
3.调用
const { status, code, msg, data } = await NebulaSDK.createSurvey({
surveyId: 3,
serverId: "1",
});
if (status === "error" || !data.survey) {
// 判断问卷是否有效，不存在则不显示问卷按钮
return;
}
// 1.问卷有效展示问卷按钮,绑定打开问卷事件
// 2.问卷按钮的创建和绑定事件游戏自行实现以下仅为示例
const surveyButton = game.drawSurveyButton();
surveyButton.onClick(() => {
// 绑定问卷返回游戏触发关闭事件
data.survey.onClose(({ status }) => {
if (status === "answered") {
// 问卷已完成
} else {
// 问卷未完成
}
});
// 打开问卷，跳转到腾讯问卷小程序
data.survey.show();
});4.参数
| 属性 | 类型 | 默认值 | 必填 | 说明 |
|---|---|---|---|---|
| surveyId | number | - | 是 | 星云腾讯问卷配置 ID |
| serverId | string | - | 是 | 游戏服务器 ID |
5.返回值
| 属性 | 类型 | 说明 |
|---|---|---|
| survey | object | 问卷对象信息 |
| survey.data | object | 问卷配置信息，无效问卷返回null |
| survey.onClose | function | 鉴定问卷关闭事件，类型survey.onClose(function listener) |
| survey.offClose | function | 移除问卷关闭监听，类型survey.offClose(function listener) |
| survey.show | function | 打开问卷,跳转到腾讯问卷，无参数 |
3.4.5 订阅消息(选接)
1.方法
function requestSubscribeMessage(args: RequestSubscribeMessageArgs): Promise<RequestSubscribeMessageResult>
2.说明
- 作用：通过传入微信公众平台维护的模版 ID，来拉起相应订阅消息
- 配置订阅消息：微信公众平台 → 功能 → 订阅消息 → 添加模板 → 获取模板 ID
- 注意事项：由于微信的规定，
一定要在按钮按下时触发订阅消息，否则无法正常拉起，所以游戏应该绑定onTouchEnd事件，然后在事件回调中调用订阅消息方法 - 返回值说明：各个模版 ID 的订阅状态，比如"接受"、"拒绝"等，游戏可以根据此下发奖励
- 推送订阅消息：完成订阅后，游戏服务端应在合适的时机调用星云的订阅推送接口，玩家微信客户端将收到相应的订阅消息，因为此方法接受的是一次性订阅消息模版，所以玩家每订阅一次，游戏只能推送一次消息给到玩家，详情请查看微信小游戏的订阅消息推送文档
- 更多介绍：请参考微信小游戏订阅消息介绍文档
- 案例介绍：以游戏签到活动为例，游戏使用签到按钮，让玩家拉起订阅消息弹窗，玩家接受订阅后，游戏服务端可以在第二天发起订阅消息推送，从而让玩家收到一条订阅消息
3.调用
// 一次最多同时订阅三个模板，相同模板名称会合并成一个
const { status, data } = await NebulaSDK.requestSubscribeMessage({
tmplIds: ["template-id-1", "template-id-2", "template-id-3"],
});
if (status === "success") {
// 订阅成功
// 订阅消息结果示例：
// [
// { tmplId: "xxxxxxxxxxxxx", status: "accept", always: false },
// { tmplId: "xxxxxxxxxxxxx", status: "filter", always: false },
// { tmplId: "xxxxxxxxxxxxx", status: "reject", always: false },
// { tmplId: "xxxxxxxxxxxxx", status: "ban", always: false },
// ];
// 订阅消息结果说明：
// 1.tmplId: 订阅模板 ID
// 2.status: 订阅状态，accept=接受、filter=过滤、reject=拒绝、ban=封禁
// 3.always: true=总是保持允许，false=总是保持拒绝
} else {
// 订阅失败
}4.参数
| 属性 | 类型 | 默认值 | 必填 | 说明 |
|---|---|---|---|---|
| tmplIds | array | - | 是 | 订阅模板 ID 数组 |
5.返回值
| 属性 | 类型 | 说明 |
|---|---|---|
<subscribeItem>.tmplId |
string | 订阅模板 ID |
<subscribeItem>.status |
string | 订阅状态，accept=接受、filter=过滤、reject=拒绝、ban=封禁 |
<subscribeItem>.always |
boolean | true=总是保持允许，false=总是保持拒绝 |
3.4.6 游戏圈(选接)
1.方法
function createGameClubButton(args: CreateGameClubButtonArgs): Promise<CreateGameClubButtonResult>
2.说明
- 作用：创建游戏圈按钮并显示，玩家可以点击游戏圈按钮打开游戏圈
- 参数说明：调用该方法需传入微信的参数对象wx.createGameClubButton，在
- 返回值说明：
data.gameClubButton游戏圈按钮实例GameClubButton，通过实例调用show方法显示游戏圈按钮，通过这个对象可以控制游戏圈按钮的一些行为
3.调用
const { status, code, msg, data } = await NebulaSDK.createGameClubButton({
type: "image",
style: {
left: 80,
top: 160,
width: 40,
height: 40,
backgroundColor: "#FFFFFF",
},
});
if (status === "success") {
// 创建游戏圈按钮成功，显示游戏圈按钮
data.gameClubButton.show();
} else {
// 创建游戏圈按钮失败
}
// ...
// 隐藏游戏圈按钮，按钮层级较高部分情况隐藏
data.gameClubButton.hide();4.参数
创建游戏圈按钮参数：点我查看
5.返回值
返回data.gameClubButton游戏圈实例按钮，更多属性参考：点我查看
3.4.7 创建 Banner 广告(选接)
1.方法
function createBannerAd(args: CreateBannerAdArgs): Promise<CreateBannerAdResult>
2.说明
- 作用：创建 Banner 广告组件并显示，通过这个对象展示 Banner 广告
- 配置 Banner 广告：微信公众平台 → 流量主 → 广告管理 → Banner 广告- → 新建广告位 → 获取广告位 ID
- 返回值说明：通过广告位 ID 创建 Banner 广告，返回
data.bannerAd广告实例，通过实例调用show方法显示 Banner 广告 - 监听事件说明：OnLoad 监听加载完成，OnError 监听加载失败，OnResize 监听广告尺寸变化
- 广告样式说明：Banner 广告宽度最小 300，小于 300 时，会取作 300；高度不用设置，会根据比例自动缩放；如果要根据 Banner 广告长宽算出 Banner 放置的位置，则需要在 OnResize 监听中获取到 Banner 最终真实的长宽，从而计算出 left 和 top 坐标
- 性能优化说明：如果离开 Banner 广告所展示的游戏页面，要调用 Destroy 方法销毁 banner 广告，释放内存资源
- 更多介绍：请参考微信 Banner 广告介绍文档
3.调用
const { status, code, msg, data } = await NebulaSDK.createBannerAd({
adUnitId: "adunit-xxxxxxxxx",
style: { left: 0, top: 0, width: systemInfo.windowWidth, height: 100 },
});
if (status === "success") {
// 创建 Banner 广告成功，显示 Banner 广告
data.bannerAd.show();
} else {
// 创建 Banner 广告失败
}
// ...
// 隐藏 Banner 广告
data.bannerAd.hide();4.参数
创建 Banner 广告参数：点我查看
5.返回值
返回data.bannerAd广告实例，更多属性参考：点我查看
3.4.8 创建激励视频广告(选接)
1.方法
function createRewardedVideoAd(args: CreateRewardedVideoAdArgs): Promise<CreateRewardedVideoAdResult>
2.说明
- 作用：创建微信小游戏的激励视频广告组件对象，通过这个对象展示激励视频广告
- 配置激励视频广告：微信公众平台 → 流量主 → 广告管理 → 激励视频广告 → 新建广告位 → 获取广告位 ID
- 视频激励广告为全局单例模式，同一个广告位 ID 多次创建的广告实例是同一个，默认广告隐藏建议初始化后直接创建广告实例提高广告加载速度
-
通过广告位 ID 创建激励视频广告，返回
data.rewardedVideoAd广告实例，通过实例调用show方法显示激励视频广告，更多细节点我查看3.调用
// 初始化完成创建广告实例
NebulaSDK.createRewardedVideoAd({ adUnitId: "adunit-xxxxxxxxx" });
// ...
// 进入需要展示广告页面创建获取广告实例
const { status, code, msg, data } = await NebulaSDK.createRewardedVideoAd({ adUnitId: "adunit-xxxxxxxxx" });
if (status === "success") {
// 显示广告触发按钮
game.showRewardedButton();
// 绑定广告按钮点击事件
game.onRewardedButtonClick(() => {
// 视频激励广告实例
const rewardedVideoAd = data.rewardedVideoAd;
// 移除所有的关闭事件监听放置多次下发奖励
rewardedVideoAd.offClose();
// 监听当前广告关闭事件进行奖励下发
rewardedVideoAd.onClose((result) => {
if (result === undefined || result.isEnded) {
// 正常播放结束，可以下发游戏奖励
} else {
// 播放中途退出，不下发游戏奖励
}
// 移除当前广告关闭事件监听
rewardedVideoAd.offClose();
});
// 显示激励视频广告
rewardedVideoAd.show();
});
} else {
// 创建激励视频广告失败
}4.参数
创建激励视频广告参数：点我查看
5.返回值
返回data.rewardedVideoAd广告实例，更多属性参考：点我查看
3.4.9 创建插屏广告(选接)
1.方法
function createInterstitialAd(args: CreateInterstitialAdArgs): Promise<CreateInterstitialAdResult>
2.说明
- 作用：创建插屏广告组件，通过这个对象展示插屏广告
- 配置插屏广告：微信公众平台 → 流量主 → 广告管理 → 插屏广告 → 新建广告位 → 获取广告位 ID
- 返回值说明：通过广告位 ID 创建插屏广告，返回
data.interstitialAd广告实例，通过实例调用show方法显示插屏广告，更多细节点我查看
3.调用
// 页面创建获取广告实例
const { status, code, msg, data } = await NebulaSDK.createInterstitialAd({ adUnitId: "adunit-xxxxxxxxx" });
if (status === "success") {
// 插屏广告实例
const interstitialAd = data.interstitialAd;
// 1.监听当前广告关闭事件进行奖励下发
// 2.多位置触发 offClose 移除监听，避免多次下发奖励
interstitialAd.onClose(() => {
// 关闭插屏广告下发奖励
});
// 显示插屏广告
interstitialAd.show();
} else {
// 创建插屏广告失败
}4.参数
创建插屏广告参数：点我查看
5.返回值
返回data.interstitialAd广告实例，更多属性参考：点我查看
3.4.10 创建原生模板广告(选接)
1.方法
function createCustomAd(args: CreateCustomAdArgs): Promise<CreateCustomAdResult>
2.说明
- 作用：创建原生模板广告组件并显示
- 配置原生模版广告：微信公众平台 → 流量主 → 广告管理 → 原生模板广告 → 新建广告位 → 获取广告位 ID
- 返回值说明：通过广告位 ID 创建原生模板广告，返回
data.customAd广告实例，通过实例调用show方法显示原生模板广告，更多细节点我查看
3.调用
const { status, code, msg, data } = await NebulaSDK.createCustomAd({
adUnitId: "adunit-xxxxxxxxx",
style: { left: 0, top: 0, width: systemInfo.windowWidth, height: 100 },
});
if (status === "success") {
// 创建原生模板广告成功，显示原生模板广告
data.customAd.show();
} else {
// 创建原生模板广告失败
}4.参数
创建原生模板广告参数：点我查看
5.返回值
返回data.customAd广告实例，更多属性参考：点我查看
3.4.11 显示被动转发按钮(选接)
1.方法
function showShareMenu(args: ShowShareMenuArgs): Promise<ShowShareMenuResult>
2.说明
- 作用：菜单中的“转发”选项默认不展示，通过此接口可动态显示这个选项，请在打开游戏以后及时调用此接口显示此转发按钮
- 更多介绍：请参考微信转发介绍文档
3.调用
// 1.shareAppMessage 分享给好友
// 2.shareTimeline 分享到朋友圈
NebulaSDK.showShareMenu({
menus: ["shareAppMessage", "shareTimeline"],
});4.参数
| 属性 | 类型 | 默认值 | 必填 | 说明 |
|---|---|---|---|---|
| menus | array | - | 是 | 转发按钮类型数组，可选值shareAppMessage、shareTimeline |
5.返回值
无
3.4.12 隐藏被动转发按钮(选接)
1.方法
function hideShareMenu(args: HideShareMenuArgs): Promise<HideShareMenuResult>
2.说明
- 作用：通过此接口可动态隐藏菜单中的“转发”选项
- 说明：显示转发按钮，默认使用当前页面截图和小游戏名称作为转发卡片的标题和图片，如果需要自定义转发卡片的标题和图片，可以使用
onShareAppMessage方法 - 更多介绍：请参考微信转发介绍文档
3.调用
// 1.shareAppMessage 分享给好友
// 2.shareTimeline 分享到朋友圈
NebulaSDK.hideShareMenu({
menus: ["shareAppMessage", "shareTimeline"],
});4.参数
| 属性 | 类型 | 默认值 | 必填 | 说明 |
|---|---|---|---|---|
| menus | array | - | 是 | 转发按钮类型数组，可选值shareAppMessage、shareTimeline |
5.返回值
无
3.4.13 绑定被动转发事件(选接)
1.方法
function onShareAppMessage(args: OnShareAppMessageArgs): Promise<OnShareAppMessageResult>
2.说明
- 作用：开启被动转发功能，绑定事件可以自定义转发卡片的标题和图片以及其他配置
- 转发配置：星云开放平台 → 游戏中心 → 选择游戏 → GM 系统 → 微信小游戏运营工具 → 微信转发 → 获取卡片 ID ，转发配置
messageCardId会自动读取卡片的标题和图片，也可以通过其他参数进行覆盖
3.调用
// 显示转发按钮
NebulaSDK.showShareMenu({ menus: ["shareAppMessage"] });
// 分享卡片参数
NebulaSDK.onShareAppMessage(() => {
return { messageCardId: 1 };
});
// 自定义参数
NebulaSDK.onShareAppMessage(() => {
return {
title: "自定义标题",
imageUrl: "xxx.png",
};
});
// 自定义参数-canvans截图
NebulaSDK.onShareAppMessage(() => {
return {
title: "自定义标题",
imageUrl: canvas.toTempFilePathSync({ destWidth: 500, destHeight: 400 }),
};
});
// 卡片ID+自定义参数
NebulaSDK.onShareAppMessage(() => {
return { messageCardId: 1, path: "/" };
});4.参数
| 属性 | 类型 | 默认值 | 必填 | 说明 |
|---|---|---|---|---|
| messageCardId | number | - | 否 | 星云转发卡片配置 ID |
其他更多参数参考：点我查看
5.返回值
无
3.4.14 移除被动转发事件(选接)
1.方法
function offShareAppMessage(args: OffShareAppMessageArgs): Promise<ShareAppMessageResult>
2.说明
- 作用：移除被动转发功能，移除绑定的事件，不再自定义转发卡片的标题和图片
- 说明：移除绑定的事件后，转发按钮会恢复默认的转发卡片标题和图片
3.调用
// 移除所有绑定的被动转发事件
NebulaSDK.offShareAppMessage();
// 被动转发回调函数
const callback = () => {
return { messageCardId: 1 };
};
// 绑定被动转发事件
NebulaSDK.onShareAppMessage(callback);
// 移除指定绑定的被动转发事件
NebulaSDK.offShareAppMessage(callback);4.参数
参数参考：点我查看
5.返回值
无
3.4.15 主动转发(选接)
1.方法
function shareAppMessage(args: ShareAppMessageArgs): Promise<ShareAppMessageResult>
2.说明
- 作用：此方法通过使用微信的参数对象进行配置，来控制转发的标题、图片等，并主动拉起转发界面
- 转发配置：星云开放平台 → 游戏中心 → 选择游戏 → GM 系统 → 微信小游戏运营工具 → 微信转发 → 获取卡片 ID ，转发配置
messageCardId会自动读取卡片的标题和图片，也可以通过其他参数进行覆盖
3.调用
// 分享卡片参数
NebulaSDK.shareAppMessage({ messageCardId: 1 });
// 自定义参数
NebulaSDK.shareAppMessage({
title: "自定义标题",
imageUrl: "xxx.png",
});
// 自定义参数-canvans截图
NebulaSDK.shareAppMessage({
title: "自定义标题",
imageUrl: canvas.toTempFilePathSync({ destWidth: 500, destHeight: 400 }),
});
// 卡片ID+自定义参数
NebulaSDK.shareAppMessage({
messageCardId: 1,
title: "自定义标题",
});4.参数
| 属性 | 类型 | 默认值 | 必填 | 说明 |
|---|---|---|---|---|
| messageCardId | number | - | 否 | 星云转发卡片配置 ID |
其他更多参数参考：点我查看
5.返回值
无
3.4.16 打开客服会话(选接)
1.方法
function openCustomerServiceConversation(args: OpenCustomerServiceConversationArgs): Promise<OpenCustomerServiceConversationResult>
2.说明
- 调用此方法打开客服会话
3.调用
NebulaSDK.openCustomerServiceConversation();4.参数
参数参考：点我查看
5.返回值
无
3.5 错误码
包含所有方法错误码
| 错误码 | 说明 | 备注 |
|---|---|---|
| 10001 | 当前环境不支持 | - |
| 10002 | 未进行初始化调用 | - |
| 10003 | 未进行登录调用 | - |
| 10004 | 获取渠道配置错误 | - |
| 10005 | 创建聚合订单失败 | - |
| 10006 | 订单回调失败 | - |
| 10007 | 预创建订单失败 | - |
| 10008 | 创建扫码订单失败 | - |
| 10009 | 账号存在异常行为，无法支付 | 建议自定义错误处理 |
| 10010 | 设备存在异常行为，无法支付 | 建议自定义错误处理 |
| 10011 | 账号存在异常行为，无法创单 | 建议自定义错误处理 |
| 20001 | 登录失败 | - |
| 30001 | 支付失败 | - |
| 30002 | 渠道支付配置关闭 | 建议自定义错误处理 |
| 30003 | 游戏币支付失败 | - |
| 30004 | 直购支付失败 | - |
| 30005 | 打开客服支付取消 | 建议自定义错误处理 |
| 30006 | 创建客服支付失败 | - |
| 30007 | 创建扫码支付失败 | - |
| 40001 | 创建广告错误 | - |
| 40002 | 创建激励广告错误 | - |
| 40003 | 创建 Banner 广告错误 | - |
| 40004 | 创建插屏广告错误 | - |
| 40005 | 创建自定义广告错误 | - |
| 50001 | 创建问卷错误 | - |
| 60001 | 订阅消息错误 | - |
| 60002 | 订阅消息上报错误 | - |
| 70001 | 分享错误 | - |
| 70002 | 显示分享菜单错误 | - |
| 70003 | 隐藏分享菜单错误 | - |
| 70004 | 分享卡片错误 | - |
| 70005 | 监听分享错误 | - |
| 70006 | 取消分享错误 | - |
4 FAQ
- 支付金额错误
支付金额单位是分，要进行转换
- 商品 ID 错误
小游戏直购未发布的商品只能使用沙箱模式支付，商品金额和商品 ID 必须与小游戏后台配置的一致
- 提示环境不支持
由于开发游戏可能用不使用微信开发者工具，在其他 IDE 中无法调用微信小游戏的接口，所以会提示环境不支持
- 渠道支付配置关闭
渠道支付配置关闭，通过星云渠道配置进行开启，不开启游戏支付返回失败，建议可以根据状态码30002进行自定义处理，显示友好提示
- 客服支付和扫码支付，手机还未进行付款返回结果支付成功
客服支付和扫码支付，无法检测到用户是否已经付款，打开客服和生成二维码即可算成功，可以根据返回值payType进行自定义处理
- 无法原生支付
商品ID和商品价格必须与微信后台一致，否则可能提示系统错误，商品未发布也可能导致支付失败
- 真机无法分享
小游戏必须认证完后才能进行分享，如果存在违规需要微信后台消息全部处理完成并且申诉通过才可以正常分享
- 部分接口无法调用
星云开放平台 → 游戏中心 → 选择游戏 → 对接中心 → 渠道打包 → 渠道配置 -> 微信配置信息，查看更新配置
- 微信商品作为档位对应多个游戏道具
支付设置参数notifyExt参数包含对应的游戏道具信息，游戏服务端根据notifyExt参数进行发放道具
5 Unity 游戏对接
如果您的游戏是 Unity 引擎开发的，我们有提供专门给 Unity 工程对接的桥接代码，以方便 Unity 游戏快速接入。请点击以下链接跳转到相应的文档：