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

本接入方案仅适用于官方原生快应用开发的项目。如果您使用的是其他开发框架（如Taro、uni-app等），请访问引力引擎SDK总览页面选择对应的框架接入文档。

1. 获取 AccessToken

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

2.配置并启动 SDK

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

将 ge_mp_sdk_version.zip 中gravityengine.quick.min.js 文件导入快应用项目中

import GravityEngine from "./helper/gravityengine.quick.min";

引入 SDK 后，即可进行 SDK 初始化参数配置：

const config = {
  accessToken: "your_access_token", // 项目通行证，在：网站后台-->设置-->应用列表中找到Access Token列 复制（首次使用可能需要先新增应用）
  clientId: "your_client_id", // 用户唯一标识
  debugMode: "debug", // 是否开启测试模式，开启测试模式后，可以在 网站后台--设置--元数据--事件流中查看实时数据上报结果。（测试时使用，上线之后一定要关掉，改成none或者删除）
  gravityQuery: {} // 从 onInit 方法中提取的启动参数，巨量线索归因会依赖此参数的传入，正确传入能极大提升归因率，建议传入
};
const ge = new GravityEngine(config);
ge.setupAndStart();

由于快应用获取启动参数必须放在 onInit 函数调用中，引力SDK无法自动采集，故需要您采集之后手动传入到 gravityQuery ，采集方式如下图：

3.初始化

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

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

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

方法示例

ge.initialize({
  name: "your_name",
  version: 123,
  enable_sync_attribution: false,
})
  .then((res) => {
    console.log("initialize success", res);
  })
  .catch((err) => {
    console.log("initialize failed", err);
  });

参数说明

参数名称	参数含义	参数类型	是否必传
name	用户名或用户唯一ID（可理解为业务中的昵称），如果不需要昵称，可以填：默认值，但是不可以传空字符串！	string	是
version	产品发布版本号，便于后续在引力后台过滤	number	是
enable_sync_attribution	是否开启同步获取归因信息（参考同步归因文档）	boolean	是
channel	当前用户来源渠道，对应用户细查中的：客户端渠道	string	否

4.事件上报

4.1 业务注册事件上报

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

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

当用户完成应用内业务注册后，您可以调用 registerEvent 方法来上报用户注册事件($AppRegister)给引力，引力会使用该事件统计指标：标准_注册数

调用示例

ge.registerEvent();

4.2 付费事件上报

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

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

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

方法示例

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

参数说明

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

调用示例

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

4.3 广告观看事件上报

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

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

方法示例

ge.adShowEvent(adType, adUnitId, otherProperties);

参数说明

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

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

参数名称	参数含义	参数类型	是否必传
adType	广告类型（取值为：reward(激励视频广告)、banner(横幅广告)、 native(信息流广告)、interstitial(插屏广告)、 splash(开屏广告) ）	string	是
adUnitId	广告位ID。一般以adunit开头，注意不要填错	string	是
otherProperties	自定义参数。其他需要携带的自定义参数，需要提前在引力后台元数据管理中针对广告观看($AdShow) 事件配置好相关属性，比如快应用上报广告 ecpm，可以使用引力预置好的属性字段：$ecpm，具体见下发代码示例。	object	是

调用示例

ge.adShowEvent("reward", "your_ad_unit_id", {custom_param: "12345" });

// 如果需要上报当次广告曝光的 ECPM，代码示例如下
ge.adShowEvent("reward", "your_ad_unit_id", {$ecpm: 1000 });

5.接入验证

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

5.1 开启 Debug 模式

Debug 模式可能会影响数据采集质量和 App 的稳定性，只用于集成阶段数据验证，不要在线上环境使用。

当前 SDK 实例支持两种运行模式：

"none": 不开启 Debug
"debug": 开启 Debug 模式，并入库

可以在 SDK 初始化的时候配置 Debug 模式：

var config = {
  debugMode: "debug",
};
var ge = new GE(config);

Debug 模式仅仅用于集成阶段数据校验，不要在生产模式下使用！上线前请关闭！

5.2 关键事件验证

在 SDK 中开启 Debug 模式，并依次在产品中触发以下几个事件。

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

测试完成之后，在事件流界面过滤测试用户的 Client ID ，查看对应事件的校验状态是否为 "校验通过" ，当事件有数据并且状态为校验通过后，则表明接入成功。

5.3 避免重复上报

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

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

以上是 SDK 的基础接入指引。如需使用 行为事件上报、用户属性上报、进阶功能、自动采集 等功能，请参考以下文档：

注意：这些功能并非所有业务场景都需要，请按需查阅。

•📄 行为事件上报

•📄 用户属性上报

•📄 进阶功能

•📄 自动采集