Uni-APP快速集成

本文档主要讲述 Uni-APP 接入 引力引擎 的技术接入方案，在开始接入前，建议您先阅读 接入前准备 以了解接入必备的基础概念。

本接入方案仅适用于 Uni-APP 开发的项目。如果您使用的是其他开发框架，请访问 引力引擎SDK总览页面 选择对应的框架接入文档。

支持平台

• 微信小程序
• 支付宝小程序
• 字节小程序
• 百度小程序
• 360小程序
• 快手小程序
• QQ小程序
• 京东小程序
• Android
• iOS

1. 获取 AccessToken

您可以在 设置-应用管理 页面点击 查看参数 按钮获取当前应用的 AccessToken，请妥善保存避免泄露。

2. Native 平台支持

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

3. 配置并启动 SDK

开始接入工作之前，您需要先 下载 SDK。

将 ge_mp_sdk_version.zip 中的 gravityengine.uniapp.js 导入工程，并初始化 SDK：

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

import GravityAnalyticsAPI from "./utils/gravityengine.uniapp.js";
const config = {
    accessToken: "your_access_token", // 项目通行证，在：网站后台-->设置-->应用列表中找到Access Token列 复制（首次使用可能需要先新增应用）
    clientId: "your_client_id", // 用户唯一标识，如产品为小游戏，则必须填用户openid（注意，不是小游戏的APPID！！！）
    name: "ge", // 全局变量名称
    // 预设公共属性
    presetSuperProperties:{
       "testSuperKey":"testSuperValue"
    },
    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://api.gravity-engine.com 配置到开发者后台 request 合法域名列表中。

4. 初始化

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

首次调用后，需要在 initialize 的 then 回调中才能继续调用其他事件上报的方法。

初始化方法调用成功之后，后续冷启动可以不再调用，只需要正常启动 SDK 即可（多次调用也不会有问题，引力做了兼容）。

4.1 方法示例

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 参数说明

5. 事件上报

5.1 业务注册事件上报

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

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

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

调用示例

ge.registerEvent();

5.2 付费事件上报

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

如果您需要通过后端 API 方式上报付费事件，请参考 混合上报模式 来接入事件上报接口报送付费事件。

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

方法示例

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

参数说明

调用示例

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

5.3 广告观看事件上报

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

抖音小游戏、快手小游戏、B站小游戏无需接入，会由引力后端自动拉取，具体配置，请参考这里

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

我们为您准备了详细的指引：👉 广告聚合平台字段配置说明

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

ge.nativeAdShowEvent(adUnionType, adPlacementId, adSourceId, adType, adnType, ecpm);

6. 接入验证

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

6.1 关键事件验证

在引力后台事件流 界面开启加载实时数据，并在产品中触发以下几个事件。事件流使用说明：事件流 - 飞书云文档

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

6.2 避免重复上报

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

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