npm package: @minipx/recommender
Description: Union SDK for weixin mini game.
Author: crossjs
Latest version: 1.3.1

# 交叉营销插件

- [1 展示规范](#1-展示规范)
  - [1.1 单图+轮播](#11-单图轮播)
  - [1.2 横向 3|4 图](#12-横向-34-图)
  - [1.3 全部展开](#13-全部展开)
- [2 素材规范](#2-素材规范)
  - [2.1 图标](#21-图标)
  - [2.2 广告语](#22-广告语)
  - [2.3 其它](#23-其它)
- [3 资源](#3-资源)
  - [3.1 素材](#31-素材)
  - [3.2 代码](#32-代码)
    - [3.2.1 NPM 包](#321-npm-包)
    - [3.2.2 独立文件](#322-独立文件)
- [4 使用说明](#4-使用说明)
  - [4.1 第一步：引入 SDK](#41-第一步引入-sdk)
  - [4.2 第二步：使用 SDK](#42-第二步使用-sdk)
    - [4.2.1 单图+轮播](#421-单图轮播)
    - [4.2.2 横向 3|4 图](#422-横向-34-图)
    - [4.2.3 全部展开](#423-全部展开)
  - [4.3 第三步：配置 game.json](#43-第三步配置-gamejson)
  - [4.4 第四步：配置 request 合法域名](#44-第四步配置-request-合法域名)

## 1 展示规范

设定屏幕宽度：750

### 1.1 单图+轮播

![ ](assets/marks/single-slide.png)

### 1.2 横向 3|4 图

![ ](assets/marks/horizontal-3.png)
![ ](assets/marks/horizontal-4.png)

### 1.3 全部展开

![ ](assets/marks/all-10.png)

## 2 素材规范

小程序/小游戏要接入交叉营销，需提供以下几个资源：

### 2.1 图标

- 144×144，PNG，直角，不透明，可以是游戏 Logo，建议不要添加文字。

示例 1：游鱼玩

![youyuwan](assets/youyuwan.png)

示例 2：全民耍剑

![shuajian](assets/shuajian.png)

### 2.2 广告语

- 1-6 个字（英文算半个），默认使用游戏名称，允许自定义。

示例 1：更多好玩~

示例 2：一起来耍剑！

### 2.3 其它

- appId：小程序/小游戏 appId
- path：打开的页面路径，可选，如果为空则打开首页
- extraData：需要传递给目标小程序的数据，可选

参考 [小程序官方文档](https://developers.weixin.qq.com/miniprogram/dev/api/wx.navigateToMiniProgram.html)

## 3 资源

### 3.1 素材

见 [assets 目录](assets/)

### 3.2 代码

#### 3.2.1 NPM 包

- [@minipx/recommender](https://www.npmjs.com/package/@minipx/recommender)

#### 3.2.2 独立文件

- [recommender.umd.js](recommender.umd.js)
- [recommender.iife.js](recommender.iife.js)

## 4 使用说明

### 4.1 第一步：引入 SDK

可以使用 NPM

```bash
npm i --save @minipx/recommender
```

也可以直接将上述的独立文件（根据实际需要选择一款即可）拷贝到项目内

### 4.2 第二步：使用 SDK

```js
// 使用 ES6 语法
import Recommender from '@minipx/recommender';
// 或者：
// import Recommender from './path/to/recommender.umd';
// 使用 ES5 语法
const Recommender = require('@minipx/recommender');
// 或者：
// const Recommender = require('./path/to/recommender.umd');

new Recommender({
  appId: '<当前小游戏的 appId>',
  openId: '<当前登录用户的 openId>',
  // 数据加载完成后的回调
  onReady: function(games, recommender) {
    // games 为 null 或数组
    // recommender 为当前营销组件实例
    if (games && games.length) {
      // 构造本地的 UI
    } else {
      // 可能什么也不需要做
    }
  },
  // 默认每八秒切换下一个 App
  onChange: function(game, recommender) {
    if (game) {
      // 构造本地的 UI，显示游戏图标/名称
      // 绑定点击事件，调用 recommender.navigateTo(game)
    } else {
      // 可能什么也不需要做
    }
  },
});
```

**重要提示：**
游戏间的跳转，必须使用 SDK 提供的 `navigateTo` 接口，否则无法准确统计数据

```js
recommender.navigateTo(game)
```

#### 4.2.1 单图+轮播

```js
new Recommender({
  ...
  // 默认每八秒切换下一个 App
  onChange: function(game, recommender) {
    if (game) {
      // 构造本地的 UI，显示游戏图标/名称
      // 绑定点击事件，调用 recommender.navigateTo(game)
    } else {
      // 可能什么也不需要做
    }
  },
});
```

#### 4.2.2 横向 3|4 图

```js
new Recommender({
  ...
  // 数据加载完成后的回调
  onReady: function(games, recommender) {
    // games 为 null 或数组
    // recommender 为当前营销组件实例
    if (games && games.length) {
      // 获取随机的 n 个游戏
      const random3games = recommender.getGames(3);
      // const random4games = recommender.getGames(4);
      // 构造本地的 UI
    } else {
      // 可能什么也不需要做
    }
  },
});
```

#### 4.2.3 全部展开

```js
new Recommender({
  ...
  // 数据加载完成后的回调
  onReady: function(games, recommender) {
    // games 为 null 或数组
    // recommender 为当前营销组件实例
    if (games && games.length) {
      // 构造本地的 UI
      // 创建按钮，绑定点击事件，点击后展开显示所有的游戏
    } else {
      // 可能什么也不需要做
    }
  },
});
```

### 4.3 第三步：配置 game.json

在 `game.json` 中配置 `navigateToMiniProgramAppIdList`，内容为允许跳转的 appId 列表

```json
{
  ...
  "navigateToMiniProgramAppIdList": [
    "wxb17a18edcbb93d0a",
    "wx644ce1d1c71f5a61",
    "wx88d09e8d4cff63ef",
    "wx954573275883779c",
    ...
  ]
}
```

P.S. 请询问支持人员获取可以跳转的 AppID 列表

### 4.4 第四步：配置 request 合法域名

在微信小游戏的开发者后台，配置 request 合法域名

```bash
https://box.minipx.cn
https://log.minipx.cn
```