# CPS组件API开发接入文档

> 基础库 3.8.6 开始支持，低版本需做[兼容处理](/minigame/dev/guide/runtime/client-lib/compatibility.md)

## 一、组件概览

CPS组件需3.8.6及以上基础库版本支持，基于 [PageManager](/minigame/dev/api/open-api/openlink/PageManager.md) 能力。
CPS组件分为「单游戏组件、多游戏组件、游戏橱窗」三种，mp端配置后均可使用API创建。

从左往右依次是「单游戏组件、多游戏组件、游戏橱窗」

![](https://mmgame.qpic.cn/image/7071a419ddc9d61c86a340022cda803842b5a217d4648f0c1d5516bf871a482b/0)
![](https://mmgame.qpic.cn/image/7dcd98bb8eb71c7025b05b0f2e42f07c68b193837e34a0b93a129e95359f52b2/0)
![](https://mmgame.qpic.cn/image/a067cbc7478630f4ee0ac34d0f2a461b538be2c1af4bc63d2c8473425b67238c/0)

### 1. 输入参数

| 参数            | 类型       | 必填 | 说明                                                                                   |
|-----------------|------------|------|----------------------------------------------------------------------------------------|
| Object.id       | string     | 是   | 必选，填入mp端配置的组件ID                                                             |
| Object.left     | number     | 否   | 可选，组件左上角屏幕横坐标
单游戏组件/多游戏组件时有效
不填时平台将自动适应游戏类型并展示 |
| Object.top      | number     | 否   | 可选，组件左上角屏幕纵坐标
单游戏组件/多游戏组件时有效
不填时平台将自动适应游戏类型并展示    |
| Object.isVertical | boolean    | 否   | 可选，当为「多游戏组件」时，可以选择「水平展示/竖直展示」，默认为false |
| Object.query    | object     | 否   | 可选，打开CPS游戏时传入的启动query参数  |

### 2. 监听事件

| 回调类型 | 回调时机                     | 返回     | 备注
|----------|------------------------------|----------|----|
| ready  | 组件加载完毕时触发           | -        | - |
| show     | 用户侧展示组件时触发         | -        | - |
| destroy  | 用户关闭组件时触发           | -        | - |
| clickgame    | 用户点击组件中的CPS游戏时触发 | Object   | 从CPS游戏返回后触发 |
| error    | 组件发生错误时触发           | Object   | - |

**clickgame callback回调返回**：

| 返回参数           | 类型   | 说明                   |
|-------------------|--------|------------------------|
| Object.targetGameName | string | 表示玩家点击的CPS游戏的名称  |

**error callback 回调返回**：

| 返回参数           | 类型   | 说明                   |
|-------------------|--------|------------------------|
| Object.errCode | number | 错误码  |
| Object.errMsg | string | **调用时返回的错误消息**
● 当前广告ID不可用
● 暂无CPS推荐组件调用权限
● 其他组件错误信息 |

### 3. 组件尺寸

ratio = 屏幕宽度 / 414

**温馨提示**：注意组件尺寸，避免显示超过组件屏幕

**单游戏组件**：

宽度 = 80 * ratio

高度 = 100 * ratio;

**多游戏组件**：

横版：

宽度 = 312 * ratio

高度 = 112 * ratio

竖版：

宽度 = 56 * ratio

高度 = 305 * ratio

## 二、最佳实践

### 1. 获取实例

```js
const pageManager = wx.createPageManager();
```

### 2. 预加载

```js
pageManager.load({
    // CPS推荐组件OPENLINK常量，直接复制即可
    openlink: 'wFFX1cDJnwJCet72QGUJJvBpa9z9lfAob-7EYHwzFENHJ_tNECj5LquvJqnbm82RktAcRyg7gORaUSh0yRSiuYF21JvF84j7-SgazajvTW-ScbwFiQccq8FWsrzHVPox1dr90HHv_CTrgRJD4HOdiRJFeLNRrDu0Pj3vsIGuonI', 
    query:{
        id: 'xxxx', // mp端配置的组件id，必填，在mp申请
        //组件的位置，选填，不填时系统自动适应，均为逻辑像素。
        left: 0, // 组件左上角屏幕横坐标，单游戏组件/多游戏组件时有效，
        top: 100, // 组件左上角屏幕纵坐标，单游戏组件/多游戏组件时有效
        isVertical:false, // 可选，多游戏组件时有效，默认为false。
    }
  });

```

### 3. 展示

**注意：若未进行预加载会首先进行预加载**

```js
// 已进行预加载
pageManager.show();

// 未进行预加载
pageManager.show({
    // CPS推荐组件OPENLINK常量，直接复制即可
    openlink:'wFFX1cDJnwJCet72QGUJJvBpa9z9lfAob-7EYHwzFENHJ_tNECj5LquvJqnbm82RktAcRyg7gORaUSh0yRSiuYF21JvF84j7-SgazajvTW-ScbwFiQccq8FWsrzHVPox1dr90HHv_CTrgRJD4HOdiRJFeLNRrDu0Pj3vsIGuonI', 
    query:{
        id: 'xxxx', // mp端配置的组件id，必填，在 mp 申请

        //组件的位置，选填，不填时系统自动适应
        left: 0, // 组件左上角屏幕横坐标，单游戏组件/多游戏组件时有效，
        top: 100, // 组件左上角屏幕纵坐标，单游戏组件/多游戏组件时有效
        isVertical:false, // 可选，多游戏组件时有效，默认为false。
        }
  });

```
### 4. 销毁

```js
pageManager.destroy();
```

### 5. 监听事件

```js
pageManager.on(
    'show', // show | destroy | error｜ clickgame
    () => {
        console.log('cps recommend component show.');
    },
)
pageManager.on(
    'clickgame', // show | destroy | error｜ clickgame
    (res) => {
        console.log('cps recommend component click：', res.targetAppName);
    },
)

```