---
description: 适于使用creator引擎开发的小游戏接口参考
---

# 常用接口

### 初始化（必接）

**初始化接口**

{% code lineNumbers="true" fullWidth="false" %}
```typescript
/**
 * 初始化小游戏sdk
 * @param appid 动能appid
 * @param appKey 动能appkey
 * @param offerId
 * @param cloudEnv
 * @param payRate 根据小游戏平台配置支付时设置的支付比例（1：1、1：10、1：100）确认传1、10、100
 * @param callBack
 * @param packageName //华为快应用需要传包名 非华为传null
 * @param gravityEngineToken //引力引擎token
 */
miniGameInit(appid: string, appKey: string, offerId: string, cloudEnv: string, payRate: number, callBack: Function, packageName?: string, gravityEngineToken?: string)
```
{% endcode %}

示例

{% hint style="danger" %}
<mark style="color:red;">**接入时H5动能appid和H5动能appkey需改为正式参数！！！**</mark>
{% endhint %}

{% code lineNumbers="true" %}
```typescript
//示例
Wb.Core.miniGameInit("您的动能appid", "您的动能appkey", "米大师侧申请的应用ID", "云函数的环境ID", 10, (ret, openId, userCode) => {
        if (ret) {
            console.log('dnsdk初始化成功');
        } else {
            console.log('dnsdk初始化失败');
        }
    }, null, "");
```
{% endcode %}

### 统计（必接）

根据统计埋点文件使用合适接口上报游戏中产生的事件。

{% hint style="danger" %}
**转化行为`active`和`active_register`事件必接！！！**
{% endhint %}

#### 1. 自定义事件（必接）

接口说明

{% code lineNumbers="true" %}
```typescript
tJCustomEvent(eventId: string): void
tJCustomEventLabel(eventId: string, label: string): void
tJCustomEventHashMap(eventId: string, attributes: string): void
```
{% endcode %}

事件说明

<table data-header-hidden data-full-width="false"><thead><tr><th></th><th></th><th></th><th></th></tr></thead><tbody><tr><td><strong>事件名称</strong></td><td><strong>事件ID</strong></td><td><strong>触发时机</strong></td><td><strong>附加参数</strong></td></tr><tr><td>游戏loading页面</td><td>app_loading_show<br></td><td>游戏引擎初始化后就触发上报</td><td>无</td></tr><tr><td>游戏内首页</td><td>app_home_show</td><td>主页展示时</td><td>无</td></tr></tbody></table>

使用示例

{% code lineNumbers="true" %}
```typescript
//示例
Wb.Tj.tJCustomEvent("app_loading_show");
Wb.Tj.tJCustomEvent("app_home_show");
```
{% endcode %}

#### 2. 转化行为上报（必接）

{% hint style="warning" %}
**注意：转化行为上报使用`tJSendTrackingEvent`接口！！！**\
**SDK会本地缓存埋点记录，再上报会进行拦截**
{% endhint %}

接口说明

{% code lineNumbers="true" %}
```typescript
/// <summary>
/// 转化行为上报
/// </summary>
/// <param name="eventId">事件id</param>
/// <param name="label">额外参数json字符串</param>
tJSendTrackingEvent(eventId: string, label: string): void
```
{% endcode %}

| **事件id**                  | **事件定义**      | **data额外携带数据** | **建议上报时机**                           |
| ------------------------- | ------------- | -------------- | ------------------------------------ |
| active(自实现上报必接)           | 激活            | <p><br></p>    | <p>首次进入主页触发<br></p>                  |
| active\_register(自实现上报必接) | <p>注册<br></p> | <p><br></p>    | 完成角色创建后触发。如果没有角色创建过程，可跟active事件同时触发。 |

使用示例

{% code lineNumbers="true" %}
```typescript
Wb.Tj.tJSendTrackingEvent("active")；
Wb.Tj.tJSendTrackingEvent("active_register")；
```
{% endcode %}

#### 3.关卡统计上报（必接）

接口说明

{% code lineNumbers="true" %}
```typescript
/// <summary>
/// 关卡开始
/// </summary>
/// <param name="level">关卡id</param>
startLevel(level: string): void 

/// <summary>
/// 关卡获胜
/// </summary>
/// <param name="level">关卡id</param>
/// <param name="score">得分</param>
finishLevel(level: string, score: string): void

/// <summary>
/// 关卡失败
/// </summary>
/// <param name="level">关卡id</param>
/// <param name="score">得分</param>
failLevel(level: string, score: string): void
```
{% endcode %}

事件说明

| **事件id** | **事件定义** | **data额外携带数据**        | **建议上报时机** |
| -------- | -------- | --------------------- | ---------- |
| begin    | 开始       | levelid:关卡ID          | 进入关卡       |
| complete | 胜利       | levelid:关卡IDscore:得分  | 关卡胜利       |
| fail     | 失败       | levelid:关卡IDscore: 得分 | 关卡失败       |

使用示例

{% code lineNumbers="true" %}
```typescript
Wb.Tj.startLevel("3-1");
Wb.Tj.finishLevel("3-1"， "100");
Wb.Tj.failLevel("3-1"， "100");
```
{% endcode %}

#### 4.用户行为统计上报

| **事件id**             | **事件定义** | **data额外携带数据**                                          | **建议上报时机**               |
| -------------------- | -------- | ------------------------------------------------------- | ------------------------ |
| online               | 在线时长     | duration--时长（秒）                                         | 用户切到后台或者杀掉进程时            |
| setting\_page\_click | 设置页点击    | button\_click：1用户反馈，2游戏圈，3微信客服                          | 设置页内点击按钮时（用户反馈，游戏圈、微信客服） |
| self\_button\_click  | 大厅内点击    | button:1-点击购物车，2-点击跳转合成界面，3-点击任务栏，4-点击能量弹窗（各游戏需要自己定义数值） | <p>大厅界面点击按钮时<br></p>     |

#### 5.分享/邀请统计上报

|          | **事件id**            | **事件定义**                                                 | **data额外携带数据**                  | **建议上报时机**                  |
| -------- | ------------------- | -------------------------------------------------------- | ------------------------------- | --------------------------- |
| 分享       | help\_share         | 分享小程序                                                    |                                 | 分享小程序到会话时                   |
| 点击求助好友按钮 | help\_button\_click | bonus\_status:1领取成功，2领取失败 help\_times\_left: 剩余领取次数1,2,3 | 点击求助好友按钮时                       |                             |
| 邀请       | invite\_click       | 点击邀请好友入口                                                 | invite\_number:邀请好友的数量 0,1,2... | 玩家在主页点击邀请好友入口时上报 （首次弹出时上报0） |
| 点击加号邀请好友 | invite\_click\_plus | /                                                        | 玩家在邀请好友界面点击加号时                  |                             |
| 点击领取奖励   | bonus\_click        | bonus\_status:1领取成功，2领取失败                                | 点击领取奖励时                         |                             |

#### 6.设置关卡和活动进度

{% hint style="warning" %}
**`sdk`上报`stay_time`事件时会携带下面设置的数据**
{% endhint %}

接口说明

{% code lineNumbers="true" %}
```typescript
/// <summary>
/// 设置上报level_id参数
/// </summary>
/// <param name="levelId"></param>
SetTjLevelId(levelId: string): void

/// <summary>
/// 设置上报活动进度参数
/// </summary>
/// <param name="json">活动json格式的字符串</param>
SetTjActivityProgress(json: string): void
```
{% endcode %}

使用示例

{% code lineNumbers="true" %}
```typescript
Wb.Tj.SetTjLevelId("10");

Wb.Tj.SetTjActivityProgress("{\"activity_id\":10,\"activity_progress\":15,\"activity_bonus_id\":15,\"begain_time\":100,\"valid_time\":120}");
```
{% endcode %}

#### 7.设置用户标识

{% hint style="warning" %}
**调用下面接口设置后，所有事件上报都会携带用户id**
{% endhint %}

{% code lineNumbers="true" %}
```typescript
/// <summary>
/// 设置用户id
/// </summary>
/// <param name="userId">用户id</param>
setLoginId(id: string): void
```
{% endcode %}

使用示例

{% code lineNumbers="true" %}
```typescript
Wb.Core.setLoginId("123321");
```
{% endcode %}

### 广告（必接）

#### 1. 打开广告

{% code lineNumbers="true" %}
```typescript
/// <summary>
/// 打开广告
 /// </summary>
/// <param name="adName">广告位名称</param>
/// <param name="callBackFun">广告关闭回调，状态0成功、1失败、2加载失败</param>
openAd(adName: string, callback: Function = null): void
```
{% endcode %}

示例

{% code lineNumbers="true" %}
```typescript
Wb.Ad.openAd("banner");
Wb.Ad.openAd("home_mfzs", (ret, data) => {
        console.log('打开视频广告 data = ' + JSON.stringify(data));
});
```
{% endcode %}

#### 2. 广告是否缓存好

广告为实时加载方式（不缓存广告），调用接口直接返回`true`

{% code lineNumbers="true" %}
```typescript
/// <summary>
/// 广告是否缓存好
/// </summary>
/// <param name="adName">广告位名称</param>
isAdReady(adName: string): boolean
```
{% endcode %}

#### 3. 某关卡是否可以打开该广告

{% code lineNumbers="true" %}
```typescript
/// <summary>
/// 某关卡是否可以打开该广告
/// </summary>
/// <param name="adName">广告位名称</param>
/// <param name="level">关卡id</param>
isAdBeOpenInLevel(adName: string, level: number): boolean
```
{% endcode %}

#### 4. 关闭广告

{% code lineNumbers="true" %}
```typescript
/// <summary>
/// 关闭广告
/// </summary>
/// <param name="adName">广告位名称</param>
closeAd(adName: string): void
```
{% endcode %}

### 支付

#### 1.支付接口

{% hint style="info" %}
**注：**\
**1： 虚拟支付 1.0版本**\
**2： 虚拟支付 2.0版本**\
**3: SDK默认为1：10旧接口升级后参数要赋值给新接口`PayParam`对应字段！！！**\
&#xNAN;**`custom`字段为透传自定义数据字段，该字段会包含在订单信息中，有透传需求请使用该字段！！！**
{% endhint %}

支付接口

{% code lineNumbers="true" %}
```typescript
/// <summary>
/// 小游戏支付
/// </summary>
/// <param name="info">支付参数</param>
/// <param name="func"></param>
miniPay(info: any, func: Function): void
```
{% endcode %}

调用示例

{% code lineNumbers="true" %}
```typescript

// id 计费点id
// price 金额（单位分）
// payDesc 商品描述，使用#拼接
// payCode 支付code，没有填写计费点payId
// giftId 礼包id，没有的话写计费点payId
// giftType 礼包类型
// giftNum 礼包数量，一次购买了几份，最小值为1
// giftPrice 礼包价值，没有可填写price金额值（单位分）
// levelId 有用户等级的传用户等级，没有用户等级的游戏传关卡id
// tokenType 代币类型（当礼包类型为代币礼包时，传参。否则传空串）
// custom 用户自定义数据代替userdata（截取16个字符赋值userdata）,最长128个字符
// payPush 礼包推送：1主动点击；0被动推送
// userId 户的账号ID，无账号游戏为空。最长128个字符

//支付参数 （后方未注释必填的可不填）
let obj = {
    "id":"test1", //若无定义可直接填giftId
    "price":"100", // 必填 单位：分
    "payCode":"testcode",  // 必填
    "payDesc":"珍贵宝箱", // 必填
    "giftId":"giftId", // 必填
    "custom":"custom", // 自定义类型参数（可根据需要传递）
    "giftType":"giftType",
    "giftNum":"1",
    "levelId":"levelId",
    "tokenType":"1",
    "extParams": { // 此参数统计事件中会携带
        "value1":"1",
        "value2":"2" 
    }
};
  Wb.Pay.miniPay(obj, (result, info) => {
    console.log("支付测试 orderPay info = " + info);
    console.log("支付result ", result)
    this.label.string = info;
    if (result) {
        let param = JSON.parse(info);
        console.log("支付测试 充值到账上报");
        //@ts-ignore
        Wb.Tj.tJPayOnAccount(param.orderId);
        console.log("支付回调成功，上报pay_token_change")
        Wb.Tj.tJCustomEventLabel("pay_token_change", "");
    }
})
```
{% endcode %}

**自测示例**

虚拟支付2.0会进行验签请求，可通过日志查看

<figure><img src="https://3109237457-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FpGDLwHS4NGOCL3SVgTBf%2Fuploads%2Fgit-blob-0a6afadab3b3422202252911387fb795092ac2d3%2Fimage%20(33).png?alt=media" alt=""><figcaption></figcaption></figure>

虚拟支付1.0不会进行验签请求，会直接拉起支付

<figure><img src="https://3109237457-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FpGDLwHS4NGOCL3SVgTBf%2Fuploads%2Fgit-blob-4a0055d8a8fdce3e9891be270ed9c18ed608cb77%2Fimage%20(34).png?alt=media" alt=""><figcaption></figcaption></figure>

#### 2.上报到账事件和消单

{% hint style="info" %}
**游戏发奖的同时调用该接口上报充值到账事件，同时sdk会进行消单处理，整个支付流程结束。**
{% endhint %}

{% code lineNumbers="true" %}
```typescript
/// <summary>
/// 充值到账后上报
/// </summary>
/// <param name="tradeId">订单id</param>
tJPayOnAccount(tradeId: string): void
```
{% endcode %}

#### 3. 补单

> 适用场景：使用sdk支付

{% hint style="info" %}
**游戏在合适时机调用该接口设置补单回调，sdk会在游戏首次调用和onShow时，触发补单逻辑进行补单**
{% endhint %}

设置补单回调，触发sdk中的补单逻辑。

{% code lineNumbers="true" %}
```typescript
/// <summary>
/// 设置补单回调
/// 调用该接口会触发sdk补单流程
/// 根据实际情况确认调用时机
/// </summary>
/// <param name="callFun">支付回调</param>
setInventoryCallBack(func: Function): void

Wb.Pay.setInventoryCallBack((payStatus, payId, userData, orderId) => {
    if (payStatus == true) {
        console.log("支付测试 充值到账上报");
        Wb.Tj.tJPayOnAccount(orderId);
    }
});
```
{% endcode %}

### 分享

分享策略名称由策划或运营提供。

#### 1.主动分享

{% code lineNumbers="true" %}
```typescript
/// <summary>
/// 小游戏-主动分享接口
/// </summary>
/// <param name="shareName">分享策略名称</param>
/// <param name="userData">自定义数据使用'&'拼接</param>
shareAppMessage(shareName: string, userData: string, callBack: Function): void

//调用示例
Wb.Social.shareAppMessage("friend_share", userData, (ret) => {
    console.log("分享 shareAppMessage ret:", ret);
});
```
{% endcode %}

#### 2. 点击右上角分享

**点击`右上角"..."进行分享`触发**，**前提是要先主动调用设置分享监听`OnShareAppMessage`，触发右上角分享时才会调用下面的设置。**

{% code lineNumbers="true" %}
```typescript
/// <summary>
/// 小游戏-右上角分享接口
/// </summary>
/// <param name="shareName">分享策略名称</param>
/// <param name="userData">自定义数据使用'&'拼接</param>
onShareAppMessage(shareName: string, userData: string): void

//调用示例
Wb.Social.onShareAppMessage("friend_share", userData);
```
{% endcode %}

### 获取游戏在线配置

{% code lineNumbers="true" %}
```typescript
/// <summary>
/// 获取游戏在线配置
/// </summary>
/// <param name="version">配置版本</param>
initGameConfig(version: number);

/// <summary>
/// 游戏在线配置回调
/// </summary>
/// <param name="fun">回调</param>
SetOnNewConfigFectched(fun: Function);

/// <summary>
///  根据key获取参数
/// </summary>
/// <param name="key">关键字</param>
getConfigValue(key: string);

//调用示例
//获取游戏在线参数
Wb.Core.initGameConfig(2);
Wb.Core.SetOnNewConfigFectched(function (result: boolean) {
    if (result) {
        console.log("获取成功");
        let ret = Wb.Core.getConfigValue("status");
        console.log('ret:' + ret);
    } else {
        console.log("获取失败");
    }
});
```
{% endcode %}

### 兑换码

#### 1. 兑换码开关

{% hint style="danger" %}
**自定义配置参数 key：dhm** **通过游戏在线参数配置 initGameConfig 获取兑换码开关！！！**
{% endhint %}

#### 2. 使用兑换码

```typescript
/// <summary>
/// 使用兑换码
/// </summary>
/// <param name="dhm">兑换码id</param>
/// <param name="callFun">回调</param>
useCDKey(dhm: string, fun: Function)
```

兑换码状态

```typescript
* 200 兑换成功
* 401 param is error 参数验证不通过
* 402 无效操作
* 403 兑换码无效
* 404 网络错误
* 405 兑换失败，当前兑换码已经被使用过了
* 406 当前兑换码已经失效
* 407 同一个兑换码只能使用一次
* 408 无法识别该兑换码
* 505 系统繁忙
```

示例：

```typescript
* @param status 使用状态
* @param price 价格分
* @param msg 提示文字
Wb.Core.useCDKey("test", (status, price, msg) => {
    console.log("useCDKey status = " + status + " price = " + price + " msg = " + msg);
});
```
