# 互动游戏

## 简介

互动游戏是DCloud联合三方服务商为开发者提供新的广告场景增值服务。开发者在App中放置入口，用户点击入口参与权益化、趣味性的活动。通过观看激励视频广告加速获取权益。沉浸的游戏体验能够降低对广告的抵触心理，增加激励视频广告展示的同时有效提高广告收益。

![](https://web-assets.dcloud.net.cn/unidoc/zh/interactive1.png)


## 活动场景类型：

共抽奖类、游戏类、养成类3种场景类型，开发者可根据自身情况选择活动类型：

1. 抽奖类活动：通过转盘、扭蛋、摇骰子等抽奖玩法获得奖品碎片或红包奖励
2. 游戏类活动：通过合成游戏、成语答题、捕鱼等游戏玩法获得金币或红包奖励
3. 养成类活动：果园、农场、养牛等长期活动，用户通过连续签到、道具收集、任务体系等玩法提升养成对象的等级，升级后可获得红包奖励或兑换奖品

![](https://web-assets.dcloud.net.cn/unidoc/zh/interactive2.jpg)

### 活动分类表
<table>
	<thead style="background-color: #f8f8f8;">
		<tr>
			<td>活动分类</td>
			<td>活动名称</td>
			<td>发放奖励</td>
			<td>活动周期</td>
			<td>是否支持积分打通</td>
		</tr>
	</thead>
	<tbody>
		<tr>
			<td rowspan="3">抽奖</td>
			<td>集碎片</td>
			<td>多奖品</td>
			<td>7天</td>
			<td></td>
		</tr>
		<tr>
			<td>印钞机</td>
			<td>现金</td>
			<td>7天</td>
			<td></td>
		</tr>
		<tr>
			<td>扭蛋机</td>
			<td>多奖品</td>
			<td>7天</td>
			<td></td>
		</tr>
		<tr>
			<td rowspan="4">游戏</td>
			<td>大富翁</td>
			<td>现金</td>
			<td>7天</td>
			<td>支持</td>
		</tr>
		<tr>
			<td>成语大赢家</td>
			<td>现金</td>
			<td>7天</td>
			<td></td>
		</tr>
		<tr>
			<td>合成招财猫</td>
			<td>现金</td>
			<td>7天</td>
			<td></td>
		</tr>
		<tr>
			<td>捕鱼达人</td>
			<td>现金</td>
			<td>长期</td>
			<td>新增支持</td>
		</tr>
		<tr>
			<td rowspan="5">养成</td>
			<td>福牛</td>
			<td>现金</td>
			<td>7天</td>
			<td></td>
		</tr>
		<tr>
			<td>果园</td>
			<td>水果</td>
			<td>长期</td>
			<td></td>
		</tr>
		<tr>
			<td>农场</td>
			<td>现金</td>
			<td>30天</td>
			<td></td>
		</tr>
		<tr>
			<td>养鸡</td>
			<td>现金</td>
			<td>长期</td>
			<td></td>
		</tr>
		<tr>
			<td>走路赚</td>
			<td>现金</td>
			<td>7天</td>
			<td>支持</td>
		</tr>
	</tbody>
</table>

注：如要选择对应的活动，请在创建互动游戏广告位时把对应的活动名称填入到广告位名称内，创建后不可修改，如需修改，请邮件联系[uniad@dcloud.io](mailto:uniad@dcloud.io)

## 关于奖励发放的说明

互动游戏的目的是吸引用户参与活动，引导用户观看广告，通过活动获取奖励，满足特定条件后需要向用户发放奖励。目前有两种奖励发放方式，一种是由DCloud联合三方服务商为开发者提供用户奖励线下代发；一种是由开发者对接App自身积分系统，将用户奖励转换为App积分，提高用户参与度和体验。

### 用户奖励线下代发服务
默认使用用户奖励线下代发服务，具体说明如下：
1. 用户参与以上活动达到一定资产时（奖品碎片或金币到达兑换门槛，红包金额到达提现门槛），可发起兑奖申请。如用户申请提现，需要填写收款的支付宝或微信账号；如用户申请兑换虚拟或者实物奖品，需要填写联系人联系方式和收货地址等；具体以兑奖弹窗为准。
2. 用户提交兑奖申请后，客服将在5个工作日内确认，确认后将尽快为您进行发货，如实物奖品有发货时间较长等问题请联系客服。
3. 如实物奖品（水果生鲜等）因为时令问题、疫情区域或者新疆、西藏等偏远地区暂时无法寄送，客服将联系用户赠送奖品价值相等的现金奖励。
4. 实物奖品发放后,快递配送请在24小时内收货,如有质量问题,请于签收后48小时内进行售后申请,超出时间不予赔付。
5. 用户不得使用任何外挂、插件以及其他破坏破坏活动规则、违背活动公平原则的方式参加本次活动，否则服务商有权取消用户参与活动的资格以及清空获得的奖励。


### 用户奖励对接App积分

积分对接需要开发者业务系统与三方服务商的互动游戏进行对接，需要一定的开发工作量，请邮件联系[uniad@dcloud.io](mailto:uniad@dcloud.io)

**平台差异说明**

|App|H5|微信小程序|支付宝小程序|百度小程序|字节跳动小程序、飞书小程序|QQ小程序|快手小程序|京东小程序|
|:-:|:-:|:-:|:-:|:-:|:-:|:-:|:-:|:-:|
|App 3.1.15+|x|x|x|x|x|x|x|x|

**开通配置广告**

[开通广告步骤详情](https://uniapp.dcloud.net.cn/uni-ad.html#start)

注意：打包时必须选择要集成的广告SDK互动游戏(变现猫)，优量汇、穿山甲、快手至少选择其中一个。

### 语法

`uni.createInteractiveAd(options)`

### 参数说明

`options` 为 object 类型，属性如下：

|属性名		|类型		|必填	|描述			|
|:-:|:-:|:-:|:-:|
|adpid	  |string	|	是 |广告位 id |
|provider	|string	|	是 |服务商标识，即插件id|
|userData	|object	|	否 |对接App积分系统参数 |


`provider` 值：

|值		|描述			|
|:-:|:-:|
|BXM-AD	  |互动游戏变现猫|



### 广告创建

广告组件默认是隐藏的，因此可以提前创建，以提前初始化组件。开发者可以在页面的 onReady 事件回调中创建广告实例，并在该页面的生命周期内重复调用该广告实例。


### 显示/隐藏

广告组件默认是隐藏的，开发者需要调用 CreateInteractiveAd.show() 进行显示。如果广告拉取失败或触发频率限制，CreateInteractiveAd.show() 方法会返回一个rejected Promise，开发者可自行监听错误信息

```js
CreateInteractiveAd.show().catch((err) => {
  console.error(err)
})
```

用户可以主动关闭广告。开发者不可控制广告组件的隐藏。


### 监听广告加载成功事件

如果广告加载成功，通过 CreateInteractiveAd.onLoad() 注册的回调函数会执行，回调函数返回广告素材参数。


|属性名		|类型		|描述			|
|:-:|:-:|:-:|
|imgUrl	  |string	|	广告素材图片的url地址 |


```js
CreateInteractiveAd.onLoad(res => {
    console.log('图片素材地址', res.imgUrl);
    console.log('广告加载成功');
})
```


HBuilder基座的测试广告位 adpid: `1042956255` (游戏); `1620839118` (抽奖); `1064042976` (养成)


示例代码

```html
<template>
  <view>
    <image class="ad-icon" v-if="imgUrl" :src="imgUrl" @click="showInteractiveAd"></image>
  </view>
</template>

<script>
  export default {
    data() {
      return {
        title: '互动游戏',
        loading: false,
        imgUrl: ""
      }
    },
    onReady() {
      this.adOption = {
        adpid: '1042956255',
        provider: 'BXM-AD'
      };

      // 创建广告实例
      this.createInteractiveAd();
    },
    methods: {
      createInteractiveAd() {
        var interactiveAd = this.interactiveAd = uni.createInteractiveAd(this.adOption);
        interactiveAd.onLoad((e) => {
          this.loading = false;
          this.imgUrl = e.imgUrl;
          console.log("广告加载成功");
          // 如果有广告图片素材, 通过 e.imgUrl 获取
        });
        interactiveAd.onClose(() => {
          // 用户点击了关闭或返回键(仅Android有返回键)
          console.log("广告关闭");
        });
        interactiveAd.onError((err) => {
          this.loading = false;
          console.log("广告加载失败");
        });

        // 广告实例创建成功后默认会执行一次 load，加载广告数据
        // 如果界面有 "显示广告" 按钮，需要先禁用掉，防止用户点击，等待广告数据加载成功后在放开
        this.loading = true;
      },
      showInteractiveAd() {
        // 调用 interactiveAd.show()，如果数据正在加载中不会显示广告，加载成功后才显示
        // 在数据没有加载成功时，需要防止用户频繁点击显示广告
        if (this.loading == true) {
          return
        }
        this.loading = true;
        this.interactiveAd.show().then(() => {
          this.loading = false;
        });
      }
    },
    onUnload() {
      // 页面关闭后销毁实例
      this.interactiveAd.destroy();
    }
  }
</script>
<style>
  .ad-icon {
    display: block;
    width: 80px;
    height: 80px;
    margin: 10px;
  }
</style>
```


#### 方法

`Promise CreateInteractiveAd.load()`

加载广告。

`Promise CreateInteractiveAd.show()`

显示广告。

`CreateInteractiveAd.reportExposure()`

场景入口曝光打点。

`CreateInteractiveAd.destroy()`

销毁广告实例。

`CreateInteractiveAd.onLoad(function callback)`

监听广告加载事件。

`CreateInteractiveAd.offLoad(function callback)`

取消监听广告加载事件

`CreateInteractiveAd.onError(function callback)`

监听错误事件。

`CreateInteractiveAd.offError(function callback)`

取消监听错误事件


### 积分对接

### 开通

1. 开发者需要提供广告位 `adpid`
2. 开发者需要提供服务器接口
  1. 获取积分接口
  2. 操作积分接口
4. 三方服务商需要提供 `secretKey` 让开发者来验签请求来源


### 获取积分

简要描述：

该接口用于获取用户总积分数量；

开发者提供url用户查询积分

请求方式 `GET`

参数：

|参数名|必选|类型|说明|
|:-:|:-:|:-:|:-:|
|appUserId|是|String|app用户Id|
|appId|是|String|SSP后台注册的appId|
|timestamp|是|String|时间戳（自1970年起，精确到毫秒）|
|sign|是|String|签名,用于验证身份。按照按 secretKey + timestamp 的进行MD5加密（注意加密后字符串要转大写，不要加上“+”号）|

返回参数说明

|参数名|类型|说明|
|:-:|:-:|:-:|
|appUserId|String|app用户Id|
|avatar|String|用户头像|
|nickname|String|用户昵称|
|amount|Long|用户总积分|

示例

```json
  {
   "appUserId" : "dcloud",
   "avatar": "https://xxx.yyy.com/xxxx.jpg",
   "nickname": "jack",
   "amount": 100
  }
```

### 操作积分

简要描述：

此接口用于操作用户积分数量，如增加、扣除；
请求参数放在body里，以JSON格式提交；
考虑到接口的安全，建议开发者采用IP白名单+签名的方式校验来源，以防备被第三方利用。


失败情况：

- URL存在特殊字符或无法通过外网访问；
- 没有按照响应格式要求返回的内容；
- 接口返回状态码非`200`的情况；
- 接口响应时间超过`3`秒。

开发者提供url用户查询积分

请求方式 `POST`

参数：

|参数名|必选|类型|说明|
|:-:|:-:|:-:|:-:|
|appUserId|是|String|App用户Id(唯一标识)|
|appId|是|String|SSP后台注册的appId|
|operateType|是|Long|操作类型：1.增加 2.扣除|
|amount|是|Long|本次操作的积分值|
|timestamp|是|String|时间戳（自1970年起，精确到毫秒）|
|sign|是|String|签名，用于验证身份。按照按 secretKey + timestamp 进行MD5加密（注意加密后字符串要转大写，不要加上“+”号）|

返回参数说明

|参数名|类型|说明|
|:-:|:-:|:-:|
|appUserId|String|App用户Id(唯一标识)|
|status|int|状态码：0. 处理失败 1. 处理成功|
|message|String|失败原因|
|amount|Long|操作后的用户总积分|

返回结果示例
```json
{
  "appUserId": "dcloud",
  "status": 1,
  "amount": 100
}
```
