# CocosCreator快速集成

> 来源：https://help.gravity-engine.com/docs/client-sdk/cocos-creator/quickstart
> 介绍 Gravity Engine CocosCreator SDK 的安装、初始化、用户注册与事件上报流程，并提供参数说明和调用示例。





本文档主要讲述 **Cocos Creator** 接入 [引力引擎](https://gravity-engine.com/) 的技术接入方案，在开始接入前，建议您先阅读 [接入前准备](/docs/getting-started/overview) 以了解接入必备的基础概念。

> 本接入方案仅适用于 **Cocos Creator** 开发的项目。如果您使用的是其他开发框架，请访问 [引力引擎SDK总览页面](/docs/client-sdk/sdk-overview) 选择对应的框架接入文档。

## 支持平台 [#支持平台]

* <img src="/docs-assets/helplook/veFoOkaP/68a8186ba99a6.png" alt="微信小游戏" style="{ display: 'inline-block', width: 20, height: 20, verticalAlign: 'middle', margin: '0 6px 0 0' }" /> 微信小游戏
* <img src="/docs-assets/helplook/veFoOkaP/68a82cba2c30e.png" alt="快手小游戏" style="{ display: 'inline-block', width: 20, height: 20, verticalAlign: 'middle', margin: '0 6px 0 0' }" /> 快手小游戏（打包成微小）
* <img src="/docs-assets/helplook/veFoOkaP/68a8193e58d7e.png" alt="抖音/Tiktok 小游戏" style="{ display: 'inline-block', width: 20, height: 20, verticalAlign: 'middle', margin: '0 6px 0 0' }" /> 抖音/Tiktok 小游戏
* <img src="/docs-assets/helplook/veFoOkaP/68a819312220d.png" alt="支付宝小游戏" style="{ display: 'inline-block', width: 20, height: 20, verticalAlign: 'middle', margin: '0 6px 0 0' }" /> 支付宝小游戏（v2.4.12以上，v3不限）
* <img src="/docs-assets/helplook/veFoOkaP/68a8195037775.png" alt="OPPO快游戏" style="{ display: 'inline-block', width: 20, height: 20, verticalAlign: 'middle', margin: '0 6px 0 0' }" /> OPPO快游戏
* <img src="/docs-assets/helplook/veFoOkaP/68a8195037775.png" alt="VIVO快游戏" style="{ display: 'inline-block', width: 20, height: 20, verticalAlign: 'middle', margin: '0 6px 0 0' }" /> VIVO快游戏
* <img src="/docs-assets/helplook/veFoOkaP/68a8195037775.png" alt="华为快游戏" style="{ display: 'inline-block', width: 20, height: 20, verticalAlign: 'middle', margin: '0 6px 0 0' }" /> 华为快游戏
* <img src="/docs-assets/helplook/veFoOkaP/68a8195037775.png" alt="荣耀快游戏" style="{ display: 'inline-block', width: 20, height: 20, verticalAlign: 'middle', margin: '0 6px 0 0' }" /> 荣耀快游戏（v2.4.15以上 或 v3.8.6以上）
* <img src="/docs-assets/helplook/veFoOkaP/68a8195037775.png" alt="小米快游戏" style="{ display: 'inline-block', width: 20, height: 20, verticalAlign: 'middle', margin: '0 6px 0 0' }" /> 小米快游戏
* <img src="/docs-assets/helplook/veFoOkaP/68a8197a7b988.png" alt="百度小游戏" style="{ display: 'inline-block', width: 20, height: 20, verticalAlign: 'middle', margin: '0 6px 0 0' }" /> 百度小游戏
* <img src="/docs-assets/helplook/veFoOkaP/68a82fc5a7e1c.png" alt="淘宝小游戏" style="{ display: 'inline-block', width: 20, height: 20, verticalAlign: 'middle', margin: '0 6px 0 0' }" /> 淘宝小游戏（v2.4.12以上，v3不限）
* <img src="/docs-assets/helplook/veFoOkaP/68a832738925a.png" alt="京东小游戏" style="{ display: 'inline-block', width: 20, height: 20, verticalAlign: 'middle', margin: '0 6px 0 0' }" /> 京东小游戏（打包成微小）
* <img src="/docs-assets/helplook/veFoOkaP/68a93bde8e9c2.png" alt="美团小游戏" style="{ display: 'inline-block', width: 20, height: 20, verticalAlign: 'middle', margin: '0 6px 0 0' }" /> 美团小游戏（打包成微小）
* <img src="/docs-assets/helplook/veFoOkaP/6979e2066bee6.png" alt="Android" style="{ display: 'inline-block', width: 20, height: 20, verticalAlign: 'middle', margin: '0 6px 0 0' }" /> Android
* <img src="/docs-assets/helplook/veFoOkaP/6979e20e75eea.png" alt="iOS" style="{ display: 'inline-block', width: 20, height: 20, verticalAlign: 'middle', margin: '0 6px 0 0' }" /> iOS
* <img src="/docs-assets/helplook/veFoOkaP/6979e21570e64.png" alt="Harmony" style="{ display: 'inline-block', width: 20, height: 20, verticalAlign: 'middle', margin: '0 6px 0 0' }" /> Harmony

### **媒体平台SDK集成说明** [#媒体平台sdk集成说明]

**🎯 集成策略说明：**

CocosCreator SDK **仅针对【微信小游戏】平台** 集成了腾讯广告小游戏SDK。对于CocosCreator项目发布至其他平台（如抖音小游戏、快手小游戏等），**我们未集成任何媒体的SDK**。

#### **微信小游戏平台 ✅** [#微信小游戏平台-]

* **状态**：已集成腾讯广告小游戏SDK
* **上报方式**：需**手动调用**我们提供的方法进行事件上报
* **版本**：自 `4.8.40` 开始支持

> 📌 **重要说明**
>
> 按照《引力&腾讯广告小游戏 SDK 接入指南》的步骤完成集成后，引力SDK会**自动上报**以下两个基础事件给腾讯：
>
> * REGISTER（用户注册）
> * RE\_ACTIVE（沉默唤起）
>
> 此外，**START\_APP（小游戏启动）**事件由腾讯SDK**自动采集**（引力SDK初始化腾讯SDK时默认开启该功能）。
>
> 除以上事件外，其他所有事件（如付费、自定义行为等）均需**客户端手动调用**我们提供的方法进行上报。
>
> 点击查看详细集成文档：[引力&腾讯广告小游戏 SDK 接入指南](https://gravityengine.feishu.cn/wiki/SnjAwe8sFiD40skjsGvcxgOkndk)

## 1. 获取 AccessToken [#1-获取-accesstoken]

您可以在[设置-应用管理](https://web.gravity-engine.com/#/manage/appmanage)页面点击 查看参数 按钮获取当前应用的 AccessToken ，请妥善保存避免泄露。

## 2. Native 平台支持 [#2-native-平台支持]

如果您的 Cocos Creator 项目需要支持 Android/iOS/Harmony 原生平台，请分别在 Cocos 导出的原生工程中完成对应平台的 SDK 集成，切换下方标签按平台查看：

<Tabs items="['Android', 'iOS', 'Harmony']">
  <Tab value="Android">
    ### 接入 Android SDK\[!toc] [#ge-android]

    在 Cocos 导出的 Android 项目里，集成 Android 版本的 GravityEngineSDK 即可，参考 [Android 接入文档](/docs/client-sdk/android/quickstart)。
  </Tab>

  <Tab value="iOS">
    ### 导入通道文件\[!toc] [#ge-ios-channel]

    将下载的 `CocosSDK/native/iOS` 下的 `GravityEngineCocosCreatorChannel.h` 和 `GravityEngineCocosCreatorChannel.mm` 类文件引入到 Cocos 导出的 iOS 项目下。

    文件地址示例：

    `CocosDemoProject/native/engine/ios/GravityEngineCocosCreatorChannel.h`

    `CocosDemoProject/native/engine/ios/GravityEngineCocosCreatorChannel.mm`

    ### 接入 iOS SDK\[!toc] [#ge-ios-sdk]

    在 Cocos 导出的 iOS 项目里集成 iOS 版本的 GravityEngineSDK，参考 [iOS 接入文档](/docs/client-sdk/ios/quickstart)。
  </Tab>

  <Tab value="Harmony">
    ### 导入通道文件\[!toc] [#ge-harmony-channel]

    将 `CocosSDK/native/harmonyos-next` 下的 `GravityEngineCocosCreatorChannel.ets` 类文件导入到 Cocos 导出的鸿蒙项目下。

    文件地址示例：

    `CocosDemoProject/native/engine/harmonyos-next/entry/src/main/ets/GravityEngineCocosCreatorChannel.ets`

    ### 通道配置\[!toc] [#ge-harmony-config]

    在 Cocos 导出的鸿蒙项目 `build-profile.json5` 里设置：

    文件地址示例：

    `CocosDemoProject/native/engine/harmonyos-next/entry/build-profile.json5`

    ```json
    buildOption: {
        arkOptions: {
          runtimeOnly: {
            sources: [
              './src/main/ets/GravityEngineCocosCreatorChannel.ets',
            ],
          },
        },
    }
    ```

    ### 接入 Harmony SDK\[!toc] [#ge-harmony-sdk]

    在 Cocos 导出的鸿蒙项目里集成 harmony 版本的 GravityEngineSDK，参考 [Harmony 接入文档](/docs/client-sdk/harmonyos/quickstart)。

    ### 建立通道\[!toc] [#ge-harmony-bridge]

    在 Cocos 导出的鸿蒙项目的 UIAbility 的 onCreate 里建立 Cocos 与 GravityEngineSDK 的通道。

    文件地址示例：

    `CocosDemoProject/native/engine/harmonyos-next/entry/src/main/ets/entryability/EntryAbility.ets`

    ```typescript
    import GravityEngineCocosCreatorChannel from '../GravityEngineCocosCreatorChannel';

    export default class EntryAbility extends UIAbility {
      onCreate(want: Want, launchParam: AbilityConstant.LaunchParam) {
        GravityEngineCocosCreatorChannel.onCocosAppStart(this.context,want.parameters);
      }
    }
    ```
  </Tab>
</Tabs>

## 3. 配置并启动 SDK [#3-配置并启动-sdk]

开始接入工作之前，您需要先 [下载 SDK](/docs/client-sdk/sdk-overview)。

从 `ge_cocoscreator_sdk_version.zip` 中导入 SDK：

### 3.1 导入 SDK [#31-导入-sdk]

**TypeScript 项目：**

* 引入类型文件 `GravityAnalyticsSDK.d.ts` 至项目中
* 引入 `gravityengine.mg.cocoscreator.min.js` 至项目中

**JavaScript 项目：**

* 引入 `gravityengine.mg.cocoscreator.min.js` 至项目中

### 3.2 初始化 SDK [#32-初始化-sdk]

> **每次冷启动过程中，`GravityEngine` 的实例化方法 `new GravityAnalyticsAPI()` 与初始化方法 `setupAndStart()` 均只能被调用一次。`clientId` 参数必须在这两个方法的其中一个传入。**

```javascript
import GravityAnalyticsAPI from "./gravityengine.mg.cocoscreator.min.js"; // cocos2.x项目可能不需要引入
const config = {
    accessToken: "your_access_token", // 项目通行证，在：网站后台-->设置-->应用列表中找到Access Token列 复制（首次使用可能需要先新增应用）
    clientId: "your_client_id", // 用户唯一标识，如产品为小游戏，则必须填用户openid（注意，不是小游戏的APPID！！！）
    name: "ge", // 全局变量名称
    // 预设公共属性
    presetSuperProperties:{
       "testSuperKey":"testSuperValue"
    },
    isChina: true, // 是否使用国内域名，TikTok需设置为false
    enableNative: false, // 是否支持Native
    // Native配置
    mClientIdPriorityOrder: ["OAID","ANDROID_ID"], // Android设备clientID优先级顺序，默认优先取 OAID 为clientId
    foregroundSessionThreshold: 0, // 前台会话阀值
    enableAndroidId: true, // 是否采集android_id，仅支持Android，默认true
    enableOAID: true, // 是否采集oaid，仅支持Android，默认true
    enableIMEI: true, // 是否采集imei，仅支持Android，默认true
    enableMAC: true, // 是否采集mac，仅支持Android，默认true
};
const ge = new GravityAnalyticsAPI(config);
ge.setupAndStart();
```

> **配置项目合法域名：** 您需要将 `https://backend.gravity-engine.com` 和 `https://api.gravity-engine.com` 配置到开发者后台 request 合法域名列表中。
>
> **TikTok 海外合法域名：** `https://global-api.gravity-engine.com`

> **如果您是从低版本（5.0 以下版本）引力 SDK 升级到高版本的，请一定记得添加 `https://api.gravity-engine.com` 域名到合法域名列表中，否则将导致事件采集失效，影响您的使用！**

## 4. 初始化 [#4-初始化]

在用户可以获取到用户唯一 ID 时调用此方法，推荐首次启动时调用。

> 首次调用后，需要在 `initialize` 的 `then` 回调中才能继续调用其他事件上报的方法。
>
> 初始化方法调用成功之后，后续冷启动可以不再调用，只需要正常启动 SDK 即可（多次调用也不会有问题，引力做了兼容）。

### 4.1 方法示例 [#41-方法示例]

```javascript
ge.initialize({
  name: "your_name",
  version: 123,
  openid: "your_openid",
  enable_sync_attribution: false,
  adData:{
    "testAdKey":"testAdValue"
  },
  // ios 配置
  caid:"", // 当前用户中广协 ID, 类型为json字符串，数组里面是字典，字典里有version和caid字段(可以为空字符串)
})
  .then((res) => {
    console.log("initialize success", res);
  })
  .catch((err) => {
    console.log("initialize failed", err);
  });
```

### 4.2 参数说明 [#42-参数说明]

| **参数名称**                  | **参数含义**                                                                                       | **参数类型** | **是否必传** |
| ------------------------- | ---------------------------------------------------------------------------------------------- | -------- | -------- |
| name                      | 用户名或用户唯一ID（可理解为业务中的昵称），如果不需要昵称，可以填：默认值，但是不可以传空字符串！                                             | string   | 是        |
| version                   | 产品发布版本号，便于后续在引力后台过滤                                                                            | number   | 是        |
| openid                    | 用户openid                                                                                       | string   | 是        |
| enable\_sync\_attribution | 是否开启同步获取归因信息（参考 [同步归因](/docs/attribution/synchronous-attribution) 文档），在媒体点击下发延迟的情况下会影响归因，请谨慎开启 | boolean  | 是        |
| channel                   | 当前用户来源渠道，对应用户细查中的：客户端渠道                                                                        | string   | 否        |
| adData                    | 预设归因信息                                                                                         | object   | 否        |

## 5. 事件上报 [#5-事件上报]

### 5.1 业务注册事件上报 [#51-业务注册事件上报]

> **此功能仅适用于需要统计业务注册转化数据的场景。如果您的应用不需要追踪用户注册行为，可以跳过此事件接入。**

> 该方法可多次调用，每次调用都会上报一个用户注册事件（计算指标时会去重）。

当用户完成应用内业务注册后，您可以调用 `registerEvent` 方法来上报用户注册事件（APP：`$AppRegister` / 小游戏：`$MPRegister`）给引力，引力会使用该事件统计指标：标准\_注册数。

#### 调用示例 [#调用示例]

```javascript
ge.registerEvent();
```

### 5.2 付费事件上报 [#52-付费事件上报]

> **付费事件上报用于收入统计和分析，如您的应用不涉及内购或付费服务，则无需接入此事件。**

> 如果您需要通过后端 API 方式上报付费事件，请参考 [混合上报模式](/docs/client-sdk/hybrid-reporting) 来接入事件上报接口报送付费事件。

当用户发生付费行为时，需要调用 `payEvent` 方法记录用户付费事件，此事件非常重要，会影响买量和 ROI 统计，请务必重点测试！

#### 方法示例 [#方法示例]

```javascript
ge.payEvent(payAmount, payType, orderId, payReason, payMethod);
```

#### 参数说明 [#参数说明]

| **参数名称**  | **参数含义**                                                                                                                 | **参数类型** | **是否必传** |
| --------- | ------------------------------------------------------------------------------------------------------------------------ | -------- | -------- |
| payAmount | 付费金额，单位为分。请务必注意，传错单位可能会导致买量受到影响！                                                                                         | number   | 是        |
| payType   | 货币类型，按照国际标准组织 ISO 4217 中规范的 3 位字母，例如 CNY 人民币、USD 美金等，具体请参考：[国际标准组织 ISO 4217 代码表](https://en.wikipedia.org/wiki/ISO_4217) | string   | 是        |
| orderId   | 订单号。引力引擎会通过订单号去重，避免重复上报，请务必准确传入！                                                                                         | string   | 是        |
| payReason | 付费原因，例如：购买钻石、办理月卡                                                                                                        | string   | 是        |
| payMethod | 付费方式，例如：支付宝、微信、银联等                                                                                                       | string   | 是        |

#### 调用示例 [#调用示例-1]

```javascript
ge.payEvent(300, "CNY", "your_order_id", "月卡", "支付宝");
```

### 5.3 广告观看事件上报 [#53-广告观看事件上报]

> **广告观看上报适用于广告变现类应用，若您的应用未集成广告模块，则无需接入此事件。**

> **抖音小游戏、快手小游戏、B站小游戏无需接入，会由引力后端自动拉取，具体配置，请参考[这里](https://gravityengine.feishu.cn/wiki/SBsxwmeb5iNrPKkUtzCcmisXnzd#OwM8doB35oKDTrxsHKkcvr9Bnqe)**

为生成准确的广告收益分析报表，请尽量遵循规范填写下方的广告平台参数。正确的字段是生成有价值报表的基础。

我们为您准备了详细的指引：👉 [广告聚合平台字段配置说明](/docs/appendix/ad-mediation-fields)

若您的产品内有广告变现，则需要在用户点击广告观看的同时上报用户广告观看事件给引力，具体参考如下：

<Tabs items="['Native', '小游戏']">
  <Tab value="Native">
    ```javascript
    ge.nativeAdShowEvent(adUnionType, adPlacementId, adSourceId, adType, adnType, ecpm)
    ```

    | **参数名称**      | **参数含义**                                                                                                                  | **参数类型** | **是否必传** |
    | ------------- | ------------------------------------------------------------------------------------------------------------------------- | -------- | -------- |
    | adUnionType   | 广告聚合平台类型（取值为：topon、gromore、admore、self，分别对应 Topon、Gromore、Admore、自建聚合）                                                    | string   | 否        |
    | adPlacementId | 广告瀑布流ID（广告位ID）                                                                                                            | string   | 否        |
    | adSourceId    | 广告源ID（代码位ID）                                                                                                              | string   | 否        |
    | adType        | 广告类型（取值为：reward(激励视频广告)、banner(横幅广告)、native(信息流广告)、interstitial(插屏广告)、splash(开屏广告)、video\_feed(视频信息流)、video\_begin(贴片广告)） | string   | 是        |
    | adnType       | 广告平台类型（取值为：csj、gdt、ks、mint、baidu，分别对应为穿山甲、优量汇、快手联盟、Mintegral、百度联盟）                                                        | string   | 否        |
    | ecpm          | 预估ECPM价格（千次展示收入（单位元））                                                                                                     | float    | 建议填写     |
  </Tab>

  <Tab value="小游戏">
    ```javascript
    ge.miniGameAdShowEvent(ad_type, ad_unit_id, otherProperties)
    ```

    | **参数名称**        | **参数含义**                                                                                                                      | **参数类型** | **是否必传** |
    | --------------- | ----------------------------------------------------------------------------------------------------------------------------- | -------- | -------- |
    | adType          | 广告类型（取值为：reward(激励视频广告)、banner(横幅广告)、native(信息流广告)、interstitial(插屏广告)、splash(开屏广告)、video\_feed(视频信息流)、video\_begin(贴片广告)）     | string   | 是        |
    | adUnitId        | 广告位ID。一般以 adunit 开头，注意不要填错                                                                                                    | string   | 是        |
    | otherProperties | 自定义参数。其他需要携带的自定义参数，需要提前在引力后台[元数据管理](https://web.gravity-engine.com/#/manage/metadata/eventProperty)中针对广告观看($AdShow) 事件配置好相关属性 | object   | 是        |
  </Tab>
</Tabs>

## 6. 接入验证 [#6-接入验证]

> **正式上线之前，请完成本节的校验，否则可能会导致买量上报异常！**

### 6.1 关键事件验证 [#61-关键事件验证]

在引力后台[事件流](https://web.gravity-engine.com/#/manage/metadata/eventFlow) 界面开启**加载实时数据**，并在产品中触发以下几个事件。事件流使用说明：[事件流 - 飞书云文档](https://gravityengine.feishu.cn/wiki/ZFmYwiDxfiZe2lkt3occ6yBonpf)

| 事件名  | 事件英文名                                     | 触发时机       | 采集方式                   | 默认映射到媒体事件 | 备注                      |
| ---- | ----------------------------------------- | ---------- | ---------------------- | --------- | ----------------------- |
| 用户注册 | APP:`$AppRegister`<br />小游戏:`$MPRegister` | 用户完成业务注册之后 | 调用SDK的**上报业务注册事件**方法采集 | 暂无        | 接入了**业务注册上报事件**的产品均需要校验 |
| 付费   | `$PayEvent`                               | 用户付费之后     | 调用SDK的**上报用户付费事件**方法采集 | 付费        | 接入了**付费事件上报事件**的产品均需要校验 |
| 广告展示 | `$AdShow`                                 | 用户观看广告之后   | 调用SDK的**上报广告展示事件**方法采集 | 暂无        | 接入了**广告事件上报事件**的产品均需要校验 |

触发操作后，请在[事件流](https://web.gravity-engine.com/#/manage/metadata/eventFlow) 界面中筛选测试用户的 Client ID，观察对应事件是否出现在实时入库页面。若事件数据正常显示，则说明接入成功；如出现于错误数据页面请根据页面错误提示进行排查；如未显示对应数据，请及时联系引力运营支持团队获取协助。

### 6.2 避免重复上报 [#62-避免重复上报]

如果您之前单独接了媒体的回传（SDK 或者 API），则上线之前需要去掉，否则可能会导致重复上报数据！

> 至此验证无误之后，您可以正常上线了。