本文档为鸿蒙设备接入引力引擎的技术接入方案，支持 HarmonyOS NEXT，基于 OpenHarmony API 12

在开始接入前，建议您先阅读接入前准备以了解接入必备的基础概念。

1.下载安装

1.1 通过 ohpm 集成（推荐使用）

ohpm install @gravityengine/analytics

1.2 通过本地 har 集成

获取最新的SDK放到项目目录中，再在终端执行：

ohpm install 本地目录/gravityengine.har

2.配置 SDK

2.1 初始化 SDK

请使用如下代码进行初始化：

import { GravityEngineSDK, gravityConfig } from "@gravityengine/analytics";

const config = new gravityConfig({
  context: this.context, // v2.0新增，必填
  accessToken: "your_access_token", // 项目通行证，在：网站后台-->设置-->应用列表中找到Access Token列 复制（首次使用可能需要先新增应用）
  clientId: "your_client_id", // 用户唯一 ID(例如 UID 或者设备 ID)
  debugMode: "debug", // 是否开启测试模式，开启测试模式后，可以在 网站后台--设置--元数据--事件流中查看实时数据上报结果。（测试时可使用，上线之后一定要关掉，改成none或者不传）
});
await GravityEngineSDK.setupAndStart(config); // 注意setupAndStart是异步方法，需要等其完成后再执行sdk其他方法

2.2 配置权限

在 module.json5 中配置所需权限：

"requestPermissions": [
  {
    "name": "ohos.permission.INTERNET"
  },
  {
    "name": "ohos.permission.GET_NETWORK_INFO"
  },
  {
    // 可选项，如需更准确的归因，则建议设置该权限
    "name": "ohos.permission.APP_TRACKING_CONSENT",
    "reason": "$string:reason", // reason 会弹窗显示给用户，具体展示内容请联系您的产品同学确认
    "usedScene": {
      "abilities": [
        "EntryFormAbility"
      ],
      "when": "inuse"
    }
  }
]

3.初始化

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

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

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

GravityEngineSDK.initialize({
  USER_CLIENT_NAME: "your_client_name", // 用户昵称
  CHANNEL: "your_channel", // 用户初始化渠道
  ENABLE_SYNC_ATTRIBUTION: false, // 是否开启同步获取归因信息，具体请参考https://help.gravity-engine.com/docs/tong-bu-gui-yin
})
  .then((res) => {
    console.log("gravityAnalytics initialize success ", JSON.stringify(res));
  })
  .catch((err: object) => {
    console.log(
      "gravityAnalytics initialize failed error",
      JSON.stringify(err)
    );
  });

3.1 开启 log

开启后，请在日志中输入 gravityAnalytics 过滤出引力的 log

GravityEngineSDK.enableLog(true);

3.2 设置静态公共属性

GravityEngineSDK.setSuperProperties({
  superKey: "superValue",
});

3.3 清除所有静态公共属性

GravityEngineSDK.clearSuperProperties();

4. 事件上报

4.1 业务注册事件上报

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

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

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

方法示例

GravityEngineSDK.trackRegisterEvent();

调用示例

GravityEngineSDK.trackRegisterEvent();

4.2 付费事件上报

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

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

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

方法示例

GravityEngineSDK.trackPayEvent({
  payAmount: 300,
  payType: "CNY",
  orderId: "your_order_id",
  payReason: "月卡",
  payMethod: "支付宝",
});

参数说明

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

调用示例

GravityEngineSDK.trackPayEvent({
  payAmount: 300,
  payType: "CNY",
  orderId: "your_order_id",
  payReason: "月卡",
  payMethod: "支付宝",
});

4.3 广告观看事件上报

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

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

方法示例

GravityEngineSDK.trackAdShowEvent({
  adUnionType: "topon",
  adPlacementId: "placement_id",
  adSourceId: "ad_source_id",
  adType: "reward",
  adnType: "csj",
  ecpm: 1,
});

参数说明

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

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

参数名称	参数含义	参数类型	是否必传
adUnionType	广告聚合平台类型（取值为：topon、gromore、admore、self，分别对应Topon、Gromore、Admore、自建聚合）	string	是
adPlacementId	广告瀑布流ID（广告位ID）	string	是
adSourceId	广告源ID（代码位ID）	string	是
adType	广告类型（取值为：reward(激励视频广告)、banner(横幅广告)、 native(信息流广告)、interstitial(插屏广告)、 splash(开屏广告) ）	string	是
adnType	广告平台类型（取值为：csj、gdt、ks、 mint 、baidu、other，分别对应为穿山甲、优量汇、快手联盟、Mintegral、百度联盟、其他平台）	string	是
ecpm	预估ECPM价格（千次展示收入（单位元））请务必注意，做好单位转换，传错单位可能会导致买量受到影响！	number	是

调用示例

GravityEngineSDK.trackAdShowEvent({
  adUnionType: "topon",
  adPlacementId: "placement_id",
  adSourceId: "ad_source_id",
  adType: "reward",
  adnType: "csj",
  ecpm: 1,
});

4.4 提现事件上报

提现事件仅与涉及用户提现功能的平台相关，如无此类业务需求，则无需接入此事件。

当用户发生应用内提现行为时，需要调用 trackWithdrawEvent 方法记录用户提现事件！

方法示例

GravityEngineSDK.trackWithdrawEvent({
  payAmount: 300,
  payType: "CNY",
  orderId: "your_order_id",
  payReason: "月卡",
  payMethod: "支付宝",
  isFirstPay: true,
});

参数说明

参数名称	参数含义	参数类型	是否必传
payAmount	提现金额单位为分	number	是
payType	货币类型按照国际标准组织ISO 4217中规范的3位字母，例如CNY人民币、USD美金等国际标准组织 ISO 4217 代码表	string	是
orderId	订单号。引力引擎会通过订单号 `orderId` 去重，避免重复上报，请务必传入！	string	是
payReason	提现原因例如：用户首次提现、用户抽奖提现	string	是
payMethod	提现支付方式例如：支付宝、微信、银联等	string	是
isFirstPay	是否首次提现	bool	是

调用示例

GravityEngineSDK.trackWithdrawEvent({
  payAmount: 300,
  payType: "CNY",
  orderId: "your_order_id",
  payReason: "月卡",
  payMethod: "支付宝",
  isFirstPay: true,
});

5.接入验证

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

5.1 开启 Debug 模式

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

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

您可以通过如下方式来开启 Debug

const config = new gravityConfig({
  debugMode: "debug"
});
await GravityEngineSDK.setupAndStart(config); // 注意setupAndStart是异步方法，需要等其完成后再执行sdk其他方法

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

5.2 关键事件验证

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

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

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

5.3 避免重复上报

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

至此验证无误之后，技术接入工作完成，您可以转交发行买量团队继续推动后续流程～