# 快速集成 > 来源：https://help.gravity-engine.com/docs/client-sdk/harmonyos/quickstart > 介绍 Gravity Engine HarmonyOS SDK 的安装、初始化、用户注册与事件上报流程，并提供参数说明和调用示例。 本文档为**鸿蒙设备**接入 [引力引擎](https://gravity-engine.com/) 的技术接入方案，支持 HarmonyOS NEXT，基于 OpenHarmony API 12。 在开始接入前，建议您先阅读 [接入前准备](/docs/getting-started/overview) 以了解接入必备的基础概念。 ## 1. 下载安装 [#1-下载安装] ### 1.1 通过 ohpm 集成（推荐使用） [#11-通过-ohpm-集成推荐使用] ```bash ohpm install @gravityengine/analytics ``` ### 1.2 通过本地 har 集成 [#12-通过本地-har-集成] 获取[最新的 SDK](/docs/client-sdk/sdk-overview)放到项目目录中，再在终端执行： ```bash ohpm install 本地目录/gravityengine.har ``` ## 2. 配置 SDK [#2-配置-sdk] ### 2.1 初始化 SDK [#21-初始化-sdk] ```ts import { GravityEngineSDK, gravityConfig } from "@gravityengine/analytics"; const config = new gravityConfig({ context: this.context, // v2.0 新增，必填 accessToken: "your_access_token", // 项目通行证，在：网站后台-->设置-->应用列表中找到Access Token列 复制（首次使用可能需要先新增应用） // 设置clientid取值顺序，默认oaid->ODID clientIdPriorityOrder: ["OAID", "ANDROID_ID"], clientId: "", // （需SDK版本大于2.0.4）如果传空字符串，则引力 sdk 内部会自动采集设备 id 填入，采集优先级顺序为：oaid->ODID(androidId)，如果所有id 都采集不到时，会生成随机的 16 位 id 保存到本地缓存中以保持相对稳定 // 在应用启动的UIAbility的生命周期里，获取want.parameters（可选，如果需要元服务App Linking跟踪（want.parameters）需设置） // 元服务App Linking跟踪：https://developer.huawei.com/consumer/cn/doc/promotion/ads-applink-0000002131566034 wantParameters: want.parameters, // 预设公共属性 presetSuperProperties: { testSuperKey: "testSuperValue", }, }); await GravityEngineSDK.setupAndStart(config); // 注意setupAndStart是异步方法，需要等其完成后再执行sdk其他方法 ``` ### 2.2 配置权限 [#22-配置权限] 在 module.json5 中配置所需权限： ```json "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. 初始化 [#3-初始化] > 首次调用后，需要在 `initialize` 的 `then` 中才能继续调用其他事件上报的方法 > > 初始化方法调用成功之后，后续冷启动可以不再调用，只需要正常启动 SDK 即可（多次调用也不会有问题，引力做了兼容） ```ts GravityEngineSDK.initialize({ USER_CLIENT_NAME: "your_client_name", // 用户昵称 CHANNEL: "your_channel", // 用户初始化渠道 ENABLE_SYNC_ATTRIBUTION: false, // 是否开启同步获取归因信息，具体请参考/docs/attribution/synchronous-attribution // 预设归因信息 AD_DATA: { testAdKey: "testAdValue", }, }) .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 [#31-开启-log] 开启后，请在日志中输入 gravityAnalytics 过滤出引力的 log ```ts GravityEngineSDK.enableLog(true); ``` ### 3.2 设置静态公共属性 [#32-设置静态公共属性] ```ts GravityEngineSDK.setSuperProperties({ superKey: "superValue", }); ``` ### 3.3 清除所有静态公共属性 [#33-清除所有静态公共属性] ```ts GravityEngineSDK.clearSuperProperties(); ``` ## 4. 事件上报 [#4-事件上报] ### 4.1 业务注册事件上报 [#41-业务注册事件上报] > **如果您的应用不需要追踪用户注册行为，可以跳过此事件接入。此功能仅适用于需要统计业务注册转化数据的场景。** > 该方法可多次调用，每次调用都会上报一个用户注册事件（计算指标时会去重） 当用户完成应用内业务注册后，您可以调用 `trackRegisterEvent` 方法来上报用户注册事件（`$AppRegister`）给引力，引力会使用该事件统计指标：标准\_注册数。 #### 调用示例 [#调用示例] ```ts GravityEngineSDK.trackRegisterEvent(); ``` ### 4.2 付费事件上报 [#42-付费事件上报] > **付费事件上报用于收入统计和分析，如您的应用不涉及内购或付费服务，则无需接入此事件。** > 如果您需要通过后端 API 方式上报付费事件，请参考 [混合上报模式](/docs/client-sdk/hybrid-reporting) 来接入事件上报接口报送付费事件。 当用户发生付费行为时，需要调用 `trackPayEvent` 方法记录用户付费事件，此事件非常重要，会影响买量和 ROI 统计，请务必重点测试！ #### 方法示例 [#方法示例] ```ts GravityEngineSDK.trackPayEvent({ payAmount: 300, payType: "CNY", orderId: "your_order_id", 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] ```ts GravityEngineSDK.trackPayEvent({ payAmount: 300, payType: "CNY", orderId: "your_order_id", payReason: "月卡", payMethod: "支付宝", }); ``` ### 4.3 广告观看事件上报 [#43-广告观看事件上报] > **广告观看上报适用于广告变现类应用，若您的应用未集成广告模块，则无需接入此事件。** 若您的产品内有广告变现，则需要在用户点击广告观看的同时上报用户广告观看事件给引力，具体参考如下： #### 方法示例 [#方法示例-1] ```ts GravityEngineSDK.trackAdShowEvent({ adUnionType: "topon", adPlacementId: "placement_id", adSourceId: "ad_source_id", adType: "reward", adnType: "csj", ecpm: 1, }); ``` #### 参数说明 [#参数说明-1] 为生成准确的广告收益分析报表，请尽量遵循规范填写下方的广告平台参数。正确的字段是生成有价值报表的基础。 我们为您准备了详细的指引：[广告聚合平台字段配置说明](/docs/appendix/ad-mediation-fields) | 参数名称 | 参数含义 | 参数类型 | 是否必传 | | ------------- | ------------------------------------------------------------------------------------------------------------------------- | ------ | ---- | | 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、other，分别对应为穿山甲、优量汇、快手联盟、Mintegral、百度联盟、其他平台） | string | 否 | | ecpm | 预估 ECPM 价格（千次展示收入，单位为元）。请务必注意，做好单位转换，传错单位可能会导致买量受到影响！ | number | 建议填写 | #### 调用示例 [#调用示例-2] ```ts GravityEngineSDK.trackAdShowEvent({ adUnionType: "topon", adPlacementId: "placement_id", adSourceId: "ad_source_id", adType: "reward", adnType: "csj", ecpm: 1, }); ``` ### 4.4 提现事件上报 [#44-提现事件上报] > **提现事件仅与涉及用户提现功能的平台相关，如无此类业务需求，则无需接入此事件。** 当用户发生应用内提现行为时，需要调用 `trackWithdrawEvent` 方法记录用户提现事件！ #### 方法示例 [#方法示例-2] ```ts GravityEngineSDK.trackWithdrawEvent({ payAmount: 300, payType: "CNY", orderId: "your_order_id", payReason: "月卡", payMethod: "支付宝", isFirstPay: true, }); ``` #### 参数说明 [#参数说明-2] | 参数名称 | 参数含义 | 参数类型 | 是否必传 | | ---------- | ------------------------------------------------------------------------------------------------------------------------ | ------ | ---- | | payAmount | 提现金额，单位为分 | number | 是 | | payType | 货币类型，按照国际标准组织 ISO 4217 中规范的 3 位字母，例如 CNY 人民币、USD 美金等，具体请参考：[国际标准组织 ISO 4217 代码表](https://en.wikipedia.org/wiki/ISO_4217) | string | 是 | | orderId | 订单号。引力引擎会通过订单号 `orderId` 去重，避免重复上报，请务必传入！ | string | 是 | | payReason | 提现原因，例如：用户首次提现、用户抽奖提现 | string | 是 | | payMethod | 提现支付方式，例如：支付宝、微信、银联等 | string | 是 | | isFirstPay | 是否首次提现 | bool | 是 | #### 调用示例 [#调用示例-3] ```ts GravityEngineSDK.trackWithdrawEvent({ payAmount: 300, payType: "CNY", orderId: "your_order_id", payReason: "月卡", payMethod: "支付宝", isFirstPay: true, }); ``` ## 5. 接入验证 [#5-接入验证] > **正式上线之前，请完成本节的校验，否则可能会导致买量上报异常！** ### 5.1 关键事件验证 [#51-关键事件验证] 在引力后台[事件流](https://web.gravity-engine.com/#/manage/metadata/eventFlow)界面开启**加载实时数据**，并在产品中触发以下几个事件。事件流使用说明：[事件流 - 飞书云文档](https://gravityengine.feishu.cn/wiki/ZFmYwiDxfiZe2lkt3occ6yBonpf) | 事件名 | 事件英文名 | 触发时机 | 采集方式 | 默认映射到媒体事件 | 备注 | | ---- | --------------- | ---------- | ------------------------ | --------- | ----------------------- | | 用户注册 | `$AppRegister` | 用户完成业务注册之后 | 调用 SDK 的**上报业务注册事件**方法采集 | 暂无 | 接入了**业务注册上报事件**的产品均需要校验 | | 付费 | `$PayEvent` | 用户付费之后 | 调用 SDK 的**上报用户付费事件**方法采集 | 付费 | 接入了**付费事件上报事件**的产品均需要校验 | | 广告展示 | `$AdShow` | 用户观看广告之后 | 调用 SDK 的**上报广告展示事件**方法采集 | 暂无 | 接入了**广告事件上报事件**的产品均需要校验 | | 用户提现 | `$UserWithdraw` | 用户提现之后 | 调用 SDK 的**上报用户提现事件**方法采集 | 暂无 | 接入了**用户提现上报事件**的产品均需要校验 | 触发操作后，请在[事件流](https://web.gravity-engine.com/#/manage/metadata/eventFlow)界面中筛选测试用户的 Client ID，观察对应事件是否出现在实时入库页面。若事件数据正常显示，则说明接入成功；如出现于错误数据页面请根据页面错误提示进行排查；如未显示对应数据，请及时联系引力运营支持团队获取协助。 ### 5.2 避免重复上报 [#52-避免重复上报] 如果您之前单独接了媒体的回传（SDK 或者 API），则上线之前需要去掉，否则可能会导致重复上报数据！ > 至此验证无误之后，技术接入工作完成，您可以转交发行买量团队继续推动后续流程～