# 全部文档
> 来源：https://help.gravity-engine.com/docs
> Gravity Engine 全部文档索引，汇总服务端集成、附录等主题，便于按功能进入对应的配置、接入或参考说明。
{/* Generated by scripts/generate-docs-routes.mjs. Do not edit. */}
## 目录 [#目录]
* [服务端集成](/docs/server-integration) — 子目录
* [附录](/docs/appendix) — 子目录
* [归因](/docs/attribution) — 子目录
* [接入前准备](/docs/getting-started) — 子目录
* [客户端SDK集成](/docs/client-sdk) — 子目录
# 广告聚合平台字段配置
> 来源：https://help.gravity-engine.com/docs/appendix/ad-mediation-fields
> 说明 TopOn 等广告聚合平台中 adUnionType、adPlacementId、adSourceId 与 eCPM 等字段的获取和上报配置。
## 文档概述 [#文档概述]
本文档详细说明了各广告聚合平台中关键字段的获取方式和配置要求，为广告集成上报提供标准化参考。
## 字段说明表 [#字段说明表]
| 英文字段名 | 中文名称 | 是否必填 | 描述 | 备注 |
| --------------- | -------------- | ---- | ------------- | --------------------------------------------------------------------------------- |
| `adUnionType` | 广告聚合平台类型 | 否 | 标识使用的广告聚合平台类型 | 取值：`topon`/`gromore`/`self` |
| `adPlacementId` | 广告瀑布流 ID | 否 | 广告位唯一标识符 | 各平台获取方式不同 |
| `adSourceId` | 广告源 ID（代码位 ID） | 否 | 广告源的唯一标识 | 平台间命名差异较大 |
| `adType` | 广告类型 | 是 | 广告展示形式 | 枚举值：`reward`/`banner`/`native`/`interstitial`/`splash`/`video_feed`/`video_begin` |
| `adnType` | 广告平台类型 | 否 | 广告网络平台标识 | 枚举值：`csj`/`gdt`/`ks`/`mint`/`baidu`/`other` |
| `ecpm` | 预估 eCPM 价格 | 建议填写 | 千次展示预估收益 | 部分平台不支持获取 |
## 各平台字段获取详细说明 [#各平台字段获取详细说明]
### 1. TopOn 聚合平台 [#1-topon-聚合平台]
#### adUnionType [#aduniontype]
* 取值：`topon`
* 说明：固定值，标识使用 TopOn 聚合
#### adPlacementId [#adplacementid]
* 获取位置：聚合管理 → 广告位
#### adSourceId [#adsourceid]
* 获取目标：TopOn 自动生成的广告源 ID
* 获取路径：聚合管理 → 广告列表 → 选择对应广告源
#### ecpm 获取 [#ecpm-获取]
* 获取方式：通过 TopOn 官方文档里的 `getEcpm` 方法获取
* 文档链接：[TopOn官方文档-回调信息说明](https://newdocs.toponad.com/docs/JSLSJN#b4fab5bf735318c7589a94b4528f00e3)
### 2. Gromore（穿山甲聚合） [#2-gromore穿山甲聚合]
#### adUnionType [#aduniontype-1]
* 取值：`gromore`
* 说明：固定值，标识使用 Gromore 聚合
#### adPlacementId [#adplacementid-1]
* 获取位置：穿山甲聚合平台 → 瀑布流管理 → 广告位 ID
#### adSourceId [#adsourceid-1]
* 获取目标：瀑布流管理中的代码位 ID
* 获取路径：穿山甲聚合平台 → 瀑布流管理 → 代码位 ID
#### ecpm 获取 [#ecpm-获取-1]
* 获取方式：通过 Gromore 官方文档里的 `getEcpm` 方法获取
* 文档链接：[Gromore官方文档](https://www.csjplatform.com/union/media/union/download/detail?id=195\&docId=27617\&locale=zh-CN\&osType=android)
### 3. Tobid 聚合平台 [#3-tobid-聚合平台]
#### adUnionType [#aduniontype-2]
* 取值：`tobid`
* 说明：固定值，标识使用 Tobid 聚合
#### adPlacementId [#adplacementid-2]
* 获取路径：Tobid 聚合平台 → 聚合管理 → 流量管理 → 广告位 ID
#### adSourceId [#adsourceid-2]
* 获取目标：瀑布流管理中的广告源 ID
* 获取路径：Tobid 聚合平台 → 聚合管理 → 瀑布流管理 → 广告源 ID
#### ecpm 获取 [#ecpm-获取-2]
* 获取方式：通过 Tobid 官方文档的广告回调接口获取的 `AdInfo` 对象获取
* 文档链接：[Tobid官方文档-AdInfo回调信息说明](https://doc.sigmob.com/ToBid%E4%BD%BF%E7%94%A8%E6%8C%87%E5%8D%97/SDK%E9%9B%86%E6%88%90%E8%AF%B4%E6%98%8E/iOS/%E9%AB%98%E7%BA%A7%E8%AE%BE%E7%BD%AE/%E5%B9%BF%E5%91%8A%E5%AF%B9%E8%B1%A1/)
### 4. 自建聚合平台 [#4-自建聚合平台]
#### adUnionType [#aduniontype-3]
* 取值：`self`
* 说明：标识使用自建聚合系统
#### adPlacementId [#adplacementid-3]
* 获取方式：自行从自建后台获取
#### adSourceId [#adsourceid-3]
* 获取方式：自行从自建后台获取
#### ecpm 获取 [#ecpm-获取-3]
* 实现方式：自行联系自建后台后端开发
### 5. 腾讯广告联盟（优量汇） [#5-腾讯广告联盟优量汇]
#### adSourceId [#adsourceid-4]
* 获取方式：广告位 ID
* 获取位置：优量汇后台 → 广告位管理
#### ecpm 支持 [#ecpm-支持]
* 状态：不支持获取 eCPM
* 备注：该平台不提供 eCPM 获取接口
### 6. 快手广告联盟 [#6-快手广告联盟]
#### adSourceId [#adsourceid-5]
* 获取方式：广告位 ID
* 获取位置：快手联盟后台 → 广告位管理
#### ecpm 支持 [#ecpm-支持-1]
* 状态：不支持获取 eCPM
* 备注：该平台不提供 eCPM 获取接口
### 7. 百度广告联盟（百青藤） [#7-百度广告联盟百青藤]
#### adSourceId [#adsourceid-6]
* 获取方式：广告位 ID
* 获取位置：百青藤后台 → 广告位管理
#### ecpm 支持 [#ecpm-支持-2]
* 状态：不支持获取 eCPM
* 备注：该平台不提供 eCPM 获取接口
### 8. Mintegral [#8-mintegral]
#### adSourceId [#adsourceid-7]
* 获取方式：广告位 ID
* 获取位置：Mintegral 后台 → 广告位管理
#### ecpm 支持 [#ecpm-支持-3]
* 状态：不支持获取 eCPM
* 备注：该平台不提供 eCPM 获取接口
### 9. OPPO 广告联盟 [#9-oppo-广告联盟]
#### adSourceId [#adsourceid-8]
* 获取方式：广告位 ID
* 获取位置：OPPO 广告联盟后台 → 广告位管理
#### ecpm 支持 [#ecpm-支持-4]
* 状态：白名单支持获取 eCPM
* 备注：需要申请白名单权限后才能获取 eCPM 数据
### 10. 其他平台 [#10-其他平台]
#### adSourceId [#adsourceid-9]
* 获取方式：广告位 ID
* 获取位置：对应平台后台管理界面
* 备注：各平台界面差异较大，需根据具体平台确定
#### ecpm 支持 [#ecpm-支持-5]
* 状态：依具体平台而定
* 备注：需要查询具体平台的 API 文档确认支持情况
## 注意事项 [#注意事项]
1. **必填字段**：`adType` 为必填字段，必须准确填写广告类型
2. **eCPM 统计**：强烈建议填写 `ecpm` 字段，否则无法统计用户 eCPM 数据
3. **平台差异**：不同平台的字段获取方式和命名存在差异，需要仔细区分
4. **权限要求**：部分平台（如 OPPO）的 eCPM 获取需要特殊权限或白名单
5. **更新维护**：各平台接口可能更新，请定期查看官方文档更新信息
## 附录 [#附录]
### 字段取值枚举说明 [#字段取值枚举说明]
#### adType 枚举值 [#adtype-枚举值]
* `reward`：激励视频广告
* `banner`：横幅广告
* `native`：信息流广告
* `interstitial`：插屏广告
* `splash`：开屏广告
#### adnType 枚举值 [#adntype-枚举值]
* `csj`：穿山甲平台
* `gdt`：优量汇平台
* `ks`：快手联盟
* `mint`：Mintegral 平台
* `baidu`：百度联盟
* `other`：其他平台
#### adUnionType 枚举值 [#aduniontype-枚举值]
* `topon`：TopOn 聚合
* `gromore`：Gromore 聚合
* `tobid`：Tobid 聚合
* `self`：自建聚合
# 广告平台枚举值
> 来源：https://help.gravity-engine.com/docs/appendix/ad-platform-enums
> 列出 Gravity Engine 支持的广告平台枚举值及对应媒体名称，供接口传参与数据核对使用。
| 枚举值 | 媒体平台 |
| ---------------------- | ----------------- |
| asa | AppleSearchAds |
| baidu | 百度营销 |
| bilibili | B站 |
| bytedance | 巨量引擎 |
| bytedance\_dy\_game | 抖音游戏 |
| bytedance\_star | 巨量星图 |
| douyu | 斗鱼 |
| gravity | 自定义 |
| honor | 荣耀广告 |
| huawei | 华为广告-鲸鸿动能 |
| huawei\_store | 华为商店 |
| huya | 虎牙 |
| iqiyi | 爱奇艺 |
| kuaishou | 磁力引擎 |
| kuaishou\_star | 磁力聚星 |
| mintegral | mintegral广告 |
| natural | 自然量 |
| oppo | oppo广告 |
| qutoutiao | 趣头条 |
| sigmob | Sigmob |
| taptap | TapTap |
| tapadn | TapADN(Dirichlet) |
| tencent | 腾讯广告 |
| topon | TopOn |
| uc | UC |
| vivo | vivo广告 |
| wechat\_video | 微信视频号加热 |
| wechat\_live | 微信视频号直播 |
| weibo | 微博 |
| xiaomi | 小米广告 |
| youku | 优酷 |
| qimao | 七猫 |
| netease\_music | 网易云音乐 |
| damai | 大麦 |
| lemeads | 斯瑞沃特 |
| xiaohongshu | 小红书 |
| wanmob | WanMob |
| meiyou | 美柚 |
| facebook | Facebook |
| google | Google |
| applovin | Applovin |
| gree | Gree |
| zhihu | 知乎 |
| saipiai | 赛皮艾 |
| chengyi | 橙益 |
| shenkai | 绅凯 |
| tonglian | 通联 |
| mitutu | 芈兔兔 |
| daliang | 达量 |
| youjiayuan | 优嘉源 |
| chiwan | 炽玩 |
| microsoft | 微软 |
| zhangwangkeji | 掌望科技 |
| huchuanghudong | 互创互动 |
| jingcheng | 京晟 |
| dsp\_qianyi | 千易 |
| dsp\_chenggong | 呈功 |
| dsp\_digitalmob | Digitalmob |
| dsp\_haiquwangluo | 嗨趣网络 |
| dsp\_boruibaite | 博瑞百特 |
| dsp\_tongjiangwancheng | 同江万城 |
| dsp\_4399 | 4399游戏盒 |
| dsp\_xinshihudong | 新视互动 |
| dsp\_gouwan | 广州够玩 |
| dsp\_yanyang | 研漾 |
| dsp\_233 | 233乐园 |
| dsp\_liandao | 联道 |
| dsp\_yisou | 壹搜 |
| dsp\_youju | 游聚 |
| youdao | 网易有道 |
| douyin\_e | 抖音企业号 |
| alipay | 支付宝灯火广告 |
| ubix | UBiX |
| octopus | 章鱼DSP |
| mangguo\_tv | 芒果TV |
| ximalaya | 喜马拉雅 |
| aisi | 爱思助手 |
| minimax | MiniMax |
| qihu360 | qihu360 |
| masterkey | WiFi万能钥匙 |
| yyb | 应用宝 |
| bing | 必应 |
| huahuo | B站花火 |
| netease\_news | 网易新闻 |
| danding | 蛋丁 |
| mty\_hupu | 摩投云 |
| gmob | Gmob |
| zxt | 智效通 |
| etuiad | 易推 |
| xykj | 享悦科技 |
| fhfy | 凤凰凤羽 |
| sina | 新浪广告 |
# 素材数据报表指标
> 来源：https://help.gravity-engine.com/docs/appendix/creative-report-metrics
> 列出素材数据报表的字段名、中文名称与指标含义，供查询接口接入和报表数据核对使用。
| 中文名 | 字段名 | 说明 |
| ---------------- | ----------------------------------- | ------------------------------------------------- |
| **基础信息** | | |
| 文件夹 | folder\_id | 素材所在的文件夹 |
| 上传时间 | create\_time | 素材上传到系统的时间 |
| 制作日期 | make\_time | 素材内容的实际制作日期 |
| 设计师(剪辑) | designer\_id | 负责剪辑的设计师 |
| 创意人 | creative\_user\_id | 负责创意构思的人员 |
| 拍摄人员 | capture\_user\_id | 负责视频拍摄的人员 |
| 参演人员 | performer\_user\_id | 视频中出镜的演员或模特 |
| 配音人员 | dub\_user\_id | 负责音频配音的人员 |
| 录屏人员 | transcribe\_user\_id | 负责屏幕录制的人员 |
| 设计师(图片) | designer\_image\_id | 负责图片设计的设计师 |
| 3D动作 | d3\_action\_user\_id | 负责3D动作设计的人员 |
| 3D渲染 | d3\_render\_user\_id | 负责3D渲染制作的人员 |
| 其他人员 | other\_user\_id | 其他参与制作的人员 |
| **基本信息** | | |
| 消耗 | AdCost | 广告总花费 |
| 千次展现均价 | AdAvgShowCost | 每千次曝光成本（消耗/展示数 × 1000） |
| 点击均价 | AdAvgClickCost | 单次点击成本（消耗/点击数） |
| 点击数 | AdClick | 用户点击广告次数 |
| 点击率 | AdClickRate | 点击占曝光比例（点击数/展示数） |
| 转化数 | AdConvert | 达成目标转化次数 |
| 转化成本 | AdConvertCost | 单次转化成本（消耗/转化数） |
| 转化率 | AdConvertRate | 点击到转化的比率（转化数/点击数） |
| 深度转化数 | AdDeepConvert | 高阶目标转化次数（如付费、表单提交等） |
| 深度转化成本 | AdDeepConvertCost | 高阶目标单次成本（消耗/深度转化数） |
| 深度转化率 | AdDeepConvertRate | 点击到深度转化比率（深度转化数/点击数） |
| 展示数 | AdShow | 广告曝光次数 |
| 激活数 | AdAppActivate | 用户激活APP次数 |
| 激活成本 | AdAppActivateCost | 单次激活成本（消耗/激活数） |
| 激活率 | AdAppActivateRate | 点击到激活比率（激活数/点击数） |
| 首日付费金额 | AdAppFirstDayPayAmount | 用户在应用内首日完成付费的金额 |
| 首日付费次数 | AdAppFirstDayPay | 用户在应用内首日完成付费的次数 |
| 首次付费数 | AdAppFirstPay | 用户首次付费次数 |
| 首次付费成本 | AdAppFirstPayCost | 获取付费用户成本（消耗/首次付费数） |
| 首次付费率 | AdAppFirstPayRate | 激活用户付费比率（首次付费数/激活数） |
| 总付费金额 | AdAppGamePayAmount | 用户在应用内完成付费的总金额 |
| 总付费成本 | AdAppGamePayCost | 单次付费成本（消耗/总付费次数） |
| 总付费次数 | AdAppGamePay | 用户在应用内完成付费的总次数 |
| 关键行为次数 | AdAppKeyActive | 用户完成关键行为次数（如注册、加入购物车等） |
| 关键行为成本 | AdAppKeyActiveCost | 单次行为成本（消耗/关键行为次数） |
| 关键行为率 | AdAppKeyActiveRate | 激活用户行为比率（关键行为次数/激活数） |
| 注册数 | AdAppRegister | 用户注册次数 |
| 注册成本 | AdAppRegisterCost | 单次注册成本（消耗/注册数） |
| 注册率 | AdAppRegisterRate | 点击到注册比率（注册数/点击数） |
| 次日留存数 | AdAppRetention | 用户激活后第二天打开APP的行为量级 |
| 次日留存成本 | AdAppRetentionCost | 留存用户单成本（消耗/次日留存数） |
| 次日留存率 | AdAppRetentionRate | 用户留存比率（次日留存数/激活数） |
| **归因漏斗指标（引力）** | | |
| 回传\_关键行为数(曝光口径) | AppKeyActiveUploadedAtv | 引力引擎实际上报给平台的关键行为数 |
| 回传\_激活数(曝光口径) | AppActivateUploadedAtv | 引力引擎实际上报给平台的激活数 |
| 回传\_次留数(曝光口径) | AppRetentionUploaded | 引力引擎实际上报给平台的次留数 |
| 回传\_首次付费金额(曝光口径) | AppFirstPayAmountUploadedAtv | 引力引擎实际上报给媒体的首次付费金额 |
| 回传\_首次付费数(曝光口径) | AppFirstPayUploadedAtv | 引力引擎实际上报给平台的首次付费数 |
| 回传\_首日付费金额(曝光口径) | AppFirstDayPayAmountUploaded | 引力引擎实际上报给平台的首日付费金额 |
| 回传\_首日付费次数(曝光口径) | AppFirstDayPayUploaded | 回传\_首日付费次数(曝光口径) |
| 回传\_首日付费人数(曝光口径) | AppFirstDayPayUserCntUploaded | 回传\_首日付费人数(曝光口径) |
| 回传\_注册数(曝光口径) | AppRegisterUploadedAtv | 引力引擎实际上报给平台的注册数 |
| 回传\_总付费金额(曝光口径) | AppGamePayAmountUploadedAtv | 引力引擎实际上报给平台的总付费金额 |
| 回传\_总付费人数(曝光口径) | AppGamePayUserCntUploadedAtv | 回传\_总付费次数按用户去重 |
| 回传\_总付费次数(曝光口径) | AppPayUploadedAtv | 引力引擎实际上报给平台的总付费数 |
| 埋点\_关键行为数(曝光口径) | AppKeyActiveBuriedAtv | 引力引擎经过映射管理处理后的关键行为数 |
| 埋点\_激活数(曝光口径) | AppActivateBuriedAtv | 引力引擎经过映射管理处理后的激活数 |
| 埋点\_次留(曝光口径) | AppRetentionBuried | 引力引擎经过映射管理处理后的次留数 |
| 埋点\_首次付费金额(曝光口径) | AppFirstPayAmountBuriedAtv | 引力引擎经过映射管理处理后的首次付费金额 |
| 埋点\_首次付费数(曝光口径) | AppFirstBuriedAtv | 引力引擎经过映射管理处理后的首次付费数 |
| 埋点\_首日付费金额(曝光口径) | AppFirstDayPayAmountBuried | 引力引擎经过映射管理处理后的首日金额 |
| 埋点\_首日付费次数(曝光口径) | AppFirstDayPayBuried | 引力引擎经过映射管理处理后的首日付费次数 |
| 埋点\_首日付费人数(曝光口径) | AppFirstDayPayUserCntBuried | 引力引擎经过映射管理处理后的首日付费人数 |
| 埋点\_注册数(曝光口径) | AppRegisterBuriedAtv | 引力引擎经过映射管理处理后的注册数 |
| 埋点\_总付费金额(曝光口径) | AppGamePayAmountBuriedAtv | 引力引擎经过映射管理处理后的总付费金额 |
| 埋点\_总付费人数(曝光口径) | AppGamePayUserCntBuriedAtv | 埋点\_总付费次数按用户去重 |
| 埋点\_总付费次数(曝光口径) | AppGamePayBuriedAtv | 引力引擎经过映射管理处理后的总付费数 |
| 首日每次付费成本(曝光口径) | AppFirstDayEachPayCost | 引力引擎收集到的全量每次付费成本 |
| 新增用户数 | AppRealRegisterCnt | 实际调用注册接口的用户数（主要用于数据核对与排查） |
| 标准\_次留数(曝光口径) | AppRetentionStandard | 引力引擎收集到的全量次留数 |
| 标准\_激活数(曝光口径) | AppActivateStandard | 基于客户端上报的用户首次启动事件统计（小程序：MPLaunch、应用：AppStart） |
| 标准\_首次付费金额(曝光口径) | AppFirstPayAmountStandardAtv | 引力引擎收集到的全量首次付费金额（含自然量） |
| 标准\_首次付费数(曝光口径) | AppFirstPayStandardAtv | 引力引擎收集到的全量首次付费数（含自然量） |
| 标准\_首日付费金额(曝光口径) | AppFirstDayPayAmountStandard | 引力引擎收集到的全量首日付费金额 |
| 标准\_首日付费次数(曝光口径) | AppFirstDayPayStandard | 引力引擎收集到的全量首日付费次数 |
| 标准\_首日付费人数(曝光口径) | AppFirstDayPayUserCntStandard | 引力引擎收集到的全量首日付费人数 |
| 标准\_注册数(曝光口径) | AppRegisterStandard | 基于客户主动上报的用户业务注册事件统计（MPRegister/AppRegister） |
| 标准\_总付费金额(曝光口径) | AppGamePayAmountStandardAtv | 引力引擎收集到的全量付费金额 |
| 标准\_总付费人数(曝光口径) | AppGamePayUserCntStandardAtv | 标准\_总付费次数按用户去重 |
| 标准\_总付费次数(曝光口径) | AppGamePayStandardAtv | 引力引擎收集到的全量付费次数（含自然量） |
| **广告变现指标（引力）** | | |
| 首日广告收入 | AppAdFirstDayRevenue | 所选时间范围内的激活用户首日产生的广告收入（注：产品为微信小游戏且为曝光归因口径时，此指标无意义） |
| 首日广告ROI | AppAdFirstDayRevenueROI | 首日广告收入/平台\_消耗 |
| 总广告收入 | AppAdRevenue | 所选时间范围内的激活用户产生的累计广告收入 |
| 总广告收入ROI | AppAdRevenueROI | 总广告收入/平台\_消耗 |
| **ROI指标（引力）** | | |
| 首日广告收入 | AppAdFirstDayRevenue | 所选时间范围内的激活用户首日产生的广告收入（注：产品为微信小游戏且为曝光归因口径时，此指标无意义） |
| 首日广告ROI | AppAdFirstDayRevenueROI | 首日广告收入/平台\_消耗 |
| 总广告收入 | AppAdRevenue | 所选时间范围内的激活用户产生的累计广告收入 |
| 总广告收入ROI | AppAdRevenueROI | 总广告收入/平台\_消耗 |
| 首日付费ROI | AppFirstDayPayROI | 标准首日付费金额/平台消耗 |
| 回传\_首日付费ROI | AppFirstDayPayROIUploaded | 所选时间范围内激活用户在激活当日经过映射回传过滤后的付费金额/消耗 |
| 总付费ROI(曝光口径) | AppGamePayAtvROI | 标准总付费金额/平台消耗 |
| 首日ARPPU(曝光口径) | AppFirstDayARPPUStandard | 标准首日付费金额(曝光口径)/标准首日付费人数(曝光口径) |
| 首日付费率(曝光口径) | AppFirstDayPayRateStandard | 标准首日付费人数(曝光口径)/标准激活数(曝光口径) |
| 首日付费成本(曝光口径) | AppDayPayCostStandard | 平台消耗/标准首日付费人数 |
| 累计付费倍率(曝光口径) | AppPayAmountAtvPower | 标准总付费金额(曝光口径)/标准首日付费金额(曝光口径) |
| 二日付费次数 | AppMultiDayGamePayBuried\_2 | 所选时间范围内的激活用户在激活后第N日的付费数之和 |
| 三日付费次数 | AppMultiDayGamePayBuried\_3 | 所选时间范围内的激活用户在激活后第N日的付费数之和 |
| 四日付费次数 | AppMultiDayGamePayBuried\_4 | 所选时间范围内的激活用户在激活后第N日的付费数之和 |
| 五日付费次数 | AppMultiDayGamePayBuried\_5 | 所选时间范围内的激活用户在激活后第N日的付费数之和 |
| 六日付费次数 | AppMultiDayGamePayBuried\_6 | 所选时间范围内的激活用户在激活后第6日的付费数之和 |
| 七日付费次数 | AppMultiDayGamePayBuried\_7 | 所选时间范围内的激活用户在激活后第7日的付费数之和 |
| 十四日付费次数 | AppMultiDayGamePayBuried\_14 | 所选时间范围内的激活用户在激活后第14日的付费数之和 |
| 三十日付费次数 | AppMultiDayGamePayBuried\_30 | 所选时间范围内的激活用户在激活后第30日的付费数之和 |
| 四十五日付费次数 | AppMultiDayGamePayBuried\_45 | 所选时间范围内的激活用户在激活后第45日的付费数之和 |
| 六十日付费次数 | AppMultiDayGamePayBuried\_60 | 所选时间范围内的激活用户在激活后第60日的付费数之和 |
| 九十日付费次数 | AppMultiDayGamePayBuried\_90 | 所选时间范围内的激活用户在激活后第90日的付费数之和 |
| 一百二十日付费次数 | AppMultiDayGamePayBuried\_120 | 所选时间范围内的激活用户在激活后第120日的付费数之和 |
| 一百八十日付费次数 | AppMultiDayGamePayBuried\_180 | 所选时间范围内的激活用户在激活后第180日的付费数之和 |
| 二百一十日付费次数 | AppMultiDayGamePayBuried\_210 | 所选时间范围内的激活用户在激活后第210日的付费数之和 |
| 二百七十日付费次数 | AppMultiDayGamePayBuried\_270 | 所选时间范围内的激活用户在激活后第270日的付费数之和 |
| 三百日付费次数 | AppMultiDayGamePayBuried\_300 | 所选时间范围内的激活用户在激活后第300日的付费数之和 |
| 三百六十五日付费次数 | AppMultiDayGamePayBuried\_365 | 所选时间范围内的激活用户在激活后第365日的付费数之和 |
| 二日付费人数 | AppMultiDayGamePayUserCnt\_2 | 所选时间范围内的激活用户在激活后第2日的付费人数之和 |
| 三日付费人数 | AppMultiDayGamePayUserCnt\_3 | 所选时间范围内的激活用户在激活后第3日的付费人数之和 |
| 四日付费人数 | AppMultiDayGamePayUserCnt\_4 | 所选时间范围内的激活用户在激活后第4日的付费人数之和 |
| 五日付费人数 | AppMultiDayGamePayUserCnt\_5 | 所选时间范围内的激活用户在激活后第5日的付费人数之和 |
| 六日付费人数 | AppMultiDayGamePayUserCnt\_6 | 所选时间范围内的激活用户在激活后第6日的付费人数之和 |
| 七日付费人数 | AppMultiDayGamePayUserCnt\_7 | 所选时间范围内的激活用户在激活后第7日的付费人数之和 |
| 十四日付费人数 | AppMultiDayGamePayUserCnt\_14 | 所选时间范围内的激活用户在激活后第14日的付费人数之和 |
| 三十日付费人数 | AppMultiDayGamePayUserCnt\_30 | 所选时间范围内的激活用户在激活后第30日的付费人数之和 |
| 四十五日付费人数 | AppMultiDayGamePayUserCnt\_45 | 所选时间范围内的激活用户在激活后第45日的付费人数之和 |
| 六十日付费人数 | AppMultiDayGamePayUserCnt\_60 | 所选时间范围内的激活用户在激活后第60日的付费人数之和 |
| 九十日付费人数 | AppMultiDayGamePayUserCnt\_90 | 所选时间范围内的激活用户在激活后第90日的付费人数之和 |
| 一百二十日付费人数 | AppMultiDayGamePayUserCnt\_120 | 所选时间范围内的激活用户在激活后第120日的付费人数之和 |
| 一百八十日付费人数 | AppMultiDayGamePayUserCnt\_180 | 所选时间范围内的激活用户在激活后第180日的付费人数之和 |
| 二百一十日付费人数 | AppMultiDayGamePayUserCnt\_210 | 所选时间范围内的激活用户在激活后第210日的付费人数之和 |
| 二百七十日付费人数 | AppMultiDayGamePayUserCnt\_270 | 所选时间范围内的激活用户在激活后第270日的付费人数之和 |
| 三百日付费人数 | AppMultiDayGamePayUserCnt\_300 | 所选时间范围内的激活用户在激活后第300日的付费人数之和 |
| 三百六十五日付费人数 | AppMultiDayGamePayUserCnt\_365 | 所选时间范围内的激活用户在激活后第365日的付费人数之和 |
| 二日付费收入 | AppMultiDayGamePayAmountBuried\_2 | 所选时间范围内的激活用户在激活后第2日的付费金额之和 |
| 三日付费收入 | AppMultiDayGamePayAmountBuried\_3 | 所选时间范围内的激活用户在激活后第3日的付费金额之和 |
| 四日付费收入 | AppMultiDayGamePayAmountBuried\_4 | 所选时间范围内的激活用户在激活后第4日的付费金额之和 |
| 五日付费收入 | AppMultiDayGamePayAmountBuried\_5 | 所选时间范围内的激活用户在激活后第5日的付费金额之和 |
| 六日付费收入 | AppMultiDayGamePayAmountBuried\_6 | 所选时间范围内的激活用户在激活后第6日的付费金额之和 |
| 七日付费收入 | AppMultiDayGamePayAmountBuried\_7 | 所选时间范围内的激活用户在激活后第7日的付费金额之和 |
| 十四日付费收入 | AppMultiDayGamePayAmountBuried\_14 | 所选时间范围内的激活用户在激活后第14日的付费金额之和 |
| 三十日付费收入 | AppMultiDayGamePayAmountBuried\_30 | 所选时间范围内的激活用户在激活后第30日的付费金额之和 |
| 四十五日付费收入 | AppMultiDayGamePayAmountBuried\_45 | 所选时间范围内的激活用户在激活后第45日的付费金额之和 |
| 六十日付费收入 | AppMultiDayGamePayAmountBuried\_60 | 所选时间范围内的激活用户在激活后第60日的付费金额之和 |
| 九十日付费收入 | AppMultiDayGamePayAmountBuried\_90 | 所选时间范围内的激活用户在激活后第90日的付费金额之和 |
| 一百二十日付费收入 | AppMultiDayGamePayAmountBuried\_120 | 所选时间范围内的激活用户在激活后第120日的付费金额之和 |
| 一百八十日付费收入 | AppMultiDayGamePayAmountBuried\_180 | 所选时间范围内的激活用户在激活后第180日的付费金额之和 |
| 二百一十日付费收入 | AppMultiDayGamePayAmountBuried\_210 | 所选时间范围内的激活用户在激活后第210日的付费金额之和 |
| 二百七十日付费收入 | AppMultiDayGamePayAmountBuried\_270 | 所选时间范围内的激活用户在激活后第270日的付费金额之和 |
| 三百日付费收入 | AppMultiDayGamePayAmountBuried\_300 | 所选时间范围内的激活用户在激活后第300日的付费金额之和 |
| 三百六十五日付费收入 | AppMultiDayGamePayAmountBuried\_365 | 所选时间范围内的激活用户在激活后第365日的付费金额之和 |
| 二日付费ROI | AppMultiDayGamePayROIBuried\_2 | 二日付费收入/平台\_消耗 |
| 三日付费ROI | AppMultiDayGamePayROIBuried\_3 | 三日付费收入/平台\_消耗 |
| 四日付费ROI | AppMultiDayGamePayROIBuried\_4 | 四日付费收入/平台\_消耗 |
| 五日付费ROI | AppMultiDayGamePayROIBuried\_5 | 五日付费收入/平台\_消耗 |
| 六日付费ROI | AppMultiDayGamePayROIBuried\_6 | 六日付费收入/平台\_消耗 |
| 七日付费ROI | AppMultiDayGamePayROIBuried\_7 | 七日付费收入/平台\_消耗 |
| 十四日付费ROI | AppMultiDayGamePayROIBuried\_14 | 十四日付费收入/平台\_消耗 |
| 三十日付费ROI | AppMultiDayGamePayROIBuried\_30 | 三十日付费收入/平台\_消耗 |
| 四十五日付费ROI | AppMultiDayGamePayROIBuried\_45 | 四十五日付费收入/平台\_消耗 |
| 六十日付费ROI | AppMultiDayGamePayROIBuried\_60 | 六十日付费收入/平台\_消耗 |
| 九十日付费ROI | AppMultiDayGamePayROIBuried\_90 | 九十日付费收入/平台\_消耗 |
| 一百二十日付费ROI | AppMultiDayGamePayROIBuried\_120 | 一百二十日付费收入/平台\_消耗 |
| 一百八十日付费ROI | AppMultiDayGamePayROIBuried\_180 | 一百八十日付费收入/平台\_消耗 |
| 二百一十日付费ROI | AppMultiDayGamePayROIBuried\_210 | 二百一十日付费收入/平台\_消耗 |
| 二百七十日付费ROI | AppMultiDayGamePayROIBuried\_270 | 二百七十日付费收入/平台\_消耗 |
| 三百日付费ROI | AppMultiDayGamePayROIBuried\_300 | 三百日付费收入/平台\_消耗 |
| 三百六十五日付费ROI | AppMultiDayGamePayROIBuried\_365 | 三百六十五日付费收入/平台\_消耗 |
| 二日广告收入 | AppMultiDayAdRevenue\_2 | 所选时间范围内的激活用户在激活后第2日产生的广告收入 |
| 三日广告收入 | AppMultiDayAdRevenue\_3 | 所选时间范围内的激活用户在激活后第3日产生的广告收入 |
| 四日广告收入 | AppMultiDayAdRevenue\_4 | 所选时间范围内的激活用户在激活后第4日产生的广告收入 |
| 五日广告收入 | AppMultiDayAdRevenue\_5 | 所选时间范围内的激活用户在激活后第5日产生的广告收入 |
| 六日广告收入 | AppMultiDayAdRevenue\_6 | 所选时间范围内的激活用户在激活后第6日产生的广告收入 |
| 七日广告收入 | AppMultiDayAdRevenue\_7 | 所选时间范围内的激活用户在激活后第7日产生的广告收入 |
| 十四日广告收入 | AppMultiDayAdRevenue\_14 | 所选时间范围内的激活用户在激活后第14日产生的广告收入 |
| 三十日广告收入 | AppMultiDayAdRevenue\_30 | 所选时间范围内的激活用户在激活后第30日产生的广告收入 |
| 四十五日广告收入 | AppMultiDayAdRevenue\_45 | 所选时间范围内的激活用户在激活后第45日产生的广告收入 |
| 六十日广告收入 | AppMultiDayAdRevenue\_60 | 所选时间范围内的激活用户在激活后第60日产生的广告收入 |
| 二日广告ROI | AppMultiDayAdRevenueROI\_2 | 二日广告收入/平台\_消耗 |
| 三日广告ROI | AppMultiDayAdRevenueROI\_3 | 三日周期的广告投资回报率 |
| 四日广告ROI | AppMultiDayAdRevenueROI\_4 | 四日周期的广告投资回报率 |
| 五日广告ROI | AppMultiDayAdRevenueROI\_5 | 五日周期的广告投资回报率 |
| 六日广告ROI | AppMultiDayAdRevenueROI\_6 | 六日周期的广告投资回报率 |
| 七日广告ROI | AppMultiDayAdRevenueROI\_7 | 七日周期的广告投资回报率 |
| 十四日广告ROI | AppMultiDayAdRevenueROI\_14 | 十四日周期的广告投资回报率 |
| 三十日广告ROI | AppMultiDayAdRevenueROI\_30 | 三十日周期的广告投资回报率 |
| 四十五日广告ROI | AppMultiDayAdRevenueROI\_45 | 四十五日周期的广告投资回报率 |
| 六十日广告ROI | AppMultiDayAdRevenueROI\_60 | 六十日周期的广告投资回报率 |
| 二日付费留存用户数 | AppMultiDayPayRetention\_2 | 第二日的付费用户留存数量 |
| 三日付费留存用户数 | AppMultiDayPayRetention\_3 | 第三日的付费用户留存数量 |
| 四日付费留存用户数 | AppMultiDayPayRetention\_4 | 第四日的付费用户留存数量 |
| 五日付费留存用户数 | AppMultiDayPayRetention\_5 | 第五日的付费用户留存数量 |
| 六日付费留存用户数 | AppMultiDayPayRetention\_6 | 第六日的付费用户留存数量 |
| 七日付费留存用户数 | AppMultiDayPayRetention\_7 | 第七日的付费用户留存数量 |
| 十四日付费留存用户数 | AppMultiDayPayRetention\_14 | 第十四日的付费用户留存数量 |
| 三十日付费留存用户数 | AppMultiDayPayRetention\_30 | 第三十日的付费用户留存数量 |
| 二日付费留存用户率 | AppMultiDayPayRetentionRate\_2 | 第二日的付费用户留存比例 |
| 三日付费留存用户率 | AppMultiDayPayRetentionRate\_3 | 第三日的付费用户留存比例 |
| 四日付费留存用户率 | AppMultiDayPayRetentionRate\_4 | 第四日的付费用户留存比例 |
| 五日付费留存用户率 | AppMultiDayPayRetentionRate\_5 | 第五日的付费用户留存比例 |
| 六日付费留存用户率 | AppMultiDayPayRetentionRate\_6 | 第六日的付费用户留存比例 |
| 七日付费留存用户率 | AppMultiDayPayRetentionRate\_7 | 第七日的付费用户留存比例 |
| 十四日付费留存用户率 | AppMultiDayPayRetentionRate\_14 | 第十四日的付费用户留存比例 |
| 三十日付费留存用户率 | AppMultiDayPayRetentionRate\_30 | 第三十日的付费用户留存比例 |
# 附录
> 来源：https://help.gravity-engine.com/docs/appendix
> Gravity Engine 附录索引，汇总变现细查报表指标、产品类型枚举值等主题，便于按功能进入对应的配置、接入或参考说明。
{/* Generated by scripts/generate-docs-routes.mjs. Do not edit. */}
## 目录 [#目录]
* [变现细查报表指标](/docs/appendix/monetization-report-metrics)
* [产品类型枚举值](/docs/appendix/product-type-enums)
* [多维报表字段](/docs/appendix/multidimensional-report-fields)
* [广告聚合平台字段配置](/docs/appendix/ad-mediation-fields)
* [广告平台枚举值](/docs/appendix/ad-platform-enums)
* [素材数据报表指标](/docs/appendix/creative-report-metrics)
* [用户订单报表指标](/docs/appendix/user-order-report-metrics)
* [用户信息报表指标](/docs/appendix/user-info-report-metrics)
# 变现细查报表指标
> 来源：https://help.gravity-engine.com/docs/appendix/monetization-report-metrics
> 列出变现细查报表的字段名、中文名称与指标含义，供查询接口接入和广告收入数据核对使用。
| 中文名 | 字段名 | 说明 |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------- | -------------------------------- |
| **用户基础指标** | | |
| 广告ID | AdAid | 广告的唯一标识符 |
| 创意ID | AdCid | 广告创意的唯一标识符 |
| 计划ID | AdGid | 广告计划的唯一标识符 |
| 广告点击时间 | AdClickTime | 用户点击广告的具体时间 |
| 广告账户ID | AdvertiserID | 广告主的账户ID |
| 客户端渠道 | Channel | 用户使用的客户端渠道 |
| 注册时间 | CreateTime | 用户注册的时间 |
| 客户ID | ClientID | 用户的唯一标识符 |
| 版位 | CSite | 广告展示的具体位置 |
| 最近活跃日期 | LatestLoginDay | 用户最近一次活跃的日期 |
| 媒体平台 | AdPlatform | 广告投放的媒体平台 |
| 用户名 | Name | 用户的名称 |
| openid | WXOpenID | 小游戏用户的openid |
| 推广活动 | TurboPromotedObjectID | 推广活动的唯一标识符 |
| 客户端版本 | Version | 客户端的版本号 |
| **再归因指标** | | |
| 广告ID(再归因) | ReAttributeAdAid | 再归因后的广告ID |
| 创意ID(再归因) | ReAttributeAdCid | 再归因后的创意ID |
| 计划ID(再归因) | ReAttributeAdGid | 再归因后的计划ID |
| 广告点击时间(再归因) | ReAttributeAdClickTime | 再归因后的广告点击时间 |
| 媒体平台(再归因) | ReAttributeAdPlatform | 再归因后的媒体平台 |
| 广告账户ID(再归因) | ReAttributeAdvertiserID | 再归因后的广告账户ID |
| 渠道(再归因) | ReAttributeChannel | 再归因后的渠道 |
| 版位(再归因) | ReAttributeCSite | 再归因后的版位 |
| 再归因时间(再归因) | ReAttributeCreateTime | 进行再归因的时间 |
| 推广活动(再归因) | ReAttributeTurboPromotedObjectID | 再归因后的推广活动 |
| 累计再归因次数 | ReAttributeRetargetingCount | 用户累计被再归因的次数 |
| **变现指标** | | |
| 事件发生时间 | AdEventTime | 事件发生的时间 |
| 其他指标为 广告展示事件(`$AdShow`)的非公共属性，格式为 event + 事件属性。例如：event$ecpm。 具体属性参见[元事件页面](https://web.gravity-engine.com/#/manage/metadata/metaEvent) `$AdShow` 事件的事件属性。 | | |
| **用户属性** | | |
| 数数#account\_id | user$ta\_account\_id | 数数用户账号ID |
| 数数#distinct\_id | user$ta\_distinct\_id | 数数用户唯一标识符 |
| 激励视频广告平均eCPM | user$reward\_ad\_avg\_ecpm | 激励视频广告平均千次展示收益 |
| 激励视频广告次数 | user$reward\_ad\_count | 用户观看激励视频广告的总次数 |
| 激励视频广告LTV | user$reward\_ad\_ltv | 激励视频广告生命周期价值 |
| 激励视频广告LTV（24h） | user$reward\_ad\_24h\_ltv | 24小时内激励视频广告生命周期价值 |
| 激励视频广告最高eCPM | user$reward\_ad\_max\_ecpm | 激励视频广告最高千次展示收益 |
| 开屏广告平均eCPM | user$splash\_ad\_avg\_ecpm | 开屏广告平均千次展示收益 |
| 开屏广告平均eCPM（24h） | user$splash\_ad\_24h\_avg\_ecpm | 24小时内开屏广告平均千次展示收益 |
| 开屏广告观看次数 | user$splash\_ad\_count | 用户观看开屏广告的总次数 |
| 开屏广告LTV | user$splash\_ad\_ltv | 开屏广告生命周期价值 |
| 开屏广告LTV（24h） | user$splash\_ad\_24h\_ltv | 24小时内开屏广告生命周期价值 |
| 开屏广告最高eCPM | user$splash\_ad\_max\_ecpm | 开屏广告最高千次展示收益 |
| 开屏广告24小时LTV | user$splash\_ad\_24\_ltv | 24小时开屏广告生命周期价值 |
| 开屏广告24小时观看次数 | user$splash\_24h\_count | 24小时内开屏广告观看次数 |
| 激励视频广告平均eCPM（24h） | user$reward\_ad\_24h\_avg\_ecpm | 24小时内激励视频广告平均千次展示收益 |
| 激励视频广告观看次数（24h） | user$reward\_24h\_count | 24小时内激励视频广告观看次数 |
| 回流次数 | user$reactive\_count | 用户回流次数统计 |
| 省份 | user$province | 用户所在省份 |
| 单次付费最大金额(分) | user$pay\_max\_amount | 用户单次付费最大金额（单位：分） |
| 付费次数 | user$pay\_count | 用户付费总次数 |
| 付费总额(分) | user$pay\_amount\_sum | 用户累计付费总额（单位：分） |
| 操作系统 | user$os | 用户使用的操作系统 |
| 原生广告最高eCPM | user$native\_ad\_max\_ecpm | 原生广告最高千次展示收益 |
| 原生广告LTV | user$native\_ad\_ltv | 原生广告生命周期价值 |
| 原生广告观看次数 | user$native\_ad\_count | 用户观看原生广告的总次数 |
| 原生广告平均eCPM | user$native\_ad\_avg\_ecpm | 原生广告平均千次展示收益 |
| 原生广告LTV（24h） | user$native\_ad\_24h\_ltv | 24小时内原生广告生命周期价值 |
| 原生广告平均eCPM（24h） | user$native\_ad\_24h\_avg\_ecpm | 24小时内原生广告平均千次展示收益 |
| 原生广告观看次数（24h） | user$native\_24h\_count | 24小时内原生广告观看次数 |
| 设备型号 | user$model | 用户使用的设备型号 |
| 设备制造商 | user$manufacturer | 用户设备的制造商 |
| 最近一次回流时间 | user$latest\_reactive\_time | 用户最近一次回流的时间 |
| 插屏广告最高eCPM | user$interstitial\_ad\_max\_ecpm | 插屏广告最高千次展示收益 |
| 插屏广告LTV | user$interstitial\_ad\_ltv | 插屏广告生命周期价值 |
| 插屏广告观看次数 | user$interstitial\_ad\_count | 用户观看插屏广告的总次数 |
| 插屏广告平均eCPM | user$interstitial\_ad\_avg\_ecpm | 插屏广告平均千次展示收益 |
| 插屏广告24小时LTV | user$interstitial\_ad\_24h\_ltv | 24小时内插屏广告生命周期价值 |
| 插屏广告平均eCPM（24h） | user$interstitial\_ad\_24h\_avg\_ecpm | 24小时内插屏广告平均千次展示收益 |
| 插屏广告24小时观看次数 | user$interstitial\_24h\_count | 24小时内插屏广告观看次数 |
| 首次付费时间 | user$first\_pay\_time | 用户首次付费的时间 |
| 首次付费支付项目 | user$first\_pay\_reason | 用户首次付费的支付项目 |
| 首次付费支付方式 | user$first\_pay\_method | 用户首次付费的支付方式 |
| 国家 | user$country | 用户所在国家 |
| 点击渠道 | user$click\_channel | 用户点击的渠道来源 |
| 城市 | user$city | 用户所在城市 |
| 客户端渠道 | user$channel | 用户使用的客户端渠道 |
| Banner广告最高eCPM | user$banner\_ad\_max\_ecpm | Banner广告最高千次展示收益 |
| Banner广告LTV | user$banner\_ad\_ltv | Banner广告生命周期价值 |
| Banner广告观看次数 | user$banner\_ad\_count | 用户观看Banner广告的总次数 |
| Banner广告平均eCPM | user$banner\_ad\_avg\_ecpm | Banner广告平均千次展示收益 |
| Banner广告24小时LTV | user$banner\_ad\_24h\_ltv | 24小时内Banner广告生命周期价值 |
| Banner广告平均eCPM（24h） | user$banner\_ad\_24h\_avg\_ecpm | 24小时内Banner广告平均千次展示收益 |
| Banner广告观看次数（24h） | user$banner\_24h\_count | 24小时内Banner广告观看次数 |
| 广告最高eCPM | user$ad\_max\_ecpm | 广告最高千次展示收益 |
| 广告LTV | user$ad\_ltv | 广告生命周期价值 |
| 广告观看次数 | user$ad\_count | 用户观看广告的总次数 |
| 广告平均eCPM | user$ad\_avg\_ecpm | 广告平均千次展示收益 |
| 广告LTV（24h） | user$ad\_24h\_ltv | 24小时内广告生命周期价值 |
| 广告观看次数（24h） | user$ad\_24h\_count | 24小时内广告观看次数 |
| 广告平均eCPM（24h） | user$ad\_24h\_avg\_ecpm | 24小时内广告平均千次展示收益 |
| IDFA | Idfa | iOS广告标识符 |
| IDFV | Idfv | iOS供应商标识符 |
| CAID1 | Caid1 | 中国广告标识符1 |
| CAID2 | Caid2 | 中国广告标识符2 |
| OAID | Oaid | 安卓广告标识符 |
| IMEI | Imei | 国际移动设备识别码 |
| AndroidId | AndroidId | 安卓设备标识符 |
| Android版本 | Android\_Version | 安卓系统版本号 |
| API版本 | Api\_Version | 系统API版本号 |
| 操作系统版本 | Rom\_version | 设备操作系统版本 |
| 分辨率 | Aspect\_Ratio | 设备屏幕分辨率 |
| 品牌 | Phone\_Brand | 手机品牌 |
| 机型 | Phone\_Model | 手机型号 |
| 系统 | OS | 操作系统类型 |
| **事件公共属性** | | |
| 应用唯一标识 | event$app\_id | 应用的唯一标识 |
| App的应用的版本 | event$app\_version | App的应用版本 |
| 设备品牌 | event$brand | 用户设备的品牌（如：Apple, Huawei） |
| 浏览器名称 | event$browser | 用户使用的浏览器名称 |
| 浏览器版本 | event$browser\_version | 用户使用的浏览器版本 |
| 运营商名称 | event$carrier | 用户设备SIM卡的运营商信息 |
| 城市 | event$city | 用户所在地的城市信息 |
| 国家 | event$country | 用户所在地的国家信息 |
| 设备ID | event$device\_id | 经过处理的匿名设备标识符 |
| ip | event$ip | 用户的IP地址 |
| SDK技术框架 | event$lib | 埋点使用的SDK技术框架（如：iOS, Android, JS） |
| 引力引擎SDK版本 | event$lib\_version | 引力引擎SDK的版本号 |
| 设备制造商 | event$manufacturer | 设备的制造商 |
| 设备型号 | event$model | 设备的具体型号 |
| 网络类型 | event$network\_type | 用户当前的网络环境（如：Wi-Fi， 4G） |
| 操作系统 | event$os | 用户设备的操作系统（如：iOS， Android） |
| 操作系统版本 | event$os\_version | 操作系统的具体版本号 |
| 省份 | event$province | 用户所在地的省份信息 |
| 启动场景 | event$scene | 应用被启动的场景 |
| 屏幕高度 | event$screen\_height | 设备屏幕的高度（像素） |
| 屏幕方向 | event$screen\_orientation | 当前屏幕的显示方向（横屏/竖屏） |
| 屏幕宽度 | event$screen\_width | 设备屏幕的宽度（像素） |
| 系统语言设置 | event$system\_language | 设备系统设置的语言 |
| 时区偏移量 | event$timezone\_offset | 用户所在时区相对于UTC的偏移量（分钟） |
| 当日首次启动场景 | event$today\_first\_scene | 用户当日首次启动应用的场景 |
| 追溯ID | event$trace\_id | 用于关联和追踪单个用户会话或事件的唯一标识 |
# 多维报表字段
> 来源：https://help.gravity-engine.com/docs/appendix/multidimensional-report-fields
> 列出多维报表可用的数据维度、指标字段和筛选操作符，供构造 data_dims 等查询参数时参考。
## 数据维度字段参考表（data\_dims） [#数据维度字段参考表data_dims]
| 中文名 | 字段名 | 说明 |
| ------ | --------------------------- | --------------------------- |
| 产品维度 | app\_id | 应用产品标识 |
| 注册包名 | bundle\_id | 应用包名标识 |
| 广告平台 | click\_company | 广告投放平台 |
| 账户维度 | advertiser\_id | 广告账户标识 |
| 计划维度 | gid | 广告计划标识 |
| 广告维度 | aid | 广告标识 |
| 创意维度 | cid | 创意标识 |
| 渠道维度 | channel | 渠道标识 |
| 设备维度 | os\_family | 设备标识 |
| 优化师 | operator\_id | 优化师标识 |
| 部门ID | dept\_id | 部门标识 |
| 推广活动ID | turbo\_promoted\_object\_id | 推广活动标识 |
| 广告版位 | csite | 广告版位标识 |
| 优化目标 | optimization\_goal | 必须要有 `click_company` 维度才可选择 |
| 深度优化目标 | deep\_optimization\_goal | 必须要有 `click_company` 维度才可选择 |
| 深度优化方式 | deep\_bid\_type | 必须要有 `click_company` 维度才可选择 |
## 关联维度字段参考表（relate\_dims） [#关联维度字段参考表relate_dims]
| 中文名 | 字段名 | 说明 |
| --------------------------------------- | ----------------------------- | ---------------------- |
| **advertiser\_id（账户维度）** | | |
| 广告账户状态 | advertiser\_status | 广告账户的当前状态，账户维度的关联维度 |
| 广告主名称 | advertiser\_name | 广告账户对应的名称，账户维度的关联维度 |
| 账户备注 | advertiser\_remark | 广告账户的备注信息，账户维度的关联维度 |
| **gid（计划维度）** | | |
| 广告计划名称 | gid\_name | 广告计划的名称，计划维度的关联维度 |
| 广告计划状态 | gid\_status | 广告计划的当前状态，计划维度的关联维度 |
| **aid（广告维度）** | | |
| 广告名称 | aid\_name | 广告的名称，广告维度的关联维度 |
| 广告状态 | aid\_status | 广告的当前状态，广告维度的关联维度 |
| **cid（创意维度）** | | |
| 创意名称 | cid\_name | 广告创意的名称，创意维度的关联维度 |
| 创意状态 | cid\_status | 广告创意的当前状态，创意维度的关联维度 |
| **operator\_id（优化师）** | | |
| 优化师 | operator\_name | 优化师姓名（默认返回），优化师的关联维度 |
| **dept\_id（部门ID）** | | |
| 部门名称 | dept\_name | 部门名称（默认返回），部门的关联维度 |
| **turbo\_promoted\_object\_id（推广活动ID）** | | |
| 推广活动名称 | turbo\_promoted\_object\_name | 推广活动名称（默认返回），推广活动的关联维度 |
| **csite（广告版位）** | | |
| 广告版位名称 | csite\_name | 广告版位名称（默认返回），广告版位的关联维度 |
| **app\_id（产品ID）** | | |
| 产品名称 | app\_name | 产品名称（默认返回），产品ID的关联维度 |
## 筛选条件字段参考表（field） [#筛选条件字段参考表field]
| 中文名 | 字段名 | 参数类型 | 说明 |
| ------ | ----------------------------- | ------ | ------------------------------------------------------------------------ |
| 媒体类型 | click\_company | string | 广告平台类型筛选（支持 `IN` 操作符），具体取值参考 [广告平台枚举值](/docs/appendix/ad-platform-enums) |
| 设备类型 | os\_family | string | 操作系统类型筛选（支持 `IN` 操作符） |
| 广告账户ID | advertiser\_id | string | 广告账户标识筛选（支持 `IN` 操作符） |
| 广告账户名称 | advertiser\_name | string | 广告账户名称模糊筛选（支持 `LIKE` 操作符） |
| 包名ID | bundle\_id | string | 包名筛选（支持 `IN` 操作符） |
| 推广活动ID | turbo\_promoted\_object\_id | string | 推广活动标识筛选（支持 `IN` 操作符） |
| 推广活动名称 | turbo\_promoted\_object\_name | string | 推广活动名称模糊筛选（支持 `LIKE` 操作符） |
| 计划ID | gid | string | 广告计划标识筛选（支持 `IN`、`NOT_IN` 操作符） |
| 广告ID | aid | string | 广告标识筛选（支持 `IN`、`NOT_IN` 操作符） |
| 优化师 | operator\_id | int | 优化师标识筛选（支持 `IN`、`EQUALS` 操作符） |
| 部门 | dept\_id | int | 部门标识筛选（支持 `IN`、`EQUALS` 操作符） |
| 产品 | app\_id | int | 应用产品标识筛选（支持 `EQUALS` 操作符） |
| 项目 | project\_id | int | 项目标识筛选（支持 `EQUALS` 操作符） |
## 操作符说明（operator） [#操作符说明operator]
| 操作符 | 符号/含义 | 说明 |
| ----------------- | ---------------------- | ------ |
| `EQUALS` | `=` | 等于 |
| `NOT_EQUALS` | `!=` | 不等于 |
| `NULL` | `NULL` | 值为空 |
| `NOT_NULL` | `NOT_NULL` | 值不为空 |
| `WITH_VAL` | `WITH_VAL` | 有值 |
| `WITHOUT_VAL` | `WITHOUT_VAL` | 无值 |
| `LESS_EQUALS` | `<=` | 小于等于 |
| `LESS` | `<` | 小于 |
| `GREATER_EQUALS` | `>=` | 大于等于 |
| `GREATER` | `>` | 大于 |
| `PATTERN` | `pattern` | 正则匹配 |
| `NOT_PATTERN` | `not pattern` | 正则不匹配 |
| `LIKE` | `like` | 模糊查询 |
| `IN` | `in` | 在列表中 |
| `NOT_IN` | `not in` | 不在列表中 |
| `RANGE_IN` | `range in` | 在范围内 |
| `CURRENT_DAY` | `current day range in` | 当天时间范围 |
| `RELATIVE_MINUTE` | 相对分钟数 | 相对分钟数 |
| `RELATIVE_HOUR` | 相对小时数 | 相对小时数 |
| `RELATIVE_DAY` | 相对天数 | 相对天数 |
| `RELATIVE_WEEK` | 相对当前周 | 相对当前周 |
| `RELATIVE_MONTH` | 相对当前月 | 相对当前月 |
# 产品类型枚举值
> 来源：https://help.gravity-engine.com/docs/appendix/product-type-enums
> 列出 Gravity Engine 产品类型枚举值及对应业务类型，供接口传参与数据核对使用。
| 枚举值 | 产品类型 |
| --- | --------- |
| 0 | iOS |
| 1 | Android |
| 2 | Web/H5 |
| 3 | 微信小游戏 |
| 4 | 微信小程序 |
| 5 | 快应用 |
| 6 | 抖音小游戏 |
| 7 | 抖音小程序 |
| 8 | 支付宝小程序 |
| 9 | 支付宝小游戏 |
| 10 | QQ小游戏 |
| 11 | B站小游戏 |
| 12 | 百度小游戏 |
| 13 | 快游戏 |
| 14 | 快手小程序 |
| 15 | 快手小游戏 |
| 16 | 淘宝小游戏 |
| 17 | 淘宝小程序 |
| 18 | 美团小游戏 |
| 19 | 京东小游戏 |
| 20 | 京东小程序 |
| 21 | 钉钉小程序 |
| 22 | 360小程序 |
| 23 | 鸿蒙 |
| 24 | UC小游戏 |
| 25 | TikTok小游戏 |
| 26 | MacOS |
| 27 | Taptap小游戏 |
| 28 | 闲鱼小游戏 |
| 29 | Windows |
| 30 | 芒果TV小游戏 |
# 用户信息报表指标
> 来源：https://help.gravity-engine.com/docs/appendix/user-info-report-metrics
> 列出用户信息报表的字段名、中文名称与指标含义，供查询接口接入和用户数据核对使用。
## 用户基础指标 [#user-base]
| 中文名 | 字段名 | 说明 |
| ------ | --------------------- | ------------ |
| 广告ID | AdAid | 广告的唯一标识符 |
| 创意ID | AdCid | 广告创意的唯一标识符 |
| 计划ID | AdGid | 广告计划的唯一标识符 |
| 广告点击时间 | AdClickTime | 用户点击广告的具体时间 |
| 广告账户ID | AdvertiserID | 广告主的账户ID |
| 客户端渠道 | Channel | 用户使用的客户端渠道 |
| 注册时间 | CreateTime | 用户注册的时间 |
| 客户ID | ClientID | 用户的唯一标识符 |
| 版位 | CSite | 广告展示的具体位置 |
| 最近活跃日期 | LatestLoginDay | 用户最近一次活跃的日期 |
| 媒体平台 | AdPlatform | 广告投放的媒体平台 |
| 用户名 | Name | 用户的名称 |
| openid | WXOpenID | 小游戏用户的openid |
| 推广活动 | TurboPromotedObjectID | 推广活动的唯一标识符 |
| 客户端版本 | Version | 客户端的版本号 |
## 再归因指标 [#re-attribute]
| 中文名 | 字段名 | 说明 |
| ----------- | -------------------------------- | ----------- |
| 广告ID(再归因) | ReAttributeAdAid | 再归因后的广告ID |
| 创意ID(再归因) | ReAttributeAdCid | 再归因后的创意ID |
| 计划ID(再归因) | ReAttributeAdGid | 再归因后的计划ID |
| 广告点击时间(再归因) | ReAttributeAdClickTime | 再归因后的广告点击时间 |
| 媒体平台(再归因) | ReAttributeAdPlatform | 再归因后的媒体平台 |
| 广告账户ID(再归因) | ReAttributeAdvertiserID | 再归因后的广告账户ID |
| 渠道(再归因) | ReAttributeChannel | 再归因后的渠道 |
| 版位(再归因) | ReAttributeCSite | 再归因后的版位 |
| 再归因时间(再归因) | ReAttributeCreateTime | 进行再归因的时间 |
| 推广活动(再归因) | ReAttributeTurboPromotedObjectID | 再归因后的推广活动 |
| 累计再归因次数 | ReAttributeRetargetingCount | 用户累计被再归因的次数 |
## ASA指标 [#asa]
| 中文名 | 字段名 | 说明 |
| ----- | ------------------ | --------------------------- |
| 关键词ID | asaKeywordId | Apple Search Ads中的关键词唯一标识符 |
| 转化类型 | asaConversionType | 用户在Apple Search Ads中的转化行为类型 |
| 地区 | asaCountryOrRegion | Apple Search Ads广告投放的地区或国家 |
## 巨量星图指标 [#bytedance-star]
| 中文名 | 字段名 | 说明 |
| ------ | -------------------------- | ---------------------------------- |
| 星图计划ID | bytedanceStarDemandId | 营销活动计划ID，一次营销活动生成一个唯一ID |
| 星图视频ID | bytedanceStarItemId | 视频内容ID，与星图平台前端video\_url中展现的视频id一致 |
| 达人信息 | bytedanceStarAwemeAuthorId | 达人抖音uid，可在达人广场手动查昵称 |
| 星图订单ID | bytedanceStarOrderId | 星图平台订单ID（已下线） |
## 素材指标 [#material]
| 中文名 | 字段名 | 说明 |
| ----------- | ------------- | -------------------- |
| 图片素材ID | bytedanceMid1 | 广告中使用的图片素材唯一标识符 |
| 标题素材ID | bytedanceMid2 | 广告中使用的标题素材唯一标识符 |
| 视频素材ID | bytedanceMid3 | 广告中使用的视频素材唯一标识符 |
| 试玩素材ID | bytedanceMid4 | 广告中使用的试玩素材唯一标识符 |
| 落地页ID | bytedanceMid5 | 广告落地页的唯一标识符 |
| 安卓下载详情页ID | bytedanceMid6 | 安卓应用下载详情页的唯一标识符 |
| 抖音小游戏试玩素材ID | bytedanceMid7 | 抖音小游戏广告中使用的试玩素材唯一标识符 |
| 抖音小游戏直玩素材ID | bytedanceMid8 | 抖音小游戏广告中使用的直玩素材唯一标识符 |
## 素材再归因指标 [#material-re-attribute]
| 中文名 | 字段名 | 说明 |
| ---------------- | ------------------------ | ---------------- |
| 图片素材ID(再归因) | ReAttributeBytedanceMid1 | 再归因后的图片素材ID |
| 标题素材ID(再归因) | ReAttributeBytedanceMid2 | 再归因后的标题素材ID |
| 视频素材ID(再归因) | ReAttributeBytedanceMid3 | 再归因后的视频素材ID |
| 试玩素材ID(再归因) | ReAttributeBytedanceMid4 | 再归因后的试玩素材ID |
| 落地页ID(再归因) | ReAttributeBytedanceMid5 | 再归因后的落地页ID |
| 安卓下载详情页ID(再归因) | ReAttributeBytedanceMid6 | 再归因后的安卓下载详情页ID |
| 抖音小游戏试玩素材ID(再归因) | ReAttributeBytedanceMid7 | 再归因后的抖音小游戏试玩素材ID |
| 抖音小游戏直玩素材ID(再归因) | ReAttributeBytedanceMid8 | 再归因后的抖音小游戏直玩素材ID |
## 用户属性 [#user-property]
| 中文名 | 字段名 | 说明 |
| ------------------- | ------------------------------------- | --------------------- |
| 数数#account\_id | user$ta\_account\_id | 数数用户账号ID |
| 数数#distinct\_id | user$ta\_distinct\_id | 数数用户唯一标识符 |
| 激励视频广告平均eCPM | user$reward\_ad\_avg\_ecpm | 激励视频广告平均千次展示收益 |
| 激励视频广告次数 | user$reward\_ad\_count | 用户观看激励视频广告的总次数 |
| 激励视频广告LTV | user$reward\_ad\_ltv | 激励视频广告生命周期价值 |
| 激励视频广告LTV（24h） | user$reward\_ad\_24h\_ltv | 24小时内激励视频广告生命周期价值 |
| 激励视频广告最高eCPM | user$reward\_ad\_max\_ecpm | 激励视频广告最高千次展示收益 |
| 开屏广告平均eCPM | user$splash\_ad\_avg\_ecpm | 开屏广告平均千次展示收益 |
| 开屏广告平均eCPM（24h） | user$splash\_ad\_24h\_avg\_ecpm | 24小时内开屏广告平均千次展示收益 |
| 开屏广告观看次数 | user$splash\_ad\_count | 用户观看开屏广告的总次数 |
| 开屏广告LTV | user$splash\_ad\_ltv | 开屏广告生命周期价值 |
| 开屏广告LTV（24h） | user$splash\_ad\_24h\_ltv | 24小时内开屏广告生命周期价值 |
| 开屏广告最高eCPM | user$splash\_ad\_max\_ecpm | 开屏广告最高千次展示收益 |
| 开屏广告24小时LTV | user$splash\_ad\_24\_ltv | 24小时开屏广告生命周期价值 |
| 开屏广告24小时观看次数 | user$splash\_24h\_count | 24小时内开屏广告观看次数 |
| 激励视频广告平均eCPM（24h） | user$reward\_ad\_24h\_avg\_ecpm | 24小时内激励视频广告平均千次展示收益 |
| 激励视频广告观看次数（24h） | user$reward\_24h\_count | 24小时内激励视频广告观看次数 |
| 回流次数 | user$reactive\_count | 用户回流次数统计 |
| 省份 | user$province | 用户所在省份 |
| 单次付费最大金额(分) | user$pay\_max\_amount | 用户单次付费最大金额（单位：分） |
| 付费次数 | user$pay\_count | 用户付费总次数 |
| 付费总额(分) | user$pay\_amount\_sum | 用户累计付费总额（单位：分） |
| 操作系统 | user$os | 用户使用的操作系统 |
| 原生广告最高eCPM | user$native\_ad\_max\_ecpm | 原生广告最高千次展示收益 |
| 原生广告LTV | user$native\_ad\_ltv | 原生广告生命周期价值 |
| 原生广告观看次数 | user$native\_ad\_count | 用户观看原生广告的总次数 |
| 原生广告平均eCPM | user$native\_ad\_avg\_ecpm | 原生广告平均千次展示收益 |
| 原生广告LTV（24h） | user$native\_ad\_24h\_ltv | 24小时内原生广告生命周期价值 |
| 原生广告平均eCPM（24h） | user$native\_ad\_24h\_avg\_ecpm | 24小时内原生广告平均千次展示收益 |
| 原生广告观看次数（24h） | user$native\_24h\_count | 24小时内原生广告观看次数 |
| 设备型号 | user$model | 用户使用的设备型号 |
| 设备制造商 | user$manufacturer | 用户设备的制造商 |
| 最近一次回流时间 | user$latest\_reactive\_time | 用户最近一次回流的时间 |
| 最近一次归因媒体 | user$latest\_attribution\_company | 用户最近一次归因的媒体 |
| 最近一次归因时间 | user$latest\_attribution\_time | 用户最近一次归因的时间 |
| 归因次数 | user$attribution\_count | 用户累计被归因的次数 |
| 插屏广告最高eCPM | user$interstitial\_ad\_max\_ecpm | 插屏广告最高千次展示收益 |
| 插屏广告LTV | user$interstitial\_ad\_ltv | 插屏广告生命周期价值 |
| 插屏广告观看次数 | user$interstitial\_ad\_count | 用户观看插屏广告的总次数 |
| 插屏广告平均eCPM | user$interstitial\_ad\_avg\_ecpm | 插屏广告平均千次展示收益 |
| 插屏广告24小时LTV | user$interstitial\_ad\_24h\_ltv | 24小时内插屏广告生命周期价值 |
| 插屏广告平均eCPM（24h） | user$interstitial\_ad\_24h\_avg\_ecpm | 24小时内插屏广告平均千次展示收益 |
| 插屏广告24小时观看次数 | user$interstitial\_24h\_count | 24小时内插屏广告观看次数 |
| 首次付费时间 | user$first\_pay\_time | 用户首次付费的时间 |
| 首次付费支付项目 | user$first\_pay\_reason | 用户首次付费的支付项目 |
| 首次付费支付方式 | user$first\_pay\_method | 用户首次付费的支付方式 |
| 国家 | user$country | 用户所在国家 |
| 点击渠道 | user$click\_channel | 用户点击的渠道来源 |
| 城市 | user$city | 用户所在城市 |
| 客户端渠道 | user$channel | 用户使用的客户端渠道 |
| Banner广告最高eCPM | user$banner\_ad\_max\_ecpm | Banner广告最高千次展示收益 |
| Banner广告LTV | user$banner\_ad\_ltv | Banner广告生命周期价值 |
| Banner广告观看次数 | user$banner\_ad\_count | 用户观看Banner广告的总次数 |
| Banner广告平均eCPM | user$banner\_ad\_avg\_ecpm | Banner广告平均千次展示收益 |
| Banner广告24小时LTV | user$banner\_ad\_24h\_ltv | 24小时内Banner广告生命周期价值 |
| Banner广告平均eCPM（24h） | user$banner\_ad\_24h\_avg\_ecpm | 24小时内Banner广告平均千次展示收益 |
| Banner广告观看次数（24h） | user$banner\_24h\_count | 24小时内Banner广告观看次数 |
| 广告最高eCPM | user$ad\_max\_ecpm | 广告最高千次展示收益 |
| 广告LTV | user$ad\_ltv | 广告生命周期价值 |
| 广告观看次数 | user$ad\_count | 用户观看广告的总次数 |
| 广告平均eCPM | user$ad\_avg\_ecpm | 广告平均千次展示收益 |
| 广告LTV（24h） | user$ad\_24h\_ltv | 24小时内广告生命周期价值 |
| 广告观看次数（24h） | user$ad\_24h\_count | 24小时内广告观看次数 |
| 广告平均eCPM（24h） | user$ad\_24h\_avg\_ecpm | 24小时内广告平均千次展示收益 |
## 设备信息 [#device-info]
| 中文名 | 字段名 | 说明 |
| --------- | ---------------- | --------- |
| IDFA | Idfa | iOS广告标识符 |
| IDFV | Idfv | iOS供应商标识符 |
| CAID1 | Caid1 | 中国广告标识符1 |
| CAID2 | Caid2 | 中国广告标识符2 |
| OAID | Oaid | 安卓广告标识符 |
| IMEI | Imei | 国际移动设备识别码 |
| AndroidId | AndroidId | 安卓设备标识符 |
| Android版本 | Android\_Version | 安卓系统版本号 |
| API版本 | Api\_Version | 系统API版本号 |
| 操作系统版本 | Rom\_version | 设备操作系统版本 |
| 分辨率 | Aspect\_Ratio | 设备屏幕分辨率 |
| 品牌 | Phone\_Brand | 手机品牌 |
| 机型 | Phone\_Model | 手机型号 |
| 系统 | OS | 操作系统类型 |
# 用户订单报表指标
> 来源：https://help.gravity-engine.com/docs/appendix/user-order-report-metrics
> 列出用户订单报表的字段名、中文名称与指标含义，供查询接口接入和付费数据核对使用。
| 中文名 | 字段名 | 说明 |
| ------------------- | -------------------------------------- | -------------------------------- |
| **用户基础指标** | | |
| 注册时间 | CreateTime | 用户注册的时间 |
| 广告点击时间 | AdClickTime | 用户点击广告的具体时间 |
| 客户ID | ClientID | 用户的唯一标识符 |
| 媒体平台 | AdPlatform | 广告投放的媒体平台 |
| 渠道 | Channel | 用户来源渠道 |
| 客户端版本 | Version | 客户端的版本号 |
| 推广活动 | TurboPromotedObjectID | 推广活动的唯一标识符 |
| 用户名 | Name | 用户的名称 |
| openid | WXOpenID | 小游戏用户的openid |
| 广告账户ID | AdvertiserID | 广告主的账户ID |
| 计划ID | AdGid | 广告计划的唯一标识符 |
| 广告ID | AdAid | 广告的唯一标识符 |
| 创意ID | AdCid | 广告创意的唯一标识符 |
| **再归因指标** | | |
| 广告ID(再归因) | ReAttributeAdAid | 再归因后的广告ID |
| 创意ID(再归因) | ReAttributeAdCid | 再归因后的创意ID |
| 计划ID(再归因) | ReAttributeAdGid | 再归因后的计划ID |
| 广告点击时间(再归因) | ReAttributeAdClickTime | 再归因后的广告点击时间 |
| 媒体平台(再归因) | ReAttributeAdPlatform | 再归因后的媒体平台 |
| 广告账户ID(再归因) | ReAttributeAdvertiserID | 再归因后的广告账户ID |
| 渠道(再归因) | ReAttributeChannel | 再归因后的渠道 |
| 版位(再归因) | ReAttributeCSite | 再归因后的版位 |
| 再归因时间(再归因) | ReAttributeCreateTime | 进行再归因的时间 |
| 推广活动(再归因) | ReAttributeTurboPromotedObjectID | 再归因后的推广活动 |
| 累计再归因次数 | ReAttributeRetargetingCount | 用户累计被再归因的次数 |
| **付费指标** | | |
| 事件发生时间 | PayEventTime | 支付事件发生的时间戳 |
| 实际回传时间 | ModifyTime | 数据实际回传到服务器的时间 |
| 金额 | Amount | 支付金额（单位：分） |
| 当前付费次数 | PayCount | 用户累计付费次数 |
| 实际回传金额 | BackAmount | 实际回传的支付金额 |
| 订单状态 | Status | 订单的当前状态 |
| 条件映射状态 | PassStatus | 支付条件映射状态 |
| 是否虚拟付费 | IsVirtual | 标记是否为虚拟付费 |
| 订单ID | TraceID | 订单的唯一标识符 |
| 支付方式 | event$pay\_method | 用户使用的支付方式 |
| 支付项目 | event$pay\_reason | 支付的具体项目或原因 |
| 手机品牌 | event$brand | 用户手机品牌信息 |
| 操作系统 | event$os | 用户设备操作系统 |
| 网络状态 | event$network\_type | 支付时的网络类型 |
| IP | event$ip | 用户支付时的IP地址 |
| 城市 | event$city | 用户所在城市 |
| 浏览器类型 | event$browser | 用户使用的浏览器类型 |
| SDK回传状态 | $sdk\_postback | SDK数据回传状态标识 |
| **用户属性** | | |
| 数数#account\_id | user$ta\_account\_id | 数数用户账号ID |
| 数数#distinct\_id | user$ta\_distinct\_id | 数数用户唯一标识符 |
| 激励视频广告平均eCPM | user$reward\_ad\_avg\_ecpm | 激励视频广告平均千次展示收益 |
| 激励视频广告次数 | user$reward\_ad\_count | 用户观看激励视频广告的总次数 |
| 激励视频广告LTV | user$reward\_ad\_ltv | 激励视频广告生命周期价值 |
| 激励视频广告LTV（24h） | user$reward\_ad\_24h\_ltv | 24小时内激励视频广告生命周期价值 |
| 激励视频广告最高eCPM | user$reward\_ad\_max\_ecpm | 激励视频广告最高千次展示收益 |
| 开屏广告平均eCPM | user$splash\_ad\_avg\_ecpm | 开屏广告平均千次展示收益 |
| 开屏广告平均eCPM（24h） | user$splash\_ad\_24h\_avg\_ecpm | 24小时内开屏广告平均千次展示收益 |
| 开屏广告观看次数 | user$splash\_ad\_count | 用户观看开屏广告的总次数 |
| 开屏广告LTV | user$splash\_ad\_ltv | 开屏广告生命周期价值 |
| 开屏广告LTV（24h） | user$splash\_ad\_24h\_ltv | 24小时内开屏广告生命周期价值 |
| 开屏广告最高eCPM | user$splash\_ad\_max\_ecpm | 开屏广告最高千次展示收益 |
| 开屏广告24小时LTV | user$splash\_ad\_24\_ltv | 24小时开屏广告生命周期价值 |
| 开屏广告24小时观看次数 | user$splash\_24h\_count | 24小时内开屏广告观看次数 |
| 激励视频广告平均eCPM（24h） | user$reward\_ad\_24h\_avg\_ecpm | 24小时内激励视频广告平均千次展示收益 |
| 激励视频广告观看次数（24h） | user$reward\_24h\_count | 24小时内激励视频广告观看次数 |
| 回流次数 | user$reactive\_count | 用户回流次数统计 |
| 省份 | user$province | 用户所在省份 |
| 单次付费最大金额(分) | user$pay\_max\_amount | 用户单次付费最大金额（单位：分） |
| 付费次数 | user$pay\_count | 用户付费总次数 |
| 付费总额(分) | user$pay\_amount\_sum | 用户累计付费总额（单位：分） |
| 操作系统 | user$os | 用户使用的操作系统 |
| 原生广告最高eCPM | user$native\_ad\_max\_ecpm | 原生广告最高千次展示收益 |
| 原生广告LTV | user$native\_ad\_ltv | 原生广告生命周期价值 |
| 原生广告观看次数 | user$native\_ad\_count | 用户观看原生广告的总次数 |
| 原生广告平均eCPM | user$native\_ad\_avg\_ecpm | 原生广告平均千次展示收益 |
| 原生广告LTV（24h） | user$native\_ad\_24h\_ltv | 24小时内原生广告生命周期价值 |
| 原生广告平均eCPM（24h） | user$native\_ad\_24h\_avg\_ecpm | 24小时内原生广告平均千次展示收益 |
| 原生广告观看次数（24h） | user$native\_24h\_count | 24小时内原生广告观看次数 |
| 设备型号 | user$model | 用户使用的设备型号 |
| 设备制造商 | user$manufacturer | 用户设备的制造商 |
| 最近一次回流时间 | user$latest\_reactive\_time | 用户最近一次回流的时间 |
| 插屏广告最高eCPM | user$interstitial\_ad\_max\_ecpm | 插屏广告最高千次展示收益 |
| 插屏广告LTV | user$interstitial\_ad\_ltv | 插屏广告生命周期价值 |
| 插屏广告观看次数 | user$interstitial\_ad\_count | 用户观看插屏广告的总次数 |
| 插屏广告平均eCPM | user$interstitial\_ad\_avg\_ecpm | 插屏广告平均千次展示收益 |
| 插屏广告24小时LTV | user$interstitial\_ad\_24h\_ltv | 24小时内插屏广告生命周期价值 |
| 插屏广告平均eCPM（24h） | user$interstitial\_ad\_24h\_avg\_ecpm | 24小时内插屏广告平均千次展示收益 |
| 插屏广告24小时观看次数 | user$interstitial\_24h\_count | 24小时内插屏广告观看次数 |
| 首次付费时间 | user$first\_pay\_time | 用户首次付费的时间 |
| 首次付费支付项目 | user$first\_pay\_reason | 用户首次付费的支付项目 |
| 首次付费支付方式 | user$first\_pay\_method | 用户首次付费的支付方式 |
| 国家 | user$country | 用户所在国家 |
| 点击渠道 | user$click\_channel | 用户点击的渠道来源 |
| 城市 | user$city | 用户所在城市 |
| 客户端渠道 | user$channel | 用户使用的客户端渠道 |
| Banner广告最高eCPM | user$banner\_ad\_max\_ecpm | Banner广告最高千次展示收益 |
| Banner广告LTV | user$banner\_ad\_ltv | Banner广告生命周期价值 |
| Banner广告观看次数 | user$banner\_ad\_count | 用户观看Banner广告的总次数 |
| Banner广告平均eCPM | user$banner\_ad\_avg\_ecpm | Banner广告平均千次展示收益 |
| Banner广告24小时LTV | user$banner\_ad\_24h\_ltv | 24小时内Banner广告生命周期价值 |
| Banner广告平均eCPM（24h） | user$banner\_ad\_24h\_avg\_ecpm | 24小时内Banner广告平均千次展示收益 |
| Banner广告观看次数（24h） | user$banner\_24h\_count | 24小时内Banner广告观看次数 |
| 广告最高eCPM | user$ad\_max\_ecpm | 广告最高千次展示收益 |
| 广告LTV | user$ad\_ltv | 广告生命周期价值 |
| 广告观看次数 | user$ad\_count | 用户观看广告的总次数 |
| 广告平均eCPM | user$ad\_avg\_ecpm | 广告平均千次展示收益 |
| 广告LTV（24h） | user$ad\_24h\_ltv | 24小时内广告生命周期价值 |
| 广告观看次数（24h） | user$ad\_24h\_count | 24小时内广告观看次数 |
| 广告平均eCPM（24h） | user$ad\_24h\_avg\_ecpm | 24小时内广告平均千次展示收益 |
| **外部归因** | | |
| 外部归因\_接收时间(再归因) | user$ea\_receive\_time\_reattribute | 从微信广告平台接收到再归因结果的时间 |
| 外部归因\_接收时间 | user$ea\_receive\_time | 从微信广告平台接收到首次归因结果的时间 |
| 外部归因\_广告曝光时间(再归因) | user$ea\_impression\_time\_reattribute | 触发再归因的广告被曝光的时间 |
| 外部归因\_广告曝光时间 | user$ea\_impression\_time | 触发首次归因的广告被曝光的时间 |
| 外部再归因ID | user$ea\_id\_reattribute | 微信广告平台为再归因事件生成的唯一标识 |
| 外部归因ID | user$ea\_id | 微信广告平台为首次归因事件生成的唯一标识 |
| 外部归因\_计划ID | user$ea\_gid\_reattribute | 触发再归因的广告计划ID |
| 外部归因\_计划ID | user$ea\_gid | 触发首次归因的广告计划ID |
| 外部归因\_累计再归因次数 | user$ea\_cum\_reattribute | 该用户累计发生再归因的次数 |
| 外部归因\_广告点击时间(再归因) | user$ea\_click\_time\_reattribute | 触发再归因的广告被点击的时间 |
| 外部归因\_广告点击时间 | user$ea\_click\_time | 触发首次归因的广告被点击的时间 |
| 外部归因\_媒体平台(再归因) | user$ea\_click\_company\_reattribute | 触发再归因的广告来源媒体平台 |
| 外部归因\_媒体平台 | user$ea\_click\_company | 触发首次归因的广告来源媒体平台 |
| 外部归因\_创意ID(再归因) | user$ea\_cid\_reattribute | 触发再归因的广告创意ID |
| 外部归因\_创意ID | user$ea\_cid | 触发首次归因的广告创意ID |
| 外部归因\_广告ID(再归因) | user$ea\_aid\_reattribute | 触发再归因的广告单元ID |
| 外部归因\_广告ID | user$ea\_aid | 触发首次归因的广告单元ID |
| 外部归因\_广告账户ID(再归因) | user$ea\_advertiser\_id\_reattribute | 触发再归因的广告主的账户ID |
| 外部归因\_广告账户ID | user$ea\_advertiser\_id | 触发首次归因的广告主的账户ID |
| **事件公共属性** | | |
| 应用唯一标识 | event$app\_id | 应用的唯一标识 |
| App的应用的版本 | event$app\_version | App的应用版本 |
| 设备品牌 | event$brand | 用户设备的品牌（如：Apple, Huawei） |
| 浏览器名称 | event$browser | 用户使用的浏览器名称 |
| 浏览器版本 | event$browser\_version | 用户使用的浏览器版本 |
| 运营商名称 | event$carrier | 用户设备SIM卡的运营商信息 |
| 城市 | event$city | 用户所在地的城市信息 |
| 国家 | event$country | 用户所在地的国家信息 |
| 设备ID | event$device\_id | 经过处理的匿名设备标识符 |
| ip | event$ip | 用户的IP地址 |
| SDK技术框架 | event$lib | 埋点使用的SDK技术框架（如：iOS, Android, JS） |
| 引力引擎SDK版本 | event$lib\_version | 引力引擎SDK的版本号 |
| 设备制造商 | event$manufacturer | 设备的制造商 |
| 设备型号 | event$model | 设备的具体型号 |
| 网络类型 | event$network\_type | 用户当前的网络环境（如：Wi-Fi， 4G） |
| 操作系统 | event$os | 用户设备的操作系统（如：iOS， Android） |
| 操作系统版本 | event$os\_version | 操作系统的具体版本号 |
| 省份 | event$province | 用户所在地的省份信息 |
| 启动场景 | event$scene | 应用被启动的场景 |
| 屏幕高度 | event$screen\_height | 设备屏幕的高度（像素） |
| 屏幕方向 | event$screen\_orientation | 当前屏幕的显示方向（横屏/竖屏） |
| 屏幕宽度 | event$screen\_width | 设备屏幕的宽度（像素） |
| 系统语言设置 | event$system\_language | 设备系统设置的语言 |
| 时区偏移量 | event$timezone\_offset | 用户所在时区相对于UTC的偏移量（分钟） |
| 当日首次启动场景 | event$today\_first\_scene | 用户当日首次启动应用的场景 |
| 追溯ID | event$trace\_id | 用于关联和追踪单个用户会话或事件的唯一标识 |
# 归因回调
> 来源：https://help.gravity-engine.com/docs/attribution/attribution-callback
> 说明归因成功后如何将匹配结果回调至业务服务器，包括回调地址、宏参数与数据处理方式。
当在**引力归因引擎**中完成一次用户归因匹配成功事件时，引力引擎会通过**归因回调链接**通知到客户自己的后端系统，客户可以通过配置接口 API 中的**宏参数**，来感知此次归因匹配成功事件，以便做后续的数据分析。
> **注意**
> **引力引擎的归因回调链接不是媒体平台的广告监测链接！请不要混淆这两个链接！**
## 支持的宏参数 [#支持的宏参数]
| 宏参数 | 备注 | 示例 |
| -------------------------------- | ------------------------------------------------------------------------------------------- | ----------------------------------------------------- |
| `__TURBO_APP_ID__` | 引力 APPID | 18760451 |
| `__TURBO_PROMOTED_OBJECT_ID__` | 推广活动 ID | duteQV0jSIsvvfaw |
| `__TURBO_PROMOTED_OBJECT_NAME__` | 推广活动名称 | 默认推广活动 |
| `__TURBO_CLICK_TIME__` | 点击时间(毫秒时间戳) | 1669867980827 |
| `__TURBO_ACTIVE_TIME__` | 归因激活时间(毫秒时间戳) | 1669867980827 |
| `__USER_INITIALIZE_TIME__` | 用户初始化时间(毫秒时间戳) | 1669867980827 |
| `__CHANNEL__` | 用户渠道 | 用户实际渠道 |
| `__CLICK_CHANNEL__` | 点击渠道 | 点击监测链接中配置的 channel 字段 |
| `__WX_OPENID__` | 微信/抖音 `open_id` | o2URF5TjZdLG\_LnSH4Vf67Knx |
| `__CLIENT_ID__` | 用户 `client_id` | gXrXc69C |
| `__USER_NAME__` | 用户名 | |
| `__AD_PLATFORM__` | 媒体平台 | 允许的枚举值请参考：[广告平台枚举值](/docs/appendix/ad-platform-enums) |
| `__ADVERTISER_ID__` | 广告主账户 ID | 19489328734 |
| `__CAMPAIGN_ID__` | 广告计划 ID | 2329843543 |
| `__CAMPAIGN_NAME__` | 广告计划名称 | 测试计划 |
| `__AD_ID__` | 广告 ID | 232456464 |
| `__AD_NAME__` | 广告名称 | 测试广告 |
| `__CREATIVE_ID__` | 广告创意 ID | 23495848545 |
| `__CREATIVE_NAME__` | 广告创意名称 | 测试创意 |
| `__PROJECT_ID__` | 巨量引擎项目 ID（请使用 `__CAMPAIGN_ID__` 替代，后续将停止下发） | ID: 7074140945750507528 |
| `__PROMOTION_ID__` | 巨量引擎广告 ID（请使用 `__AD_ID__` 替代，后续将停止下发） | ID: 7074806092097929253 |
| `__MID1__` | 巨量引擎图片素材宏参数（下发原始素材 ID） | |
| `__MID2__` | 巨量引擎标题素材宏参数（下发原始素材 ID） | |
| `__MID3__` | 巨量引擎视频素材宏参数（下发原始素材 ID） | |
| `__MID4__` | 巨量引擎搭配试玩素材宏参数（下发原始素材 ID） | |
| `__MID5__` | 巨量引擎落地页素材宏参数（下发原始素材 ID） | |
| `__MID6__` | 巨量引擎安卓下载详情页素材宏参数（下发原始素材 ID） | |
| `__MID7__` | 巨量引擎抖音小游戏试玩素材宏参数（下发原始素材 ID） | |
| `__MID8__` | 巨量引擎抖音小游戏直玩素材宏参数（下发原始素材 ID） | |
| `__CLICK_IP__` | 点击 IP | 192.174.3.2 |
| `__ACTIVE_IP__` | 激活 IP | 192.174.3.2 |
| `__CSITE__` | 广告投放版位 | |
| `__OS_TYPE__` | 设备类型 | ios/android |
| `__ROM__` | ROM | miui |
| `__DEVICE_BRAND__` | 设备品牌 | xiaomi |
| `__DEVICE_MODEL__` | 设备型号 | mi 9 |
| `__IMEI__` | imei | |
| `__OAID__` | OAID | |
| `__CAID1_MD5__` | 当前用户中广协 ID 的 md5 hash（20230330 版本） | |
| `__CAID2_MD5__` | 当前用户中广协 ID 的 md5 hash（20220111/20250325 版本） | |
| `__ANDROID_ID__` | Android id | |
| `__MAC__` | MAC 地址 | |
| `__ANDROID_VERSION__` | Android api version | |
| `__IDFA__` | IDFA | |
| `__IDFV__` | IDFV | |
| `__ASA_KEYWORD_ID__` | ASA 关键词 ID | |
| `__ASA_CONVERSION_TYPE__` | ASA 转化类型 | |
| `__ASA_COUNTRY_OR_REGION__` | ASA 地区 | |
| `__ASA_CLAIM_TYPE__` | ASA 归因类型 | 枚举值：Click/Impression |
| `__STAR_ITEM_ID__` | 巨量星图视频 ID | |
| `__STAR_LIVE_ITEM_ID__` | 巨量星图直播场景 `room_id` | |
| `__STAR_AWEME_ITEM_ID__` | 巨量星图短视频场景 `video_id` | |
| `__STAR_GAME_CHANNEL__` | 巨量星图场景枚举 | 1 - 直播，2 - 短视频，3 - 内容社区 |
| `__STAR_ORDER_ID__` | 巨量星图任务 ID | |
| `__STAR_DEMAND_ID__` | 巨量星图计划 ID | |
| `__STAR_AWEME_AUTHOR_ID__` | 巨量星图抖音达人的 `uid` | |
| `__CUSTOM_PARAMS__` | 自定义参数，您可以在引力提供的监测链接后使用 `custom_params` 作为 key，自定义自己的参数，引力会直接透传 | |
| `__EXTRA_PARAMS__` | 媒体监测链接中的其他参数，会拼接成 JSON 字符串，例如 `{"key1":"value1","key2":"value2"}`，放在 `__EXTRA_PARAMS__` 宏参中 | |
| `__TENCENT_CLICK_ID__` | 腾讯点击 ID，只在归因为腾讯的用户下有值 | |
| `__MATERIAL_ID__` | 媒体素材 ID | |
| `__RETARGETING_COUNT__` | 再归因次数（再归因为自然量时不统计） | 当前用户执行过的再归因次数，首次归因为 0，第一次再归因为 1，依次类推 |
| `__LATEST_RETARGETING_TIME__` | 最新再归因时间（毫秒时间戳，再归因为自然量时不统计） | 1669867980827 |
| `__OPERATOR_NAME__` | 优化师信息 | 当前用户对应推广活动所绑定的优化师信息，例如（张三-1） |
| `__LTS_ATTRIBUTION_BUNDLE_ID__` | 最近一次归因的应用包名 | 例如：com.gravity.test |
| `__RTA_TRACE_ID__` | RTA 请求唯一标识 | |
| `__RTA_CPC_BID__` | RTA CPC 出价 | |
| `__RTA_EXP_ID__` | 实验分桶 ID | |
| `__RTA_USER_WEIGHT__` | 用户竞争力等级 | |
| `__RTA_VALID_FEATURES__` | 功能状态码 | |
| `__RTA_CPA_PRICE__` | RTA CPA 出价 | |
| `__RTA_USER_WEIGHT_FACTOR__` | 用户竞争力加权系数 | |
| `__RTA_DSP_TAG__` | 自定义实验分桶(数字) | |
| `__RTA_OUT_TARGET_ID__` | 策略 ID | |
## 使用方法 [#使用方法]
例如：您目前只关心在发生归因匹配成功时，对应用户的广告组 ID、广告计划 ID、手机系统，则您只需要将 `__CAMPAIGN_ID__`、`__AD_ID__`、`__OS_TYPE__` 三个宏参数加入到后端链接中。假设您的域名是 [https://your.domain.com、接口是](https://your.domain.com、接口是) `track`，则您配置的归因回调链接可能是这样：
```text
https://your.domain.com/track?campaign_id=__CAMPAIGN_ID__&ad_id=__AD_ID__&os_type=__OS_TYPE__
```
在发生归因匹配成功事件时，引力引擎会替换里面的宏参数，并发起 **GET** 请求这个链接，具体需要哪些参数，您可以自行根据需求定义。
## 用户属性回调 [#用户属性回调]
如果您需要回调用户属性，可以通过 `__GRAVITY_用户属性__` 的方式进行配置。例如需要回调 `$latest_attribution_company` 这个用户属性，可以配置成 `__GRAVITY_$LATEST_ATTRIBUTION_COMPANY__`。假设您的域名是 [https://your.domain.com、接口是](https://your.domain.com、接口是) `track`，则您配置的归因回调链接可能是这样：
```text
https://your.domain.com/track?latest_attribution_company=__GRAVITY_$LATEST_ATTRIBUTION_COMPANY__
```
## 兜底回调链接 [#兜底回调链接]
为了避免每个推广活动都需要配置一遍归因回调链接，我们提供了**兜底回调链接**，在回调触发时，会优先使用推广活动下的归因回调链接，若当前推广活动没有配置，则取兜底回调链接来完成归因信息的数据回调。
您可以在[引力后台-设置-应用管理-配置](https://web.gravity-engine.com/#/manage/appmanage)中添加兜底回调链接。
# 获取设备ID
> 来源：https://help.gravity-engine.com/docs/attribution/device-id
> 说明归因联调阶段如何获取 Android OAID 与 iOS IDFA，并将测试设备标识用于数据对接验证。
**文档目的**：本文档旨在帮助客户在联调测试阶段，快速获取测试设备的唯一标识符（OAID/IDFA），并提供给引力运营团队，以顺利完成数据对接的验证工作。
**阅读对象**：正在进行引力平台 SDK 接入联调测试的客户/运营人员。
## 一、联调准备工作核心目标 [#一联调准备工作核心目标]
在开始联调前，您需要在一台**真实的测试手机**上，获取其设备标识符，并将此 ID 提供给引力的运营人员。
* 如果您使用 **Android 手机**进行测试 → 需要获取 **OAID/AndroidID**
* 如果您使用 **Harmony 手机**进行测试 → 需要获取 **OAID/ODID（AndroidID）**
* 如果您使用 **iPhone** 进行测试 → 需要获取 **IDFA**
**请注意**：此流程**仅用于联调测试**，正式环境中 SDK 会自动完成采集，无需手动操作。
为保证获取方式的稳定性和准确性，Android 端推荐使用我们提供的专用工具；Harmony 端请直接通过系统设置查看。
## 二、Android 测试机获取 OAID/AndroidID 指南 [#二android-测试机获取-oaidandroidid-指南]
**推荐方案：使用引力平台官方推荐的测试工具**
1. **下载安装**
* 请使用**安卓测试手机**的**浏览器**访问下载链接。
* **下载链接**：[gravity-oaid-demo.apk](/docs-assets/attachments/G04JPBoP/gravity-oaid-demo.apk "gravity-oaid-demo.apk")
* 在浏览器中打开链接后，下载并安装应用。
2. **获取 OAID**
* 安装成功后，在手机桌面找到并打开应用。
* 应用启动后，点击**获取设备标识符**，页面会清晰显示本机的 **OAID/AndroidID**。
* 复制获取到的设备信息。
3. **提交信息**
* 将获取到的设备 ID 提供给与您对接的**引力平台运营人员**。
## 三、Harmony 测试机获取 OAID 指南 [#三harmony-测试机获取-oaid-指南]
请根据您设备的 HarmonyOS 版本，在系统设置中查找 OAID。
### HarmonyOS 5.0 及以上设备 [#harmonyos-50-及以上设备]
依次进入 **设置 > 隐私和安全 > 跨应用关联**，滑到底部即可查看 OAID，可长按复制。
### HarmonyOS 5.0 以下设备 [#harmonyos-50-以下设备]
请根据您的系统版本，选择对应的查找路径：
1. **HarmonyOS 4.X**：设置 > 隐私 > 跟踪管理 > 滑到底部点击“查看 OAID”，可长按复制
2. **HarmonyOS 3.X**：设置 > 隐私 > 广告与隐私 > 底部点击“查看 OAID”，可长按复制
3. **HarmonyOS 2.X**（以下两种方式任选其一）：
* 设置 > 安全和隐私 > 更多安全设置 > 匿名设备标识 > 点击“查看 OAID”
* 设置 > 隐私 > 广告与隐私 > 底部点击“查看 OAID”
4. **EMUI 9.X**：设置 > 应用 > 应用管理 > 搜索“HMS Core” > 点击右上角齿轮按钮进入“设置” > 选择“广告” > 点击“查看 OAID”
5. **其他版本**（以下两种方式任选其一）：
* 设置 > HMS Core > 广告
* 设置 > 隐私 > HMS Core > 广告
> **提示**
> 若以上方法均找不到 OAID，可先卸载 HMS Core 更新（设置 > 应用/应用和服务 > 应用管理 > HMS Core > 右上角三/四点 > 卸载更新），再按上述路径重新查找。
## 四、iOS 测试机获取 IDFA 指南 [#四ios-测试机获取-idfa-指南]
我们推荐使用`My Device ID by AppsFlyer`获取 IDFA，该方法直接、可靠。
**操作步骤：**
1. **下载安装**
* 请使用 **iPhone 测试机**打开 **App Store**。
* 在搜索框中输入 **“My Device ID by AppsFlyer”** 搜索下载并安装。
2. **获取 IDFA**
* 安装完成后，打开下载好的应用。
* 应用启动后，复制 **IDFA** 值。
3. **提交信息**
* 将复制好的 IDFA 提供给与您对接的**引力平台运营人员**。
## 五、常见问题（FAQ） [#五常见问题faq]
**Q1：为什么一定要提供 OAID/IDFA？**
A：这是联调测试的关键步骤。我们需要用您提供的 ID 在后台系统中验证数据链路是否通畅，行为数据能否正确关联到您的测试设备，从而确认 SDK 是否集成成功。
**Q2：在 iOS 上弹出了“允许追踪”的弹窗，该怎么办？**
A：请务必点击\*\*“允许”\*\*，否则将获取到无效的标识符。
**Q3：iOS 获取到的 IDFA 是 00000000-0000-0000-0000-000000000000 怎么办？**
A：在**设置 > 隐私与安全性 > 跟踪**中开启“允许 App 请求跟踪”。
**Q4：工具无法安装或打开怎么办？**
A：请先确认：
* Android 手机：请在“设置”中开启“允许来自未知来源的应用”的安装权限。
* iOS 手机：请确认设备系统版本为 iOS 9 或以上。
* 如果问题依旧，请直接联系引力运营人员。
***
**如有任何疑问，请联系您的引力平台对接运营或技术支持。**
**祝您联调顺利！**
# 事件回调
> 来源：https://help.gravity-engine.com/docs/attribution/event-callback
> 说明如何配置事件回调，在用户触发指定事件时将事件数据与归因信息发送至业务服务器。
## 一、功能概述 [#一功能概述]
事件回调功能用于当用户在你的应用内触发指定事件时，系统自动将事件数据及用户归因信息回传到你配置的服务器地址。
### 适用场景 [#适用场景]
* 实时获取用户行为事件数据
* 与自有 BI/数据系统进行打通
* 基于事件数据进行二次营销或分析
## 二、配置步骤 [#二配置步骤]
### 1. 开启事件回调开关 [#1-开启事件回调开关]
在后台应用管理页面找到[事件回调](https://web.gravity-engine.com/#/manage/appmanage)配置模块，打开开关以启用功能。
### 2. 选择回调事件 [#2-选择回调事件]
在回调事件下拉框中，选择需要监听的事件类型（如激活、付费等）。
### 3. 配置回调地址 [#3-配置回调地址]
> **注意**
> **注意：请确保该地址为可公网访问的域名，且服务稳定。**
在回调地址输入框中，填写你的服务端接收数据的 URL。
### 4. 配置回调参数（可选） [#4-配置回调参数可选]
点击新增按钮，添加回调宏参数
系统会将这些参数追加到回调请求中，方便你在服务端进行识别。
| 参数类型 | 说明 | 示例 |
| ----- | ------------------- | -------------- |
| 自定义参数 | 你自己定义的参数名 | `turbo_app_id` |
| 宏参数 | 系统预置宏参数变量，如引力 APPID | 引力 APPID |
### 5. 设置请求方式 [#5-设置请求方式]
回调方法：固定为 `POST`
### 6. 设置超时与重试 [#6-设置超时与重试]
| 配置项 | 默认值 | 说明 |
| ---- | ------- | ------------------ |
| 超时时长 | 2000 毫秒 | 服务端需在此时限内响应，否则视为超时 |
| 重试次数 | 1 次 | 请求失败后会自动重试的次数 |
## 三、签名生成 [#三签名生成]
引力在触发事件回调时，会携带签名参数，您可以考虑校验该值来避免接口被滥用，计算签名的步骤如下：
```python
import json
import hashlib
def get_sign(params: dict , access_token: str) -> str:
"""
@param params: 请求体参数
@param access_token: 引力 App 的 access_token（该参数在应用管理界面可以获取）
"""
param_list = []
for k, v in params.items():
if k == "sign":
continue
param_list.append(f"{k}={json.dumps(v,sort_keys=True)}")
param_list.sort()
sb = "&".join(param_list) + access_token
current_str = sb.replace("\"", "").replace(" ", "")
return hashlib.md5(current_str.encode("utf-8")).hexdigest()
```
## 四、回调数据结构说明 [#四回调数据结构说明]
当事件触发后，引力服务端会以 `POST` 方式向你配置的回调地址发送以下 JSON 格式数据：
### 请求体格式 [#请求体格式]
```json
{
"app_id": "your_app_id",
"client_id": "your_client_id",
"sign": "8bf4b8a9abadab70009b3f84cdd14eba",
"events": [
{
"event": "eventname",
"time": 1779439377000,
"properties": {}
}
],
"callback_params": {
"key1": "value1",
"key2": "value2"
}
}
```
### 字段说明 [#字段说明]
| 字段 | 类型 | 说明 |
| --------------------- | ------ | -------------------------------------- |
| `app_id` | string | 引力平台分配的应用 ID |
| `client_id` | string | 客户唯一标识 ID |
| `sign` | string | 签名，生成规则参考上方的签名生成 |
| `events` | array | 事件列表，可同时包含多个事件 |
| `events[].event` | string | 事件名称（如 `$UserAttribution`、`$PayEvent`） |
| `events[].time` | number | 事件发生时的毫秒级时间戳（Unix timestamp） |
| `events[].properties` | object | 事件的事件属性，根据事件类型动态变化 |
| `callback_params` | object | 你在配置界面添加的宏参数和自定义参数 |
## 五、接入示例 [#五接入示例]
### 回调请求示例 [#回调请求示例]
```bash
curl -X POST 'https://your-server.com/callback' \
-H 'Content-Type: application/json' \
-d '{
"app_id": "your_app_id",
"client_id": "your_client_id",
"sign": "8bf4b8a9abadab70009b3f84cdd14eba",
"events": [
{
"event": "eventname",
"time": 1779439377000,
"properties": {}
}
],
"callback_params": {
"key1": "value1",
"key2": "value2"
}
}'
```
### 服务端响应要求 [#服务端响应要求]
您的服务端收到回调后，应在超时时间内返回 HTTP `200` 状态码，且响应结果为 JSON 格式 `{"code":0}`，表示回调成功。若返回非 `200` 状态码、响应结果不是 JSON 格式，或请求超时，系统将按照配置的重试次数进行重试。
## 六、联调与重复请求处理 [#六联调与重复请求处理]
1. 使用测试用户触发已配置的事件，在接收端核对 `app_id`、`client_id`、`events` 及 `callback_params`，不要只检查请求是否到达。
2. 验签时使用接收的完整 JSON 请求体（排除 `sign`），按本页算法计算并与 `sign` 比较。这里使用引力应用 Access Token，不使用 OpenAPI 开发者应用 `app_key`。
3. 响应超时或失败可能触发重试，请让接收处理具备幂等性。订单事件可结合应用 ID 与实际订单号设计去重；其他事件应根据业务唯一标识设计，不能只按 ClientID 去重，否则会丢弃同一用户的不同事件。
4. 需要异步处理时，先可靠保存收到的数据，再按本页格式响应成功，后续由您的业务系统消费。不要在尚未保存时就返回成功。
回调示例中的签名和业务字段仅展示结构。自行发送联调请求时，需用测试应用凭证根据实际请求体重新计算 `sign`。
# 归因
> 来源：https://help.gravity-engine.com/docs/attribution
> Gravity Engine 归因索引，汇总归因回调、获取设备ID等主题，便于按功能进入对应的配置、接入或参考说明。
{/* Generated by scripts/generate-docs-routes.mjs. Do not edit. */}
## 目录 [#目录]
* [归因回调](/docs/attribution/attribution-callback)
* [获取设备ID](/docs/attribution/device-id)
* [联调指南](/docs/attribution/integration-testing)
* [事件回调](/docs/attribution/event-callback)
* [同步归因](/docs/attribution/synchronous-attribution)
* [再归因](/docs/attribution/reattribution)
# 联调指南
> 来源：https://help.gravity-engine.com/docs/attribution/integration-testing
> 说明归因联调前需要准备的设备标识与测试信息，以及点击、激活和归因结果的验证流程。
在开始联调前，请确保已完成 SDK 接入，并已正常采集到以下设备信息：
* Android：OAID / AndroidID
* iOS：IDFA
联调时，请创建**独立的联调专属**推广活动，使用对应的监测链接进行测试，**请勿直接使用线上正在推广的推广活动**的监测链接，以便快速定位来自具体媒体的点击下发数据。
## 联调操作顺序 [#联调操作顺序]
1. 记录测试应用 ID、SDK 版本、ClientID、设备标识类型及本次联调时间。设备标识获取方式见 [获取设备 ID](/docs/attribution/device-id)。
2. 创建独立推广活动并核对应用和媒体，将该活动的监测链接用于本次测试。
3. 按媒体的联调方式触发一次有效点击，确认引力收到对应点击记录，再启动应用并完成 SDK 初始化。
4. 在事件流中核对测试 ClientID 的事件入库，再检查归因平台、推广活动和点击时间是否符合本次测试。
5. 如需媒体回传，再核对媒体回传状态；如需业务回调，再核对业务服务端日志。三者分别验收。
重复测试前先确认测试用户是否已有归因、是否涉及再归因及窗口期，不要默认反复启动应用就会产生新的首次归因。
## 一、核心逻辑 [#一核心逻辑]
归因是指将一次**用户转化**（如激活、注册、付费）归功于某一次**广告点击**的过程。其核心逻辑如下：
1. **数据基础**
* **点击数据**：媒体（如快手、腾讯）在用户点击广告时，向下发的点击监测链接中包含设备信息。
* **激活数据**：集成在您应用中的 SDK，在用户启动应用时**采集到的设备信息**或**启动参数**。
2. **匹配规则**
* 系统将**激活数据**与**媒体下发的点击数据**进行匹配。
* 匹配时，会按照各平台预设的**标识符优先级**（见下文）进行。
* 匹配遵循**末次点击归因模型**，即转化会被归因于**最后一次有效的广告点击**。
## 二、各平台归因匹配优先级 [#二各平台归因匹配优先级]
系统按照以下优先级匹配标识符，匹配成功则归因，全部无法匹配则判定为自然量。
| 平台 | 归因优先级（从高到低） |
| ---------------- | ------------------- |
| Android 应用 / 快应用 | OAID > IMEI > IP+UA |
| iOS 应用 | IDFA / CAID > IP+UA |
| 小游戏 / 小程序 / 快游戏 | 启动参数 > OpenID |
| Web 网页 | 网页 URL 参数 |
**自然量判定**：当一次激活事件中，SDK 采集到的信息无法与任何一次广告点击数据匹配成功时，该次激活被判定为“自然量”。
## 三、常见问题排查（FAQ） [#三常见问题排查faq]
**Q1：联调时如何获取设备 ID**
A1：参考文档：[获取设备ID](/docs/attribution/device-id)
**Q2：Android 应用未采集到 OAID 或 AndroidID，首先怎么办？**
A2：请优先确认并升级 SDK 至最新版本。旧版本 SDK 可能存在兼容性问题，新版本对 OAID 等标识符的获取支持更好。
**Q3：iOS 应用未采集到 IDFA 或未弹出 ATT 弹窗？**
A3：请分步检查：
* **ATT 弹窗未弹出**：新版本 SDK 会自动调用 ATT。如果您使用的是旧版本，请检查代码是否按文档正确调用了授权方法。建议升级至最新版 SDK。
* **用户未授权**：如果用户在弹窗中选择了“要求 App 不跟踪”（或在设置中关闭了跟踪开关），则无法获取 IDFA，归因将降级至精度较低的 IP+UA 方式。
**Q4：联调时媒体有下发点击记录但未成功归因（常见于快手、腾讯等媒体），可能是什么原因？**
A4：按链路逐项核对，不要只凭“有点击”判断一定能匹配：
* 点击记录与激活是否属于同一引力应用、推广活动和测试设备；
* 媒体下发的设备 ID 或启动参数是否完整，并能与 SDK 实际采集的值对应；
* 点击与激活顺序、回溯窗口是否有效，测试用户是否已归因或进入再归因流程；
* SDK 初始化与事件采集是否正常。
仍无法定位时，提供应用 ID、推广活动 ID、ClientID、点击/激活时间（含时区）及脱敏日志给引力技术支持，按实际记录复核后重新联调。
**Q5：如果激活有 OAID，但点击只有 IP+UA，能归因成功吗？**
A5：能，但这属于降级匹配。
* **流程**：系统首先用 OAID 匹配，失败后，会自动降级并使用 IP+UA 进行新一轮匹配。若 IP+UA 信息一致，则归因成功。
* **结论**：只要在任一优先级上匹配成功，都算有效归因。但设备 ID 匹配的准确性远高于 IP+UA 匹配。
**Q6：“末次点击匹配”到底是什么意思？**
A6：归因遵循“末次点击匹配”原则，即激活将被归因于**最后一次提供了可匹配标识符的有效点击**。“有效”的关键在于点击数据中是否包含能与激活信息匹配的标识符，而非单纯的点击时间先后。
**例如**：用户先后点击了媒体 A 和媒体 B 的广告。媒体 A 下发的点击数据中包含了正确的设备 ID（如 OAID），而媒体 B 下发的数据中仅包含 IP 与 UA。即使媒体 B 的点击时间更晚，系统也会因成功匹配到媒体 A 提供的设备 ID，而将激活归因给媒体 A。
**归因成功的两个关键点是：1. 媒体下发正确的点击数据；2. 您应用的 SDK 成功采集到匹配的设备信息。** 保持 SDK 为最新版本是确保采集成功的最有效方式。
# 再归因
> 来源：https://help.gravity-engine.com/docs/attribution/reattribution
> 介绍沉默用户再次与广告互动并返回应用时的再归因机制，以及回溯、归因、沉默和回传窗口期。
沉默用户与新的广告素材互动并重新返回到您的应用时，引力引擎可对此进行再归因。本文档主要讲述关于再归因的基本介绍和常见问题解答。
## 工作原理 [#工作原理]
再归因是指沉默用户再次与广告互动后，返回到您的应用并被引力引擎分配到新的流量来源。
我们对具备以下条件的用户（使用 Client ID 来做唯一性排重）进行再归因：
* 之前已完成了引力的注册流程；
* 在指定的再归因窗口期内启动了应用；
* 在本次启动之前，用户处于沉默状态（连续非活跃状态）达到一定时长（这取决于您定义的沉默窗口期）。
如果用户满足以上所有条件，则引力引擎将对其进行再归因，并把用户之后的所有应用内活动报告给最新的归因来源。
## 窗口期 [#窗口期]
根据归因的实现逻辑，引力定义了几个重要的窗口期，窗口期在整个归因和数据回传过程中，扮演着非常重要的角色。
### 回溯窗口期 [#回溯窗口期]
指从用户注册引力时间开始，向前回溯指定时间范围内的广告点击事件，超过回溯窗口期的点击事件，将不会作为有效的归因依据。根据回溯的值不同，分为 ID 回溯和 IP 回溯两种：
* ID 回溯：通过设备 ID/微信 open ID 可以做精准匹配归因
* IP 回溯：通过 IP+UA 可以做模糊匹配归因
### 归因窗口期 [#归因窗口期]
指从用户归因完成时间算起，向后指定时间范围内，即使用户重新点击广告激活，也不进行再归因的时间窗口范围。
### 再归因窗口期 [#再归因窗口期]
用户归因窗口期结束之后的其余时间，都为再归因窗口期。
### 沉默窗口期 [#沉默窗口期]
用户连续沉默超过沉默窗口期天数之后，才能触发再归因。
### 回传窗口期 [#回传窗口期]
从用户归因完成时间算起，超过回传窗口期的事件将不再回传给媒体。
> **注意**
> 您可以通过配置归因窗口期和沉默窗口期来控制再归因逻辑。
>
> 您可以在[窗口期配置](https://web.gravity-engine.com/#/manage/backtrack)页面配置以上窗口期。
# 同步归因
> 来源：https://help.gravity-engine.com/docs/attribution/synchronous-attribution
> 说明如何在调用 initialize 接口时开启同步归因，以便立即取得当前用户的买量归因结果，并介绍归因耗时分布与常见问题。
如果客户端需要在引力完成对该用户的归因后立即拿到买量归因结果，可以在调用引力 `initialize` 接口时开启**同步归因**（具体开启方式请参考对应技术栈客户端接入文档中 `initialize` 接口的说明）。
开启之后，引力会在 `initialize` 调用中同步执行归因逻辑并阻塞返回，归因完成后才会返回结果，返回的即为最终归因结果。
> **注意**
> **开启之后极端情况会有长达 `10s` 的接口阻塞，请谨慎开启！** 仅当客户端需要立即拿到归因结果时才建议开启；如果客户端不需要，请勿开启，可改用 [归因回调链接](/docs/attribution/attribution-callback) 在服务端接收归因结果，更符合常规的数据分析需求。
开启之后，`initialize` 接口的返回结果中会包含以下归因字段：
| 字段 | 类型 | 说明 |
| -------------------------- | ------ | ---------------------------------------------------------- |
| `token` | string | 用户 clientId |
| `click_company` | string | 归因平台，允许的枚举值请参考 [广告平台枚举值](/docs/appendix/ad-platform-enums) |
| `turbo_promoted_object_id` | string | 引力推广活动 ID |
| `ad_params` | object | 在归因回调链接里拼接的参数，可参考下方「参数拼接」部分 |
示例：
```json
{
"token": "123456789",
"click_company": "bytedance",
"turbo_promoted_object_id": "af12sdafga6",
"ad_params": {}
}
```
## 同步归因耗时 [#同步归因耗时]
同步归因会阻塞 `initialize` 接口的返回，归因耗时分布如下（线上数据统计）：
| 耗时区间 | 占比 |
| ------------ | ------ |
| ≤500ms | 81.38% |
| >500ms \~ 1s | 7.01% |
| >1s \~ 2s | 6.95% |
| >2s \~ 3s | 2.28% |
| >3s \~ 5s | 1.90% |
| >5s | 0.49% |
从统计结果看，绝大多数请求（81.38%）在 500ms 内返回，约 88% 的请求在 1s 内完成，只有 0.49% 的请求超过 5s（极端情况最长可达 `10s`）。
需要注意的是，同步归因会**阻塞 `initialize` 接口的返回**：归因耗时越长，客户端初始化等待越久。**仅当客户端需要立即使用归因结果时才建议开启**；如果客户端不需要，不建议开启，可改用 [归因回调链接](/docs/attribution/attribution-callback) 在服务端接收归因结果。
## 参数拼接 [#参数拼接]
您可以在推广活动页面配置拼接参数，具体支持的参数请参考：[归因回调链接](/docs/attribution/attribution-callback)。配置的归因回调参数会拼接到返回的 `ad_params` 中。
举例：
```text
?advertiser_id=__ADVERTISER_ID__&your_ad_id=__AD_ID__&a=b
```
则这个推广活动带来的用户，返回的 `ad_params` 为：
```json
{
"advertiser_id": "123456",
"your_ad_id": "123456",
"a": "b"
}
```
## 兜底回调链接 [#兜底回调链接]
为了避免每个推广活动都需要配置一遍归因回调链接，我们提供了**兜底回调链接**，在回调触发时，会优先使用推广活动下的归因回调链接，若当前推广活动没有配置，则取兜底回调链接来完成归因信息的数据回调。
您可以在[引力后台-设置-应用管理-配置](https://web.gravity-engine.com/#/manage/appmanage)中添加兜底回调链接。
## 常见问题 [#常见问题]
1. **什么场景适合用同步归因？相比异步能缩短多少等待时间？**
1. 客户端需要立即拿到归因结果时使用。相比异步回调，同步归因省去了服务端异步回调的排队耗时和归因流程内部重试的等待，`initialize` 接口返回时即可拿到最终归因结果，预期可缩短约 `4s`。
2. **同步归因和异步归因（归因回调链接）除了回调时机，还有其它区别吗？**
1. 没有。两者只在归因完成后的回调方式、以及归因流程内部的重试上有区别，接入配置、参数与历史用户处理等均无差异。
3. **异步归因为什么会重试？重试对耗时有什么影响？**
1. 异步归因在未能归因到媒体时会重试。典型场景：腾讯广告投放的微信小游戏，用户点击广告的瞬间小游戏就被拉起并触发归因，但腾讯侧的点击检测可能存在几秒延迟，此时还无法归因到腾讯，异步模式会重试，因此增加了归因耗时。同步归因在调用 `initialize` 接口时直接返回本次归因结果，省去了这部分重试等待。
4. **`initialize` 接口返回时归因已经完成了吗？拿到的是完整结果吗？**
1. 已完成。同步归因会阻塞 `initialize` 接口，等待归因完成后才返回，返回的即为最终归因结果（即上方字段表中的全部字段）。
5. **开启同步归因会影响归因成功率吗？**
1. App 场景基本无影响：App 从点击到激活的间隔较长，不存在媒体点击检测延迟下发的问题，因此不会重试，影响极低。小游戏场景下，如果媒体侧点击下发存在延迟，可能影响归因成功率。
6. **同时收到同步归因结果和异步回调，符合预期吗？两边结果会不一致吗？**
1. 符合预期，两者结果一致，先后顺序不影响最终结果。
7. **同步结果和异步回调之间有唯一的归因事件 ID 吗？重复回调如何处理？**
1. 没有唯一 ID。重复回调建议每次都按最新一次的结果覆盖更新全部归因字段：发生再归因时部分字段会更新，避免沿用过旧的数据。
# 数据模型
> 来源：https://help.gravity-engine.com/docs/getting-started/data-model
> 解释用户、行为事件、事件属性和用户属性之间的关系，并说明如何据此设计数据采集方案。
在您开始接入之前，需要对您的项目进行理解和分析，了解您需要监控的指标和需要分析的事件，从而决定要上报什么样的数据；在开始之前，我们会先为您介绍 `Event & User` 模型。
## 1. Event & User 模型的介绍 [#1-event--user-模型的介绍]
`Event` 代表了用户的某个或一系列有意义的行为，比如用户将一个商品加入了购物车、浏览了一个视频等等，一条 `Event` 主要包含两部分信息:
* 一部分用以描述该行为如何发生，主要有行为的名字（`What`）、产生行为的用户（`Who`）以及在何时产生的（`When`）；
* 另一部分是该行为的属性，比如浏览视频的视频名称，或者付费事件当中的支付金额，这些属性是分析的主要对象，也是需要仔细斟酌的内容，我们将会在[用户属性与事件属性](/docs/getting-started/event-and-user-properties)中给出属性设置的建议。
`User` 则用以描述每名用户的最新状态与固定属性，比如用户的 `ID`、注册时间或者累计付费金额等等。通过 `User` 的属性，您可以在用户行为分析时快速筛选出您要分析的用户，比如您想分析付费用户的活跃情况，则只需要分析“累计付费金额”这一用户属性的值大于 0 的用户即可。
## 2. 整理需求 [#2-整理需求]
在理解好 `Event & User` 模型之后，您可以开始着手整理分析需求，如果您对于该流程不太熟悉的话，可以遵循下列步骤来完成需求整理：
### 2.1 明确基础的分析指标 [#21-明确基础的分析指标]
我们建议您在一开始的时候先从基础的分析指标开始着手，比如注册、登录、付费等等，如果您对这些行为没有特殊的分析需求，推荐使用我们 SDK 内提供的预置接口上传数据，如果您有特殊的分析需求，我们也推荐优先确定这些指标的取法。
### 2.2 确定追踪的事件 [#22-确定追踪的事件]
在确定好基础的分析指标之后，建议您将应用中考量每个系统、功能的重要事件转化为 `Event` 的形式。
如果您对于如何将分析需求转化为 `Event` 的形式存有疑惑，可以参考我们给出的下列建议：
* 重要的行为，推荐一个行为设定为一个 `Event`，再根据您的分析点进行属性的设置。
* 不重要的行为，比如只需要分析参与次数、参与人数的行为，您可以将多个这样的行为设置成一个 `Event`，再通过属性的方式标识具体的行为，比如设置一个 `Event` 叫次要事件，再通过一个属性事件类型来说明追踪的是哪个行为。
* 如果特别关注某些关键行为，比如付费购买行为中的一键购买，可以单独将这一行为作为一个 `Event` 进行追踪。
我们强烈建议您通过文档的形式对所有 `Event` 进行整理（比如 Excel 表格），文档当中需要包含所有 `Event` 的名称、描述，这份文档能够帮助您在设置属性以及埋点时与技术人员进行沟通，您可以参考我们为您准备的埋点模板来批量添加事件和属性：
* [批量添加事件模板](/docs-assets/attachments/4yhSMSsE/%E5%BC%95%E5%8A%9B%E5%BC%95%E6%93%8E_%E6%89%B9%E9%87%8F%E6%B7%BB%E5%8A%A0%E4%BA%8B%E4%BB%B6%E6%A8%A1%E6%9D%BF.xlsx "引力引擎_批量添加事件模板.xlsx")
* [批量添加公共属性模板](/docs-assets/attachments/4yhSMSsE/%E5%BC%95%E5%8A%9B%E5%BC%95%E6%93%8E_%E6%89%B9%E9%87%8F%E6%B7%BB%E5%8A%A0%E5%85%AC%E5%85%B1%E5%B1%9E%E6%80%A7%E6%A8%A1%E6%9D%BF.xlsx "引力引擎_批量添加公共属性模板.xlsx")
# 数据规则
> 来源：https://help.gravity-engine.com/docs/getting-started/data-rules
> 说明事件名、属性名、数据类型和取值限制等上报规则，供客户端 SDK 与服务端 API 接入前核对。
本章节将会详细介绍 引力引擎 后台的数据结构、数据类型以及数据限制。通过本章节，您将了解如何构建符合规则的数据。
如果您使用的是 `API`上传数据，需要按照本章节中的数据规则对数据进行格式处理。
## 1. 数据结构 [#1-数据结构]
引力引擎 后台接受的是符合规则的 `JSON` 数据：如果使用的是 SDK 接入，则数据将会被转化成 `JSON` 数据进行传输。如果使用 API POST 方法上传数据，则数据需要是符合规则的 `JSON` 数据。
每个事件对象表示一次用户行为，或一次用户属性操作。通过 [RESTful API](/docs/server-integration/event-collection/restful-api) 上报时，需要将事件对象放入请求体的 `event_list` 数组，并在外层传入 `client_id`；下方示例仅展示单个事件对象，不能直接作为完整请求体发送。
JSON 可以包含用于排版的空白和换行，但不支持注释。示例中的 `time` 为历史时间戳，实际调用时请替换为事件发生时的毫秒时间戳。
* 以下是行为事件数据的样例：
```json
{
"type": "track",
"event": "$AdShow",
"time": 1675927637000,
"time_free": false,
"properties": {
"$ad_type": "reward",
"$ecpm": 500,
"$adn_type": "gdt"
}
}
```
* 以下是用户属性设置的样例：
```json
{
"type": "profile",
"event": "profile_set",
"time": 1675927637000,
"time_free": false,
"properties": {
"$age": 23,
"$gender": "女"
}
}
```
从结构和功能上，可以将一条 `JSON` 数据分为两个部分：
### 1.1 数据信息部分 [#11-数据信息部分]
**properties** 的同层其他字段，组成了该条数据的基本信息，其中只包括以下几项：
* 表示事件类型的 `type` 字段，该字段决定了该条数据的类型，是用户的行为记录、还是修改用户属性的操作处理，枚举可选值为如下：
* `track` 表明为行为事件
* `profile` 表明为用户属性设置事件
* 表示事件名称的 `event` 字段
* 在行为事件数据下，`event` 字段为当前事件对应的英文名称，可以在 [元事件](https://web.gravity-engine.com/#/manage/metadata/metaEvent) 页面进行配置。
* 用户属性设置事件下， `event` 字段枚举可选值如下：
* `profile_set` ：对用户表进行操作，覆盖一个或多个用户属性，如果该属性已有值存在，覆盖先前值
* `profile_set_once` ：对用户表进行操作，初始化一个或多个用户属性，如果该属性已有值存在，则忽略本次操作
* `profile_increment` ：对用户表进行操作，为一个或多个数值型用户属性做累加计算
* `profile_number_max` ：对用户表进行操作，为一个或多个数值型用户属性做取最大值计算
* `profile_number_min` ：对用户表进行操作，为一个或多个数值型用户属性做取最小值计算
* `profile_append` ：对用户表进行操作，为用户的列表类型属性值添加元素
* `profile_uniq_append` ：对用户表进行操作，为用户的列表类型属性值添加元素，并会进行一次全列表去重（去重保证前后原有的元素顺序不变）
* `profile_unset` ：对用户表进行操作，清空该名用户的一个或多个用户属性的属性值
* `profile_delete`：对用户表进行操作，删除该名用户的所有用户属性
* 表明事件产生时间的 `time` 字段，格式必须是精确到毫秒的时间戳
* 表明是否忽略时间正确性校验的 `time_free` 字段，默认 false，建议在导入历史数据时使用，SDK 采集的实时数据不建议使用。
> **注意**
> 尽管对 User 表的操作数据也需要配置 `time` ，但对于用户属性的操作会按照后台收到数据的先后顺序进行操作。
### 1.2 数据主体部分 [#12-数据主体部分]
数据的另一部分，则是`properties`内层所包含的数据，`properties`是一个 JSON 对象，里面的数据以键值对的形式表示。如果是用户行为数据，其代表了该行为的属性及指标（相当于行为表中的字段），这些属性及指标可在分析时直接使用；如果是用户属性的操作处理，则代表需要设置的属性内容。
```json
{
"type": "track",
"event": "$AdShow",
"time": 1675927637000,
"time_free": false,
"properties": {
"$ad_type": "reward",
"$ecpm": 500,
"$adn_type": "gdt"
}
}
```
key 值为该属性的名称，类型是字符串，自定义的属性必须以字母开头，只能包含：字母（忽略大小写）、数字和下划线“\_”，且长度最大只能 50 个字符；另外还存在以 `$` 开头的属性，此类属性为预置属性，预置属性不需要特别设置，SDK 会在特定的事件发生时默认采集。
value 值为该属性的值，可以是字符串、整型、浮点、布尔、日期以及时间类型，数据类型的表示方式如下表所示：
| 引力数据类型 | 取值样例 | 取值说明 | 数据类型 |
| ------ | -------------------------------------------------- | ------------------------- | -------- |
| 文本 | "ABC" | 字符长度上限是 8192 | String |
| 整数 | 123 | 数据范围是-9E15 至 9E15 | Integer |
| 浮点数 | 1.2 | 数据范围是-9E15 至 9E15 | Float |
| 布尔值 | true,false | - | Bool |
| 时间 | "2023-01-01 00:00:00" | 上报格式 yyyy-MM-dd HH:mm:ss | DateTime |
| 日期 | "2023-01-01" | 上报格式 yyyy-MM-dd | Date |
| 列表 | \["Interstellar", "The Negro Motorist Green Book"] | 默认为字符串元素的数组，数组最大元素个数为 500 | Array |
> **注意**
> **属性值的类型为在引力引擎后台创建该属性值时确定的类型，如果数据中某个属性的值的类型与此前确定的类型不符，此次事件将被系统丢弃!**
## 2. 用户表操作逻辑 [#2-用户表操作逻辑]
修改用户在用户表中的数据，也就是上报数据中 `event` 字段为`profile_set` 、 `profile_set_once` 、 `profile_increment` 、`profile_number_max` 、`profile_number_min` 、 `profile_append` 、 `profile_uniq_append` 、 `profile_unset` 、 `profile_delete` 的数据，本质上可以看作是一条指令，也就是对该条数据所指用户的用户表数据进行操作，操作的类型由 `event`字段决定，而操作的内容以 `properties` 中的属性所决定。
以下是主要的用户表属性操作的具体逻辑：
| **字段** | **描述** | **备注** |
| --------------------- | -------------- | ----------------------------------------------------------------------------------------------------------------------- |
| profile\_set | 覆盖用户属性 | 只覆盖 `properties` 中指定的属性；未传入的属性不受影响。 |
| profile\_set\_once | 初始化用户属性 | 根据 `properties`中的属性，对未赋值（为空）的属性进行设置，如果该用户的某需要设置的属性已经有值，则不会进行覆盖。 |
| profile\_increment | 累加用户属性 | 根据 `properties`中的属性，对数值型的属性进行累加操作，如果传入负值，则从原属性值中减去该值的绝对值（例如原值为 10，传入 -3 后为 7），如果该用户的某需要设置的属性未赋值（为空），则会默认设置为 0 后再进行累加操作。 |
| profile\_number\_max | 用户属性取最大值 | 对 `properties` 中指定的数值型属性比较并保留较大值。 |
| profile\_number\_min | 用户属性取最小值 | 对 `properties` 中指定的数值型属性比较并保留较小值。 |
| profile\_append | 添加列表型用户属性的元素 | 根据 `properties`中的属性，对列表型的属性进行添加元素操作 |
| profile\_uniq\_append | 去重添加列表型用户属性的元素 | 根据 `properties`中的属性，对列表型的属性进行去重添加元素操作 |
| profile\_unset | 清空用户属性值 | 根据 `properties`中的属性，清空其中的所有属性（字符串型设置为空字符串，数值型设置为 0，布尔型设置为 false），如果某个属性不存在不会新建该属性。 |
| profile\_delete | 删除用户 | 将该用户的所有用户属性从用户表中删除，该用户的事件数据不会被删除。 |
# 事件属性与用户属性
> 来源：https://help.gravity-engine.com/docs/getting-started/event-and-user-properties
> 说明事件属性与用户属性的用途和区别，帮助接入人员为行为分析和用户分析选择正确的数据类型。
在完成前期数据模型准备之后，需要追踪的事件已基本确定，接下来要做的是为这些事件以及用户设置属性。值得注意的是，`事件属性`与`用户属性`的设置会直接影响到分析的深度，因此如何设定需要仔细斟酌，本节将会简单介绍设置用户属性与事件属性的要点。
## 1. 事件属性还是用户属性？ [#1-事件属性还是用户属性]
一般情况下，`Event` 都是在用户产生某个有意义的行为时上报的，因此事件属性除了与该事件相关的属性外，还能够反映用户在进行该行为时的状态；而用户属性则只表示用户最新的状态。比如同样表示会员等级的字段，事件属性中的等级表示用户发生该行为时的会员等级，而用户属性的等级则是用户现在的会员等级。
另外，引力引擎 的客户端 SDK 将会自动收集一些事件属性以及用户属性，如果您想了解这些属性，您可以在[事件属性页面](https://web.gravity-engine.com/#/manage/metadata/eventProperty)中过滤查看`预置属性`。
## 2. 哪些属性应该作为公共事件属性？ [#2-哪些属性应该作为公共事件属性]
公共事件属性是会作用于每一个事件的属性，建议您将重要的属性或常用属性在上传事件前设置为公共事件属性，我们建议将会员等级、渠道设置为公共事件属性。
## 3. 哪些属性应该作为事件属性？ [#3-哪些属性应该作为事件属性]
事件属性是每种事件所独有的属性，在您上传某个事件之前需要手动配置。对于如何设置事件属性，需要使用您在[模型介绍](/docs/getting-started/data-model)整理好的事件列表，根据您的分析需求以及埋点触发的条件进行设置。
事件属性的英文名称，我们建议只使用英文大写、英文小写以及下划线进行标识，并且名称最好是有意义的，请勿使用中文命名。如果有在不同事件中存在意义相同的属性，比如递交订单中的购买商品 ID 以及加入购物车时的商品 ID，最好设置为同一属性名，其作用相当于合并属性。
目前支持的属性值类型有文本、整数、浮点数、布尔值、日期、时间以及列表，自定义属性名必须以英文字母开头，只能包含英文字母、数字和下划线，长度不超过 50 个字符；布尔值属于属性值类型，不能作为属性名规则，如果需要了解属性具体的含义，您可以去[元数据页面](https://web.gravity-engine.com/#/manage/metadata/metaEvent)中查看备注信息。
当您设置好一条属性之后，请将属性的名称、类型以及备注补充到[数据模型](/docs/getting-started/data-model)整理的事件文档中，此时的事件文档中会有每个事件的名称、描述、重要程度、分析点以及属性名、属性类型和属性意义。
## 4. 哪些属性应该作为用户属性？ [#4-哪些属性应该作为用户属性]
用户属性表示的是用户的不变的属性以及最新状态，我们建议将下列三种属性设置为用户属性：
（1）固定属性：固定属性指的是用户不会变更的属性，这些属性往往是注册时的信息或首次产生某行为时的信息，比如首次注册时间、首次来源渠道、首次付费时间等。对于这样的属性，在埋点时请调用对应 SDK 的“仅首次设置”方法（如小游戏/小程序的 `userSetOnce`），并建议在属性名前加上 `first`。
（2）最新状态：最新状态指的是用户的当前状态，往往是用户最后产生某行为的信息，比如最后上线时间、最后付费时间等等。对于这样的属性，在埋点时请调用对应 SDK 的“覆盖设置”方法（如小游戏/小程序的 `userSet`），并建议属性名前加上 `latest`。
（3）累计值：累计值实质上是最新状态的一种特殊形式，累计值的数据类型为数值型，主要是产生某重要行为的次数或者数值型的最新状态，比如累计付费次数、累计付费金额、累计登录次数等等，在埋点时请调用对应 SDK 的“数值累加”方法（如小游戏/小程序的 `userAdd`），每次调用都会在原先的数值上进行累加操作。
在设置完用户属性后，请将这些属性加入到[数据模型](/docs/getting-started/data-model)整理的事件文档中。
上述方法名会因平台而异，请从 [SDK 总览](/docs/client-sdk/sdk-overview) 进入所选平台的“用户属性上报”文档；属性名称和取值限制请统一参考 [数据规则](/docs/getting-started/data-rules)。
# 接入前准备
> 来源：https://help.gravity-engine.com/docs/getting-started
> Gravity Engine 接入前准备索引，汇总概述、数据模型等主题，便于按功能进入对应的配置、接入或参考说明。
{/* Generated by scripts/generate-docs-routes.mjs. Do not edit. */}
## 目录 [#目录]
* [概述](/docs/getting-started/overview)
* [数据模型](/docs/getting-started/data-model)
* [事件属性与用户属性](/docs/getting-started/event-and-user-properties)
* [数据规则](/docs/getting-started/data-rules)
* [接入验收与排错](/docs/getting-started/integration-checklist)
# 接入验收与排错
> 来源：https://help.gravity-engine.com/docs/getting-started/integration-checklist
> 按准备、初始化、事件入库、归因联调和上线五个阶段验收 Gravity Engine 接入，提供常见故障的排查顺序与支持信息清单。
代码集成完成后，请用测试用户走完本页流程。**初始化成功、事件入库、广告归因成功和媒体回传成功是不同的验收项，应分别确认。**
## 1. 准备接入信息 [#1-准备接入信息]
| 检查项 | 通过标准 |
| ----- | -------------------------------------------------------------------------------------------------------- |
| 应用与环境 | 明确测试使用的引力应用 ID、目标平台、SDK 版本及国内/海外节点；测试数据与正式数据的归属已确认 |
| 接入方式 | 已按 [SDK 总览](/docs/client-sdk/sdk-overview) 选择技术栈；服务端补充上报时已阅读 [混合上报模式](/docs/client-sdk/hybrid-reporting) |
| 凭证 | SDK/事件采集使用引力应用 Access Token；OpenAPI 使用开发者应用 `app_key`；微信/抖音平台 Token 与两者分别管理 |
| 采集方案 | 明确事件名、触发时机、属性类型、金额单位和上报端；自定义事件及属性已在后台配置 |
| 用户标识 | 客户端与服务端使用同一引力应用、同一 [ClientID](/docs/client-sdk/client-id)，业务登录后不会随意切换标识 |
| 权限与网络 | 已按对应平台文档配置网络权限及合法域名，并确认 SDK 的启动时机符合项目的隐私授权流程 |
## 2. 验证初始化 [#2-验证初始化]
1. 按对应平台快速集成文档配置 SDK，区分启动配置 `setupAndStart` 和用户初始化 `initialize`。
2. 观察初始化成功回调或返回结果；发生异常时先排查错误，不继续发送依赖初始化的事件。
3. 记录本次测试的应用 ID、SDK 版本、ClientID 和初始化时间，用同一个 ClientID 核对后续数据。
4. 如需服务端上报，先把客户端初始化成功后的 ClientID 传给业务服务端，再触发上报。
初始化调用次数及后续冷启动行为以对应平台文档为准。不要通过更换 ClientID 并重新初始化来关联业务账号；业务账号应使用对应平台的用户属性方法记录。
## 3. 验证事件入库 [#3-验证事件入库]
在后台 [事件流](https://web.gravity-engine.com/#/manage/metadata/eventFlow) 开启“加载实时数据”，按测试 ClientID 筛选，再逐项触发实际业务操作。
| 验收项 | 核对内容 |
| ---- | ------------------------------------------------- |
| 事件 | 应采集的事件均出现，事件名和触发次数符合预期；无需的业务事件不必为验收额外接入 |
| 用户 | 事件归属当前测试用户，客户端和服务端事件没有落到两个 ClientID 下 |
| 时间 | 使用实际事件时间；事件采集 `time` 为毫秒时间戳，常规实时上报不启用 `time_free` |
| 属性 | 必填属性完整，数据类型与元数据定义一致；错误数据页面没有相关校验错误 |
| 付费 | 使用测试订单验证，金额单位为分，例如 6 元传 600；订单号准确，客户端/服务端的上报职责已明确 |
| 广告观看 | 如有广告变现业务，核对广告平台、广告位和 eCPM；以对应 SDK 文档要求的单位传入 |
| 用户属性 | 更新后值符合预期；累加、首次设置、清空等操作分别验证，避免误用删除全部属性的方法 |
接口返回 `code=0` 后仍需核对入库结果。报表可能有更新延迟，不应仅凭报表尚未出现数据就重复补报。
## 4. 验证归因与媒体回传 [#4-验证归因与媒体回传]
1. 创建独立的联调推广活动，避免使用正在投放的活动进行试验。
2. 按 [归因联调指南](/docs/attribution/integration-testing) 核对点击记录、设备标识或启动参数、初始化时间、窗口期及归因结果。
3. 如需向自有业务系统接收结果，按用途选择 [归因回调](/docs/attribution/attribution-callback) 或 [事件回调](/docs/attribution/event-callback)，核对实际请求和服务端响应。
4. 如需向广告媒体回传转化，单独核对媒体回传状态；事件已入库或已收到业务回调，不能代替媒体回传验收。
5. 按媒体和事件核对所有回传来源，确认引力回传、媒体 SDK 与自有 API 没有重复上报同一转化。
## 5. 常见问题排查顺序 [#5-常见问题排查顺序]
| 现象 | 优先排查 |
| ------------ | --------------------------------------------------------------------------------- |
| 初始化失败 | 当前应用 Access Token、必填参数、ClientID、网络权限及国内/海外节点是否匹配 |
| 初始化成功但看不到事件 | 是否已触发事件、是否按当前 ClientID 筛选、SDK 是否仍在缓存、网络请求是否发出；再查看事件流的错误数据 |
| 事件出现在错误数据中 | 事件和属性是否已配置，名称、必填字段和数据类型是否符合 [数据规则](/docs/getting-started/data-rules) |
| 服务端上报失败 | 客户端是否已初始化成功，应用与 ClientID 是否一致，`event_list` 结构、毫秒时间戳及 `properties.$lib="api"` 是否正确 |
| OpenAPI 验签失败 | 是否使用开发者应用 `app_key`，是否按实际请求体重新生成 `sign` 和 `Authorization`，是否误用了后台登录 Token |
| 事件正常但归因为自然量 | 是否收到有效点击，标识符或启动参数能否匹配，是否在有效窗口内；不要先通过反复换 ClientID 或补造点击数据排查 |
| 付费或 ROI 异常 | 金额单位、订单号、事件次数、重复回传以及报表的时间范围和更新频率 |
| 小游戏广告收入未出现 | 广告观看事件、平台 Token 接入模式及有效性、对应报表的更新时间 |
## 6. 上线交接与获取支持 [#6-上线交接与获取支持]
上线前记录已通过的验收项及未使用的功能，按少量投放验证后再扩大投放的顺序推进。测试开关和日志级别按对应 SDK 文档调整。
如仍有问题，请向引力运营或技术支持提供：应用 ID、平台及 SDK 版本、ClientID、问题发生时间及所在时区、预期结果与实际结果、脱敏后的请求/响应和错误日志。归因问题另附推广活动 ID、媒体名称、点击时间及设备标识类型；订单问题另附测试订单号与金额单位。
请勿在公开问题单中附上完整 Access Token、`app_key`、AppSecret 或 `Authorization`；设备标识及用户信息按必要范围脱敏。
# 概述
> 来源：https://help.gravity-engine.com/docs/getting-started/overview
> 概述 Gravity Engine 的数据接入流程、数据模型与数据格式，帮助业务、研发和测试团队明确接入顺序。
开始正式技术接入，您需要依次完成以下步骤：
1. 根据业务需求的整理，梳理出数据采集方案；
2. 由研发人员根据数据采集方案完成数据接入工作；
3. 验证数据接入正确性；
4. 数据接入验证无误之后，客户开始在媒体投放平台少量投放广告验证归因的正确性；
5. 归因验证无误之后，客户起量投放，并在引力引擎后台查看后向数据分析买量行为。
本篇文档将会对必要的接入相关知识做一个整体的介绍，本文的目标读者是所有与接入相关的同事，包括业务人员、研发人员、测试人员等。
## 按目标选择接入路径 [#按目标选择接入路径]
| 您要完成的工作 | 阅读顺序 |
| -------------- | ---------------------------------------------------------------------------------------------------------------- |
| 首次采集客户端数据 | 本页 → [SDK 总览](/docs/client-sdk/sdk-overview) → 对应平台快速集成 → [接入验收与排错](/docs/getting-started/integration-checklist) |
| 服务端补报付费等关键事件 | [混合上报模式](/docs/client-sdk/hybrid-reporting) → [事件采集 API](/docs/server-integration/event-collection/restful-api) |
| 查询报表、导出数据或管理应用 | [服务端接入总览](/docs/server-integration/overview) → [签名生成](/docs/server-integration/request-signing) → 具体接口 |
| 验证广告归因 | 完成客户端接入和事件入库验证 → [归因联调指南](/docs/attribution/integration-testing) |
`setupAndStart` 用于启动和配置 SDK，`initialize` 用于引力用户初始化；业务注册事件用于记录产品内注册行为，不能代替 SDK 用户初始化。具体方法名及调用顺序以所选平台文档为准。
## 1. 基础知识 [#1-基础知识]
### 1.1 数据模型 [#11-数据模型]
在进行数据接入之前，首先我们需要理解 引力引擎 中的数据是什么。
数据采集方案的设计实际上就是根据业务分析的目标确定采集哪些用户行为事件的过程。例如，如果要分析用户充值情况，要采集的可能是用户支付行为数据。用户行为数据可以分解为：谁 (`WHO`)，什么时候 (`WHEN`)，在哪里 (`WHERE`)，以什么方式 (`HOW`)，进行了充值行为 (`WHAT`)，如下图所示：
用户行为数据会被组织成**用户相关数据**和**行为事件相关数据**，并分别存入**用户表**和**事件表**中。
* 用户数据主要用于描述用户的状态和不会经常发生变化的属性；
* 事件数据用于描述与具体行为事件相关的信息。
在数据采集方案中，您需要确定在什么时机需要触发用户数据的上报，在什么时机需要触发行为事件的上报。
在我们的所有数据接入指南中，都会分别介绍上报行为事件数据和用户数据的方法。
关于数据模型的进一步了解，可以参考：[数据模型](/docs/getting-started/data-model)。
关于用户数据和事件数据的进一步了解，可以参考：[用户属性与事件属性](/docs/getting-started/event-and-user-properties)。
### 1.2 数据格式 [#12-数据格式]
无论通过哪一种方式接入数据，在发送到数据接收端的时候都使用统一的数据格式，和相同的数据限制。[数据规则](/docs/getting-started/data-rules)一章对数据格式和对应的数据限制做了详细的描述。
如果您通过 SDK 对接数据，只需要调用对应的接口，SDK 会将数据整理成需要的数据格式进行上报；如果您通过[API](/docs/server-integration)接入数据，则需要根据数据规则中的描述整理好数据格式，然后上报。
关于数据格式，需要特别注意命名规则和数据类型：
* 命名规则：事件名和属性名都只能包含字母、数字、和下划线 \_，以字母开头，不能超过 50 个字符，属性名对大小写不敏感；事件名对大小写敏感
* 属性值数据类型：
| 引力数据类型 | 取值样例 | 取值说明 | 数据类型 |
| ------ | -------------------------------------------------- | ------------------------------------------------ | -------- |
| 文本 | "ABC" | 文本长度限制见 [数据规则](/docs/getting-started/data-rules) | String |
| 整数 | 123 | 数据范围是-9E15 至 9E15 | Integer |
| 浮点数 | 1.2 | 数据范围是-9E15 至 9E15 | Float |
| 布尔值 | true,false | - | Bool |
| 时间 | "2023-01-01 00:00:00" | 上报格式 yyyy-MM-dd HH:mm:ss | DateTime |
| 日期 | "2023-01-01" | 上报格式 yyyy-MM-dd | Date |
| 列表 | \["Interstellar", "The Negro Motorist Green Book"] | 默认为字符串元素的数组，数组最大元素个数为 500 | Array |
> **注意**
> **属性值的类型为在引力引擎后台创建该属性值时确定的类型，如果数据中某个属性的值的类型与此前确定的类型不符，此次事件将被系统丢弃!**
在 引力引擎 后台，您可能会注意到某些属性名是以 `$` 开头的，此类属性为预置属性。预置属性不需要特别设置，SDK 会在特定的事件发生时**默认采集**。
您需要特别注意的是，当数据格式或者数据类型没有正确设置的时候，数据无法入库。因此在接入阶段和接入之后，你可能需要通过 [元数据模块](https://web.gravity-engine.com/#/manage/metadata/metaEvent) 来检验或者观察数据上报的正确性，并对出现的问题及时修正。
## 2. 接入必备信息 [#2-接入必备信息]
在正式由研发进行数据接入之前，需要再次确认以下信息已经准备好：
1. 项目 `Access Token`：在 引力引擎 后台创建项目的时候会生成项目的 `Access Token`，可以在 [应用管理](https://web.gravity-engine.com/#/manage/appmanage) 页面点击查看参数获取
2. 数据采集方案，要包括：
* 数据接入的方式：客户端 SDK、API 或者混合使用的方式
* 待接入数据的内容和触发的时机
恭喜您完成了接入前准备文档的阅读。接下来，您就可以根据选定的接入方式，参考对应的接入指南文档，开始进行数据接入了，不同技术栈接入指南导航请参考：[SDK总览](/docs/client-sdk/sdk-overview)
## 3. 验证接入是否成功 [#3-验证接入是否成功]
在正式上线之前，请先完成对应 SDK 文档中的事件验证，再按 [接入验收与排错](/docs/getting-started/integration-checklist) 逐项确认用户标识、事件属性、金额单位、归因及媒体回传。初始化成功不等于全部验收通过。
# 引力Skill快速接入SDK
> 来源：https://help.gravity-engine.com/docs/client-sdk/ai-skill
> 说明如何下载并安装 Gravity Engine 集成 Skill，让编码智能体结合本地项目与官方文档完成 SDK 接入。
## 1. 准备工作 [#1-准备工作]
* 准备好本地项目（iOS / Android / Flutter / Unity 等）
* **下载配套文件**：
* Skill 压缩包：[integration-gravity-engine-1.0.1.zip](/docs-assets/attachments/1XGyl60w/integration-gravity-engine-1.0.1.zip "integration-gravity-engine-1.0.1.zip")
## 2. 引入 Skill [#2-引入-skill]
在支持的 AI 工具（如 Claude Code、Cursor 等）中加载该 Skill 解压后的文件夹。
## 3. 使用指令 [#3-使用指令]
在项目目录下向 AI 发送以下任一指令：
| 指令 | 效果 |
| ------------------ | --------------------------- |
| 接入引力引擎SDK | 自动识别引擎，引入国内版 SDK，默认国内节点 |
| 接入引力引擎海外SDK | 同上，但引入海外版 SDK，配置海外域名 |
| 使用pod方式接入引力引擎国内SDK | 强制用 CocoaPods 安装国内版 iOS SDK |
AI 会自动修改项目文件、添加依赖、生成初始化代码。
## 4. 执行完成后 [#4-执行完成后]
### 4.1 结果示例 [#41-结果示例]
1. AI 仅自动引入 SDK，自动添加 `setupAndStart` 和 `initialize` 方法，其他如事件上报、用户属性设置等调用需按对应平台文档自行补充。
2. AI 添加 `setupAndStart` 时，`your_access_token` 和 `appid` 均为固定占位符，需开发者替换为真实值。
3. 部分小游戏平台（微信、快手、抖音、B站）AI 会自动通过 `getOpenId` 方法获取 openid 并设为 clientId，开发者需在引力后台配置对应的 token，具体参考配置文档：[快捷获取 openid](/docs/client-sdk/mini-games/advanced/quick-get-openid)
4. 不支持 `getOpenId` 的小游戏平台，需开发者自行获取对应 ID 并设置为 clientId。
5. `setupAndStart` 由 AI 自动识别并添加，但开发者需确认初始化时机，确保在用户同意隐私后再调用。
6. 部分引擎可能还需要其他配置，请根据 AI 执行后的输出提示进行补充。
完成生成不代表接入验收通过。请继续执行 [接入验收与排错](/docs/getting-started/integration-checklist)，确认初始化、事件入库、金额单位及归因结果。
请仔细阅读 AI 输出的提示信息。AI 会告知哪些步骤已自动完成，以及哪些事项需要你手动处理（例如填写 `Token`、配置隐私权限等）。不同 AI 工具的提示内容可能不同，以实际输出为准。
# ClientID说明
> 来源：https://help.gravity-engine.com/docs/client-sdk/client-id
> 介绍 ClientID 的定义、各客户端平台的生成与获取方式，以及初始化顺序和保持用户标识准确的接入规范。
本文档详细阐述了引力平台用户唯一标识符 ClientID 的定义、在各平台（Android, iOS, 小程序等）的生成规则、获取方式以及确保数据准确性的重要接入规范和注意事项。
**ClientID 是引力平台用于标识用户唯一性的核心字段，是用户行为追踪和数据关联的基础。通常在初始化 SDK 时传入或 SDK 自动采集。**
## 1. ClientID 的定义与生成规则 [#1-clientid-的定义与生成规则]
* **Android 平台**
* **定义**：在调用 `initialize`方法时传入的 `USER_CLIENT_ID`参数即为 ClientID。
* **自动生成规则（5.0.9+版本）**：若传入空字符串，SDK 将按以下优先级自动采集设备 ID 作为 ClientID：**OAID > Android ID > IMEI**。若所有 ID 均无法获取，SDK 会生成一个随机且唯一的 16 位 ID 并持久化保存至本地缓存，以确保应用生命周期内该标识的稳定性。
* **iOS 平台**
* **定义**：在调用 `initialize`方法时传入的 `USER_CLIENT_ID`参数即为 ClientID。
* **自动生成规则**：若传入空字符串，SDK 默认会采集 **IDFV** 作为 ClientID。我们推荐您使用最佳实践方案，该方案已内置自动采集逻辑，可直接使用稳定的 IDFV 而无需手动处理。
* **Harmony 平台**
* **定义**：初始化 SDK 时，通过 config 配置对象中的 `clientId`字段传入。
* **自动生成规则（SDK版本大于2.0.4）**：若传入空字符串，SDK 将按以下优先级自动采集设备 ID 作为 ClientID：**OAID > ODID**。若所有 ID 均无法获取，SDK 会生成一个随机且唯一的 16 位 ID 并持久化保存至本地缓存，以确保应用生命周期内该标识的稳定性。
* **小游戏/小程序平台**
* **定义**：初始化 SDK 时，通过 config 配置对象中的 `clientId`字段传入。
* **建议**：通常使用平台的用户唯一标识（如微信 **OpenID**）作为 ClientID，用于标识当前应用内的用户。不同小程序或小游戏的 OpenID 不能直接视为同一个用户标识，跨应用关联需单独设计业务账号映射。
* **快应用/快游戏平台**
* **定义**：初始化 SDK 时，通过 config 配置对象中的 `clientId`字段传入。
* **Web/H5平台**
* **定义**：初始化 SDK 时，通过 config 配置对象中的 `clientId`字段传入。
* **自动生成规则**：如果不传`clientId`字段，会使用SDK生成的uuid代替。
## 2. 如何获取 ClientID？ [#2-如何获取-clientid]
> **注意**
> **为确保获取到正确的值，请确保在 SDK initialize成功完成后再调用此方法。**
* **Android 与 iOS 平台**：调用 `getCurrentClientId()`方法可获取当前用户的 ClientID。
* **HarmonyOS**：调用`getCurrentClientId()`方法可获取当前用户的 ClientID。
* **Unity 平台**：调用 `GetCurrentClientID()`方法可获取当前用户的 ClientID。
* **Web/H5平台**：调用`ge.config.clientId()`方法可获取当前用户的 ClientID。
## 3. 关于 ClientID 初始化的重要说明 [#3-关于-clientid-初始化的重要说明]
为了帮助您获得准确可靠的数据分析结果，请您务必了解 ClientID 的初始化机制及其对数据的影响。
### 3.1 初始化机制是如何工作的？ [#31-初始化机制是如何工作的]
简单来说，每次您调用 `initialize`方法并成功传入参数时，SDK 都会将这次传入的值记录下来并缓存到本地，作为这台设备的唯一标识。**请注意，多次成功调用 `initialize`方法，新的 ClientID 会覆盖之前存储的 ClientID**，之后所有的事件都会与这个最新的标识符关联。
### 3.2 一个需要避免的常见做法 [#32-一个需要避免的常见做法]
我们理解，您可能会希望在用户登录后，将其业务账号ID设置为ClientID以便于关联。然而，**我们强烈不建议这样做**。
如果您在应用的一次运行过程中，先后两次调用初始化方法并**传入了两个不同的ID**（例如：首次初始化后，在用户登录时又再次初始化并传入了用户的账号ID），这会产生一个您可能意想不到的结果：
* 平台会将这两个ID识别为**两个完全独立的用户**。
* 这会导致该设备在**切换ID之前**的行为数据（例如：广告点击、浏览记录）和**切换ID之后**的行为数据（例如：登录、付费）被割裂开来，无法归属于同一个人。
* 从而严重影响后续的广告效果归因、用户行为路径分析等数据的准确性。
### 3.3 我们的建议与最佳实践 [#33-我们的建议与最佳实践]
为了确保数据的连续性和准确性，我们为您推荐以下做法：
1. **保持标识符稳定**
理想情况下，应在应用启动时初始化一次SDK，并在此后保持使用同一个ClientID。您可以将首次初始化得到的ClientID进行本地保存，后续需要时（如重试初始化）始终使用这个保存的值，以确保标识符的一致性。
2. **如何正确关联用户信息**
如果您需要在用户登录后关联其业务身份，**请不要通过重新初始化SDK来实现**。我们提供了更安全的方式：请使用 **用户属性设置接口**（如小游戏/小程序的 `userSet()`；其他平台请使用对应文档中的方法名）。
这样，既能将用户ID与设备行为关联起来，又不会破坏设备标识符的稳定性。
3. **安全地重试初始化**
如果出于网络容错等原因需要多次调用初始化，请确保每次传入的都是同一个ClientID。重试时仍需遵循对应 SDK 的调用时机和次数约束，避免在多个业务入口并发初始化。
### 3.4 总结 [#34-总结]
请将初始化时传入的ClientID视为设备的“身份证”，一旦确定，应尽量避免更改。关联用户信息时，请使用对应平台的用户属性设置方法；设置业务账号属性不会自动合并不同 ClientID 的历史数据。
# 合规指南
> 来源：https://help.gravity-engine.com/docs/client-sdk/compliance
> 说明 Gravity Engine 客户端 SDK 采集的字段、采集时机、使用目的及 Android、iOS 权限配置要求。
为了更好地落实保护用户个人信息的相关要求，帮助开发者更好的在符合法律法规、政策及标准的规定下使用第三方 SDK 业务，引力引擎制定本合规指南。
## SDK 收集的个人信息 [#sdk-收集的个人信息]
### 1. 采集的字段 [#1-采集的字段]
* 设备唯一标识（AndroidID、IMEI、OAID、MAC、IDFA、IDFV）
* IP 地址、国家、国家代码、省份、城市、操作系统版本、设备制造商、操作系统、设备 ID、设备型号、App 版本、应用唯一标识、SDK 类型、SDK 版本、网络状态、网络运营商、后台事件时长、事件时长、页面标题、页面名称、页面地址、前向地址。
### 2. 采集的时机 [#2-采集的时机]
* 在您调用引力引擎 SDK 初始化方法 `initialize` 时采集
为了保护用户隐私，如需要关闭设备 Id 采集，您可以通过在调用 `setupAndStart` 方法时传入的 `GEConfig` 里配置，举例如下：
```java
// 在主线程中配置并启动SDK
GEConfig config = GEConfig.getInstance(context, ACCESS_TOKEN);
config.enableAndroidId(false); // 传入 false，则表示关闭 Androidid采集，非必须不要关闭，会影响归因率！
config.enableOAID(false); // 传入 false，则表示关闭 OAID采集，非必须不要关闭，会影响归因率！
config.enableIMEI(false); // 传入 false，则表示关闭 IMEI 采集，非必须不要关闭，会影响归因率！
config.enableMAC(false); // 传入 false，则表示关闭 mac采集，非必须不要关闭，会影响归因率！
// 保存此实例，后续调用方法均需要用到
GravityEngineSDK gravityEngineSDKInstance = GravityEngineSDK.setupAndStart(config);
```
* 关闭 AndroidId 采集：调用 enableAndroidId(false);
* 关闭 OAID 采集：调用 enableOAID(false);
* 关闭 IMEI 采集：调用 enableIMEI(false);
* 关闭 MAC/BSSID/SSID 采集：调用 enableMAC(false);
### 3. 采集的目的 [#3-采集的目的]
* 实现本平台的基本业务功能（包括广告归因、广告模型优化、用户行为数据分析、安全风控）
## SDK 所需的系统权限 [#sdk-所需的系统权限]
### Android SDK 产品权限说明 [#android-sdk-产品权限说明]
为保证支持客户数据收集的正常展开，Android SDK 需要以下系统权限：
| 权限 | 用途 | 是否必须 | 申请时机 |
| ------------------------ | ------------------ | ------------------------ | ------------------- |
| READ\_PHONE\_STATE（可选） | 允许应用获取设备 IMEI、MEID | 可选权限 | 开启 IMEI 采集之后获取IMEI时 |
| INTERNET | 允许应用发送统计数据 | 必须权限，SDK 发送埋点数据需要此权限 | 上报事件时 |
| ACCESS\_NETWORK\_STATE | 允许应用检测网络状态 | 必须权限，SDK 会根据网络状态选择是否发送数据 | 上报事件时 |
| READ\_EXTERNAL\_STORAGE | 允许应用读取文件内容 | 可选权限 | SDK启动时 |
| WRITE\_EXTERNAL\_STORAGE | 允许应用写入文件内容 | 可选权限 | SDK启动时 |
### iOS SDK 产品权限说明 [#ios-sdk-产品权限说明]
为保证支持客户数据收集的正常展开，iOS SDK 需要以下系统权限：
| 权限 | 用途 | 是否必须 | 申请时机 |
| ---- | ------------------- | -------------------- | ------- |
| 网络权限 | 允许应用发数据 | 必须权限，SDK 发送埋点数据需要此权限 | 应用启动时使用 |
| IDFA | 允许应用获取 IDFA 以完成精准归因 | 可选权限 | 应用启动时使用 |
### 获取权限时机 [#获取权限时机]
在您调用引力引擎 SDK 初始化方法 `initialize` 时采集
## SDK 隐私政策披露要求与示例 [#sdk-隐私政策披露要求与示例]
### 要求内容 [#要求内容]
《SDK 合规使用说明》应提供 App 向最终用户披露 SDK 隐私政策条款的示例，包括 SDK 名称、公司名 、处理个人信息种类及目的、采集方式、隐私政策链接等内容。
### 接入说明 [#接入说明]
开发者在 App 集成引力引擎 SDK 后，引力引擎 SDK 的正常运行会收集必要的最终用户信息，实现用户行为分析、数据归因等功能。请开发者根据集成引力引擎 SDK 的实际情况，在您 App 的隐私政策中，对引力引擎 SDK 名称、公司名称、处理个人信息种类及目的、采集方式、隐私政策链接等内容进行披露。
### 披露示例 [#披露示例]
**SDK 名称：** 引力引擎 SDK
**涉及个人信息：** 系统运行信息（设备平台、系统版本、设备型号、设备厂商、设备品牌、屏幕分辨率）、网络状态信息（IP 地址、运营商信息、WiFi 信息）、国际移动设备识别码（IMEI）、匿名设备标识符(OAID)、Android ID、匿名 ID、IDFA、IDFV
**合作方主体：** 深圳引力引擎科技有限公司
**使用目的：** 实现广告监测归因、投放效果优化等与广告活动相关的使用目的
**使用场景：** 广告监测归因、投放效果优化的场景
**收集方式：** SDK 自行采集
**官网链接：** [https://www.gravity-engine.com/](https://www.gravity-engine.com/)
**隐私政策链接：** [https://www.gravity-engine.com/h-col-101.html](https://www.gravity-engine.com/h-col-101.html)
## 最终用户同意方式的示例 [#最终用户同意方式的示例]
### 要求内容 [#要求内容-1]
《SDK 合规使用说明》应详细说明 App 获取最终用户授权同意的建议方式，其中需要取得最终用户单独同意的，应显著提示并给出示例。
### 接入说明 [#接入说明-1]
App 首次运行时应当有隐私弹窗，隐私弹窗中应公示简版隐私政策内容并附完整版隐私政策链接，并明确提示最终用户阅读并选择是否同意隐私政策；隐私弹窗应提供同意按钮和拒绝同意的按钮，并由最终用户主动选择。
## 初始化 SDK [#初始化-sdk]
您应确保在用户同意《隐私政策》后才能调用引力引擎 SDK 初始化，APP 安装后首次冷启动时的初始化步骤参考如下：
1. 启动 SDK 方法不会采集设备信息，也不会向引力引擎后台上报数据；
2. 确保 APP 首次冷启动时，在用户同意《隐私政策》之后，才调用正式初始化方法，此时 SDK 才会真正采集设备信息并上报数据；反之，如果用户不同意《隐私政策》，则不能调用初始化方法。
## 最终用户行使权利的配置说明 [#最终用户行使权利的配置说明]
### 要求内容 [#要求内容-2]
最终用户对其个人信息的处理享有知情、决定、查阅、复制、补充、更正、撤回授权同意、删除、注销账号等权利。以嵌入接口形式向最终用户提供行使权利的，应提供接口调用方式、示例。
### 接入说明 [#接入说明-2]
开发者在其 App 中集成引力引擎 SDK 后，引力引擎 SDK 的正常运行会收集必要的最终用户信息用于实现用户行为分析、数据归因等功能。开发者应根据相关法律法规为最终用户提供行使个人信息主体权利的路径或功能，需要引力引擎 SDK 配合的，请与引力引擎 SDK 及时进行联系，我们将与开发者协同妥善解决最终用户的诉求。联系客服电子邮箱地址：[client@gravity-engine.com](mailto:client@gravity-engine.com)
如果在使用过程中有任何疑问，请联系技术支持或您的客户经理咨询。
## 针对儿童隐私保护的特别说明 [#针对儿童隐私保护的特别说明]
### 核心原则 [#核心原则]
若您的应用需遵守美国的《儿童在线隐私权保护法》(COPPA) 或其他类似法规，或您的应用**目标用户**包含或主要面向**13周岁以下**的儿童，您有责任将该应用标识为“儿童应用”。
### 配置指南 [#配置指南]
为确保符合相关法规，请在集成引力引擎SDK时，**必须**参考 Android/iOS 快速集成文档中关于“启动SDK配置”的部分，将您的应用明确标记为儿童应用 (Kids App)。此设置将影响SDK对特定数据的处理逻辑，以满足儿童隐私保护的特殊要求。此配置建议在SDK初始化时完成。
### 开发者责任 [#开发者责任]
请开发者知悉，引力引擎 SDK 不主动识别用户年龄。**您作为应用提供方，是履行COPPA等法规的首要责任人**。这包括但不限于：
* 对应用是否面向儿童做出准确判断。
* 在采集、使用或分享儿童个人信息前，获取可验证的家长同意。
* 在应用内实施本指南所提的标记配置。
## 针对欧盟《通用数据保护条例》(GDPR)的合规说明 [#针对欧盟通用数据保护条例gdpr的合规说明]
### 概述与功能支持 [#概述与功能支持]
为支持开发者在欧盟地区遵守《通用数据保护条例》(GDPR)，引力引擎 SDK 提供了专门的配置接口。通过设置，SDK可控制对特定敏感个人数据的采集行为，为开发者履行“数据最小化”等原则提供技术工具。
### 配置说明 [#配置说明]
* **默认行为**：SDK初始化时，**默认不将用户识别为GDPR管辖区域的用户**（即GDPR模式开关处于关闭状态，对应参数为`FALSE`）。在此默认状态下，SDK会遵循标准的数据采集策略，**采集包括设备标识符（如IDFA/GAID）在内的信息**，以保障广告归因、数据分析等核心功能的正常运行。
* **设置方法**：开发者可以明确告知SDK当前用户是否位于GDPR管辖区域。一旦将用户标记为GDPR区域用户，SDK将默认**不再采集**IDFA、IDFV、GAID等设备标识符。
* **设置时机**：此设置可在SDK启动时配置。具体调用方法请参阅Android/iOS 快速集成文档中的示例代码。
### 重要操作指引 [#重要操作指引]
* **审慎判断**：您需要根据您应用服务的实际用户群体和地理位置，自主判断并调用此功能。**此功能仅供处理GDPR管辖区域内用户的场景下使用。**
* **风险提示**：对于明确知晓的非GDPR区域用户，**请勿调用**此设置。误操作可能导致无法采集必要的设备标识符，进而**影响广告归因、数据分析等核心功能的准确性，甚至导致关键数据丢失**。请务必谨慎评估后使用。
# 混合上报模式
> 来源：https://help.gravity-engine.com/docs/client-sdk/hybrid-reporting
> 说明客户端 SDK 与业务服务端共同上报数据的混合模式，并以付费事件为例讲解用户标识传递和接入步骤。
如果您应用内有些事件需要通过自有后端直接报送给引力引擎，那我们推荐您使用 **混合上报模式** 来完成接入，继续阅读本篇文档，我们将以付费事件为例讲解混合上报模式的接入步骤。
## 1. 客户端接入 [#1-客户端接入]
客户端接入引力引擎提供的 SDK，不同客户端技术栈，对应不同的 SDK，具体可以参考 [SDK 总览](/docs/client-sdk/sdk-overview)。
> **注意**
> 客户端 SDK 会负责自采集很多基础事件和属性，这部分工作引力提供的 SDK 已经完成封装
## 2. 服务端接入 [#2-服务端接入]
服务端接入[事件收集上报接口](/docs/server-integration/event-collection/restful-api)，完成事件的服务端报送功能，您需要注意以下几点：
* 服务端仅负责事件的收集上报，不负责用户的注册，用户注册需要调用客户端 SDK 的 `initialize` 方法完成；
* 客户端和服务端使用的用户 `client id` 需要保持一致；
* 在客户端完成 `initialize` 方法调用之后，服务端才能开始做事件采集上报，否则上报不成功；
* 服务端接入事件上报时，请参考 [元事件页面](https://web.gravity-engine.com/#/manage/metadata/metaEvent) 下关于事件的详情属性；
* 请尽量上报事件的公共属性，引力不做强制要求，但是上报足够多属性，可以方便您后续在引力平台使用数据分析功能（ `$city`、 `$province` 、 `$country` 、 `$browser` 、 `$browser_version` 属性可以不上报，引力后端会自动采集）；
* 关于属性的更多信息，请您参考 [事件属性页面](https://web.gravity-engine.com/#/manage/metadata/eventProperty)。
> **注意**
> **通过 API 上报请务必添加参数：`$lib`，并固定传入字符串`api`**
## 3. 付费事件示例与验收 [#3-付费事件示例与验收]
推荐顺序：客户端初始化成功 → 将当前 ClientID 传给业务服务端并关联订单 → 业务服务端确认支付成功 → 上报付费事件。先确定付费事件由哪一端负责，避免客户端和服务端各上报一次。
以下是放入 `event_list` 的单个事件对象，不是完整请求体。外层 `client_id`、`access_token` 和完整调用方式请参考 [事件采集 API](/docs/server-integration/event-collection/restful-api)。
`time` 为事件实际发生的毫秒时间戳，示例时间仅用于展示结构，调用前必须替换；实时业务请保持 `time_free=false`。`$pay_amount` 单位为分，示例的 600 表示 6 元；`$order_id` 使用真实业务订单号。设备与网络信息只传入已采集到的真实值，不要复制示例值。
```json
{
"type": "track",
"event": "$PayEvent",
"time": 1669860000000,
"time_free": false,
"properties": {
"$lib_version": "1.0",
"$lib": "api",
"$network_type": "4g",
"$manufacturer": "HONOR",
"$brand": "HONOR",
"$model": "JLH-AN00",
"$screen_width": 360,
"$screen_height": 796,
"$system_language": "zh_CN",
"$os": "android",
"$os_version": "Android 12",
"$pay_amount": 600,
"$pay_type": "CNY",
"$order_id": "你的订单ID",
"$pay_reason": "月卡",
"$pay_method": "微信",
"$is_first_pay": false,
"$ip": "用户真实IP"
}
}
```
收到成功响应后，请在 [事件流](https://web.gravity-engine.com/#/manage/metadata/eventFlow) 按相同 ClientID 核对订单号、金额和事件次数，再按 [接入验收与排错](/docs/getting-started/integration-checklist) 完成上线检查。
# 客户端SDK集成
> 来源：https://help.gravity-engine.com/docs/client-sdk
> Gravity Engine 客户端SDK集成索引，汇总合规指南、SDK总览等主题，便于按功能进入对应的配置、接入或参考说明。
{/* Generated by scripts/generate-docs-routes.mjs. Do not edit. */}
## 目录 [#目录]
* [合规指南](/docs/client-sdk/compliance)
* [SDK总览](/docs/client-sdk/sdk-overview)
* [ClientID说明](/docs/client-sdk/client-id)
* [混合上报模式](/docs/client-sdk/hybrid-reporting)
* [引力Skill快速接入SDK](/docs/client-sdk/ai-skill)
* [Android](/docs/client-sdk/android) — 子目录
* [iOS](/docs/client-sdk/ios) — 子目录
* [小游戏](/docs/client-sdk/mini-games) — 子目录
* [小程序](/docs/client-sdk/mini-programs) — 子目录
* [快应用](/docs/client-sdk/quick-apps) — 子目录
* [快游戏](/docs/client-sdk/quick-games) — 子目录
* [HarmonyOS](/docs/client-sdk/harmonyos) — 子目录
* [Web](/docs/client-sdk/web) — 子目录
* [Unity](/docs/client-sdk/unity) — 子目录
* [Flutter](/docs/client-sdk/flutter) — 子目录
* [CocosCreator](/docs/client-sdk/cocos-creator) — 子目录
* [Laya](/docs/client-sdk/laya) — 子目录
* [Egret](/docs/client-sdk/egret) — 子目录
* [C++](/docs/client-sdk/cpp) — 子目录
* [其他开发框架](/docs/client-sdk/other-frameworks) — 子目录
# SDK总览
> 来源：https://help.gravity-engine.com/docs/client-sdk/sdk-overview
> 汇总 Gravity Engine 客户端 SDK 支持的平台、SDK 下载地址和 Demo 入口，便于选择对应的接入文档。
按您的技术栈在下表中选择平台，点击平台名进入对应的接入文档。下载项中的 `version` 表示压缩包版本占位名称，请在下载页选择实际发布版本，并记录本次接入版本以便排错。
用 Cocos Creator、Laya、Egret 等游戏引擎开发的项目，请从「游戏引擎」分组接入；后续发布到微信、抖音等小游戏平台时，再参考「小游戏」分组中对应平台的说明。
## 原生 App 与 Web [#原生-app-与-web]
| 接入平台 | SDK 下载 | Demo |
| --------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------- |
| **[Android](/docs/client-sdk/android/quickstart)** | [`Android SDK 下载`](https://github.com/GravityInfinite/GravityEngine-Android-Demo/releases) | [Demo](https://github.com/GravityInfinite/GravityEngine-Android-Demo) |
| **[iOS](/docs/client-sdk/ios/quickstart)** | [`iOS SDK 下载`](https://github.com/GravityInfinite/GravityEngine-iOS-Demo/releases) | [Demo](https://github.com/GravityInfinite/GravityEngine-iOS-Demo) |
| **[鸿蒙 HarmonyOS](/docs/client-sdk/harmonyos/quickstart)** | [`gravityengine_v2.0.12.zip`](/docs-assets/sdk/gravityengine_v2.0.12.zip "gravityengine_v2.0.12.zip") | — |
| **[C++](/docs/client-sdk/cpp/quickstart)** | [`C++ SDK 下载`](https://github.com/GravityInfinite/cpp-client-sdk/releases/) | [Demo](https://github.com/GravityInfinite/cpp-client-sdk/) |
| **[Web(JavaScript)](/docs/client-sdk/web/quickstart)** | [`ge_js_sdk_5.0.6.zip`](https://plutus-misc.oss-cn-beijing.aliyuncs.com/SDK/ge_js_sdk_5.0.6.zip "ge_js_sdk_5.0.6.zip") | — |
TikTok 接入请使用对应文档中的海外节点配置，勿直接沿用抖音国内配置。
## 游戏引擎 [#游戏引擎]
请先在对应引擎文档中确认目标平台及版本要求。发布到支持的小游戏平台时，使用引擎 SDK 的适配文件；发布到 Android、iOS、HarmonyOS 原生平台时，还需按引擎文档集成对应的原生 SDK 和桥接文件。
| 接入平台 | SDK 下载 | Demo |
| -------------------------------------------------------------- | ------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------- |
| **[Unity](/docs/client-sdk/unity/quickstart)** | [`Unity SDK 下载`](https://github.com/GravityInfinite/GravityEngine-Unity-Demo/releases) | [Demo](https://github.com/GravityInfinite/GravityEngine-Unity-Demo) |
| **[Cocos Creator](/docs/client-sdk/cocos-creator/quickstart)** | [`ge_cocoscreator_sdk_version.zip`](https://github.com/GravityInfinite/mpg-demos/releases) | [Demo](https://github.com/GravityInfinite/GravityEngine-Mini-Demo/tree/release/cocoscreatorv3.8.3-demo) |
| **[Laya](/docs/client-sdk/laya/quickstart)** | [`ge_laya_sdk_version.zip`](https://github.com/GravityInfinite/mpg-demos/releases) | [Demo](https://github.com/GravityInfinite/GravityEngine-Mini-Demo/tree/release/laya2-demo) |
| **[Egret](/docs/client-sdk/egret/quickstart)** | [`ge_egret_sdk_version.zip`](https://github.com/GravityInfinite/mpg-demos/releases) | [Demo](https://github.com/GravityInfinite/GravityEngine-Mini-Demo/tree/release/egret-demo) |
## 小游戏 [#小游戏]
| 接入平台 | SDK 下载 | Demo |
| ------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------- |
| **[微信小游戏(原生)](/docs/client-sdk/mini-games/wechat-quickstart)** | [`ge_mg_sdk_version.zip/gravityengine.mg.wx.min.js`](https://github.com/GravityInfinite/mpg-demos/releases) | [Demo](https://github.com/GravityInfinite/GravityEngine-Mini-Demo/tree/release/minigame-demo) |
| **[抖音小游戏(原生)](/docs/client-sdk/mini-games/douyin-quickstart)** | [`ge_mg_sdk_version.zip/gravityengine.mg.tt.min.js`](https://github.com/GravityInfinite/mpg-demos/releases) | [Demo](https://github.com/GravityInfinite/GravityEngine-Mini-Demo/tree/release/minigame-demo) |
| **[TikTok小游戏(原生)](/docs/client-sdk/mini-games/tiktok-quickstart)** | [`ge_mg_sdk_version.zip/gravityengine.mg.tt.min.js`](https://github.com/GravityInfinite/mpg-demos/releases) | [Demo](https://github.com/GravityInfinite/GravityEngine-Mini-Demo) |
| **[QQ小游戏(原生)](/docs/client-sdk/mini-games/qq-quickstart)** | [`ge_mg_sdk_version.zip/gravityengine.mg.qq.min.js`](https://github.com/GravityInfinite/mpg-demos/releases) | [Demo](https://github.com/GravityInfinite/GravityEngine-Mini-Demo/tree/release/minigame-demo) |
| **[快手小游戏(原生)](/docs/client-sdk/mini-games/kuaishou-quickstart)** | [`ge_mg_sdk_version.zip/gravityengine.mg.ks.min.js`](https://github.com/GravityInfinite/mpg-demos/releases) | [Demo](https://github.com/GravityInfinite/GravityEngine-Mini-Demo/tree/release/minigame-demo) |
| **[B站小游戏(原生)](/docs/client-sdk/mini-games/bilibili-quickstart)** | [`ge_mg_sdk_version.zip/gravityengine.mg.bl.min.js`](https://github.com/GravityInfinite/mpg-demos/releases) | [Demo](https://github.com/GravityInfinite/GravityEngine-Mini-Demo/tree/release/minigame-demo) |
| **[百度小游戏(原生)](/docs/client-sdk/mini-games/baidu-quickstart)** | [`ge_mg_sdk_version.zip/gravityengine.mg.swan.min.js`](https://github.com/GravityInfinite/mpg-demos/releases) | [Demo](https://github.com/GravityInfinite/GravityEngine-Mini-Demo/tree/release/minigame-demo) |
| **[支付宝小游戏(原生)](/docs/client-sdk/mini-games/alipay-quickstart)** | [`ge_mg_sdk_version.zip/gravityengine.mg.my.min.js`](https://github.com/GravityInfinite/mpg-demos/releases) | [Demo](https://github.com/GravityInfinite/GravityEngine-Mini-Demo/tree/release/minigame-demo) |
| **[闲鱼小游戏(原生)](/docs/client-sdk/mini-games/goofish-quickstart)** | [`ge_mg_sdk_version.zip/gravityengine.mg.goofish.min.js`](https://github.com/GravityInfinite/mpg-demos/releases) | [Demo](https://github.com/GravityInfinite/GravityEngine-Mini-Demo/tree/release/minigame-demo) |
| **[TapTap小游戏(原生)](/docs/client-sdk/mini-games/taptap-quickstart)** | [`ge_mg_sdk_version.zip/gravityengine.mg.tap.min.js`](https://github.com/GravityInfinite/mpg-demos/releases) | [Demo](https://github.com/GravityInfinite/GravityEngine-Mini-Demo/tree/release/minigame-demo) |
| **[芒果TV小游戏(原生)](/docs/client-sdk/mini-games/mgtv-quickstart)** | [`ge_mg_sdk_version.zip/gravityengine.mg.mgtv.min.js`](https://github.com/GravityInfinite/mpg-demos/releases) | [Demo](https://github.com/GravityInfinite/GravityEngine-Mini-Demo/tree/release/minigame-demo) |
| **[京东小游戏](/docs/client-sdk/mini-games/jd-quickstart)** | 不支持原生打包接入，请使用游戏引擎（Cocos Creator / Laya / Egret）方式接入 | [Demo](https://github.com/GravityInfinite/GravityEngine-Mini-Demo/tree/release/minigame-demo) |
| **[淘宝小游戏](/docs/client-sdk/mini-games/taobao-quickstart)** | 不支持原生打包接入，请使用游戏引擎（Cocos Creator / Laya / Egret）方式接入 | [Demo](https://github.com/GravityInfinite/GravityEngine-Mini-Demo/tree/release/minigame-demo) |
| **[美团小游戏](/docs/client-sdk/mini-games/meituan-quickstart)** | 不支持原生打包接入，请使用游戏引擎（Cocos Creator / Laya / Egret）方式接入 | [Demo](https://github.com/GravityInfinite/GravityEngine-Mini-Demo/tree/release/minigame-demo) |
## 小程序 [#小程序]
| 接入平台 | SDK 下载 | Demo |
| --------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------ |
| **[微信小程序(原生)](/docs/client-sdk/mini-programs/wechat-quickstart)** | [`ge_mp_sdk_version.zip/gravityengine.wx.min.js`](https://github.com/GravityInfinite/mpg-demos/releases) | [Demo](https://github.com/GravityInfinite/GravityEngine-Mini-Demo/tree/release/miniprogram-demo) |
| **[抖音小程序(原生)](/docs/client-sdk/mini-programs/douyin-quickstart)** | [`ge_mp_sdk_version.zip/gravityengine.tt.min.js`](https://github.com/GravityInfinite/mpg-demos/releases) | [Demo](https://github.com/GravityInfinite/GravityEngine-Mini-Demo) |
| **[TikTok小程序(原生)](/docs/client-sdk/mini-programs/tiktok-quickstart)** | [`ge_mp_sdk_version.zip/gravityengine.tt.min.js`](https://github.com/GravityInfinite/mpg-demos/releases) | [Demo](https://github.com/GravityInfinite/GravityEngine-Mini-Demo) |
| **[快手小程序(原生)](/docs/client-sdk/mini-programs/kuaishou-quickstart)** | [`ge_mp_sdk_version.zip/gravityengine.mp.ks.min.js`](https://github.com/GravityInfinite/mpg-demos/releases) | [Demo](https://github.com/GravityInfinite/GravityEngine-Mini-Demo) |
| **[百度小程序(原生)](/docs/client-sdk/mini-programs/baidu-quickstart)** | [`ge_mp_sdk_version.zip/gravityengine.mp.swan.min.js`](https://github.com/GravityInfinite/mpg-demos/releases) | [Demo](https://github.com/GravityInfinite/GravityEngine-Mini-Demo) |
| **[支付宝小程序(原生)](/docs/client-sdk/mini-programs/alipay-quickstart)** | [`ge_mp_sdk_version.zip/gravityengine.my.min.js`](https://github.com/GravityInfinite/mpg-demos/releases) | [Demo](https://github.com/GravityInfinite/GravityEngine-Mini-Demo) |
| **[京东小程序(原生)](/docs/client-sdk/mini-programs/jd-quickstart)** | [`ge_mp_sdk_version.zip/gravityengine.mp.jd.min.js`](https://github.com/GravityInfinite/mpg-demos/releases) | [Demo](https://github.com/GravityInfinite/GravityEngine-Mini-Demo) |
| **[钉钉小程序(原生)](/docs/client-sdk/mini-programs/dingtalk-quickstart)** | [`ge_mp_sdk_version.zip/gravityengine.mp.dd.min.js`](https://github.com/GravityInfinite/mpg-demos/releases) | [Demo](https://github.com/GravityInfinite/GravityEngine-Mini-Demo) |
| **[360小程序(原生)](/docs/client-sdk/mini-programs/360-quickstart)** | [`ge_mp_sdk_version.zip/gravityengine.mp.qh.min.js`](https://github.com/GravityInfinite/mpg-demos/releases) | [Demo](https://github.com/GravityInfinite/GravityEngine-Mini-Demo) |
## 快应用与快游戏 [#快应用与快游戏]
| 接入平台 | SDK 下载 | Demo |
| ----------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------- |
| **[快应用](/docs/client-sdk/quick-apps/quickstart)** | [`ge_mp_sdk_version.zip/gravityengine.quick.min.js`](https://github.com/GravityInfinite/mpg-demos/releases) | [Demo](https://github.com/GravityInfinite/GravityEngine-Mini-Demo/tree/release/quickapp-demo) |
| **[vivo快游戏](/docs/client-sdk/quick-games/vivo-quickstart)** | [`ge_mg_sdk_version.zip/gravityengine.mg.vivo.min.js`](https://github.com/GravityInfinite/mpg-demos/releases) | — |
| **[OPPO快游戏](/docs/client-sdk/quick-games/oppo-quickstart)** | [`ge_mg_sdk_version.zip/gravityengine.oppo.ks.min.js`](https://github.com/GravityInfinite/mpg-demos/releases) | — |
| **[小米快游戏](/docs/client-sdk/quick-games/xiaomi-quickstart)** | [`ge_mg_sdk_version.zip/gravityengine.mg.xiaomi.min.js`](https://github.com/GravityInfinite/mpg-demos/releases) | — |
| **[华为快游戏](/docs/client-sdk/quick-games/huawei-quickstart)** | 不支持原生打包接入，请使用游戏引擎方式接入 | — |
| **[荣耀快游戏](/docs/client-sdk/quick-games/honor-quickstart)** | 不支持原生打包接入，请使用 Cocos Creator 方式接入 | — |
| **[魅族快游戏](/docs/client-sdk/quick-games/meizu-quickstart)** | [`ge_mg_sdk_version.zip/gravityengine.mg.mz.min.js`](https://github.com/GravityInfinite/mpg-demos/releases) | — |
## 跨端框架 [#跨端框架]
| 接入平台 | SDK 下载 | Demo |
| ------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- |
| **[Flutter](/docs/client-sdk/flutter/quickstart)** | [`Flutter SDK 下载`](https://pub.dev/packages/gravity_engine_flutter_sdk) | [Demo](https://github.com/GravityInfinite/GravityEngine-Flutter-Demo) |
| **[Uni-APP](/docs/client-sdk/other-frameworks/uni-app-quickstart)** | [`ge_mp_sdk_version.zip/gravityengine.uniapp.js`](https://github.com/GravityInfinite/mpg-demos/releases) | — |
| **[Taro](/docs/client-sdk/other-frameworks/taro-quickstart)** | [`ge_mp_sdk_version.zip/gravityengine.taro.js`](https://github.com/GravityInfinite/mpg-demos/releases) | [Demo](https://github.com/GravityInfinite/GravityEngine-Mini-Demo/tree/release/taro-demo) |
# 服务端集成
> 来源：https://help.gravity-engine.com/docs/server-integration
> Gravity Engine 服务端集成索引，汇总接入总览、签名生成等主题，便于按功能进入对应的配置、接入或参考说明。
{/* Generated by scripts/generate-docs-routes.mjs. Do not edit. */}
## 目录 [#目录]
* [接入总览](/docs/server-integration/overview)
* [签名生成](/docs/server-integration/request-signing)
* [通用状态码](/docs/server-integration/status-codes)
* [报表查询](/docs/server-integration/reporting) — 子目录
* [事件采集](/docs/server-integration/event-collection) — 子目录
* [小游戏Token接入](/docs/server-integration/mini-game-tokens) — 子目录
* [其他](/docs/server-integration/other-apis) — 子目录
# 接入总览
> 来源：https://help.gravity-engine.com/docs/server-integration/overview
> 概述通过 API 或服务端 SDK 接入 Gravity Engine 高级能力的方式，并指引事件采集、报表查询和其他接口文档。
本指南将会为您介绍如何使用 API 的方式接入引力引擎部分高级能力。
由于广告归因需要采集很多参数，为避免重复造轮子，我们提供了 SDK 来封装好了数据采集的逻辑，API 接入方案建议只考虑用来查询报表或者上报某些重要的事件，例如：通过后端上报**付费和广告观看事件**，其他事件，建议使用 SDK 采集，这样能有效提高接入效率！
SDK 接入，请您参考[SDK 导览页](/docs/client-sdk/sdk-overview)。
## 选择接口与凭证 [#选择接口与凭证]
| 场景 | 使用凭证 | 接入要求 |
| -------------------------------------------------------------------------------- | --------------------------------------------- | ------------------------------------------------------------------------ |
| [事件采集上报](/docs/server-integration/event-collection/restful-api) | 引力应用 Access Token，放在 query 的 `access_token` | 客户端先完成用户初始化，再用相同 ClientID 上报；不套用 OpenAPI 签名 |
| [报表查询](/docs/server-integration/reporting)、导出和应用管理 | 开发者应用 `app_key`，用于生成 `sign` 和 `Authorization` | 开发者应用审核通过、启用且有目标应用权限；详见 [签名生成](/docs/server-integration/request-signing) |
| [微信/抖音 Token 透传](/docs/server-integration/mini-game-tokens/refresh-access-token) | 引力应用 Access Token、项目加密密钥和媒体 Token | 使用该接口专用签名；媒体 Token 与引力 Token 用途不同 |
请按具体接口准备参数，不要将后台网页登录 Token 作为 OpenAPI 的 `Authorization`。请求示例中的 `YOUR_SIGN`、`YOUR_AUTHORIZATION`、ID 和日期均需替换；修改请求体后必须重新生成签名和认证字符串。
## 功能入口 [#功能入口]
API 接入主要包括以下模块：
1. [事件采集上报](/docs/server-integration/event-collection)：您可以通过此模块的接口通过服务端上报事件给引力后台。
2. [Token 接入](/docs/server-integration/mini-game-tokens)：您可以通过此模块的接口对接小游戏平台的 Access Token 到引力后台。
3. [报表查询](/docs/server-integration/reporting)：查询报表，以及创建导出任务和获取下载结果。
4. [其他接口](/docs/server-integration/other-apis)：查询或创建应用、管理推广活动、批量上传素材。
## 判断结果与排错 [#判断结果与排错]
先检查 HTTP 状态，再检查响应中的 `code`、`msg`、`extra.error` 和接口要求的 `data` 字段。接口有特殊成功判断时，以该接口说明为准；事件采集还需核对事件流入库结果，导出任务需继续查询至完成。
限频、分页、时间范围和数据更新周期以各接口文档为准。遇到错误请参考 [通用状态码](/docs/server-integration/status-codes)；首次上线请完成 [接入验收与排错](/docs/getting-started/integration-checklist)。
# 签名生成
> 来源：https://help.gravity-engine.com/docs/server-integration/request-signing
> 说明 Gravity Engine OpenAPI 的 sign 与 Authorization 生成步骤，并提供 Java、Go 和 Python 示例代码。
调用引力服务端 openapi 接口时，部分接口需要 `Authorization` 和 `sign` 字段，本文主要给出示例，我们提供了以下 Java、Golang 和 Python 版本的示例，请参照示例生成签名。
主要分为两个方法：
1. 获取 sign
2. 获取 Authorization
现分别介绍如下。
## 1. 获取 sign [#1-获取-sign]
获取 `sign` 时，先组装 `params` 参数，参数为接口除了 `sign` 字段之外的其他所有字段的字典集合，组装完成后，调用 `getSign` 方法获取 sign 字符串。
> **注意**
> 针对 params 参数，不同的接口有不同的要求，具体请参考各个接口说明文档。
## 2. 获取 Authorization [#2-获取-authorization]
使用上一步获取的 `sign` 和 `app_key`，调用 `getAuthorization` 方法获取 `Authorization` 字符串，其中 `app_key` 为您申请的开发者应用的 key，您可以在[引力后台-设置-引力开发者](https://web.gravity-engine.com/#/manage/develop)中查看。
## 3. 代码示例 [#3-代码示例]
Python 示例依赖 `PyJWT`（安装命令：`python -m pip install PyJWT`，导入名为 `jwt`）。Java 示例依赖 Fastjson2、Guava 和 Hutool JWT；Go 示例使用所示 JWT 包，依赖版本请与项目统一。示例中的方法仅生成认证信息，不会发送请求。
签名依据服务端解析后的 JSON 值计算：对象键排序，非 ASCII 字符按 Unicode 转义，再按代码规则处理双引号和空格。不要自行增加 URL 编码、改变字段类型或遗漏实际发送的字段。跨语言使用浮点数或大整数时，还需核对数值精度和序列化结果；不要把 ID 转成浮点数。
**Java**
```java
package com.example;
import java.util.ArrayList;
import java.util.Collections;
import java.util.HashMap;
import java.util.List;
import java.util.Map;
import com.alibaba.fastjson2.JSONObject;
import com.alibaba.fastjson2.JSONWriter;
import com.google.common.base.Charsets;
import com.google.common.base.Joiner;
import com.google.common.collect.Maps;
import com.google.common.hash.Hashing;
import cn.hutool.jwt.JWTUtil;
import cn.hutool.jwt.signers.JWTSigner;
import cn.hutool.jwt.signers.JWTSignerUtil;
/**
* 引力引擎签名工具类
*/
public class SignUtil {
/**
* 字符串转Unicode编码
* @param string 原始字符串
* @return Unicode编码字符串
*/
public static String string2Unicode(String string) {
StringBuffer unicode = new StringBuffer();
for (int i = 0; i < string.length(); i++) {
char c = string.charAt(i);
if (c < 0x20 || c > 0x7E) {
String tmp = Integer.toHexString(c);
if (tmp.length() >= 4) {
unicode.append("\\u" + Integer.toHexString(c));
} else if (tmp.length() == 3) {
unicode.append("\\u0" + Integer.toHexString(c));
} else if (tmp.length() == 2) {
unicode.append("\\u00" + Integer.toHexString(c));
} else if (tmp.length() == 1) {
unicode.append("\\u000" + Integer.toHexString(c));
} else {
unicode.append("\\u0000");
}
} else {
unicode.append(c);
}
}
return unicode.toString();
}
/**
* 参数加签
* @param map 请求参数
* @param appKey 申请的引力APPKEY
* @return 签名字符串
*/
public static String getSign(Map map, String appKey) {
List params = new ArrayList<>();
for (Map.Entry entry : map.entrySet()) {
if (entry.getKey().equals("sign")) {
continue;
}
params.add(entry.getKey() + "=" + JSONObject.toJSONString(entry.getValue(), JSONWriter.Feature.MapSortField));
}
Collections.sort(params);
StringBuilder sb = new StringBuilder();
sb.append(Joiner.on("&").join(params));
sb.append(appKey);
String str = sb.toString().replaceAll("\"", "").replaceAll(" ", "");
return Hashing.md5().newHasher().putString(string2Unicode(str), Charsets.UTF_8).hash().toString();
}
/**
* 请求头加签
* @param appKey 申请的引力APPKEY
* @param sign 参数加签
* @return Authorization 请求头签名
*/
public static String getAuthorization(String appKey, String sign) {
HashMap payload = Maps.newHashMap();
payload.put("app_key", appKey);
JWTSigner jwtSigner = JWTSignerUtil.hs256(sign.getBytes());
return JWTUtil.createToken(payload, jwtSigner);
}
}
```
**Golang**
```go
package test
import (
"bytes"
"crypto/md5"
"encoding/json"
"fmt"
"github.com/dgrijalva/jwt-go"
"sort"
"strings"
"unicode/utf16"
)
// asciiEscape 与 Python json.dumps 的 ensure_ascii=True 保持一致。
func asciiEscape(s string) string {
var buf strings.Builder
for _, r := range s {
if r < 0x7f {
buf.WriteRune(r)
} else if r <= 0xffff {
fmt.Fprintf(&buf, "\\u%04x", r)
} else {
hi, lo := utf16.EncodeRune(r)
fmt.Fprintf(&buf, "\\u%04x\\u%04x", hi, lo)
}
}
return buf.String()
}
// 参数签名
// @param params map[string]interface{} 参数
// @param appKey string app key
func getSign(params map[string]interface{}, appKey string) string {
paramsList := make([]string, 0)
for k, v := range params {
if k == "sign" {
continue
}
var raw bytes.Buffer
encoder := json.NewEncoder(&raw)
encoder.SetEscapeHTML(false) // 保持 URL 中的 &、<、> 与 Python 示例一致
if err := encoder.Encode(v); err != nil {
panic(err) // 示例中止执行；业务代码应返回并处理错误
}
jsonString := asciiEscape(strings.TrimSuffix(raw.String(), "\n"))
paramString := fmt.Sprintf("%s=%s", k, jsonString)
paramsList = append(paramsList, paramString)
}
sort.Strings(paramsList)
currentString := strings.ReplaceAll(strings.ReplaceAll(strings.Join(paramsList, "&")+appKey, "\"", ""), " ", "")
sign := fmt.Sprintf("%x", md5.Sum([]byte(currentString)))
return sign
}
// 获取请求 authorization
// @param sign string 签名
// @param appKey 请求key
func getAuthorization(sign, appKey string) string {
type MyClaims struct {
AppKey string `json:"app_key"`
jwt.StandardClaims
}
claims := MyClaims{
AppKey: appKey,
StandardClaims: jwt.StandardClaims{},
}
t := jwt.NewWithClaims(jwt.SigningMethodHS256, claims)
token, _ := t.SignedString([]byte(sign))
return token
}
```
**Python**
```python
import json
import hashlib
import jwt
def get_sign(params: dict , app_key: str) -> str:
"""
@param params: 请求参数
@param app_key: 引力申请的开发者app_key
"""
param_list = []
for k, v in params.items():
if k == "sign":
continue
param_list.append(f"{k}={json.dumps(v,sort_keys=True)}")
param_list.sort()
sb = "&".join(param_list) + app_key
current_str = sb.replace("\"", "").replace(" ", "")
return hashlib.md5(current_str.encode("utf-8")).hexdigest()
def get_authorization(sign: str, app_key: str) -> str:
"""
@param sign: 签名
@param app_key: 引力申请的开发者app_key
"""
return jwt.encode({"app_key": app_key}, sign, algorithm="HS256")
```
## 4. 调用顺序与排错 [#4-调用顺序与排错]
1. 组装本次实际发送的 JSON body，暂不包含 `sign`。所有可选参数、分页和筛选条件都应先确定。
2. 用开发者应用的 `app_key` 生成 `sign`，将其加入 body。
3. 用同一个 `sign` 和 `app_key` 生成 HS256 JWT，将结果原样放入请求头 `Authorization`；不要使用后台登录 Token，也不要自行添加 `Bearer ` 前缀。
4. 发送请求。修改任何字段后，包括翻页，都重新执行上述步骤。
本页算法对应 OpenAPI。事件采集 API 使用应用 Access Token；微信/抖音 Token 透传和事件回调验签各有专用规则，请参考各自接口文档。
遇到“签名验证失败”或“APPKEY验证失败”时，先确认开发者应用已审核并启用、凭证来源正确，再比较用于签名与实际发送的 body。请保留脱敏后的请求及错误信息，勿公开完整凭证。
# 通用状态码
> 来源：https://help.gravity-engine.com/docs/server-integration/status-codes
> 列出 Gravity Engine 服务端接口的通用状态码（错误码）、错误含义与对应处理建议，供请求排查时参考。
以下为响应体 `code` 的业务状态码，请结合具体接口的 `msg`、`extra.error` 和返回数据排查。HTTP 状态码需单独检查，不要将业务 `code=301` 与 HTTP 重定向直接等同。
| **状态码** | **描述** | **解决方案** |
| ------- | --------- | ---------------------------------------------------------------- |
| 0 | 成功 | 1. 请求正常完成，无需额外处理。 |
| 301 | 请求地址有误 | 1. 检查URL路径是否完整（如末尾需加"/"） |
| 1000 | 未知错误 | 1. 检查日志获取更详细的错误信息。
2. 联系引力运营或技术支持。 |
| 1001 | 数据错误 | 1. 检查请求或返回的数据格式是否正确。
2. 验证数据完整性（如必要字段是否缺失）。 |
| 1002 | 超时 | 1. 检查网络连接是否稳定。
2. 稍后重试请求。 |
| 1003 | 表单错误 | 1. 检查提交的表单字段是否符合要求（类型、长度、必填项）。
2. 根据接口文档验证每个字段的格式。 |
| 1004 | 参数错误 | 1. 检查API调用时传入的参数是否正确（参数名、类型、值）。
2. 查阅接口文档，确认必填和可选参数。 |
| 1005 | 分页错误 | 1. 检查分页参数（如 page、size）是否有效且在规定范围内。 |
| 1006 | 校验错误 | 1. 检查输入数据是否符合业务规则（如手机号格式、邮箱格式、唯一性约束等）。 |
| 2000 | 权限不足 | 事件采集场景：确认 ClientID 有效且客户端已初始化成功。OpenAPI 场景：确认开发者应用、主体及目标应用的授权范围。 |
| 2001 | 应用未授权或已过期 | 检查目标应用的授权状态；OpenAPI 同时检查开发者应用是否审核通过并启用。凭证类型以当前接口要求为准。 |
| 3000 | 稍后再试 | 1. 请求过于频繁，请降低调用频率。
2. 等待一段时间（如 1 分钟、5 分钟）后再次尝试。 |
| 4002 | 接口不可用 | 1. 确认接口地址（URL）是否正确。 |
| 5000 | 系统错误 | 1. 服务器内部故障，请稍后重试。 |
# CocosCreator
> 来源：https://help.gravity-engine.com/docs/client-sdk/cocos-creator
> Cocos Creator SDK索引，汇总CocosCreator快速集成、行为事件上报等主题，便于按功能进入对应的配置、接入或参考说明。
{/* Generated by scripts/generate-docs-routes.mjs. Do not edit. */}
## 目录 [#目录]
* [CocosCreator快速集成](/docs/client-sdk/cocos-creator/quickstart)
* [行为事件上报](/docs/client-sdk/cocos-creator/track-events)
* [用户属性上报](/docs/client-sdk/cocos-creator/user-properties)
* [进阶功能](/docs/client-sdk/cocos-creator/advanced) — 子目录
# 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) 选择对应的框架接入文档。
## 支持平台 [#支持平台]
* 
微信小游戏
* 
快手小游戏（打包成微信小游戏）
* 
抖音/Tiktok 小游戏
* 
支付宝小游戏（v2.4.12以上，v3不限）
* 
OPPO快游戏
* VIVO快游戏
* 华为快游戏
* 荣耀快游戏（v2.4.15以上 或 v3.8.6以上）
* 小米快游戏
* 
百度小游戏
* 
淘宝小游戏（v2.4.12以上，v3不限）
* 
京东小游戏（打包成微信小游戏）
* 
美团小游戏（打包成微信小游戏）
* 
Android
* 
iOS
* 
Harmony
### **媒体平台SDK集成说明** [#媒体平台sdk集成说明]
**🎯 集成策略说明：**
CocosCreator SDK **仅针对【微信小游戏】平台** 集成了腾讯广告小游戏SDK。对于CocosCreator项目发布至其他平台（如抖音小游戏、快手小游戏等），**我们未集成任何媒体的SDK**。
#### **微信小游戏平台 ✅** [#微信小游戏平台-]
* **状态**：已集成腾讯广告小游戏SDK
* **上报方式**：需**手动调用**我们提供的方法进行事件上报
* **版本**：自 `4.8.40` 开始支持
> **重要说明**
> 按照《腾讯广告小游戏 SDK 集成》的步骤完成集成后，引力SDK会**自动上报**以下两个基础事件给腾讯：
>
> * REGISTER（用户注册）
> * RE\_ACTIVE（沉默唤起）
>
> 此外，**START\_APP（小游戏启动）**事件由腾讯SDK**自动采集**（引力SDK初始化腾讯SDK时默认开启该功能）。
>
> 除以上事件外，其他所有事件（如付费、自定义行为等）均需**客户端手动调用**我们提供的方法进行上报。
>
> 点击查看详细集成文档：[腾讯广告小游戏 SDK 集成](/docs/client-sdk/mini-games/advanced/tencent-ads-integration)
## 1. 获取 AccessToken [#1-获取-accesstoken]
您可以在[设置-应用管理](https://web.gravity-engine.com/#/manage/appmanage)页面点击 查看参数 按钮获取当前应用的 AccessToken ，请妥善保存避免泄露。
## 2. Native 平台支持 [#2-native-平台支持]
如果您的 Cocos Creator 项目需要支持 Android/iOS/Harmony 原生平台，请分别在 Cocos 导出的原生工程中完成对应平台的 SDK 集成，切换下方标签按平台查看：
**Android**
### 接入 Android SDK [#接入-android-sdk]
在 Cocos 导出的 Android 项目里，集成 Android 版本的 GravityEngineSDK 即可，参考 [Android 接入文档](/docs/client-sdk/android/quickstart)。
**iOS**
### 导入通道文件 [#导入通道文件]
将下载的 `CocosSDK/native/iOS` 下的 `GravityEngineCocosCreatorChannel.h` 和 `GravityEngineCocosCreatorChannel.mm` 类文件引入到 Cocos 导出的 iOS 项目下。
文件地址示例：
`CocosDemoProject/native/engine/ios/GravityEngineCocosCreatorChannel.h`
`CocosDemoProject/native/engine/ios/GravityEngineCocosCreatorChannel.mm`
### 接入 iOS SDK [#接入-ios-sdk]
在 Cocos 导出的 iOS 项目里集成 iOS 版本的 GravityEngineSDK，参考 [iOS 接入文档](/docs/client-sdk/ios/quickstart)。
**Harmony**
### 导入通道文件 [#导入通道文件-1]
将 `CocosSDK/native/harmonyos-next` 下的 `GravityEngineCocosCreatorChannel.ets` 类文件导入到 Cocos 导出的鸿蒙项目下。
文件地址示例：
`CocosDemoProject/native/engine/harmonyos-next/entry/src/main/ets/GravityEngineCocosCreatorChannel.ets`
### 通道配置 [#通道配置]
在 Cocos 导出的鸿蒙项目 `build-profile.json5` 中合并以下 `buildOption` 配置；这是配置片段，请保留文件中的其他字段：
文件地址示例：
`CocosDemoProject/native/engine/harmonyos-next/entry/build-profile.json5`
```json5
buildOption: {
arkOptions: {
runtimeOnly: {
sources: [
'./src/main/ets/GravityEngineCocosCreatorChannel.ets',
],
},
},
}
```
### 接入 Harmony SDK [#接入-harmony-sdk]
在 Cocos 导出的鸿蒙项目里集成 harmony 版本的 GravityEngineSDK，参考 [Harmony 接入文档](/docs/client-sdk/harmonyos/quickstart)。
### 建立通道 [#建立通道]
在 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);
}
}
```
## 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();
```
> **注意**
> 通过 **非自建中台** 的方式导入历史用户到引力时，默认以 Android\_ID 作为 `clientID`。SDK 需将 `mClientIdPriorityOrder` 设为 **Android\_ID 优先**（如 `["ANDROID_ID","OAID"]`），与导入规则保持一致，否则同一设备会被算作两个用户。
> **注意**
> **配置项目合法域名：** 您需要将 `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)
若您的产品内有广告变现，则需要在用户点击广告观看的同时上报用户广告观看事件给引力，具体参考如下：
**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 | 建议填写 |
**小游戏**
```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 | 是 |
## 6. 接入验证 [#6-接入验证]
> **注意**
> **正式上线之前，请完成本节的校验，否则可能会导致买量上报异常！**
### 6.1 关键事件验证 [#61-关键事件验证]
在引力后台[事件流](https://web.gravity-engine.com/#/manage/metadata/eventFlow) 界面开启**加载实时数据**，并在产品中触发以下几个事件。事件验收与排错：[接入验收与排错](/docs/getting-started/integration-checklist)
| 事件名 | 事件英文名 | 触发时机 | 采集方式 | 默认映射到媒体事件 | 备注 |
| ---- | ----------------------------------------- | ---------- | ---------------------- | --------- | ----------------------- |
| 用户注册 | APP:`$AppRegister`
小游戏:`$MPRegister` | 用户完成业务注册之后 | 调用SDK的**上报业务注册事件**方法采集 | 暂无 | 接入了**业务注册上报事件**的产品均需要校验 |
| 付费 | `$PayEvent` | 用户付费之后 | 调用SDK的**上报用户付费事件**方法采集 | 付费 | 接入了**付费事件上报事件**的产品均需要校验 |
| 广告展示 | `$AdShow` | 用户观看广告之后 | 调用SDK的**上报广告展示事件**方法采集 | 暂无 | 接入了**广告事件上报事件**的产品均需要校验 |
触发操作后，请在[事件流](https://web.gravity-engine.com/#/manage/metadata/eventFlow) 界面中筛选测试用户的 Client ID，观察对应事件是否出现在实时入库页面。若事件数据正常显示，则说明接入成功；如出现于错误数据页面请根据页面错误提示进行排查；如未显示对应数据，请及时联系引力运营支持团队获取协助。
### 6.2 避免重复上报 [#62-避免重复上报]
上线前，请按媒体和事件核对回传来源（引力回传、媒体 SDK 自动采集、客户端手动上报、自有服务端 API），确认同一转化不会通过多条链路重复回传。需要切换到引力回传的事件，应在验证新链路正常后停用原有重复链路；媒体 SDK 的其他功能是否保留，请按对应集成文档确认。
> **注意**
> 至此验证无误之后，您可以正常上线了。
# 行为事件上报
> 来源：https://help.gravity-engine.com/docs/client-sdk/cocos-creator/track-events
> 说明如何使用 Gravity Engine Cocos Creator SDK 上报业务事件，并管理事件公共属性。
本文档详细介绍了SDK提供的事件上报功能，帮助开发者全面采集用户行为事件数据，为业务分析和运营决策提供数据支持。
通过上报应用内用户行为事件，您可以：
* **完整记录用户行为**：追踪用户在应用内的关键操作路径
* **支持多维度分析**：通过事件属性丰富分析维度
* **构建数据闭环**：为产品优化和精准运营提供数据基础
## 1. 上报自定义事件 [#1-上报自定义事件]
> **注意**
> **如需上报自定义事件，您必须先在[元事件](https://web.gravity-engine.com/#/manage/metadata/metaEvent)中添加，否则会上报失败！**
您可以直接调用 `track` 上传自定义事件，建议您根据准备阶段梳理的文档来设置事件的属性以及发送信息的条件，此处以购买商品为范例：
```javascript
ge.track(
"$purchase", // 追踪事件的名称
{
Item: "商品A",
ItemNum: 1,
Cost: 100,
Elements: ["apple", "ball", "cat"],
} // 需要上传的事件属性
);
```
* `track` 接口共有两个参数，第一个参数为事件的名称，第二个参数为事件的属性。
* 事件的名称是字符串，只能以字母开头，可包含数字、字母和下划线 "\_"，长度最大为 50 个字符。
* 事件的属性是 JS 对象，每个元素代表一个属性。
* 元素的 name 对应属性的名称，规定只能以字母开头，包含数字、字母和下划线 "\_"，长度最大为 50 个字符。
* 元素的 Value 为该属性的值，支持 `String`、`Integer`、`Float`、`Boolean`、`Date`、`DateTime` 和 `Array`；`Array` 中的内容可以为 `String`。
## 2. 公共属性 [#2-公共属性]
> **注意**
> **公共属性需要先在[事件属性](https://web.gravity-engine.com/#/manage/metadata/eventProperty)中添加，否则会上报失败!**
公共事件属性是所有事件（包括自动采集事件）都会包含的属性，用户属性中不会包含。
本节会介绍如何设置公共事件属性和动态公共属性。如果公共属性与事件中设置的自定义属性有相同 key 值，则最终的属性会根据下述优先级取值：
用户自定义事件属性 > 动态公共属性 > 事件公共属性
您可以调用 `setSuperProperties` 来设置公共事件属性，公共事件属性的格式要求与事件属性一致。在设置时只能传入常量，适合设置变化不频繁的属性。
根据属性优先级，自定义属性优先级高于事件公共属性，因此事件公共属性也可以作为某个属性的缺省值，在需要修改的事件中设置同名 Key 覆盖缺省值。
### 2.1 设置公共属性 [#21-设置公共属性]
```javascript
// 设置公共事件属性
ge.setSuperProperties({ channel: "渠道" });
// 使用 track 上传事件，此时事件中会带有公共事件属性
ge.track(
"Purchase", // 追踪事件的名称
{
Item: "商品A",
ItemNum: 1,
Cost: 100,
} // 需要上传的事件属性
);
/* 等价于在事件中加入这些公共属性
ge.track(
'Purchase', // 追踪事件的名称
{
Item:'商品A',
ItemNum:1,
Cost:100,
channel:'渠道' // 相当于在事件中加入这个属性
}
);
*/
```
如果多次调用 `setSuperProperties` 设置公共事件属性，则同名字段后面的调用会覆盖之前的同名字段。
### 2.2 删除公共属性 [#22-删除公共属性]
如果您需要删除某个公共事件属性，可以调用 `unsetSuperProperty()` 清除其中一个公共事件属性。
```javascript
// 清除属性名为 CHANNEL 的公共属性
ge.unsetSuperProperty("CHANNEL");
```
### 2.3 清空公共属性 [#23-清空公共属性]
如果您想要清空所有公共事件属性，则可以调用 `clearSuperProperties()`。
```javascript
// 清除公共事件属性
ge.clearSuperProperties();
```
### 2.4 获取公共属性 [#24-获取公共属性]
如果您想要获取所有公共事件属性，可以调用 `getSuperProperties`。
```javascript
// 获取静态公共事件属性
ge.getSuperProperties();
```
## 3. 设置事件上报时间 [#3-设置事件上报时间]
事件触发的时间默认取本机时间，但在一些情况下，可能需要手动设置事件的时间，可以使用以下方法进行调用：
> **注意**
> **第三个参数为事件触发时间，必须是 Date 类型，将会替换事件触发的时间，如果不传该参数，则事件触发时间默认选取用户的本机时间。**
```javascript
// 第三个参数可以输入 Date 类型的参数，替换事件触发时间
ge.track("event", { parakey: "paravalue" }, new Date());
// 如果没有 properties 需要上传，请传入一个空对象
ge.track("event", {}, new Date());
```
## 4. 记录事件时长 [#4-记录事件时长]
您可以调用 `timeEvent` 来开始计时，配置您想要计时的事件名称，当您上传该事件时，将会自动在您的事件属性中加入 `$event_duration` 这一属性来表示记录的时长，单位为秒。
```javascript
// 用户进入商品页面，开始计时，记录的事件为 "Enter_Shop"
ge.timeEvent("Enter_Shop");
// ...
// 上传事件，计时结束，"Enter_Shop" 这一事件中将会带有表示事件时长的属性 $event_duration
ge.track("Enter_Shop", { product_id: "A1354" });
```
## 5. 立即上报事件 [#5-立即上报事件]
如果需要立即上报缓存的事件，可以调用 `flush` 来上报所有缓存的事件。
```javascript
ge.flush();
```
# 用户属性上报
> 来源：https://help.gravity-engine.com/docs/client-sdk/cocos-creator/user-properties
> 说明如何使用 Gravity Engine Cocos Creator SDK 设置、追加、累加和删除用户属性，并提供参数要求与调用示例。
本文档详细介绍了SDK提供的用户属性上报功能，帮助开发者高效地收集、更新和维护用户画像数据。
通过本功能，您可以：
* **全面记录用户特征**：存储用户基础信息（如昵称、性别）、行为偏好等关键数据
* **灵活更新用户画像**：支持覆盖、追加、数值计算等多种更新方式
* **构建精准用户模型**：通过属性组合分析，实现用户分群和个性化服务
> **注意**
> **如需上报自定义的用户属性，您必须先在[元数据](https://web.gravity-engine.com/#/manage/metadata/userProperty)中添加对应的用户属性，否则会上报失败！**
## 1. 设置用户属性 [#1-设置用户属性]
对于一般的用户属性，您可以调用 `userSet` 来进行设置，使用该接口上传的属性将会覆盖原有的属性值。
```javascript
// 设置用户属性，会员等级
ge.userSet({ vip_level: "钻石会员" });
```
> **注意**
> 属性格式要求与事件属性保持一致。
## 2. 初始化用户属性 [#2-初始化用户属性]
如果您要上传的用户属性只要设置一次，则可以调用 `userSetOnce` 来进行设置，当该属性之前已经有值的时候，将会忽略这条信息。
```javascript
// 以设置用户名为例，如果用户名已设置，则忽略本次设置
ge.userSetOnce({ user_name: "TestUser" });
```
> **注意**
> 属性格式要求与事件属性保持一致。
## 3. 累加用户属性 [#3-累加用户属性]
当您要上传数值型的属性时，您可以调用 `userAdd` 来对该属性进行累加操作。
```javascript
// 以付费为例，用户每次付费时调用此接口，则 'total_revenue' 字段每次会做累加付费金额的处理
ge.userAdd({ total_revenue: 50 });
```
> **注意**
> 设置的属性 key 为字符串，Value 只允许为数值。
## 4. 重置用户属性 [#4-重置用户属性]
当您要清空用户的某个用户属性值时，您可以调用 `userUnset` 来对指定属性进行清空操作。
```javascript
// 清空属性名为 userPropertyKey 的用户属性值，即设置为 NULL
ge.userUnset("userPropertyKey");
```
> **注意**
> `userUnset` 的传入值为被清空属性的 Key 值。
## 5. 清空用户属性 [#5-清空用户属性]
如果您要删除某个用户，可以调用 `userDel` 将这名用户删除，您将无法再查询该名用户的用户属性，但该用户产生的事件仍然可以被查询到。
```javascript
ge.userDel();
```
## 6. 用户属性追加（Array） [#6-用户属性追加array]
您可以调用 `userAppend` 对 Array（List）类型的用户数据追加元素。
```javascript
ge.userAppend({ Movies: ["Interstellar", "The Negro Motorist Green Book"] });
```
## 7. 用户属性去重追加（Array） [#7-用户属性去重追加array]
`userUniqAppend` 用来对 Array（List）类型的用户数据**去重**追加元素。
```javascript
ge.userUniqAppend({
Movies: ["Interstellar", "The Negro Motorist Green Book"],
});
```
## 8. 用户属性取最大值 [#8-用户属性取最大值]
`userNumberMax` 用来比较数值大小，保存较大的。
```javascript
ge.userNumberMax({
ad_ecpm_max: 300,
});
```
## 9. 用户属性取最小值 [#9-用户属性取最小值]
`userNumberMin` 用来比较数值大小，保存较小的。
```javascript
ge.userNumberMin({
ad_ecpm_min: 17,
});
```
# C++
> 来源：https://help.gravity-engine.com/docs/client-sdk/cpp
> C++ SDK索引，汇总C++快速集成、用户属性上报等主题，便于按功能进入对应的配置、接入或参考说明。
{/* Generated by scripts/generate-docs-routes.mjs. Do not edit. */}
## 目录 [#目录]
* [C++快速集成](/docs/client-sdk/cpp/quickstart)
* [用户属性上报](/docs/client-sdk/cpp/user-properties)
# C++快速集成
> 来源：https://help.gravity-engine.com/docs/client-sdk/cpp/quickstart
> 介绍 Gravity Engine C++ SDK 的安装、初始化、用户注册与事件上报流程，并提供参数说明和调用示例。
本文档为 **C++** 接入 [引力引擎](https://gravity-engine.com/) 的技术接入方案，建议您先阅读 [接入前准备](/docs/getting-started/overview) 以了解接入必备的基础概念。
## 1. SDK 基础配置 [#1-sdk-基础配置]
下载最新的 [SDK](/docs/client-sdk/sdk-overview) 文件，并导入到您的项目中。
将整个 `GravityEngineSDK/` 目录复制到您的项目中，然后用 CMake 引入。
### 1.1 CMake 接入（推荐） [#11-cmake-接入推荐]
SDK 通过 `target_include_directories PUBLIC` 自动将头文件路径传递给依赖它的目标，**无需手动配置 include 路径**。
**场景 A：SDK 在项目子目录内**
```
your_project/
├── GravityEngineSDK/ ← 复制到这里
├── src/
└── CMakeLists.txt
```
```cmake
add_subdirectory(GravityEngineSDK)
add_executable(your_app src/main.cpp)
target_link_libraries(your_app gedata)
```
**场景 B：SDK 与项目平级（如本 demo 的结构）**
```
workspace/
├── GravityEngineSDK/
└── your_project/
├── main.cpp
└── CMakeLists.txt
```
```cmake
set(SDK_DIR "${CMAKE_CURRENT_SOURCE_DIR}/../GravityEngineSDK")
add_subdirectory(${SDK_DIR} ${CMAKE_CURRENT_BINARY_DIR}/gedata_build)
add_executable(your_app main.cpp)
target_link_libraries(your_app gedata)
```
两种场景的源码写法完全相同：
```cpp
#include "GEAnalytics.h" // 无需写路径，CMake 自动处理
```
### 1.2 手动编译（macOS / Linux） [#12-手动编译macos--linux]
```bash
clang++ -std=c++11 \
-I GravityEngineSDK/include \
-I GravityEngineSDK/src \
GravityEngineSDK/src/*.cpp \
your_app.cpp \
-lcurl -lpthread \
-o your_app
# macOS 额外添加
# -framework IOKit -framework CoreFoundation
```
### 1.3 Windows（MSVC） [#13-windowsmsvc]
* 包含目录：`GravityEngineSDK\include`、`GravityEngineSDK\src`、`GravityEngineSDK\thirdParty\curl\include`
* 附加库目录：`GravityEngineSDK\thirdParty\curl\lib`
* 附加依赖项：`libcurl.lib`、`Advapi32.lib`
### 1.4 头文件引入 [#14-头文件引入]
```cpp
#include "GEAnalytics.h"
```
## 2. 初始化 [#2-初始化]
在用户可以获取到用户唯一性信息时调用 `initialize` 方法，后续其他方法均需在本方法回调成功之后才可正常使用。
> **注意**
> 首次调用后，需要在 `initialize` 回调成功之后**才能继续调用其他事件上报的方法**。
### 2.1 方法示例 [#21-方法示例]
```cpp
#include "GEAnalytics.h"
#include
#include
using namespace GEData;
int main() {
// 1. 配置初始化参数
GEPropertiesNode config;
config.SetString("access_token", "YOUR_ACCESS_TOKEN"); // 必填
config.SetString("client_id", "unique_device_id"); // 必填
config.SetBool ("is_china", true); // true=国内，false=海外
config.SetBool ("enable_log", true); // 开启调试日志
config.SetString("channel", "windows_store"); // 渠道名
config.SetString("name", "username"); // 用户名
config.SetNumber("version", 2); // 应用版本号
// 2. 初始化 SDK（异步，回调在后台线程触发）
GEAnalytics::initialize(config, [](bool ok, const std::string& msg) {
if (!ok) {
// 失败原因见 msg，常见：access_token 无效、网络不通
return;
}
// 3. 初始化成功后即可上报
GEPropertiesNode props;
props.SetString("scene", "launch");
GEAnalytics::track("$AppStart", props);
GEAnalytics::flush();
});
// 主循环占位（实际项目替换为你的事件循环）
std::this_thread::sleep_for(std::chrono::seconds(5));
GEAnalytics::close(); // 退出前必须调用
return 0;
}
```
### 2.2 参数说明 [#22-参数说明]
| **参数名称** | **参数含义** | **参数类型** | **是否必传** |
| ------------- | -------------------------------------------------------------------------------------------------------- | -------- | -------- |
| access\_token | 应用凭证。您可以在[设置-应用管理](https://web.gravity-engine.com/#/manage/appmanage)页面点击 **查看参数** 按钮获取当前应用的 AccessToken | string | 是 |
| client\_id | 当前用户在引力系统中的唯一标识 | string | 是 |
| is\_china | 是否使用国内域名 | bool | 是 |
| enable\_log | 是否打开日志 | bool | 否 |
| name | 用户名或用户唯一ID（可理解为业务中的昵称） | string | 否 |
| version | 用户初始化的程序发布更新的版本号 | number | 否 |
| channel | 当前用户来源渠道，对应用户细查中的：客户端渠道（默认值：base\_channel） | string | 否 |
## 3. 事件上报 [#3-事件上报]
### 3.1 事件上报 [#31-事件上报]
> **注意**
> **如需上报事件，您必须先在[元事件](https://web.gravity-engine.com/#/manage/metadata/metaEvent)中添加，否则会上报失败！**
建议您先在[元事件](https://web.gravity-engine.com/#/manage/metadata/metaEvent)中添加事件，然后在页面中指定位置埋点调用 `track` 方法上报自定义事件。
```cpp
GEPropertiesNode props;
props.SetString("item_id", "sku_001");
props.SetNumber("price", 99.9);
props.SetBool ("is_gift", false);
GEAnalytics::track("Purchase", props);
```
* 事件名称是 `string` 类型，只能以字母开头，可包含数字，字母和下划线 "\_"，长度最大为 50 个字符。
* 事件属性是 `Record` 类型，其中每个元素代表一个属性；
* 事件属性 `Key` 为属性名称，为 `string` 类型，规定只能以字母开头，包含数字，字母和下划线 "\_"，长度最大为 50 个字符；
* 属性 `Value` 支持 `string`、`number`、`boolean`、`Date`、`Array`；
当您调用 `track` 时，SDK 会取系统当前时间作为事件发生的时刻，如果您需要指定事件时间，可以传入 Date 类型的参数来设置事件触发时间。
> **注意**
> **尽管事件可以设置触发时间，但是接收端会做如下的限制：只接收相对服务器时间在前 10 天至后 1 小时的数据，超过时限的数据将会被视为异常数据，整条数据无法入库!**
### 3.2 数据上报控制 [#32-数据上报控制]
SDK 内部缓冲事件，累积满 20 条后自动触发网络请求。
```cpp
GEAnalytics::flush(); // 立即上报全部缓冲数据
GEAnalytics::close(); // flush 后释放资源（程序退出前必须调用）
```
> **注意**
> **注意：** 程序退出前未调用 `close()`，缓冲中不足 20 条的数据**不会**发送。
## 4. 接入验证 [#4-接入验证]
> **注意**
> **正式上线之前，请完成本节的校验，否则可能会导致买量上报异常！**
### 4.1 关键事件验证 [#41-关键事件验证]
在引力后台[事件流](https://web.gravity-engine.com/#/manage/metadata/eventFlow) 界面开启**加载实时数据**，并在产品中触发以下几个事件。事件验收与排错：[接入验收与排错](/docs/getting-started/integration-checklist)
| 事件名 | 事件英文名 | 触发时机 | 采集方式 | 默认映射到媒体事件 | 备注 |
| --- | ----------- | ------ | ---------------------- | --------- | ----------------------- |
| 付费 | `$PayEvent` | 用户付费之后 | 调用SDK的**上报用户付费事件**方法采集 | 付费 | 接入了**付费事件上报事件**的产品均需要校验 |
触发操作后，请在[事件流](https://web.gravity-engine.com/#/manage/metadata/eventFlow) 界面中筛选测试用户的 Client ID，观察对应事件是否出现在实时入库页面。若事件数据正常显示，则说明接入成功；如出现于错误数据页面请根据页面错误提示进行排查；如未显示对应数据，请及时联系引力运营支持团队获取协助。
### 4.2 避免重复上报 [#42-避免重复上报]
上线前，请按媒体和事件核对回传来源（引力回传、媒体 SDK 自动采集、客户端手动上报、自有服务端 API），确认同一转化不会通过多条链路重复回传。需要切换到引力回传的事件，应在验证新链路正常后停用原有重复链路；媒体 SDK 的其他功能是否保留，请按对应集成文档确认。
> **注意**
> 至此验证无误之后，您可以正常上线了。
# 用户属性上报
> 来源：https://help.gravity-engine.com/docs/client-sdk/cpp/user-properties
> 说明如何使用 Gravity Engine C++ SDK 设置、追加、累加和删除用户属性，并提供参数要求与调用示例。
本文档详细介绍了SDK提供的用户属性上报功能，帮助开发者高效地收集、更新和维护用户画像数据。
通过本功能，您可以：
* **全面记录用户特征**：存储用户基础信息（如昵称、性别）、行为偏好等关键数据
* **灵活更新用户画像**：支持覆盖、追加、数值计算等多种更新方式
* **构建精准用户模型**：通过属性组合分析，实现用户分群和个性化服务
> **注意**
> **如需上报自定义的用户属性，您必须先在[元数据](https://web.gravity-engine.com/#/manage/metadata/userProperty)中添加对应的用户属性，否则会上报失败！**
## 1. 设置用户属性 [#1-设置用户属性]
对于一般的用户属性，您可以调用 `user_set` 来进行设置，使用该接口上传的属性将会覆盖原有的属性值。
```cpp
GEPropertiesNode u;
u.SetString("username", "Alice");
GEAnalytics::user_set(u);
```
## 2. 初始化用户属性 [#2-初始化用户属性]
如果您要上传的用户属性只要设置一次，则可以调用 `user_set_once` 来进行设置，当该属性之前已经有值的时候，将会忽略这条信息。
```cpp
GEPropertiesNode r;
r.SetString("register_date", "2026-01-01");
GEAnalytics::user_set_once(r);
```
## 3. 累加用户属性 [#3-累加用户属性]
当您要上传数值型的属性时，您可以调用 `user_increment` 来对该属性进行累加操作，可传入负值，等同于相减操作。
```cpp
GEPropertiesNode n;
n.SetNumber("coins", 100);
GEAnalytics::user_increment(n);
```
> **注意**
> 设置的属性 key 为字符串，Value 只允许为数值。
## 4. 重置用户属性 [#4-重置用户属性]
如果您需要重置用户的某个属性，可以调用 `user_unset` 将该用户指定用户属性的值重置。
```cpp
GEPropertiesNode n;
n.SetNumber("coins", 0); // value 固定为 0
GEAnalytics::user_unset(n);
```
> **注意**
> `user_unset` 的传入 key 值为被重置属性的名称，value 固定为 0。
## 5. 清空用户属性 [#5-清空用户属性]
如果您要删除某个用户，可以调用 `user_del` 将这名用户删除，您将无法再查询该名用户的用户属性，但该用户产生的事件仍然可以被查询到。
```cpp
GEAnalytics::user_del();
```
## 6. 用户属性追加（Array） [#6-用户属性追加array]
您可以调用 `user_append` 对 Array (List) 类型的用户数据追加元素。
```cpp
GEPropertiesNode list_props;
std::vector tags = {"vip", "new"};
list_props.SetList("tags", tags);
GEAnalytics::user_append(list_props);
```
## 7. 用户属性去重追加（Array） [#7-用户属性去重追加array]
`user_uniq_append` 用来对 Array (List) 类型的用户数据**去重**追加元素。
```cpp
GEPropertiesNode list_props;
std::vector tags = {"vip", "new"};
list_props.SetList("tags", tags);
GEAnalytics::user_uniq_append(list_props);
```
# 发版记录
> 来源：https://help.gravity-engine.com/docs/client-sdk/android/changelog
> 记录 Gravity Engine Android SDK 各版本的发布日期、功能变更和升级备注，便于核对版本能力。
| 版本号 | 发布日期 | 备注 |
| ------ | ---------- | ---------------------------------------- |
| 5.0.37 | 2026-10-19 | 设备信息获取优化 |
| 5.0.36 | 2026-10-15 | 移除mac地址获取 |
| 5.0.35 | 2026-09-18 | 数据上报优化 |
| 5.0.34 | 2026-09-10 | 限制 $AdShow 的 $ad\_type 取值 |
| 5.0.33 | 2026-07-28 | 支持预设公共属性和归因信息，设备信息获取优化 |
| 5.0.32 | 2026-06-23 | 设备敏感信息获取限频 |
| 5.0.31 | 2026-06-03 | 接口请求移除敏感信息 |
| 5.0.30 | 2026-05-28 | 支持用户基础信息更新；支持获取华为归因 |
| 5.0.29 | 2026-04-16 | 优化初始化信息获取 |
| 5.0.28 | 2026-03-05 | 国内海外域名区分；演练模式接口优化 |
| 5.0.27 | 2026-02-09 | 新增获取设备信息方法；支持h5打通 |
| 5.0.26 | 2026-01-29 | 接入优化 |
| 5.0.25 | 2026-01-20 | 降低Android ID获取频率 |
| 5.0.24 | 2026-01-09 | 网络请求优化 |
| 5.0.23 | 2025-12-17 | 支持设置前台会话阀值,优化AppEnd时间统计 |
| 5.0.22 | 2025-12-12 | 支持设置 ClientId 取值顺序 |
| 5.0.21 | 2025-12-02 | SDK海外适配 |
| 5.0.20 | 2025-11-20 | 演练模式支持返回原因 |
| 5.0.19 | 2025-11-04 | 性能优化 |
| 5.0.18 | 2025-10-31 | 优化 flush 时机，性能优化提升，建议升级！ |
| 5.0.17 | 2025-10-24 | 更改接入方式，优化客户接入体验 |
| 5.0.16 | 2025-10-22 | 支持 enableMac 动态启停 Mac 采集 |
| 5.0.15 | 2025-10-13 | 接入优化 |
| 5.0.12 | 2025-09-19 | 修复华为设备未正确添加依赖时闪退的问题 |
| 5.0.8 | 2025-09-06 | 支持百度 bd\_vid 注入方案 |
| 5.0.7 | 2025-09-05 | 优化自动采集开启逻辑 |
| 5.0.6 | 2025-08-30 | 提供接入最佳实践，支持自动采集 ClientID |
| 5.0.3 | 2025-06-11 | 继续采集 $device\_id |
| 5.0.2 | 2025-04-25 | 优化设备 Id 采集 |
| 5.0.1 | 2025-04-23 | 性能优化 |
| 4.8.26 | 2025-04-21 | 优化信息采集 |
| 4.8.25 | 2025-03-25 | 优化设备 ID 上报时机 |
| 4.8.24 | 2025-02-28 | 优化 AndroidID 获取逻辑；避免客户误用 login、logout 方法 |
| 4.8.19 | 2024-11-30 | 进一步优化演练模式接入流程，降低接入门槛 |
| 4.8.15 | 2024-11-28 | 优化演练模式 |
| 4.8.12 | 2024-11-12 | Unity 支持演练模式 |
| 4.8.11 | 2024-09-26 | 优化性能 |
| 4.8.10 | 2024-08-28 | 优化性能 |
| 4.8.9 | 2024-08-01 | 适配高版本 |
| 4.8.6 | 2024-05-05 | 支持传入 mas 秘钥字符串；支持获取预置属性信息 |
| 4.8.4 | 2024-04-22 | 支持立即上报设备信息，优化设备信息采集成功率 |
| 4.8.3 | 2024-04-15 | bug fix |
| 4.7.8 | 2024-03-03 | 优化设备信息绑定逻辑 |
| 4.7.5 | 2024-01-22 | 优化性能问题 |
| 4.7.4 | 2023-12-26 | 放开可见性问题 |
| 4.7.3 | 2023-12-26 | 支持历史用户初始化 |
| 4.7.2 | 2023-12-11 | 接入流程优化，不再自动采集$AppRegister 事件 |
| 4.6.3 | 2023-11-23 | 优化 ID 获取逻辑 |
| 4.6.2 | 2023-11-06 | 优化 ID 获取逻辑 |
| 4.5.7 | 2023-10-20 | 注册接口支持返回注册的结构体信息；修复混淆问题 |
| 4.5.5 | 2023-09-20 | 支持同步获取归因结果信息 |
| 4.5.3 | 2023-08-30 | 支持查询用户信息接口 |
| 4.3.2 | 2023-07-14 | 性能优化 |
| 4.3.1 | 2023-07-13 | 支持重置 Client ID；支持打通三方数据平台 |
| 4.2.8 | 2023-06-29 | 性能优化 |
| 4.2.7 | 2023-06-23 | 性能优化 |
| 4.2.6 | 2023-06-16 | 支持 Unity 原生 Android 项目打通 |
| 4.2.5 | 2023-06-14 | 性能优化 |
| 4.2.4 | 2023-06-12 | 优化唯一 ID 逻辑，开放获取 |
| 4.2.3 | 2023-05-25 | 修复线上可能的崩溃，优化性能 |
| 4.2.2 | 2023-05-20 | 自动采集是否首次付费字段 |
| 4.2.1 | 2023-04-19 | 性能优化 |
| 4.2.0 | 2023-04-17 | 优化 login 方法 |
| 4.1.8 | 2023-04-03 | 1. 自动采集注册事件；2. 广告观看事件立即上报，避免数据 gap |
| 4.1.6 | 2023-03-20 | 支持自动标记是否首次付费属性 |
| 4.1.5 | 2023-03-16 | 支持全埋点自采集方案 |
| 4.1.3 | 2023-03-14 | 重构上线，解除 okhttp 和 androidx 依赖，优化事件采集性能。 |
# gravityengine合规使用指南
> 来源：https://help.gravity-engine.com/docs/client-sdk/android/compliance
> 说明 Android 应用接入 Gravity Engine SDK 时的个人信息处理、隐私授权、初始化时机与合规配置要求。
根据《个人信息保护法》、《数据安全法》、《网络安全法》等法律法规和监管部门规章要求，App 开发运营者（以下简称为“开发者”）在提供网络产品服务时应尊重和保护最终用户的个人信息，不得违法违规收集使用个人信息，保证和承诺就个人信息处理行为获得最终用户的授权同意，遵循最小必要原则，且应当采取有效的技术措施和组织措施确保个人信息安全。
为帮助开发者在使用 gravityengineSDK 的过程中更好地落实用户个人信息保护相关要求，避免出现侵害最终用户个人信息权益的情形，特制定本合规使用说明，供开发者在接入使用 gravityengineSDK 服务时参照自查和合理配置，不断提升个人信息保护水平。
## SDK 个人信息说明 [#sdk-个人信息说明]
**要求内容：** 《SDK合规使用说明》应详细说明 SDK 各项个人信息使用目的、场景及对应关闭的配置方式、示例。
**gravityengineSDK 个人信息说明：**
| 产品功能类型 | 产品功能名称 | 个人信息类型及字段 | 是否必选 | 用途和目的 | 关闭方式 |
| ------ | ------ | ----------------------------------------- | ---- | ------------------------------ | ------------------------------- |
| 基本功能 | 数据统计 | 设备唯一标识（包括 Android ID） | 可选 | 用于生成终端用户设备唯一标识，以确保数据统计的准确性 | `config.enableAndroidId(false)` |
| | | 设备唯一标识（包括 IMEI、MEID） | 可选 | 用于生成终端用户设备唯一标识，以确保数据统计的准确性 | `config.enableIMEI(false)` |
| | | 设备唯一标识（包括 OAID） | 可选 | 帮助你分析用户来源，便于优化应用推广等。 | `config.enableOAID(false)` |
| | | 设备唯一标识（包括 MAC、BSSID、SSID） | 可选 | 用于生成终端用户设备唯一标识，以确保数据统计的准确性 | `config.enableMAC(false)` |
| | | 设备硬件信息（包括操作系统版本、设备制造商、操作系统、设备型号、屏幕分辨率） | 必选 | 用于保证服务在不同设备上的兼容性，确保服务准确生效 | 基础功能，必要信息 |
| | | 网络信息（包括 IP 地址、国家、国家代码、省份、城市、网络状态、网络运营商） | 必选 | 用于判断用户所在地区，保证归因及数据统计的准确性 | 基础功能，必要信息 |
| | | 应用信息（包括 App 版本、应用唯一标识、SDK 类型、SDK 版本） | 必选 | 用于保证服务在不同版本上的兼容性，确保服务准确生效 | 基础功能，必要信息 |
| | | 用户行为信息（包括页面地址、前向地址、页面标题、页面名称、事件时长、后台事件时长） | 必选 | 帮助你分析用户应用内行为路径，便于优化应用内容，提高留存等。 | 基础功能，必要信息 |
## SDK 可按照不同频次、精度收集个人信息的配置说明 [#sdk-可按照不同频次精度收集个人信息的配置说明]
**要求内容：** 如果 SDK 可按照不同频次、精度收集个人信息的，《SDK合规使用说明》应说明不同频次的使用目的、场景及对应选择的配置方式、示例。
**接入说明：** 收集频次方面，gravityengineSDK 的数据采集仅在 App 调用/最终用户触发相关功能时触发，不涉及定时逻辑等频次控制选项。App 如欲控制数据采集频次，可通过重载主动控制器，接管相关数据项对应系统 API 的调用时机，进而控制数据采集频次。
**gravityengineSDK 个人信息收集频次及对应配置情况：**
| 个人信息类型及字段 | 是否可配置 | 用途和目的 | 频次 |
| ----------------------------------------- | ----- | ------------------------------ | ----------- |
| 设备唯一标识（包括 Android ID、IMEI、MEID、OAID、MAC） | 可配置 | 用于生成终端用户设备唯一标识，以确保数据统计的准确性 | SDK 启动时采集一次 |
| 设备硬件信息（包括操作系统版本、设备制造商、操作系统、设备型号、屏幕分辨率） | 不可配置 | 用于保证服务在不同设备上的兼容性，确保服务准确生效 | SDK 启动时采集一次 |
| 网络信息（包括 IP 地址、国家、国家代码、省份、城市、网络状态、网络运营商） | 不可配置 | 用于判断用户所在地区，保证归因及数据统计的准确性 | SDK 启动时采集一次 |
| 应用信息（包括 App 版本、应用唯一标识、SDK 类型、SDK 版本） | 不可配置 | 用于保证服务在不同版本上的兼容性，确保服务准确生效 | SDK 启动时采集一次 |
| 用户行为信息（包括页面地址、前向地址、页面标题、页面名称、事件时长、后台事件时长） | 不可配置 | 帮助你分析用户应用内行为路径，便于优化应用内容，提高留存等。 | 客户主动调用时采集一次 |
## SDK 申请系统权限的说明 [#sdk-申请系统权限的说明]
**要求内容：** 《SDK合规使用说明》应详细说明 SDK 所需的系统权限与各业务功能间的关系，并说明权限申请时机。
**接入说明：** 对于 gravityengineSDK 可选申请的系统权限，您可以参考相关如下表格的内容，详细了解相关权限与各业务功能的关系及其申请时机。gravityengineSDK 不主动申请可选系统权限，但相关权限的不申请将会对其对应的功能造成影响，您可以结合业务实际需要进行合理配置。
**Android 操作系统应用权限列表：**
| 权限 | 权限功能说明 | 用途和目的 | 申请时机 |
| ------------------------ | ---------------------- | ----------------------------------- | --------------------- |
| READ\_PHONE\_STATE | 【可选】允许应用获取设备 IMEI、MEID | 用于获取设备标识符，实现广告归因等业务功能 | 开启 IMEI 采集之后获取 IMEI 时 |
| INTERNET | 【必选】允许应用使用网络 | 用于连接网络，实现 gravityengine 业务所需的日志上报功能 | 上报事件时 |
| ACCESS\_NETWORK\_STATE | 【必选】允许应用检测网络状态 | 用于检测当前网络信息，SDK 会根据网络状态选择是否发送数据 | 上报事件时 |
| READ\_EXTERNAL\_STORAGE | 【可选】允许应用读取文件内容 | 用于读取本地缓存中的设备标识等信息 | SDK 启动时 |
| WRITE\_EXTERNAL\_STORAGE | 【可选】允许应用写入文件内容 | 用于将设备标识等信息写入本地缓存 | SDK 启动时 |
## SDK 初始化及业务功能调用时机 [#sdk-初始化及业务功能调用时机]
**要求内容：** 《SDK合规使用说明》应详细说明 SDK 初始化及各项业务功能接口合规调用时机。App 应当在 App 登录注册页面及 App 首次运行时，通过弹窗、文本链接及附件等简洁明显且易于访问的方式，向最终用户告知涵盖个人信息处理主体、处理目的、处理方式、处理类型、保存期限等内容的个人信息处理规则，并且获得最终用户授权同意后才能处置最终用户数据。
**接入说明：** 请务必在用户同意您 App 中的隐私政策后，再进行 gravityengineSDK 的初始化。用户同意隐私政策之前，避免动态申请涉及用户个人信息的敏感设备权限；用户同意隐私政策前，您应避免私自采集和上报个人信息。当您的 App 未向用户提供服务时，例如 App 在后台运行时，请勿请求 gravityengineSDK 的相关服务。启动 SDK 方法不会采集设备信息，也不会向引力引擎后台上报数据；只有在用户同意《隐私政策》之后调用正式初始化方法，SDK 才会真正采集设备信息并上报数据。具体示例请参考下方案例：
```java
if (用户同意隐私政策弹窗) {
GEConfig config = GEConfig.getInstance(context, ACCESS_TOKEN);
GravityEngineSDK.setupAndStart(config);
}
```
## SDK 隐私政策披露要求与示例 [#sdk-隐私政策披露要求与示例]
**要求内容：** 《SDK合规使用说明》应提供 App 向最终用户披露 SDK 隐私政策条款的示例，包括 SDK 名称、公司名、处理个人信息种类及目的、采集方式、隐私政策链接等内容。
**接入说明：** 开发者在 App 集成 gravityengineSDK 后，gravityengineSDK 的正常运行会收集必要的最终用户信息，实现用户行为分析、数据归因等功能。请开发者根据集成 gravityengineSDK 的实际情况，在您 App 的隐私政策中，对 gravityengineSDK 名称、公司名称、处理个人信息种类及目的、采集方式、隐私政策链接等内容进行披露。
**披露示例：**
**SDK名称**：gravityengine
**涉及个人信息**：
| 个人信息类型及字段 | 用途和目的 |
| ----------------------------------------- | ------------------------------ |
| 设备唯一标识（包括 Android ID、IMEI、MEID、OAID、MAC） | 用于生成终端用户设备唯一标识，以确保数据统计的准确性 |
| 设备硬件信息（包括操作系统版本、设备制造商、操作系统、设备型号、屏幕分辨率） | 用于保证服务在不同设备上的兼容性，确保服务准确生效 |
| 网络信息（包括 IP 地址、国家、国家代码、省份、城市、网络状态、网络运营商） | 用于判断用户所在地区，保证归因及数据统计的准确性 |
| 应用信息（包括 App 版本、应用唯一标识、SDK 类型、SDK 版本） | 用于保证服务在不同版本上的兼容性，确保服务准确生效 |
| 用户行为信息（包括页面地址、前向地址、页面标题、页面名称、事件时长、后台事件时长） | 帮助你分析用户应用内行为路径，便于优化应用内容，提高留存等。 |
**合作方主体**：深圳引力引擎科技有限公司
**使用目的**：实现广告监测归因、投放效果优化等与广告活动相关的使用目的
**使用场景**：广告监测归因、投放效果优化的场景
**收集方式**：SDK自行采集
**官网链接**：[https://www.gravity-engine.com/](https://www.gravity-engine.com/)
**隐私政策链接**：[https://www.gravity-engine.com/h-col-101.html](https://www.gravity-engine.com/h-col-101.html)
## 最终用户同意方式的示例 [#最终用户同意方式的示例]
**要求内容：** 《SDK合规使用说明》应详细说明 App 获取最终用户授权同意的建议方式，其中需要取得最终用户单独同意的，应显著提示并给出示例。
**接入说明：** App 首次运行时应当有隐私弹窗，隐私弹窗中应公示简版隐私政策内容并附完整版隐私政策链接，并明确提示最终用户阅读并选择是否同意隐私政策；隐私弹窗应提供同意按钮和拒绝同意的按钮，并由最终用户主动选择。
## 最终用户行使权利的配置说明 [#最终用户行使权利的配置说明]
**要求内容：** 最终用户对其个人信息的处理享有知情、决定、查阅、复制、补充、更正、撤回授权同意、删除、注销账号等权利。以嵌入接口形式向最终用户提供行使权利的，应提供接口调用方式、示例。
**接入说明：** 开发者在其 App 中集成 gravityengineSDK 后，gravityengineSDK 的正常运行会收集必要的最终用户信息用于实现用户行为分析、数据归因等功能。开发者应根据相关法律法规为最终用户提供行使个人信息主体权利的路径或功能，需要 gravityengineSDK 配合的，请与 gravityengineSDK 及时进行联系，我们将与开发者协同妥善解决最终用户的诉求。联系客服电子邮箱地址：[client@gravity-engine.com](mailto:client@gravity-engine.com)
## 针对儿童隐私保护的特别说明 [#针对儿童隐私保护的特别说明]
**要求内容：** 若您的应用需遵守美国的《儿童在线隐私权保护法》(COPPA) 或其他类似法规，或您的应用目标用户包含或主要面向 13 周岁以下的儿童，您有责任将该应用标识为“儿童应用”。
**接入说明：** 为确保符合相关法规，请在初始化 `GEConfig` 时将应用明确标记为儿童应用（Kids App），此设置会影响 SDK 对特定数据的处理逻辑，以满足儿童隐私保护的特殊要求。示例：
```java
GEConfig config = GEConfig.getInstance(context, ACCESS_TOKEN);
config.setKidsAppEnabled(true); // 标记为儿童应用，5.0.21 及以上版本支持
config.setCoppaEnabled(true); // 需符合《儿童在线隐私权保护法》(COPPA)，5.0.21 及以上版本支持
GravityEngineSDK.setupAndStart(config);
```
请开发者知悉，引力引擎 SDK 不主动识别用户年龄。**您作为应用提供方，是履行 COPPA 等法规的首要责任人**，这包括但不限于：对应用是否面向儿童做出准确判断；在采集、使用或分享儿童个人信息前，获取可验证的家长同意；在应用内实施上述标记配置。
## 针对欧盟《通用数据保护条例》(GDPR)的合规说明 [#针对欧盟通用数据保护条例gdpr的合规说明]
**要求内容：** 为支持开发者在欧盟地区遵守《通用数据保护条例》(GDPR)，gravityengineSDK 提供专门的配置接口，通过设置控制对特定敏感个人数据的采集行为，为开发者履行“数据最小化”等原则提供技术工具。
**接入说明：** SDK 初始化时默认不将用户识别为 GDPR 管辖区域的用户（对应参数为 `FALSE`），此状态下 SDK 会采集包括设备标识符（如 Android ID、OAID）在内的信息，以保障广告归因、数据分析等核心功能的正常运行。开发者可明确告知 SDK 当前用户是否位于 GDPR 管辖区域，一旦将用户标记为 GDPR 区域用户，SDK 将默认不再采集 Android ID、OAID 等设备标识符。此设置可在 SDK 启动时配置，示例：
```java
GEConfig config = GEConfig.getInstance(context, ACCESS_TOKEN);
config.isGDPRArea(true); // 标记为 GDPR 管辖区域用户，5.0.21 及以上版本支持
GravityEngineSDK.setupAndStart(config);
```
**重要操作指引：** 您需要根据应用服务的实际用户群体和地理位置，自主判断并调用此功能，**此功能仅供处理 GDPR 管辖区域内用户的场景下使用**。对于明确知晓的非 GDPR 区域用户，**请勿调用**此设置，误操作可能导致无法采集必要的设备标识符，进而影响广告归因、数据分析等核心功能的准确性，甚至导致关键数据丢失，请务必谨慎评估后使用。
# GooglePlay上线指南
> 来源：https://help.gravity-engine.com/docs/client-sdk/android/google-play-release
> 说明集成 Gravity Engine Android SDK 的应用在 Google Play 上架时如何填写数据安全表单。
## 1. 数据收集与安全性 [#1-数据收集与安全性]
| 问题 | 是 | 否 |
| -------------------------- | - | - |
| 您的应用是否会收集或分享任何必须披露的用户数据类型？ | ✅ | |
| 您的应用收集的所有用户数据在传输过程中是否会加密？ | ✅ | |
| 您是否为用户提供了请求删除其数据的方法？ | ✅ | |
## 2. 数据类型 [#2-数据类型]
| 位置 | 无 |
| ------------ | ----------------- |
| 个人信息 | 名称，用户ID，其他信息 |
| 财务信息 | 无 |
| 健康与健身 | 无 |
| 信息 | 其他应用内消息 |
| 照片和视频 | 无 |
| 音频文件 | 无 |
| 文件和文档 | 无 |
| 日历 | 无 |
| 通讯录 | 无 |
| 应用活动 | 已安装的应用，其他由用户生成的内容 |
| 网页浏览 | 无 |
| 应用信息和性能 | 崩溃日志 |
| 设备 ID 或其他 ID | 设备 ID 或其他 ID |
## 3. 数据使用和处理 [#3-数据使用和处理]
### 个人信息 [#个人信息]
#### 名称 [#名称]
| 您是否会收集和/或分享这些数据？ | 收集数据 |
| ------------------------------------ | ------------------------ |
| 这些数据是临时处理的数据吗？ | 否，收集的此类数据不会受到临时处理 |
| 您的应用是否必须使用这些数据，还是用户可以选择是否要让应用收集这些数据？ | 必须收集这些数据（用户无法关闭这项数据收集操作） |
| 为什么要收集这些用户数据？请选择所有适用的选项。 | 应用功能，分析，账号管理 |
#### 用户ID [#用户id]
| 您是否会收集和/或分享这些数据？ | 收集数据 |
| ------------------------------------ | ------------------------ |
| 这些数据是临时处理的数据吗？ | 否，收集的此类数据不会受到临时处理 |
| 您的应用是否必须使用这些数据，还是用户可以选择是否要让应用收集这些数据？ | 必须收集这些数据（用户无法关闭这项数据收集操作） |
| 为什么要收集这些用户数据？请选择所有适用的选项。 | 应用功能，分析，个性定制，账号管理 |
#### 其他信息 [#其他信息]
| 您是否会收集和/或分享这些数据？ | 收集数据 |
| ------------------------------------ | ------------------------ |
| 这些数据是临时处理的数据吗？ | 否，收集的此类数据不会受到临时处理 |
| 您的应用是否必须使用这些数据，还是用户可以选择是否要让应用收集这些数据？ | 必须收集这些数据（用户无法关闭这项数据收集操作） |
| 为什么要收集这些用户数据？请选择所有适用的选项。 | 应用功能，分析，账号管理 |
### 信息 [#信息]
#### 其他应用内消息 [#其他应用内消息]
| 您是否会收集和/或分享这些数据？ | 收集数据 |
| ------------------------------------ | ------------------------ |
| 这些数据是临时处理的数据吗？ | 否，收集的此类数据不会受到临时处理 |
| 您的应用是否必须使用这些数据，还是用户可以选择是否要让应用收集这些数据？ | 必须收集这些数据（用户无法关闭这项数据收集操作） |
| 为什么要收集这些用户数据？请选择所有适用的选项。 | 应用功能，分析，账号管理 |
### 应用信息和性能 [#应用信息和性能]
#### 崩溃日志 [#崩溃日志]
| 您是否会收集和/或分享这些数据？ | 收集数据 |
| ------------------------------------ | ------------------------ |
| 这些数据是临时处理的数据吗？ | 否，收集的此类数据不会受到临时处理 |
| 您的应用是否必须使用这些数据，还是用户可以选择是否要让应用收集这些数据？ | 必须收集这些数据（用户无法关闭这项数据收集操作） |
| 为什么要收集这些用户数据？请选择所有适用的选项。 | 分析 |
### 应用活动 [#应用活动]
#### 已安装的应用 [#已安装的应用]
| 您是否会收集和/或分享这些数据？ | 收集数据 |
| ------------------------------------ | ------------------------ |
| 这些数据是临时处理的数据吗？ | 否，收集的此类数据不会受到临时处理 |
| 您的应用是否必须使用这些数据，还是用户可以选择是否要让应用收集这些数据？ | 必须收集这些数据（用户无法关闭这项数据收集操作） |
| 为什么要收集这些用户数据？请选择所有适用的选项。 | 应用功能，个性定制 |
#### 其他由用户生成的内容 [#其他由用户生成的内容]
| 您是否会收集和/或分享这些数据？ | 收集数据 |
| ------------------------------------ | ------------------------ |
| 这些数据是临时处理的数据吗？ | 否，收集的此类数据不会受到临时处理 |
| 您的应用是否必须使用这些数据，还是用户可以选择是否要让应用收集这些数据？ | 必须收集这些数据（用户无法关闭这项数据收集操作） |
| 为什么要收集这些用户数据？请选择所有适用的选项。 | 分析 |
### 设备 ID 或其他 ID [#设备-id-或其他-id]
| 您是否会收集和/或分享这些数据？ | 收集数据 |
| ------------------------------------ | ------------------------ |
| 这些数据是临时处理的数据吗？ | 否，收集的此类数据不会受到临时处理 |
| 您的应用是否必须使用这些数据，还是用户可以选择是否要让应用收集这些数据？ | 必须收集这些数据（用户无法关闭这项数据收集操作） |
| 为什么要收集这些用户数据？请选择所有适用的选项。 | 应用功能，分析，个性定制，账号管理 |
## 4. 谷歌的数据安全问卷 [#4-谷歌的数据安全问卷]
根据[Google 的数据安全要求](https://support.google.com/googleplay/android-developer/answer/10787469?hl=en#zippy=%2Cdata-types%2Cwhat-users-will-see%2Cdata-collection%2Cpurposes%2Coptional-format-for-sdks%2Cdata-sharing%2Cdata-handling%2Cother-app-and-data-disclosures%2Ccommitted-to-follow-the-families-policy-available-soon-to-applicable-apps%2Cam-i-required-to-provide-a-deletion-mechanism-must-it-be-for-any-and-all-user-data%2Chow-should-i-treat-the-collection-and-use-of-ip-addresses)，应用程序开发者需要定义他们的应用程序和集成在他们的应用程序中的 SDK 收集哪些数据。
下表指定了引力SDK收集的数据，可以用来正确准确地回答谷歌的数据安全问卷。
| 数据类型 | 目的 | 必须/可选 | 从设备传输 | 与其他第三方共享 |
| ----------- | --------- | ----- | ----- | -------- |
| 大概位置（IP 地址） | 应用功能，分析 | 必须 | 否 | 否 |
| 已安装的应用 | 应用功能，个性定制 | 必须 | 是 | 否 |
| 崩溃日志 | 分析 | 可选 | 是 | 否 |
| 设备或其他标识符 | 分析 | 可选 | 是 | 否 |
| 问题 | 是否 |
| ------ | -- |
| 传输中的加密 | 是的 |
| 支持删除请求 | 是的 |
# Android
> 来源：https://help.gravity-engine.com/docs/client-sdk/android
> Android SDK索引，汇总快速集成、行为事件上报等主题，便于按功能进入对应的配置、接入或参考说明。
{/* Generated by scripts/generate-docs-routes.mjs. Do not edit. */}
## 目录 [#目录]
* [快速集成](/docs/client-sdk/android/quickstart)
* [行为事件上报](/docs/client-sdk/android/track-events)
* [用户属性上报](/docs/client-sdk/android/user-properties)
* [进阶功能](/docs/client-sdk/android/advanced) — 子目录
* [GooglePlay上线指南](/docs/client-sdk/android/google-play-release)
* [gravityengine合规使用指南](/docs/client-sdk/android/compliance)
* [Android SDK下载](/docs/client-sdk/android/sdk-download)
* [发版记录](/docs/client-sdk/android/changelog)
# 快速集成
> 来源：https://help.gravity-engine.com/docs/client-sdk/android/quickstart
> 介绍 Gravity Engine Android SDK 的安装、初始化、用户注册与事件上报流程，并提供参数说明和调用示例。
本文档主要讲述 **Android** 原生包接入 [引力引擎](https://gravity-engine.com/) 的技术接入方案，在开始接入前，建议您先阅读 [接入前准备](/docs/getting-started/overview)以了解接入必备的基础概念。
> **重要说明**
> Android SDK**未集成任何媒体SDK**（如巨量引擎、腾讯广告等）。如您需要在Android端上报事件给媒体平台，请：
>
> 1. **自行集成**所需媒体的官方SDK
> 2. 按照各媒体的文档要求进行事件上报
## 1. 获取 AccessToken [#1-获取-accesstoken]
您可以在[设置-应用管理](https://web.gravity-engine.com/#/manage/appmanage)页面点击 查看参数 按钮获取当前应用的 AccessToken ，请妥善保存避免泄露。
## 2. 集成 SDK [#2-集成-sdk]
### 2.1 自动集成(推荐) [#21-自动集成推荐]
* 在 `Project` 级别的 `build.gradle` 文件中添加如下配置依赖：
```groovy
maven { url 'https://nexus.gravity-engine.com/repository/maven-releases/' }
maven { url 'https://nexus.gravity-engine.com/repository/maven-snapshots/' }
maven { url 'https://developer.huawei.com/repo' }
maven { url 'https://developer.hihonor.com/repo' }
```
在 `Module` 工程目录下的 `build.gradle` 文件中添加依赖项，按您的发行地区选择：
**国内**
```groovy
implementation ("cn.gravity.android:GravityEngineSDK:${LATEST_VERSION}")
// 添加依赖
implementation "com.huawei.hms:ads-identifier:3.4.62.300"//华为SDK
implementation 'com.hihonor.mcs:ads-identifier:1.0.3.300'//荣耀SDK
```
**海外**
```groovy
implementation ("oversea.gravity.android:GravityEngineSDK:${LATEST_VERSION}")
// 添加依赖
implementation "com.huawei.hms:ads-identifier:3.4.62.300"//华为SDK
implementation 'com.hihonor.mcs:ads-identifier:1.0.3.300'//荣耀SDK
//海外需额外添加依赖
implementation "com.android.installreferrer:installreferrer:+"//Google
```
> **注意**
> 如果您集成SDK后编译时**出现**类似 `com.hihonor.ads.identifier.AdvertisingIdClient$Info is defined multiple times`的错误，请根据实际情况处理：
>
> 1. 如果是**荣耀设备**出现的冲突，请在依赖配置中去掉荣耀SDK的implementation
> 2. 如果是**华为设备**出现的冲突，请在依赖配置中去掉华为SDK的implementation
> 3. 如果同时存在两个库的冲突，请在依赖配置中去掉华为和荣耀SDK的implementation
> **注意**
> `${LATEST_VERSION}` 请参见[发版记录](/docs/client-sdk/android/changelog) 请使用其中最新版本的 version 以保证获得引力及时的更新支持。
### 2.2 手动集成 [#22-手动集成]
* 下载并解压最新 Android SDK 包，您可以在[SDK下载](/docs/client-sdk/sdk-overview)下载最新版本 SDK aar 包
* 在项目 `libs` 文件夹中添加 `GravityEngineSDK.aar`
* 在 `Project` 级别的 `build.gradle` 文件中添加如下配置依赖：
```groovy
// 添加 repo 地址
maven { url 'https://developer.huawei.com/repo' }
maven { url 'https://developer.hihonor.com/repo' }
```
* 在 `Module` 工程目录下的 `build.gradle` 添加如下配置引入依赖
```groovy
dependencies {
implementation fileTree(dir: 'libs', include: ['*.jar','*.aar'])
// 添加依赖
implementation "com.huawei.hms:ads-identifier:3.4.62.300"//华为SDK
implementation "com.hihonor.mcs:ads-identifier:1.0.3.300"//荣耀SDK
// 海外需额外添加依赖
implementation "com.android.installreferrer:installreferrer:+"//Google
}
```
> **注意**
> 如果您集成SDK后编译时**出现**类似 `com.hihonor.ads.identifier.AdvertisingIdClient$Info is defined multiple times`的错误，请根据实际情况处理：
>
> 1. 如果是**荣耀设备**出现的冲突，请在依赖配置中去掉荣耀SDK的implementation
> 2. 如果是**华为设备**出现的冲突，请在依赖配置中去掉华为SDK的implementation
> 3. 如果同时存在两个库的冲突，请在依赖配置中去掉华为和荣耀SDK的implementation
## 3. 初始化 SDK [#3-初始化-sdk]
> **注意**
> 应用每次启动都要执行 `SDK` 的启动逻辑，建议在用户同意隐私政策弹窗之后尽早调用。
> **注意**
> 通过 **非自建中台** 的方式导入历史用户到引力时，默认以 Android\_ID 作为 `clientID`。SDK需通过 `setClientIdPriorityOrder` 将 `clientID` 生成顺序设为 **Android\_ID 优先**，与导入规则保持一致，否则同一设备会被算作两个用户。
**国内**
```java
// 在主线程中配置并启动SDK
GEConfig config = GEConfig.getInstance(context, ACCESS_TOKEN);
config.enableAndroidId(true); // 传入 false，则表示关闭 Androidid采集，非必须不要关闭，会影响归因率！5.0.9 及以上版本支持
config.enableOAID(true); // 传入 false，则表示关闭 OAID采集，非必须不要关闭，会影响归因率！5.0.9 及以上版本支持
config.enableIMEI(true); // 传入 false，则表示关闭 IMEI 采集，非必须不要关闭，会影响归因率！5.0.9 及以上版本支持
config.enableMAC(true); // 传入 false，则表示关闭 mac采集，非必须不要关闭，会影响归因率！5.0.16及以上版本支持，5.0.36及后续版本将不会再收集MAC地址
//设置clientID生成顺序。默认OAID第一，Android_ID第二，其他遵循SDK自动生成顺序。5.0.22及以上版本支持
config.setClientIdPriorityOrder(new ArrayList<>(Arrays.asList(GEConfig.ClientIdType.CLIENTID_OAID,GEConfig.ClientIdType.CLIENTID_ANDROID_ID )));
//预设公共属性
JSONObject superProperties = new JSONObject();
superProperties.put("testSuperKey","testSuperValue");
config.setPresetSuperProperties(superProperties);
// 保存此实例，后续调用方法均需要用到
GravityEngineSDK gravityEngineSDKInstance = GravityEngineSDK.setupAndStart(config);
```
**海外**
```java
// 在主线程中配置并启动SDK
GEConfig config = GEConfig.getInstance(context, ACCESS_TOKEN);
config.isGDPRArea(false); //是否欧盟地区 选调，默认false 如果你的应用在欧盟地区运营，则需要符合欧盟隐私保护法律的规定（关于GDPR），请务必在用户拒绝采集设备敏感信息时设置 isGDPRArea(true) 5.0.21 及以上版本支持
config.setCoppaEnabled(false); //是否需要符合《儿童在线隐私权保护法》 选调，默认false 如果您的应用需要符合《儿童在线隐私权保护法》(COPPA) 规定，设置 setCoppaEnabled = true 5.0.21 及以上版本支持
config.setKidsAppEnabled(false); //是否儿童应用 选调，默认false 如果您的应用会定向到不满 13 周岁的儿童，则需要将其标记为儿童应用 (Kids App)，设置 setKidsAppEnabled = true 5.0.21 及以上版本支持
config.setFbAppID(""); //应用Facebook appId 选调，默认"" 如果您的应用需要进行Facebook归因，请设置你的FacebookID 5.0.21及以上版本支持
config.adPersonalizationEnabled(false); //户是否允许Google将其数据用于个性化广告的意见结果 选调，默认false 如果你的应用在欧盟地区运营并且在Google投放您的应用，请务必将用户是否允许Google将其数据用于个性化广告的意见结果传入该属性，以确保您符合Google对欧盟用户意见征求政策的新政策 5.0.21 及以上版本支持
config.adUserDataEnabled(false); //用户是否同意将其数据发送到Google的意见结果 选调，默认false 如果你的应用在欧盟地区运营并且在Google投放您的应用，请务必将用户是否同意将其数据发送到Google的意见结果传入该属性，以确保您符合Google对欧盟用户意见征求政策的新政策 5.0.21 及以上版本支持
// 保存此实例，后续调用方法均需要用到
GravityEngineSDK gravityEngineSDKInstance = GravityEngineSDK.setupAndStart(config);
```
参数说明：
* `ACCESS_TOKEN` : 在第一步中获取的项目通行证 AccessToken
## 4. 用户统计上报 [#4-用户统计上报]
在用户可以获取到用户唯一性 `ID` 时调用此方法，推荐首次安装启动时调用，请启动应用之后尽早调用。
调用此方法后，会生成引力自定义用户ID，后续事件都将和该ID进行绑定。
> **注意**
> 首次调用后，需要等 `InitializeCallback` 回调的 `onSuccess` **回调成功之后才能继续调用其他事件上报的方法**
> 初始化方法调用成功之后，后续冷启动可以不再调用，只需要正常启动 SDK 即可（多次调用也不会有问题，引力做了兼容）
```java
JSONObject adData = new JSONObject();
adData.put("testAdKey","testAdValue");
gravityEngineSDKInstance.initialize(ACCESS_TOKEN, USER_CLIENT_ID, USER_CLIENT_NAME, CHANNEL, new InitializeCallback() {
@Override
public void onFailed(String errorMsg, JSONObject initializeBody) {
Log.d(TAG, "initialize failed " + errorMsg);
}
@Override
public void onSuccess(JSONObject responseJson, JSONObject initializeBody) {
Log.d(TAG, "initialize success");
}
}, ENABLE_SYNC_ATTRIBUTION, adData);
```
参数说明：
| 参数名称 | 参数含义 | 参数类型 | 是否必传 |
| ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ | ------- | ---- |
| ACCESS\_TOKEN | 项目通行证，同启动 SDK 时保持一致 | string | 是 |
| USER\_CLIENT\_ID | 用户唯一 ID(例如 UID 或者设备 ID)。（需SDK版本大于5.0.9）如果传空字符串，则引力 sdk 内部会自动采集设备 id 填入，采集优先级顺序为：oaid > android\_id > imei，如果所有id 都采集不到时，会生成随机的 16 位 id 保存到本地缓存中以保持相对稳定 | string | 否 |
| USER\_CLIENT\_NAME | 用户昵称，如果传空，则引力 sdk 内部会自动根据 client\_id 计算 md5 生成 | string | 否 |
| CHANNEL | 用户初始化渠道(例如 xiaomi、huawei 等) | string | 是 |
| ENABLE\_SYNC\_ATTRIBUTION | 是否开启同步获取归因信息，具体请参考[同步归因](/docs/attribution/synchronous-attribution) | boolean | 是 |
| adData | 预设归因信息 | object | 否 |
## 5. 事件上报 [#5-事件上报]
### 5.1 业务注册事件上报 [#51-业务注册事件上报]
> **注意**
> **如果您的应用不需要追踪用户注册行为，可以跳过此事件接入。此功能仅适用于需要统计业务注册转化数据的场景。**
> **注意**
> 该方法可多次调用，每次调用都会上报一个用户注册事件（计算指标时会去重）
当用户完成应用内业务注册后，您可以调用 `trackRegisterEvent` 方法来上报用户注册事件(`$AppRegister`)给引力，引力会使用该事件统计后台计算指标：标准\_注册数
#### 方法示例 [#方法示例]
```java
public String trackRegisterEvent()
```
#### 返回值 [#返回值]
返回值为当前事件生成的事件 trace\_id
#### 调用示例 [#调用示例]
```java
gravityEngineSDKInstance.trackRegisterEvent();
```
### 5.2 付费事件上报 [#52-付费事件上报]
> **注意**
> **付费事件上报用于收入统计和分析，如您的应用不涉及内购或付费服务，则无需接入此事件。**
> **注意**
> 如果您需要通过后端 API 方式上报付费事件，请参考 [混合上报模式](/docs/client-sdk/hybrid-reporting) 来接入事件上报接口报送付费事件。
当用户发生付费行为时，需要调用 `trackPayEvent` 方法记录用户付费事件，此事件非常重要，会影响买量和 ROI 统计，请务必重点测试！
#### 方法示例 [#方法示例-1]
```java
public String trackPayEvent(int payAmount, String payType, String orderId, String payReason, String payMethod)
```
#### 参数说明 [#参数说明]
| 参数名称 | 参数含义 | 参数类型 | 是否必传 |
| --------- | ----------------------------------------------------------------------------------------------------------------- | ------ | ---- |
| payAmount | 付费金额 单位为分。请务必注意，传错单位可能会导致买量受到影响！ | int | 是 |
| payType | 货币类型 按照国际标准组织ISO 4217中规范的3位字母，例如CNY人民币、USD美金等，具体请参考：[国际标准组织 ISO 4217 代码表](https://en.wikipedia.org/wiki/ISO_4217) | string | 是 |
| orderId | 订单号。引力引擎会通过订单号去重，避免重复上报，请务必准确传入！ | string | 是 |
| payReason | 付费原因 例如：购买钻石、办理月卡 | string | 是 |
| payMethod | 付费方式 例如：支付宝、微信、银联等 | string | 是 |
#### 返回值 [#返回值-1]
返回值为当前事件生成的事件 trace\_id
#### 调用示例 [#调用示例-1]
```java
gravityEngineSDKInstance.trackPayEvent(300, "CNY", "order_id" + System.currentTimeMillis(), "月卡", "支付宝");
```
### 5.3 广告观看事件上报 [#53-广告观看事件上报]
> **注意**
> **广告观看上报适用于广告变现类应用，若您的应用未集成广告模块，则无需接入此事件。**
若您的产品内有广告变现，则需要在用户点击广告观看的同时上报用户广告观看事件给引力，具体参考如下：
#### 方法示例 [#方法示例-2]
```java
public String trackAdShowEvent(String adUnionType, String adPlacementId, String adSourceId, String adType, String adnType, float ecpm)
```
#### 参数说明 [#参数说明-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价格（千次展示收入（单位元）） 请务必注意，做好单位转换，传错单位可能会导致买量受到影响！ | float | 建议填写 |
#### 返回值 [#返回值-2]
返回值为当前事件生成的事件 trace\_id
#### 调用示例 [#调用示例-2]
```java
// 上报广告观看事件
gravityEngineSDKInstance.trackAdShowEvent("topon", "placement_id", "ad_source_id", "reward", "csj", 1);
```
### 5.4 提现事件上报 [#54-提现事件上报]
> **注意**
> **提现事件仅与涉及用户提现功能的平台相关，如无此类业务需求，则无需接入此事件。**
当用户发生应用内提现行为时，需要调用 `trackWithdrawEvent` 方法记录用户提现事件！
#### 方法示例 [#方法示例-3]
```java
public String trackWithdrawEvent(int payAmount, String payType, String orderId, String payReason, String payMethod)
```
#### 参数说明 [#参数说明-2]
| 参数名称 | 参数含义 | 参数类型 | 是否必传 |
| --------- | ------------------------------------------------------------------------------------------------------------- | ------ | ---- |
| payAmount | 提现金额 单位为分 | int | 是 |
| payType | 货币类型 按照国际标准组织ISO 4217中规范的3位字母，例如CNY人民币、USD美金等 [国际标准组织 ISO 4217 代码表](https://en.wikipedia.org/wiki/ISO_4217) | string | 是 |
| orderId | 订单号。引力引擎会通过订单号 `orderId` 去重，避免重复上报，请务必传入！ | string | 是 |
| payReason | 提现原因 例如：用户首次提现、用户抽奖提现 | string | 是 |
| payMethod | 提现支付方式 例如：支付宝、微信、银联等 | string | 是 |
#### 返回值 [#返回值-3]
返回值为当前事件生成的事件 trace\_id
#### 调用示例 [#调用示例-3]
```java
gravityEngineSDKInstance.trackWithdrawEvent(300, "CNY", "order_id" + System.currentTimeMillis(), "用户首次提现", "支付宝");
```
## 6. 接入验证 [#6-接入验证]
> **注意**
> **正式上线之前，请完成本节的校验，否则可能会导致买量上报异常！**
### 6.1 关键事件验证 [#61-关键事件验证]
在引力后台[事件流](https://web.gravity-engine.com/#/manage/metadata/eventFlow) 界面开启**加载实时数据**，并在产品中触发以下几个事件。事件验收与排错：[接入验收与排错](/docs/getting-started/integration-checklist)
| 事件名 | 事件英文名 | 触发时机 | 采集方式 | 默认映射到媒体事件 | 备注 |
| ---- | --------------- | ---------- | ----------------------- | --------- | ----------------------- |
| 用户注册 | `$AppRegister` | 用户完成业务注册之后 | 调用SDK的**上报业务注册事件**方法采集 | 暂无 | 接入了**业务注册上报事件**的产品均需要校验 |
| 付费 | `$PayEvent` | 用户付费之后 | 调用SDK的**上报用户付费事件**方法采集 | 付费 | 接入了**付费事件上报事件**的产品均需要校验 |
| 广告展示 | `$AdShow` | 用户观看广告之后 | 调用SDK的**上报广告展示事件**方法采集 | 暂无 | 接入了**广告事件上报事件**的产品均需要校验 |
| 用户提现 | `$UserWithdraw` | 用户提现之后 | 调用SDK的**上报用户提现事件** 方法采集 | 暂无 | 接入了**用户提现上报事件**的产品均需要校验 |
触发操作后，请在[事件流](https://web.gravity-engine.com/#/manage/metadata/eventFlow) 界面中筛选测试用户的 Client ID，观察对应事件是否出现在实时入库页面。若事件数据正常显示，则说明接入成功；如出现于错误数据页面请根据页面错误提示进行排查；如未显示对应数据，请及时联系引力运营支持团队获取协助。
### 6.2 避免重复上报 [#62-避免重复上报]
如果您之前单独接了媒体的回传(SDK 或者 API)，则上线之前需要去掉，否则可能会导致重复上报数据！
> **注意**
> 至此验证无误之后，技术接入工作完成，您可以转交发行买量团队继续推动后续流程～
# Android SDK下载
> 来源：https://help.gravity-engine.com/docs/client-sdk/android/sdk-download
> 提供 Android SDK 的下载入口，并关联安装接入、合规配置和版本说明。
集成指南：[Android集成文档](/docs/client-sdk/android/quickstart)
合规指引：[gravityengine合规使用指南](/docs/client-sdk/android/compliance)
隐私政策：[gravityengine隐私政策](https://www.gravity-engine.com/h-col-101.html)
SDK名称：gravityengine
SDK包名：cn.gravity.android:GravityEngineSDK（海外：oversea.gravity.android:GravityEngineSDK）
SDK功能：一站式买量归因分析中台
开发者：深圳引力引擎科技有限公司
版本号：5.0.37
更新日期：2026-10-19
下载地址：[Android SDK下载地址](https://github.com/GravityInfinite/GravityEngine-Android-Demo/releases)
# 行为事件上报
> 来源：https://help.gravity-engine.com/docs/client-sdk/android/track-events
> 说明如何使用 Gravity Engine Android SDK 上报业务事件，并管理事件公共属性。
本文档详细介绍了SDK提供的事件上报功能，帮助开发者全面采集用户行为事件数据，为业务分析和运营决策提供数据支持。
通过上报应用内用户行为事件，您可以：
* **完整记录用户行为**：追踪用户在应用内的关键操作路径
* **支持多维度分析**：通过事件属性丰富分析维度
* **构建数据闭环**：为产品优化和精准运营提供数据基础
## 1. 上报自定义事件 [#1-上报自定义事件]
> **注意**
> **如需上报自定义事件，您必须先在[元事件](https://web.gravity-engine.com/#/manage/metadata/metaEvent)中添加，否则会上报失败！**
您可以调用 `track` 方法，记录用户自定义事件。
您需要先在[元事件](https://web.gravity-engine.com/#/manage/metadata/metaEvent)中添加自定义事件，然后在游戏中指定位置埋点调用 `track` 方法上报自定义事件。
```java
JSONObject jsonObject = new JSONObject();
jsonObject.put("guild_id", "100");
jsonObject.put("guild_level", 10);
jsonObject.put("guild_name", "北方之狼");
gravityEngineSDKInstance.track("AddGuild", jsonObject);
```
* 事件名称是 `String` 类型，只能以字母开头，可包含数字，字母和下划线 “\_”，长度最大为 50 个字符。
* 事件属性是 `Map` 类型，其中每个元素代表一个属性；
* 事件属性 `Key` 为属性名称，为 `String` 类型，规定只能以字母开头，包含数字，字母和下划线 “\_”，长度最大为 50 个字符；
* 属性 `Value` 支持`String`、`int`、`float`、`boolean`、`Date`、`List`；当事件属性为列表类型时，您需要使用 `JSONArray` 传入，不要使用 ArrayList，否则会校验失败！
当您调用 `track` 时，SDK 会取系统当前时间作为事件发生的时刻，如果您需要指定事件时间，可以传入 `Date` 类型的参数来设置事件触发时间。
SDK 提供了时间校准接口，允许使用服务器时间对 SDK 时间进行校准，具体请参考[进阶功能](/docs/client-sdk/android/advanced)中关于时间校准章节的说明。
> **注意**
> **尽管事件可以设置触发时间，但是接收端会做如下的限制：只接收相对服务器时间在前 10 天至后 1 小时的数据，超过时限的数据将会被视为异常数据，整条数据无法入库!**
## 2. 设置公共事件属性 [#2-设置公共事件属性]
> **注意**
> **公共属性需要先在[事件属性](https://web.gravity-engine.com/#/manage/metadata/eventProperty)中添加，否则会上报失败!**
对于一些通用的属性，譬如玩家的区服和渠道等，这些属性需要设置在每个事件中，此时您可以将这些属性设置为公共事件属性。公共事件属性指的就是每个事件都会带有的属性，您可以调用 `setSuperProperties` 来设置公共事件属性，我们推荐您在发送事件前，先设置公共事件属性。
```java
JSONObject superProperties = new JSONObject();
superProperties.put("AGE",29);
superProperties.put("CHANNEL","xiaomi");
gravityEngineSDKInstance.setSuperProperties(superProperties);
```
公共事件属性将会被保存到缓存中，无需每次启动 APP 时调用。如果调用 `setSuperProperties` 上传了先前已设置过的公共事件属性，则会覆盖之前的属性。如果公共事件属性和 `track()` 上传的某个属性的 Key 重复，则该事件的属性会覆盖公共事件属性。
### 删除公共事件属性 [#删除公共事件属性]
如果您需要删除某个公共事件属性，可以调用 `unsetSuperProperty` 清除其中一个公共事件属性；
```java
// 清除属性名为 CHANNEL 的公共属性
gravityEngineSDKInstance.unsetSuperProperty("CHANNEL");
```
### 清空公共事件属性 [#清空公共事件属性]
如果您想要清空所有公共事件属性，则可以调用 `clearSuperProperties`;
```java
// 清空所有公共属性
gravityEngineSDKInstance.clearSuperProperties();
```
### 获取公共事件属性 [#获取公共事件属性]
如果您想要获取所有公共事件属性，可以调用`getSuperProperties`;
```java
// 获取所有公共属性
gravityEngineSDKInstance.getSuperProperties();
```
## 3. 记录事件时长 [#3-记录事件时长]
如果您需要记录某个事件持续时长，您可以调用 `timeEvent` 来开始计时，配置您想要计时的事件名称，当您上传该事件时，将会自动在您的事件属性中加入 `$event_duration` 这一属性来表示记录的时长，单位为秒。
```java
// 调用 timeEvent 开启对 TIME_EVENT 事件的计时
gravityEngineSDKInstance.timeEvent("TIME_EVENT");
// do some thing...
// 通过 track 上传 TIME_EVENT 事件时，会在属性中添加 $event_duration 属性
gravityEngineSDKInstance.track("TIME_EVENT");
```
## 4. 立即上报事件 [#4-立即上报事件]
如果需要立即上报缓存的事件，可以调用 `flush` 来上报所有缓存的事件。
```java
// 调用 flush() 上报缓存事件
gravityEngineSDKInstance.flush();
```
# 用户属性上报
> 来源：https://help.gravity-engine.com/docs/client-sdk/android/user-properties
> 说明如何使用 Gravity Engine Android SDK 设置、追加、累加和删除用户属性，并提供参数要求与调用示例。
本文档详细介绍了SDK提供的用户属性上报功能，帮助开发者高效地收集、更新和维护用户画像数据。
通过本功能，您可以：
* **全面记录用户特征**：存储用户基础信息（如昵称、性别）、行为偏好等关键数据
* **灵活更新用户画像**：支持覆盖、追加、数值计算等多种更新方式
* **构建精准用户模型**：通过属性组合分析，实现用户分群和个性化服务
> **注意**
> **如需上报自定义的用户属性，您必须先在[元数据](https://web.gravity-engine.com/#/manage/metadata/userProperty)中添加对应的用户属性，否则会上报失败！**
## 1. 设置用户属性 [#1-设置用户属性]
对于一般的用户属性，您可以调用 `user_set` 来进行设置，使用该接口上传的属性将会覆盖原有的属性值。
```java
// 若某key已存在则覆盖其值
JSONObject jsonObject = new JSONObject();
jsonObject.put("$name", "turboUserName");
jsonObject.put("$gender", "男");
gravityEngineSDKInstance.user_set(jsonObject);
```
## 2. 初始化用户属性 [#2-初始化用户属性]
对于只在首次设置时有效的属性，我们可以使用 `user_setOnce` 记录这些属性。与 `user_set` 方法不同的是，如果被设置的用户属性已存在，则这条记录会被忽略而不会覆盖已有数据。因此，`user_setOnce` 适用于为用户设置首次激活时间、首次注册时间等属性。例如：
```java
JSONObject jsonObject = new JSONObject();
jsonObject.put("$gender", "male");
gravityEngineSDKInstance.user_setOnce(jsonObject);
```
## 3. 累加用户属性 [#3-累加用户属性]
对于数值型的用户属性，可以使用 `user_increment` 对属性值进行累加。常用于记录用户付费次数、付费额度、积分等属性。例如：
```java
// 增加或减少一个用户的某个NUMBER类型的Profile值
gravityEngineSDKInstance.user_increment("$age", 27);
```
## 4. 用户属性取最大值 [#4-用户属性取最大值]
对于数值型的用户属性，可以使用 `user_max` 用来比较数值大小，保存较大的
```java
gravityEngineSDKInstance.user_max("ad_ecpm_max", 300);
```
## 5. 用户属性取最小值 [#5-用户属性取最小值]
对于数值型的用户属性，可以使用 `user_min` 用来比较数值大小，保存较小的
```java
gravityEngineSDKInstance.user_min("ad_ecpm_min", 100);
```
## 6. 用户属性追加（Array） [#6-用户属性追加array]
对用户喜爱的电影、用户点评过的餐厅等属性，可以调用 `user_append` 记录列表型属性，例如：
```java
// 向某个用户的某个数组类型的用户表添加一个或者多个值,默认不去重
JSONArray moviesJsonArray = new JSONArray();
moviesJsonArray.put("Interstellar");
moviesJsonArray.put("The Negro Motorist Green Book");
JSONObject jsonObject = new JSONObject();
jsonObject.put("Movies", moviesJsonArray);
gravityEngineSDKInstance.user_append(jsonObject);
```
## 7. 用户属性去重追加（Array） [#7-用户属性去重追加array]
调用 `user_uniqAppend` 用来对 Array 类型的用户数据去重追加元素，例如：
```java
// 向某个用户的某个数组类型的用户表添加一个或者多个值，会做去重
JSONArray moviesJsonArray = new JSONArray();
moviesJsonArray.put("Interstellar");
moviesJsonArray.put("The Negro Motorist Green Book");
JSONObject jsonObject = new JSONObject();
jsonObject.put("Movies", moviesJsonArray);
gravityEngineSDKInstance.user_uniqAppend(jsonObject);
```
## 8. 清空用户属性 [#8-清空用户属性]
调用 `user_delete` 方法，将把当前用户属性清空，您将无法再查询该名用户的用户属性，但该用户产生的事件仍然可以被查询到
```java
// 删除一个用户的所有属性值
gravityEngineSDKInstance.user_delete();
```
## 9. 重置用户属性 [#9-重置用户属性]
如果需要重置已设置的某个用户属性，可以调用 `user_unset` 进行重置：
```java
// 将某个用户的某些属性值设置为空
gravityEngineSDKInstance.user_unset("$name");
```
# Egret
> 来源：https://help.gravity-engine.com/docs/client-sdk/egret
> Egret SDK索引，汇总Egret快速集成、行为事件上报等主题，便于按功能进入对应的配置、接入或参考说明。
{/* Generated by scripts/generate-docs-routes.mjs. Do not edit. */}
## 目录 [#目录]
* [Egret快速集成](/docs/client-sdk/egret/quickstart)
* [行为事件上报](/docs/client-sdk/egret/track-events)
* [用户属性上报](/docs/client-sdk/egret/user-properties)
* [进阶功能](/docs/client-sdk/egret/advanced) — 子目录
# Egret快速集成
> 来源：https://help.gravity-engine.com/docs/client-sdk/egret/quickstart
> 介绍 Gravity Engine Egret SDK 的安装、初始化、用户注册与事件上报流程，并提供参数说明和调用示例。
本文档主要讲述 **Egret** 接入 [引力引擎](https://gravity-engine.com/) 的技术接入方案，在开始接入前，建议您先阅读 [接入前准备](/docs/getting-started/overview) 以了解接入必备的基础概念。
> **注意**
> 本接入方案仅适用于 **Egret** 开发的项目。如果您使用的是其他开发框架，请访问 [引力引擎SDK总览页面](/docs/client-sdk/sdk-overview) 选择对应的框架接入文档。
## 支持平台 [#支持平台]
* 
微信小游戏
* 
快手小游戏（打包成微信小游戏）
* 
抖音/Tiktok 小游戏
* 
支付宝小游戏
* 
OPPO快游戏
* 
VIVO快游戏
* 
华为快游戏
* 
小米快游戏
* 
百度小游戏
* 
淘宝小游戏
* 
360小游戏
* 
京东小游戏（打包成微信小游戏）
* 
美团小游戏（打包成微信小游戏）
* 
Android
* 
iOS
### **媒体平台SDK集成说明** [#媒体平台sdk集成说明]
**🎯 集成策略说明：**
Egret SDK **仅针对【微信小游戏】平台** 集成了腾讯广告小游戏SDK。对于Egret项目发布至其他平台（如抖音小游戏、快手小游戏等），**我们未集成任何媒体的SDK**。
#### **微信小游戏平台 ✅** [#微信小游戏平台-]
* **状态**：已集成腾讯广告小游戏SDK
* **上报方式**：需**手动调用**我们提供的方法进行事件上报
* **版本**：自 `4.8.40` 开始支持
> **重要说明**
> 按照《腾讯广告小游戏 SDK 集成》的步骤完成集成后，引力SDK会**自动上报**以下两个基础事件给腾讯：
>
> * REGISTER（用户注册）
> * RE\_ACTIVE（沉默唤起）
>
> 此外，**START\_APP（小游戏启动）**事件由腾讯SDK**自动采集**（引力SDK初始化腾讯SDK时默认开启该功能）。
>
> 除以上事件外，其他所有事件（如付费、自定义行为等）均需**客户端手动调用**我们提供的方法进行上报。
>
> 点击查看详细集成文档：[腾讯广告小游戏 SDK 集成](/docs/client-sdk/mini-games/advanced/tencent-ads-integration)
## 1. 获取 AccessToken [#1-获取-accesstoken]
您可以在 [设置-应用管理](https://web.gravity-engine.com/#/manage/appmanage) 页面点击 **查看参数** 按钮获取当前应用的 AccessToken，请妥善保存避免泄露。
## 2. Native 平台支持 [#2-native-平台支持]
如果您的 Egret 项目需要支持 Android/iOS 原生平台，请分别在 Egret 导出的原生工程中完成对应平台的 SDK 集成，切换下方标签按平台查看：
**Android**
### 1. 集成 SDK [#1-集成-sdk]
在 Egret 导出的 Android 项目里，集成 Android 版本的 GravityEngineSDK 即可，参考 [Android 接入文档](/docs/client-sdk/android/quickstart)。
### 2. 导入通道文件 [#2-导入通道文件]
将下载的 `Egretsdk/native/android/GravityEngineEgretChannel.java` 类文件引入到 Egret 导出的 Android 项目 code 中，不要修改 `GravityEngineEgretChannel.java` 里的代码及包名。
### 3. 建立通道 [#3-建立通道]
在启动的 MainActivity 的 `onCreate` 方法中调用 `GravityEngineEgretChannel` 建立 Gravity 与 egret 的通道：
```java
cn.gravity.engine.channel.GravityEngineEgretChannel.registExternalInterface(nativeAndroid, this);
```
**iOS**
### 1. 导入通道文件 [#1-导入通道文件]
将下载的 `Egretsdk/native/iOS` 下的 `GravityEngineCocosCreatorChannel.h` 和 `GravityEngineCocosCreatorChannel.mm` 类文件引入到 Egret 导出的 iOS 项目下。
### 2. 接入 iOS SDK [#2-接入-ios-sdk]
在 Egret 导出的 iOS 项目里集成 iOS 版本的 GravityEngineSDK，参考 [iOS 接入文档](/docs/client-sdk/ios/quickstart)。
### 3. 建立通道 [#3-建立通道-1]
在 `AppDelegate.mm` 的 `application:didFinishLaunchingWithOptions:` 方法中注册 Native 代理，调用代码：
```objc
[GravityEngineEgretChannel registExternalInterface:_native];
```
## 3. 配置并启动 SDK [#3-配置并启动-sdk]
开始接入工作之前，您需要先 [下载 SDK](/docs/client-sdk/sdk-overview)。
### 3.1 导入 SDK [#31-导入-sdk]
在项目的 `libs` 目录下创建 `GravityAnalyticsSDK` 目录，将 `ge_egret_sdk_version.zip` 中的 `GravityAnalyticsSDK.d.ts` 和 `GravityAnalyticsSDK.js` 两个文件放入其中，然后在您项目的配置文件 `egretProperties.json` 中引入 SDK：
```json
{
"name": "GravityAnalyticsSDK",
"path": "./libs/GravityAnalyticsSDK"
}
```
### 3.2 初始化 SDK [#32-初始化-sdk]
集成 SDK 后，您可以在代码中直接使用 `GravityAnalyticsAPI`：
> **注意**
> **每次冷启动过程中，`GravityEngine` 的实例化方法 `new GravityAnalyticsAPI()` 与初始化方法 `setupAndStart()` 均只能被调用一次。`clientId` 参数必须在这两个方法的其中一个传入。**
```javascript
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();
```
> **注意**
> 通过 **非自建中台** 的方式导入历史用户到引力时，默认以 Android\_ID 作为 `clientID`。SDK 需将 `mClientIdPriorityOrder` 设为 **Android\_ID 优先**（如 `["ANDROID_ID","OAID"]`），与导入规则保持一致，否则同一设备会被算作两个用户。
> **注意**
> **配置项目合法域名：** 您需要将 `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)
若您的产品内有广告变现，则需要在用户点击广告观看的同时上报用户广告观看事件给引力，具体参考如下：
**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 | 建议填写 |
**小游戏**
```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 | 是 |
## 6. 接入验证 [#6-接入验证]
> **注意**
> **正式上线之前，请完成本节的校验，否则可能会导致买量上报异常！**
### 6.1 关键事件验证 [#61-关键事件验证]
在引力后台[事件流](https://web.gravity-engine.com/#/manage/metadata/eventFlow) 界面开启**加载实时数据**，并在产品中触发以下几个事件。事件验收与排错：[接入验收与排错](/docs/getting-started/integration-checklist)
| 事件名 | 事件英文名 | 触发时机 | 采集方式 | 默认映射到媒体事件 | 备注 |
| ---- | ----------------------------------------- | ---------- | ---------------------- | --------- | ----------------------- |
| 用户注册 | APP:`$AppRegister`
小游戏:`$MPRegister` | 用户完成业务注册之后 | 调用SDK的**上报业务注册事件**方法采集 | 暂无 | 接入了**业务注册上报事件**的产品均需要校验 |
| 付费 | `$PayEvent` | 用户付费之后 | 调用SDK的**上报用户付费事件**方法采集 | 付费 | 接入了**付费事件上报事件**的产品均需要校验 |
| 广告展示 | `$AdShow` | 用户观看广告之后 | 调用SDK的**上报广告展示事件**方法采集 | 暂无 | 接入了**广告事件上报事件**的产品均需要校验 |
触发操作后，请在[事件流](https://web.gravity-engine.com/#/manage/metadata/eventFlow) 界面中筛选测试用户的 Client ID，观察对应事件是否出现在实时入库页面。若事件数据正常显示，则说明接入成功；如出现于错误数据页面请根据页面错误提示进行排查；如未显示对应数据，请及时联系引力运营支持团队获取协助。
### 6.2 避免重复上报 [#62-避免重复上报]
上线前，请按媒体和事件核对回传来源（引力回传、媒体 SDK 自动采集、客户端手动上报、自有服务端 API），确认同一转化不会通过多条链路重复回传。需要切换到引力回传的事件，应在验证新链路正常后停用原有重复链路；媒体 SDK 的其他功能是否保留，请按对应集成文档确认。
> **注意**
> 至此验证无误之后，您可以正常上线了。
# 行为事件上报
> 来源：https://help.gravity-engine.com/docs/client-sdk/egret/track-events
> 说明如何使用 Gravity Engine Egret SDK 上报业务事件，并管理事件公共属性。
本文档详细介绍了SDK提供的事件上报功能，帮助开发者全面采集用户行为事件数据，为业务分析和运营决策提供数据支持。
通过上报应用内用户行为事件，您可以：
* **完整记录用户行为**：追踪用户在应用内的关键操作路径
* **支持多维度分析**：通过事件属性丰富分析维度
* **构建数据闭环**：为产品优化和精准运营提供数据基础
## 1. 上报自定义事件 [#1-上报自定义事件]
> **注意**
> **如需上报自定义事件，您必须先在[元事件](https://web.gravity-engine.com/#/manage/metadata/metaEvent)中添加，否则会上报失败！**
您可以直接调用 `track` 上传自定义事件，建议您根据准备阶段梳理的文档来设置事件的属性以及发送信息的条件，此处以购买商品为范例：
```javascript
ge.track(
"$purchase", // 追踪事件的名称
{
Item: "商品A",
ItemNum: 1,
Cost: 100,
Elements: ["apple", "ball", "cat"],
} // 需要上传的事件属性
);
```
* `track` 接口共有两个参数，第一个参数为事件的名称，第二个参数为事件的属性。
* 事件的名称是字符串，只能以字母开头，可包含数字、字母和下划线 "\_"，长度最大为 50 个字符。
* 事件的属性是 JS 对象，每个元素代表一个属性。
* 元素的 name 对应属性的名称，规定只能以字母开头，包含数字、字母和下划线 "\_"，长度最大为 50 个字符。
* 元素的 Value 为该属性的值，支持 `String`、`Integer`、`Float`、`Boolean`、`Date`、`DateTime` 和 `Array`；`Array` 中的内容可以为 `String`。
## 2. 公共属性 [#2-公共属性]
> **注意**
> **公共属性需要先在[事件属性](https://web.gravity-engine.com/#/manage/metadata/eventProperty)中添加，否则会上报失败!**
公共事件属性是所有事件（包括自动采集事件）都会包含的属性，用户属性中不会包含。
本节会介绍如何设置公共事件属性和动态公共属性。如果公共属性与事件中设置的自定义属性有相同 key 值，则最终的属性会根据下述优先级取值：
用户自定义事件属性 > 动态公共属性 > 事件公共属性
您可以调用 `setSuperProperties` 来设置公共事件属性，公共事件属性的格式要求与事件属性一致。在设置时只能传入常量，适合设置变化不频繁的属性。
根据属性优先级，自定义属性优先级高于事件公共属性，因此事件公共属性也可以作为某个属性的缺省值，在需要修改的事件中设置同名 Key 覆盖缺省值。
### 2.1 设置公共属性 [#21-设置公共属性]
```javascript
// 设置公共事件属性
ge.setSuperProperties({ channel: "渠道" });
// 使用 track 上传事件，此时事件中会带有公共事件属性
ge.track(
"Purchase", // 追踪事件的名称
{
Item: "商品A",
ItemNum: 1,
Cost: 100,
} // 需要上传的事件属性
);
/* 等价于在事件中加入这些公共属性
ge.track(
'Purchase', // 追踪事件的名称
{
Item:'商品A',
ItemNum:1,
Cost:100,
channel:'渠道' // 相当于在事件中加入这个属性
}
);
*/
```
如果多次调用 `setSuperProperties` 设置公共事件属性，则同名字段后面的调用会覆盖之前的同名字段。
### 2.2 删除公共属性 [#22-删除公共属性]
如果您需要删除某个公共事件属性，可以调用 `unsetSuperProperty()` 清除其中一个公共事件属性。
```javascript
// 清除属性名为 CHANNEL 的公共属性
ge.unsetSuperProperty("CHANNEL");
```
### 2.3 清空公共属性 [#23-清空公共属性]
如果您想要清空所有公共事件属性，则可以调用 `clearSuperProperties()`。
```javascript
// 清除公共事件属性
ge.clearSuperProperties();
```
### 2.4 获取公共属性 [#24-获取公共属性]
如果您想要获取所有公共事件属性，可以调用 `getSuperProperties`。
```javascript
// 获取静态公共事件属性
ge.getSuperProperties();
```
## 3. 设置事件上报时间 [#3-设置事件上报时间]
事件触发的时间默认取本机时间，但在一些情况下，可能需要手动设置事件的时间，可以使用以下方法进行调用：
> **注意**
> **第三个参数为事件触发时间，必须是 Date 类型，将会替换事件触发的时间，如果不传该参数，则事件触发时间默认选取用户的本机时间。**
```javascript
// 第三个参数可以输入 Date 类型的参数，替换事件触发时间
ge.track("event", { parakey: "paravalue" }, new Date());
// 如果没有 properties 需要上传，请传入一个空对象
ge.track("event", {}, new Date());
```
## 4. 记录事件时长 [#4-记录事件时长]
您可以调用 `timeEvent` 来开始计时，配置您想要计时的事件名称，当您上传该事件时，将会自动在您的事件属性中加入 `$event_duration` 这一属性来表示记录的时长，单位为秒。
```javascript
// 用户进入商品页面，开始计时，记录的事件为 "Enter_Shop"
ge.timeEvent("Enter_Shop");
// ...
// 上传事件，计时结束，"Enter_Shop" 这一事件中将会带有表示事件时长的属性 $event_duration
ge.track("Enter_Shop", { product_id: "A1354" });
```
## 5. 立即上报事件 [#5-立即上报事件]
如果需要立即上报缓存的事件，可以调用 `flush` 来上报所有缓存的事件。
```javascript
ge.flush();
```
# 用户属性上报
> 来源：https://help.gravity-engine.com/docs/client-sdk/egret/user-properties
> 说明如何使用 Gravity Engine Egret SDK 设置、追加、累加和删除用户属性，并提供参数要求与调用示例。
本文档详细介绍了SDK提供的用户属性上报功能，帮助开发者高效地收集、更新和维护用户画像数据。
通过本功能，您可以：
* **全面记录用户特征**：存储用户基础信息（如昵称、性别）、行为偏好等关键数据
* **灵活更新用户画像**：支持覆盖、追加、数值计算等多种更新方式
* **构建精准用户模型**：通过属性组合分析，实现用户分群和个性化服务
> **注意**
> **如需上报自定义的用户属性，您必须先在[元数据](https://web.gravity-engine.com/#/manage/metadata/userProperty)中添加对应的用户属性，否则会上报失败！**
## 1. 设置用户属性 [#1-设置用户属性]
对于一般的用户属性，您可以调用 `userSet` 来进行设置，使用该接口上传的属性将会覆盖原有的属性值。
```javascript
// 设置用户属性，会员等级
ge.userSet({ vip_level: "钻石会员" });
```
> **注意**
> 属性格式要求与事件属性保持一致。
## 2. 初始化用户属性 [#2-初始化用户属性]
如果您要上传的用户属性只要设置一次，则可以调用 `userSetOnce` 来进行设置，当该属性之前已经有值的时候，将会忽略这条信息。
```javascript
// 以设置用户名为例，如果用户名已设置，则忽略本次设置
ge.userSetOnce({ user_name: "TestUser" });
```
> **注意**
> 属性格式要求与事件属性保持一致。
## 3. 累加用户属性 [#3-累加用户属性]
当您要上传数值型的属性时，您可以调用 `userAdd` 来对该属性进行累加操作。
```javascript
// 以付费为例，用户每次付费时调用此接口，则 'total_revenue' 字段每次会做累加付费金额的处理
ge.userAdd({ total_revenue: 50 });
```
> **注意**
> 设置的属性 key 为字符串，Value 只允许为数值。
## 4. 重置用户属性 [#4-重置用户属性]
当您要清空用户的某个用户属性值时，您可以调用 `userUnset` 来对指定属性进行清空操作。
```javascript
// 清空属性名为 userPropertyKey 的用户属性值，即设置为 NULL
ge.userUnset("userPropertyKey");
```
> **注意**
> `userUnset` 的传入值为被清空属性的 Key 值。
## 5. 清空用户属性 [#5-清空用户属性]
如果您要删除某个用户，可以调用 `userDel` 将这名用户删除，您将无法再查询该名用户的用户属性，但该用户产生的事件仍然可以被查询到。
```javascript
ge.userDel();
```
## 6. 用户属性追加（Array） [#6-用户属性追加array]
您可以调用 `userAppend` 对 Array（List）类型的用户数据追加元素。
```javascript
ge.userAppend({ Movies: ["Interstellar", "The Negro Motorist Green Book"] });
```
## 7. 用户属性去重追加（Array） [#7-用户属性去重追加array]
`userUniqAppend` 用来对 Array（List）类型的用户数据**去重**追加元素。
```javascript
ge.userUniqAppend({
Movies: ["Interstellar", "The Negro Motorist Green Book"],
});
```
## 8. 用户属性取最大值 [#8-用户属性取最大值]
`userNumberMax` 用来比较数值大小，保存较大的。
```javascript
ge.userNumberMax({
ad_ecpm_max: 300,
});
```
## 9. 用户属性取最小值 [#9-用户属性取最小值]
`userNumberMin` 用来比较数值大小，保存较小的。
```javascript
ge.userNumberMin({
ad_ecpm_min: 17,
});
```
# Flutter
> 来源：https://help.gravity-engine.com/docs/client-sdk/flutter
> Flutter SDK索引，汇总快速集成、行为事件上报等主题，便于按功能进入对应的配置、接入或参考说明。
{/* Generated by scripts/generate-docs-routes.mjs. Do not edit. */}
## 目录 [#目录]
* [快速集成](/docs/client-sdk/flutter/quickstart)
* [行为事件上报](/docs/client-sdk/flutter/track-events)
* [用户属性上报](/docs/client-sdk/flutter/user-properties)
* [进阶功能](/docs/client-sdk/flutter/advanced) — 子目录
# 快速集成
> 来源：https://help.gravity-engine.com/docs/client-sdk/flutter/quickstart
> 介绍 Gravity Engine Flutter SDK 的安装、初始化、用户注册与事件上报流程，并提供参数说明和调用示例。
本文档为**Flutter**接入 [引力引擎](https://gravity-engine.com/)的技术接入方案，具体 Demo 请参考[GitHub](https://github.com/GravityInfinite/GravityEngine-Flutter-Demo)开源项目，Demo 工程中可以参考 `main.dart` 脚本中对每一个方法的调用示例。
在开始接入前，建议您先阅读 [接入前准备](/docs/getting-started/overview)以了解接入必备的基础概念。
## 1. SDK 基础配置 [#1-sdk-基础配置]
如果要在您的 Flutter 应用中使用GrivityEngine Flutter SDK，请先将 SDK 加入项目。
**请把以下内容添加到你Flutter工程的 pubspec.yaml 文件中：**
> **注意**
> Flutter最新version请参考[gravity-flutter库](https://pub.dev/packages/gravity_engine_flutter_sdk)
```yaml
dependencies:
gravity_engine_flutter_sdk: ^version
```
### 1.1 Android配置 [#11-android配置]
在 `Project` 级别的 `build.gradle` 文件中添加如下配置依赖：
```groovy
maven("https://nexus.gravity-engine.com/repository/maven-releases/")
maven("https://nexus.gravity-engine.com/repository/maven-snapshots/")
maven("https://developer.huawei.com/repo")
maven("https://developer.hihonor.com/repo")
```
### 1.2 Harmony配置 [#12-harmony配置]
在App模块启动的Ability里，onCreate方法里添加sdk生命周期
```typescript
import GravityEngineFlutterSdkPlugin from 'gravity_engine_flutter_sdk';
export default class EntryAbility extends FlutterAbility {
onCreate(want: Want, launchParam: AbilityConstant.LaunchParam): void {
super.onCreate(want,launchParam);
GravityEngineFlutterSdkPlugin.onFlutterAppStart(this.context,want.parameters);
}
}
```
## 2. 配置并启动 SDK [#2-配置并启动-sdk]
请参考以下代码来进行 SDK 的初始化，建议在能够获取到用户唯一 ID，如Android 设备的`oaid`、iOS 设备的`IDFV`时，尽早的进行初始化。
> **注意**
> 通过 **非自建中台** 的方式导入历史用户到引力时，默认以 Android\_ID 作为 `clientID`。SDK 需将 `mClientIdPriorityOrder` 设为 **Android\_ID 优先**，与导入规则保持一致，否则同一设备会被算作两个用户。
```dart
import 'package:gravity_engine_flutter_sdk/GravityEngineSDK.dart';
GravityEngineSDK.startGravityEngine(
accessToken:xxxxxxx // 项目通行证，在：网站后台-->设置-->应用列表中找到Access Token列 复制（首次使用可能需要先新增应用）
//预设公共属性
presetSuperProperties:{"testSuperKey":"testSuperValue"}
//鸿蒙应用的clientid在此传入，不传或传空会由引力SDK自动生成
//clientId:xxxxxxx
//设置clientID生成顺序。默认OAID第一，Android_ID第二，其他遵循SDK自动生成顺序。
//mClientIdPriorityOrder: [SDKClientIdType.OAID,SDKClientIdType.ANDROID_ID]
);
//开启自动采集
GravityEngineSDK.enableAutoTrack([AUTO_TRACK_EVENTS.APP_ALL])
```
## 3. 初始化 [#3-初始化]
### 3.1 添加 att 弹窗描述（iOS配置） [#31-添加-att-弹窗描述ios配置]
需要先在 info.plist 文件中添加跟踪权限请求描述文字，如果不添加会导致 `idfa` 获取失败！描述文字内容仅作示例，具体请联系您的产品同学确认！
```xml
NSUserTrackingUsageDescription
此标识符将用于向您推荐个性化广告。
```
### 3.2 调用引力初始化 [#32-调用引力初始化]
在可以获取到用户唯一性信息时调用本方法，推荐首次安装启动时调用，后续其他方法均需在本方法回调成功之后才可正常使用。
**Android/Harmony**
> **注意**
> **Harmony 建议在startGravityEngine之后延迟500ms在调用Harmony 的initialize**
```dart
GravityEngineSDK.initialize(clientId,nickname,enableSyncAttribution,channel,MyCallBack(),adData: {"testAdKey":"testAdValue"});
class MyCallBack extends InitializeCallback {
@override
void onSuccess(Map? responseJson) {
// 成功回调的处理
print("Initialization succeeded with response: $responseJson");
}
@override
void onFailed(String? errorMsg) {
// 失败回调的处理
print("Initialization failed with error: $errorMsg");
}
}
```
参数说明：
| **参数名称** | **参数含义** | **参数类型** | **是否必传** |
| --------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- | -------- | -------- |
| clientId | 用户唯一 ID(例如 UID 或者设备 ID)。如果传空，则引力 sdk 内部会自动采集设备 id 填入，采集优先级顺序为：oaid > android\_id > imei，如果所有id 都采集不到时，会生成随机的 16 位 id 保存到本地缓存中以保持相对稳定 鸿蒙应用无需传入此参数 | string | 否 |
| nickname | 用户昵称，如果传空，则引力 sdk 内部会自动根据 client\_id 计算 md5 生成 | string | 否 |
| channel | 用户初始化渠道(例如 xiaomi、huawei 等) | string | 是 |
| enableSyncAttribution | 是否开启同步获取归因信息，具体请参考同步归因 | boolean | 是 |
| adData | 预设归因信息 | object | 否 |
**iOS**
```dart
GravityEngineSDK.initializeIOS(true,USER_CLIENT_ID,CAID_STR,ENABLE_SYNC_ATTRIBUTION,CHANNEL,MyCallBack(),adData: {"testAdKey":"testAdValue"});
class MyCallBack extends InitializeCallback {
@override
void onSuccess(Map? responseJson) {
// 成功回调的处理
print("Initialization succeeded with response: $responseJson");
}
@override
void onFailed(String? errorMsg) {
// 失败回调的处理
print("Initialization failed with error: $errorMsg");
}
}
```
参数说明：
| **参数名称** | **参数含义** | **参数类型** | **是否必传** |
| ------------------------- | ------------------------------------------------------------------------------------------- | -------- | -------- |
| ENABLE\_ASA | 是否开启 ASA 广告采集，建议传 YES 以开启归因采集能力，由引力后台的归因配置开关控制是否开启ASA归因。 | bool | 是 |
| USER\_CLIENT\_ID | 当前用户在引力系统中的唯一标识，如果传空字符串，则引力 sdk 内部会采集一个稳定的 idfv （保存在 keychain 中保持 idfv 稳定）作为用户唯一标识（推荐传空字符串） | String | 否 |
| CAID\_STR | 当前用户中广协 ID, 类型为json字符串，数组里面是字典，字典里有version和caid字段(可以为空字符串) | String | 是 |
| ENABLE\_SYNC\_ATTRIBUTION | 是否开启同步获取归因信息，具体请参考[同步归因](/docs/attribution/synchronous-attribution) | bool | 是 |
| CHANNEL | 当前用户渠道，您可以自行定义传入的参数，如无自定义的需求，可以传入默认值：appstore | String | 是 |
| adData | 预设归因信息 | object | 否 |
## 4. 事件上报 [#4-事件上报]
### 4.1 业务注册事件上报 [#41-业务注册事件上报]
> **注意**
> **如果您的应用不需要追踪用户注册行为，可以跳过此事件接入。此功能仅适用于需要统计业务注册转化数据的场景。**
> **注意**
> 该方法可多次调用，每次调用都会上报一个用户注册事件（计算指标时会去重）
当用户完成应用内业务注册后，您可以调用 `trackRegisterEvent` 方法来上报用户注册事件(`$AppRegister`)给引力，引力会使用该事件统计指标：标准\_注册数
#### 方法示例 [#方法示例]
```dart
static Future trackRegisterEvent();
```
#### 调用示例 [#调用示例]
```dart
GravityEngineSDK.trackRegisterEvent();
```
### 4.2 付费事件上报 [#42-付费事件上报]
> **注意**
> **付费事件上报用于收入统计和分析，如您的应用不涉及内购或付费服务，则无需接入此事件。**
> **注意**
> 如果您需要通过后端 API 方式上报付费事件，请参考 [混合上报模式](/docs/client-sdk/hybrid-reporting) 来接入事件上报接口报送付费事件。
当用户发生付费行为时，需要调用 `trackPayEvent` 方法记录用户付费事件，此事件非常重要，会影响买量和 ROI 统计，请务必重点测试！
#### 方法示例 [#方法示例-1]
```dart
static Future trackPayEvent(int payAmount, String payType, String orderId, String payReason, String payMethod);
```
#### 参数说明 [#参数说明]
| **参数名称** | **参数含义** | **参数类型** | **是否必传** |
| --------- | ----------------------------------------------------------------------------------------------------------------- | -------- | -------- |
| payAmount | 付费金额 单位为分。请务必注意，传错单位可能会导致买量受到影响！ | int | 是 |
| payType | 货币类型 按照国际标准组织ISO 4217中规范的3位字母，例如CNY人民币、USD美金等，具体请参考：[国际标准组织 ISO 4217 代码表](https://en.wikipedia.org/wiki/ISO_4217) | String | 是 |
| orderId | 订单号。引力引擎会通过订单号去重，避免重复上报，请务必准确传入！ | String | 是 |
| payReason | 付费原因 例如：购买钻石、办理月卡 | String | 是 |
| payMethod | 付费方式 例如：支付宝、微信、银联等 | String | 是 |
#### 调用示例 [#调用示例-1]
```dart
GravityEngineSDK.trackPayEvent(300, "CNY","order_id","月卡", "支付宝");
```
### 4.3 广告观看事件上报 [#43-广告观看事件上报]
> **注意**
> **广告观看上报适用于广告变现类应用，若您的应用未集成广告模块，则无需接入此事件。**
若您的产品内有广告变现，则需要在用户点击广告观看的同时上报用户广告观看事件给引力，具体参考如下：
#### 方法示例 [#方法示例-2]
```dart
static Future trackAdShowEvent(String adUnionType,String adPlacementId,String adSourceId,String adType,String adnType,double ecpm);
```
#### 参数说明 [#参数说明-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]
```dart
GravityEngineSDK.trackAdShowEvent("topon","placement_id","ad_source_id","reward","csj",1.0,);
```
### 4.4 提现事件上报 [#44-提现事件上报]
> **注意**
> **提现事件仅与涉及用户提现功能的平台相关，如无此类业务需求，则无需接入此事件。**
当用户发生应用内提现行为时，需要调用 `trackWithdrawEvent` 方法记录用户提现事件！
#### 方法示例 [#方法示例-3]
```dart
static Future trackWithdrawEvent(int payAmount,String withPayType,String withOrderId,String payReason,String payMethod);
```
#### 参数说明 [#参数说明-2]
| **参数名称** | **参数含义** | **参数类型** | **是否必传** |
| --------- | ------------------------------------------------------------------------------------------------------------- | -------- | -------- |
| payAmount | 提现金额 单位为分 | int | 是 |
| payType | 货币类型 按照国际标准组织ISO 4217中规范的3位字母，例如CNY人民币、USD美金等 [国际标准组织 ISO 4217 代码表](https://en.wikipedia.org/wiki/ISO_4217) | String | 是 |
| orderId | 订单号。引力引擎会通过订单号去重，避免重复上报，请务必传入！ | String | 是 |
| payReason | 提现原因 例如：用户首次提现、用户抽奖提现 | String | 是 |
| payMethod | 提现支付方式 例如：支付宝、微信、银联等 | String | 是 |
#### 调用示例 [#调用示例-3]
```dart
GravityEngineSDK.trackWithdrawEvent(300, "CNY", "order_id_xxxx1", "用户首次提现","支付宝");
```
## 5. 接入验证 [#5-接入验证]
> **注意**
> **正式上线之前，请完成本节的校验，否则可能会导致买量上报异常！**
### 5.1 关键事件验证 [#51-关键事件验证]
在引力后台[事件流](https://web.gravity-engine.com/#/manage/metadata/eventFlow) 界面开启**加载实时数据**，并在产品中触发以下几个事件。事件验收与排错：[接入验收与排错](/docs/getting-started/integration-checklist)
| 事件名 | 事件英文名 | 触发时机 | 采集方式 | 默认映射到媒体事件 | 备注 |
| ---- | --------------- | ---------- | ---------------------- | --------- | ----------------------- |
| 用户注册 | `$AppRegister` | 用户完成业务注册之后 | 调用SDK的**上报业务注册事件**方法采集 | 暂无 | 接入了**业务注册上报事件**的产品均需要校验 |
| 付费 | `$PayEvent` | 用户付费之后 | 调用SDK的**上报用户付费事件**方法采集 | 付费 | 接入了**付费事件上报事件**的产品均需要校验 |
| 广告展示 | `$AdShow` | 用户观看广告之后 | 调用SDK的**上报广告展示事件**方法采集 | 暂无 | 接入了**广告事件上报事件**的产品均需要校验 |
| 用户提现 | `$UserWithdraw` | 用户提现之后 | 调用SDK的**上报用户提现事件**方法采集 | 暂无 | 接入了**用户提现上报事件**的产品均需要校验 |
触发操作后，请在[事件流](https://web.gravity-engine.com/#/manage/metadata/eventFlow) 界面中筛选测试用户的 Client ID，观察对应事件是否出现在实时入库页面。若事件数据正常显示，则说明接入成功；如出现于错误数据页面请根据页面错误提示进行排查；如未显示对应数据，请及时联系引力运营支持团队获取协助。
### 5.2 避免重复上报 [#52-避免重复上报]
如果您之前单独接了媒体的回传(SDK 或者 API)，则上线之前需要去掉，否则可能会导致重复上报数据！
> **注意**
> 至此验证无误之后，您可以正常上线了。
# 行为事件上报
> 来源：https://help.gravity-engine.com/docs/client-sdk/flutter/track-events
> 说明如何使用 Gravity Engine Flutter SDK 上报业务事件，并管理事件公共属性。
本文档详细介绍了SDK提供的事件上报功能，帮助开发者全面采集用户行为事件数据，为业务分析和运营决策提供数据支持。
通过上报应用内用户行为事件，您可以：
* **完整记录用户行为**：追踪用户在应用内的关键操作路径
* **支持多维度分析**：通过事件属性丰富分析维度
* **构建数据闭环**：为产品优化和精准运营提供数据基础
通过 `GravityEngineSDK.track()` 可以上报事件及其属性。一般情况下，您可能需要上传十几到上百个不同的事件，如果您是第一次使用引力引擎事件采集系统，我们推荐您先上传几个关键事件。
我们也支持了若干自动采集事件，包括游戏启动、关闭、异常、小游戏添加收藏、Unity 场景加载或者卸载等事件，您可以根据业务需求选择是否开启自动采集事件。
## 1. 上报自定义事件 [#1-上报自定义事件]
> **注意**
> **如需上报自定义事件，您必须先在[元事件](https://web.gravity-engine.com/#/manage/metadata/metaEvent)中添加，否则会上报失败！**
您必须先在[元事件](https://web.gravity-engine.com/#/manage/metadata/metaEvent)中添加自定义事件，然后在游戏中指定位置埋点调用 `Track` 方法上报自定义事件。
```dart
/// 事件名称
/// 事件属性
GravityEngineSDK.track(eventName,properties)
```
* 事件名称是 `string` 类型，只能以字母开头，可包含数字，字母和下划线 “\_”，长度最大为 50 个字符。
* 事件属性是 `Dictionary` 类型，其中每个元素代表一个属性；
* 事件属性 `Key` 为属性名称，为 `string` 类型，规定只能以字母开头，包含数字，字母和下划线 “\_”，长度最大为 50 个字符；
* 属性 `Value` 支持`string`、`int`、`float`、`bool`、`DateTime`、`List`；
当您调用 `track()` 时，SDK 会取系统当前时间作为事件发生的时刻，如果您需要指定事件时间，可以传入 DateTime 类型的参数来设置事件触发时间。
SDK 提供了时间校准接口，允许使用服务器时间对 SDK 时间进行校准，具体请参考 Demo 中对 `CalibrateTime` 和 `CalibrateTimeWithNtp` 方法的使用。
> **注意**
> **尽管事件可以设置触发时间，但是接收端会做如下的限制：只接收相对服务器时间在前 10 天至后 1 小时的数据，超过时限的数据将会被视为异常数据，整条数据无法入库!**
## 2. 公共属性 [#2-公共属性]
公共事件属性指的就是每个事件都会带有的属性，对于一些重要的属性，譬如玩家的区服和渠道等，这些属性需要设置在每个事件中，此时您可以将这些属性设置为公共事件属性。
> **注意**
> **公共属性需要先在[事件属性](https://web.gravity-engine.com/#/manage/metadata/eventProperty)中添加，否则会上报失败!**
### 设置公共属性 [#设置公共属性]
您可以调用 `SetSuperProperties` 来设置公共事件属性，我们推荐您在发送事件前，先设置公共事件属性。
```dart
GravityEngineSDK.setSuperProperties({"age":2,"channel":"xiaomi"});
```
公共事件属性将会被保存到缓存中，无需每次启动 APP 时调用。如果调用 `SetSuperProperties` 上传了先前已设置过的公共事件属性，则会覆盖之前的属性。如果公共事件属性和 `Track()` 上传的某个属性的 Key 重复，则该事件的属性会覆盖公共事件属性。
### 删除公共属性 [#删除公共属性]
如果您需要删除某个公共事件属性，可以调用 `UnsetSuperProperty` 清除其中一个公共事件属性；
```dart
// 清除属性名为 CHANNEL 的公共属性
GravityEngineSDK.UnsetSuperProperty("CHANNEL");
```
### 清空公共属性 [#清空公共属性]
如果您想要清空所有公共事件属性，则可以调用 `ClearSuperProperties`;
```dart
// 清空所有公共属性
GravityEngineSDK.ClearSuperProperties();
```
### 获取公共属性 [#获取公共属性]
如果您想要获取所有公共事件属性，可以调用`GetSuperProperties`;
```dart
// 获取所有公共属性
GravityEngineSDK.GetSuperProperties();
```
## 3. 记录事件时长 [#3-记录事件时长]
如果您需要记录某个事件持续时长，您可以调用 `TimeEvent()` 来开始计时，配置您想要计时的事件名称，当您上传该事件时，将会自动在您的事件属性中加入 `$event_duration` 这一属性来表示记录的时长，单位为秒。
```dart
// 调用 TimeEvent 开启对 TIME_EVENT 事件的计时
GravityEngineSDK.TimeEvent("TIME_EVENT");
// do some thing...
// 通过 Track 上传 TIME_EVENT 事件时，会在属性中添加 $event_duration 属性
GravityEngineSDK.Track("TIME_EVENT");
```
## 4. 立即上报事件 [#4-立即上报事件]
如果需要立即上报缓存的事件，可以调用 `flush()` 来上报所有缓存的事件。
```dart
// 调用 Flush() 上报缓存事件
GravityEngineSDK.flush();
```
# 用户属性上报
> 来源：https://help.gravity-engine.com/docs/client-sdk/flutter/user-properties
> 说明如何使用 Gravity Engine Flutter SDK 设置、追加、累加和删除用户属性，并提供参数要求与调用示例。
本文档详细介绍了SDK提供的用户属性上报功能，帮助开发者高效地收集、更新和维护用户画像数据。
通过本功能，您可以：
* **全面记录用户特征**：存储用户基础信息（如昵称、性别）、行为偏好等关键数据
* **灵活更新用户画像**：支持覆盖、追加、数值计算等多种更新方式
* **构建精准用户模型**：通过属性组合分析，实现用户分群和个性化服务
> **注意**
> **如需上报自定义的用户属性，您必须先在[元数据](https://web.gravity-engine.com/#/manage/metadata/userProperty)中添加对应的用户属性，否则会上报失败！**
## 1. 设置用户属性 [#1-设置用户属性]
对于一般的用户属性，您可以调用 `UserSet` 来进行设置，使用该接口上传的属性将会覆盖原有的属性值。
```dart
GravityEngineSDK.userSet({"\$name":"turboUserName","\$gender":"男"});
```
## 2. 初始化用户属性 [#2-初始化用户属性]
如果您要上传的用户属性只要设置一次，则可以调用 `UserSetOnce` 来进行设置，当该属性之前已经有值的时候，将会忽略这条信息：
```dart
GravityEngineSDK.userSetOnce({"\$gender":"male"});
```
## 3. 累加用户属性 [#3-累加用户属性]
当您要上传数值型的属性时，您可以调用 `UserAdd` 来对该属性进行累加操作，可传入负值，等同于相减操作。
```dart
GravityEngineSDK.userAdd({"\$age":27});
```
> **注意**
> 设置的属性 key 为字符串，Value 只允许为数值。
## 4. 重置用户属性 [#4-重置用户属性]
如果您需要重置用户的某个属性，可以调用 `UserUnset` 将该用户指定用户属性的值重置。
```dart
// 删除用户属性
GravityEngineSDK.userUnset(["\$age"]);
```
> **注意**
> `UserUnset` 的传入值为被重置属性的 Key 值。
## 5. 清空用户属性 [#5-清空用户属性]
如果您要删除某个用户，可以调用 `UserDelete` 将这名用户删除，您将无法再查询该名用户的用户属性，但该用户产生的事件仍然可以被查询到。
```dart
GravityEngineSDK.UserDelete();
```
## 6. 用户属性追加（Array） [#6-用户属性追加array]
可以调用 UserAppend 为 List 类型的用户属性追加元素:
```dart
// 为属性名为 movies 的用户属性追加 2 个元素
GravityEngineSDK.userAppend({"Movies":["Interstellar","The Negro Motorist Green Book"]});
```
## 7. 用户属性去重追加（Array） [#7-用户属性去重追加array]
可以调用 UserUniqAppend 为 List 类型的用户属性进行去重追加元素:
```dart
GravityEngineSDK.userUniqAppend({"Movies":["Interstellar","The Negro Motorist Green Book"]});
```
## 8. 用户属性取最大值 [#8-用户属性取最大值]
可以调用 `UserNumberMax` 用来比较数值大小，保存较大的。
```dart
GravityEngineSDK.userNumberMax({"ad_ecpm_max":300});
```
## 9. 用户属性取最小值 [#9-用户属性取最小值]
可以调用 `UserNumberMin` 用来比较数值大小，保存较小的。
```dart
GravityEngineSDK.userNumberMin({"ad_ecpm_min":100});
```
# 发版记录
> 来源：https://help.gravity-engine.com/docs/client-sdk/harmonyos/changelog
> 记录 Gravity Engine HarmonyOS SDK 各版本的发布日期、功能变更和升级备注，便于核对版本能力。
| 版本 | 日期 | 备注 |
| ------ | ---------- | -------------------------------------------- |
| 2.0.12 | 2026-09-18 | 数据上报优化 |
| 2.0.11 | 2026-09-10 | 限制 $AdShow 的 $ad\_type 取值；支持团结引擎自动打包 |
| 2.0.10 | 2026-07-28 | 支持预设公共属性和归因信息，其他优化 |
| 2.0.9 | 2026-05-28 | 支持更新用户信息 |
| 2.0.8 | 2026-04-15 | 修复bug 未成功initialize时不上报事件 |
| 2.0.7 | 2026-03-05 | 演练模式优化，支持获取设备信息 |
| 2.0.6 | 2026-02-12 | 支持事件缓存,批量上传，添加flush方法 |
| 2.0.5 | 2026-01-20 | unity，flutter引擎通讯支持 |
| 2.0.4 | 2026-01-09 | 归因：支持鸿蒙系统的快应用监控 支持自动生成clientId并设置生成顺序 其他优化 |
| 2.0.2 | 2025-09-28 | 新增getCurrentClientId方法 |
| 2.0.1 | 2025-09-17 | compatibleSdkVersion 降低为 API 12 |
| 2.0.0 | 2025-09-10 | 优化 Id 采集 |
| 1.0.4 | 2024-12-11 | 优化代码 |
| 1.0.0 | 2024-12-03 | 首次发布 |
# gravityengine合规使用指南
> 来源：https://help.gravity-engine.com/docs/client-sdk/harmonyos/compliance
> 说明 HarmonyOS 应用接入 Gravity Engine SDK 时的个人信息处理、隐私授权、初始化时机与合规配置要求。
根据《个人信息保护法》、《数据安全法》、《网络安全法》等法律法规和监管部门规章要求，App 开发运营者（以下简称为“开发者”）在提供网络产品服务时应尊重和保护最终用户的个人信息，不得违法违规收集使用个人信息，保证和承诺就个人信息处理行为获得最终用户的授权同意，遵循最小必要原则，且应当采取有效的技术措施和组织措施确保个人信息安全。
为帮助开发者在使用 gravityengineSDK 的过程中更好地落实用户个人信息保护相关要求，避免出现侵害最终用户个人信息权益的情形，特制定本合规使用说明，供开发者在接入使用 gravityengineSDK 服务时参照自查和合理配置，不断提升个人信息保护水平。
## SDK 个人信息说明 [#sdk-个人信息说明]
**要求内容：** 《SDK合规使用说明》应详细说明 SDK 各项个人信息使用目的、场景及对应关闭的配置方式、示例。
**gravityengineSDK 个人信息说明：**
| 产品功能类型 | 产品功能名称 | 个人信息类型及字段 | 是否必选 | 用途和目的 | 关闭方式 |
| ------ | ------ | ---------------------------------- | ---- | ------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 基本功能 | 数据统计 | 可变设备标识符（包括 ODID） | 必选 | 用于生成终端用户设备唯一标识，以确保数据统计的准确性 | 基础功能，必要信息 |
| | | 可变设备标识符（包括 OAID） | 可选 | 帮助你分析用户来源，便于优化应用推广等。 | 项目配置 requestPermissions 权限列表，如果不声明 ohos.permission.APP\_TRACKING\_CONSENT 权限，SDK 则不会获取 OAID；即使声明了，用户也可以拒绝，拒绝后 SDK 也不会获取 OAID |
| | | 设备硬件信息（包括操作系统版本、设备制造商、操作系统、备型型号） | 必选 | 用于保证服务在不同设备上的兼容新，确保服务准确生效 | 基础功能，必要信息 |
| | | 用户行为信息（包括页面地址、前向地址、页面标题、页面名称、事件时长） | 必选 | 帮助你分析用户应用内行为路径，便于优化应用内容，提高留存等。 | 基础功能，必要信息 |
| | | 屏幕分辨率 | 可选 | 采集屏幕分辨率进行屏幕分辨率统计 | `const config = new gravityConfig({ context: this.context, accessToken: "**********", clientId: "**********", disableScreen: true // 关闭屏幕信息收集 }) await GravityEngineSDK.setupAndStart(config)` |
## SDK 可按照不同频次、精度收集个人信息的配置说明 [#sdk-可按照不同频次精度收集个人信息的配置说明]
**要求内容：** 如果 SDK 可按照不同频次、精度收集个人信息的，《SDK合规使用说明》应说明不同频次的使用目的、场景及对应选择的配置方式、示例。
**接入说明：** 收集频次方面，gravityengineSDK 的数据采集仅在 App 调用/最终用户触发相关功能时触发，不涉及定时逻辑等频次控制选项。App 如欲控制数据采集频次，可通过重载主动控制器，接管相关数据项对应系统 API 的调用时机，进而控制数据采集频次。
**gravityengineSDK 个人信息收集频次及对应配置情况：**
| 个人信息类型及字段 | 是否可配置 | 用途和目的 | 频次 |
| ---------------------------------- | --------- | ------------------------------ | ----------- |
| 设备标识符（包括 ODID） | 不可配置 | 用于生成终端用户设备唯一标识，以确保数据统计的准确性 | SDK 启动时采集一次 |
| 设备硬件信息（包括操作系统版本、设备制造商、操作系统、备型型号） | 不可配置 | 用于保证服务在不同设备上的兼容新，确保服务准确生效 | SDK 启动时采集一次 |
| 用户行为信息（包括页面地址、前向地址、页面标题、页面名称、事件时长） | 不可配置 | 帮助你分析用户应用内行为路径，便于优化应用内容，提高留存等。 | 客户主动调用时采集一次 |
| 设备标识符（包括 OAID） | 可配置，用户可拒绝 | 用于判断用户来源，对用户进行分群，用户数据分析 | SDK 启动时采集一次 |
| 屏幕分辨率 | 可配置 | 采集屏幕分辨率进行屏幕分辨率统计 | SDK 启动时采集一次 |
## SDK 申请系统权限的说明 [#sdk-申请系统权限的说明]
**要求内容：** 《SDK合规使用说明》应详细说明 SDK 所需的系统权限与各业务功能间的关系，并说明权限申请时机。
**接入说明：** 对于 gravityengineSDK 可选申请的系统权限，您可以参考相关如下表格的内容，详细了解相关权限与各业务功能的关系及其申请时机。gravityengineSDK 不主动申请可选系统权限，但相关权限的不申请将会对其对应的功能造成影响，您可以结合业务实际需要进行合理配置。
**鸿蒙操作系统应用权限列表：**
| 权限 | 权限功能说明 | 用途和目的 | 申请时机 |
| -------------------------------------- | -------------------- | ----------------------------------- | ------------------------- |
| ohos.permission.INTERNET | 【必选】允许使用 Internet 网络 | 用于连接网络，实现 gravityengine 业务所需的日志上报功能 | 由开发者在调用需要该权限的 SDK 功能前进行调用 |
| ohos.permission.GET\_NETWORK\_INFO | 【必选】允许应用获取数据网络信息 | 用于检测当前网络信息以确保 gravityengine 网络状态采集 | 由开发者在调用需要该权限的 SDK 功能前进行调用 |
| ohos.permission.APP\_TRACKING\_CONSENT | 【可选】允许应用获取 OAID 进行归因 | 用于用户归因，实现 gravityengine 业务所需的用户归因功能 | 由开发者在调用需要该权限的 SDK 功能前进行调用 |
## SDK 初始化及业务功能调用时机 [#sdk-初始化及业务功能调用时机]
**要求内容：** 《SDK合规使用说明》应详细说明 SDK 初始化及各项业务功能接口合规调用时机。App 应当在 App 登录注册页面及 App 首次运行时，通过弹窗、文本链接及附件等简洁明显且易于访问的方式，向最终用户告知涵盖个人信息处理主体、处理目的、处理方式、处理类型、保存期限等内容的个人信息处理规则，并且获得最终用户授权同意后才能处置最终用户数据。
**接入说明：** 请务必在用户同意您 App 中的隐私政策后，再进行 gravityengineSDK 的初始化。用户同意隐私政策之前，避免动态申请涉及用户个人信息的敏感设备权限；用户同意隐私政策前，您应避免私自采集和上报个人信息。当您的 App 未向用户提供服务时，例如 App 在后台运行时，请勿请求 gravityengineSDK 的相关服务。具体示例请参考下方案例：
```ts
if (用户同意隐私政策弹窗) {
const config = new gravityConfig({
accessToken: "your_access_token",
clientId: "your_client_id",
});
await GravityEngineSDK.setupAndStart(this.context, config);
}
```
## SDK 隐私政策披露要求与示例 [#sdk-隐私政策披露要求与示例]
**要求内容：** 《SDK合规使用说明》应提供 App 向最终用户披露 SDK 隐私政策条款的示例，包括 SDK 名称、公司名、处理个人信息种类及目的、采集方式、隐私政策链接等内容。
**接入说明：** 开发者在 App 集成 gravityengineSDK 后，gravityengineSDK 的正常运行会收集必要的最终用户信息，实现用户行为分析、数据归因等功能。请开发者根据集成 gravityengineSDK 的实际情况，在您 App 的隐私政策中，对 gravityengineSDK 名称、公司名称、处理个人信息种类及目的、采集方式、隐私政策链接等内容进行披露。
**披露示例：**
**SDK名称**：gravityengine
**涉及个人信息**：
| 个人信息类型及字段 | 用途和目的 |
| -------------------------------------- | ------------------------------ |
| 可变设备标识符（包括 ODID，OAID） | 用于生成终端用户设备唯一标识，以确保数据统计的准确性 |
| 设备硬件信息（包括操作系统版本、设备制造商、操作系统、备型型号、屏幕分辨率） | 用于保证服务在不同设备上的兼容新，确保服务准确生效 |
| 用户行为信息（包括页面地址、前向地址、页面标题、页面名称、事件时长） | 帮助你分析用户应用内行为路径，便于优化应用内容，提高留存等。 |
**合作方主体**：深圳引力引擎科技有限公司
**使用目的**：实现广告监测归因、投放效果优化等与广告活动相关的使用目的
**使用场景**：广告监测归因、投放效果优化的场景
**收集方式**：SDK自行采集
**官网链接**：[https://www.gravity-engine.com/](https://www.gravity-engine.com/)
**隐私政策链接**：[https://www.gravity-engine.com/h-col-101.html](https://www.gravity-engine.com/h-col-101.html)
## 最终用户同意方式的示例 [#最终用户同意方式的示例]
**要求内容：** 《SDK合规使用说明》应详细说明 App 获取最终用户授权同意的建议方式，其中需要取得最终用户单独同意的，应显著提示并给出示例。
**接入说明：** App 首次运行时应当有隐私弹窗，隐私弹窗中应公示简版隐私政策内容并附完整版隐私政策链接，并明确提示最终用户阅读并选择是否同意隐私政策；隐私弹窗应提供同意按钮和拒绝同意的按钮，并由最终用户主动选择。
## 最终用户行使权利的配置说明 [#最终用户行使权利的配置说明]
**要求内容：** 最终用户对其个人信息的处理享有知情、决定、查阅、复制、补充、更正、撤回授权同意、删除、注销账号等权利。以嵌入接口形式向最终用户提供行使权利的，应提供接口调用方式、示例。
**接入说明：** 开发者在其 App 中集成 gravityengineSDK 后，gravityengineSDK 的正常运行会收集必要的最终用户信息用于实现用户行为分析、数据归因等功能。开发者应根据相关法律法规为最终用户提供行使个人信息主体权利的路径或功能，需要 gravityengineSDK 配合的，请与 gravityengineSDK 及时进行联系，我们将与开发者协同妥善解决最终用户的诉求。联系客服电子邮箱地址：[client@gravity-engine.com](mailto:client@gravity-engine.com)
# HarmonyOS
> 来源：https://help.gravity-engine.com/docs/client-sdk/harmonyos
> HarmonyOS SDK索引，汇总快速集成、行为事件上报等主题，便于按功能进入对应的配置、接入或参考说明。
{/* Generated by scripts/generate-docs-routes.mjs. Do not edit. */}
## 目录 [#目录]
* [快速集成](/docs/client-sdk/harmonyos/quickstart)
* [行为事件上报](/docs/client-sdk/harmonyos/track-events)
* [用户属性上报](/docs/client-sdk/harmonyos/user-properties)
* [进阶功能](/docs/client-sdk/harmonyos/advanced) — 子目录
* [gravityengine合规使用指南](/docs/client-sdk/harmonyos/compliance)
* [HarmonyOS SDK下载](/docs/client-sdk/harmonyos/sdk-download)
* [发版记录](/docs/client-sdk/harmonyos/changelog)
# 快速集成
> 来源：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` 的 `module` 对象中合并以下 `requestPermissions` 配置；这是配置片段，请保留已有权限及其他字段：
```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. 初始化 [#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)界面开启**加载实时数据**，并在产品中触发以下几个事件。事件验收与排错：[接入验收与排错](/docs/getting-started/integration-checklist)
| 事件名 | 事件英文名 | 触发时机 | 采集方式 | 默认映射到媒体事件 | 备注 |
| ---- | --------------- | ---------- | ------------------------ | --------- | ----------------------- |
| 用户注册 | `$AppRegister` | 用户完成业务注册之后 | 调用 SDK 的**上报业务注册事件**方法采集 | 暂无 | 接入了**业务注册上报事件**的产品均需要校验 |
| 付费 | `$PayEvent` | 用户付费之后 | 调用 SDK 的**上报用户付费事件**方法采集 | 付费 | 接入了**付费事件上报事件**的产品均需要校验 |
| 广告展示 | `$AdShow` | 用户观看广告之后 | 调用 SDK 的**上报广告展示事件**方法采集 | 暂无 | 接入了**广告事件上报事件**的产品均需要校验 |
| 用户提现 | `$UserWithdraw` | 用户提现之后 | 调用 SDK 的**上报用户提现事件**方法采集 | 暂无 | 接入了**用户提现上报事件**的产品均需要校验 |
触发操作后，请在[事件流](https://web.gravity-engine.com/#/manage/metadata/eventFlow)界面中筛选测试用户的 Client ID，观察对应事件是否出现在实时入库页面。若事件数据正常显示，则说明接入成功；如出现于错误数据页面请根据页面错误提示进行排查；如未显示对应数据，请及时联系引力运营支持团队获取协助。
### 5.2 避免重复上报 [#52-避免重复上报]
上线前，请按媒体和事件核对回传来源（引力回传、媒体 SDK 自动采集、客户端手动上报、自有服务端 API），确认同一转化不会通过多条链路重复回传。需要切换到引力回传的事件，应在验证新链路正常后停用原有重复链路；媒体 SDK 的其他功能是否保留，请按对应集成文档确认。
> **注意**
> 至此验证无误之后，技术接入工作完成，您可以转交发行买量团队继续推动后续流程～
# HarmonyOS SDK下载
> 来源：https://help.gravity-engine.com/docs/client-sdk/harmonyos/sdk-download
> 提供 HarmonyOS SDK 的下载入口，并关联安装接入、合规配置和版本说明。
集成指南：[鸿蒙集成文档](/docs/client-sdk/harmonyos/quickstart)
合规指引：[gravityengine合规使用指南](/docs/client-sdk/harmonyos/compliance)
隐私政策：[gravityengine隐私政策](https://www.gravity-engine.com/h-col-101.html)
SDK名称：gravityengine
SDK包名：@gravityengine/analytics
SDK功能：一站式买量归因分析中台
开发者：成都引力引擎科技有限公司
版本号：2.0.10
更新日期：2026-07-28
MD5值：199a72e1d0cf734a8fbfdb1190e3af7b
下载地址：[鸿蒙SDK下载地址](/docs-assets/helplook/h8dDbLOe/gravityengine_v2.0.10.zip "gravityengine_v2.0.10.zip")
# 行为事件上报
> 来源：https://help.gravity-engine.com/docs/client-sdk/harmonyos/track-events
> 说明如何使用 Gravity Engine HarmonyOS SDK 上报业务事件，并管理事件公共属性。
本文档详细介绍了 SDK 提供的事件上报功能，帮助开发者全面采集用户行为事件数据，为业务分析和运营决策提供数据支持。
通过上报应用内用户行为事件，您可以：
* **完整记录用户行为**：追踪用户在应用内的关键操作路径
* **支持多维度分析**：通过事件属性丰富分析维度
* **构建数据闭环**：为产品优化和精准运营提供数据基础
## 上报自定义事件 [#上报自定义事件]
> **注意**
> **如需上报自定义事件，您必须先在[元事件](https://web.gravity-engine.com/#/manage/metadata/metaEvent)中添加，否则会上报失败！**
您可以直接调用 `track` 上传自定义事件，建议您根据准备阶段梳理的文档来设置事件的属性以及发送信息的条件，此处以购买商品为范例：
```ts
GravityEngineSDK.track(
"$purchase", // 追踪事件的名称
{
// 需要上传的事件属性
Item: "商品A",
ItemNum: 1,
Cost: 100,
Elements: ["apple", "ball", "cat"],
}
);
```
* `track` 接口共有两个参数，第一个参数为事件的名称，第二个参数为事件的属性。
* 事件的名称是字符串，只能以字母开头，可包含数字、字母和下划线（\_），长度最大为 50 个字符。
* 事件的属性是 JS 对象，每个元素代表一个属性。
* 元素的 name 对应属性的名称，规定只能以字母开头，包含数字、字母和下划线（\_），长度最大为 50 个字符。
* 元素的 Value 为该属性的值，支持 `String`、`Integer`、`Float`、`Boolean`、`Date`、`DateTime` 和 `Array`；`Array` 中的内容可以为 `String`。
## 立即上报事件 [#立即上报事件]
如果需要立即上报缓存的事件，可以调用 `flush` 来上报所有缓存的事件。
```ts
GravityEngineSDK.flush()
```
## 记录事件时长 [#记录事件时长]
如果您需要记录某个事件持续时长，您可以调用 `timeEvent` 来开始计时，配置您想要计时的事件名称，当您上传该事件时，将会自动在您的事件属性中加入 `$event_duration` 这一属性来表示记录的时长，单位为秒。
```ts
// 调用 timeEvent 开启对 TIME_EVENT 事件的计时
GravityEngineSDK.timeEvent("TIME_EVENT");
// do some thing...
// 通过 track 上传 TIME_EVENT 事件时，会在属性中添加 $event_duration 属性
GravityEngineSDK.track("TIME_EVENT", {});
```
# 用户属性上报
> 来源：https://help.gravity-engine.com/docs/client-sdk/harmonyos/user-properties
> 说明如何使用 Gravity Engine HarmonyOS SDK 设置、追加、累加和删除用户属性，并提供参数要求与调用示例。
本文档详细介绍了 SDK 提供的用户属性上报功能，帮助开发者高效地收集、更新和维护用户画像数据。
通过本功能，您可以：
* **全面记录用户特征**：存储用户基础信息（如昵称、性别）、行为偏好等关键数据
* **灵活更新用户画像**：支持覆盖、追加、数值计算等多种更新方式
* **构建精准用户模型**：通过属性组合分析，实现用户分群和个性化服务
> **注意**
> **如需上报自定义的用户属性，您必须先在[元数据](https://web.gravity-engine.com/#/manage/metadata/userProperty)中添加对应的用户属性，否则会上报失败！**
## 1. 设置用户属性 [#1-设置用户属性]
对于一般的用户属性，您可以调用 `userSet` 来进行设置，使用该接口上传的属性将会覆盖原有的属性值。
```ts
// 设置用户属性，会员等级
GravityEngineSDK.userSet({ vip_level: "钻石会员" });
```
> **注意**
> 属性格式要求与事件属性保持一致。
## 2. 初始化用户属性 [#2-初始化用户属性]
如果您要上传的用户属性只要设置一次，则可以调用 `userSetOnce` 来进行设置，当该属性之前已经有值的时候，将会忽略这条信息。
```ts
// 以设置用户名为例，如果用户名已设置，则忽略本次设置
GravityEngineSDK.userSetOnce({ user_name: "TestUser" });
```
> **注意**
> 属性格式要求与事件属性保持一致。
## 3. 累加用户属性 [#3-累加用户属性]
对于数值型的用户属性，可以调用 `userAdd` 进行累加操作。
```ts
// 以付费为例，用户每次付费时调用此接口，则 total_revenue 字段每次会做累加付费金额的处理
GravityEngineSDK.userAdd({ total_revenue: 50 });
```
> **注意**
> 设置的属性 key 为字符串，Value 只允许为数值。
## 4. 重置用户属性 [#4-重置用户属性]
当您要清空用户的某个用户属性值时，可以调用 `userUnset` 来对指定属性进行清空操作。
```ts
// 清空指定 key 的用户属性值，即设置为 null
GravityEngineSDK.userUnset("userPropertyKey");
```
> **注意**
> `userUnset` 的传入值为被清空属性的 Key 值。
## 5. 清空用户属性 [#5-清空用户属性]
如果您要删除某个用户，可以调用 `userDelete` 将这名用户删除，您将无法再查询该名用户的用户属性，但该用户产生的事件仍然可以被查询到：
```ts
GravityEngineSDK.userDelete();
```
## 6. 用户属性追加（Array） [#6-用户属性追加array]
您可以调用 `userAppend` 对 Array（List）类型的用户数据追加元素。
```ts
GravityEngineSDK.userAppend({
Movies: ["Interstellar", "The Negro Motorist Green Book"],
});
```
## 7. 用户属性去重追加（Array） [#7-用户属性去重追加array]
`userUniqAppend` 用来对 Array（List）类型的用户数据**去重**追加元素。
```ts
GravityEngineSDK.userUniqAppend({
Movies: ["Interstellar", "The Negro Motorist Green Book"],
});
```
## 8. 用户属性取最大值 [#8-用户属性取最大值]
对于数值型的用户属性，可以使用 `userNumberMax` 用来比较数值大小，保存较大的。
```ts
GravityEngineSDK.userNumberMax({
ad_ecpm_max: 300,
});
```
## 9. 用户属性取最小值 [#9-用户属性取最小值]
对于数值型的用户属性，可以使用 `userNumberMin` 用来比较数值大小，保存较小的。
```ts
GravityEngineSDK.userNumberMin({
ad_ecpm_min: 17,
});
```
# AppStore上线指南
> 来源：https://help.gravity-engine.com/docs/client-sdk/ios/app-store-release
> 说明集成 Gravity Engine iOS SDK 的应用在 App Store 上架时如何填写隐私信息。
苹果在 iOS 14.3 系统更新了隐私政策，要求 App 更新或发布时需要发布者填写一份隐私报告。此时如果 App 集成SDK 应该如何填写。
默认情况下只需选择 「设备ID」。如果开启自动采集需继续选择 「产品交互」。如果使用用户关联，即调用 initialize: 接口则还需勾选 「用户 ID」
存储后会在 App 隐私页面根据我们的选择生成一系列收集类型面板，点击对应面板后可以继续做详细的选择。
## 1. 用户 ID [#1-用户-id]
引力 SDK 会在调用 initialize: 接口时收集用户 ID 用于分析功能，因此这里选择「分析」即可
勾选后点击下一步会选择收集的用户 ID 是否与用户身份关联，这里根据具体的业务进行勾选，具体可以参考 Apple 公司对是否关联的定义，如图 3：
* 在收集数据前去除直接标识符（例如电子邮件地址或姓名）
* 通过对数据的处理，断开与真实身份的关联并防止再次关联
* 此外，为了不使数据关联到特定用户身份，您必须在收集数据后避免某些活动：
* 您不得尝试将数据再次关联到用户身份
* 您不得将数据与其他能够让数据关联到用户身份的数据集绑定
请注意：根据相关隐私法的定义，“个人信息”和“个人数据”视为与用户关联。
点击下一步，需要选择是否用于追踪目的。这里如果调用了接口 -enableAutoTrack: 采集安装事件需要选择是。这里引力 SDK 追踪的目的是用于分析衡量广告投放效果
## 2. 设备 ID [#2-设备-id]
引力 SDK 收集设备 ID 用于收集用户登录前的数据，因此这里继续选择「分析」
点击下一步，因为收集到的数据会与设备 ID 绑定，所以此处继续选择是
继续下一步，同用户 ID ，如果调用自动采集接口需继续选择是，引力 SDK 会使用 IDFV 与第三方数据相关联以用于定向广告或广告评估目的
## 3. 产品交互 [#3-产品交互]
开启引力 SDK 自动采集后，会收集 App 启动，退出，用户点击，浏览等相关行为用于分析产品，因此这里继续选择「分析」
点击下一步，继续选择是：
# 发版记录
> 来源：https://help.gravity-engine.com/docs/client-sdk/ios/changelog
> 记录 Gravity Engine iOS SDK 各版本的发布日期、功能变更和升级备注，便于核对版本能力。
| 版本号 | 发布日期 | 备注 |
| ------ | ---------- | -------------------------------------------------- |
| 5.0.29 | 2026-10-19 | asa信息获取逻辑优化 |
| 5.0.28 | 2026-09-18 | 数据上报优化 |
| 5.0.27 | 2026-09-10 | idfa获取权限请求冲突优化；限制 $AdShow 的 $ad\_type 取值 |
| 5.0.26 | 2026-08-05 | 兼容引擎老版本设置caid信息 |
| 5.0.25 | 2026-07-28 | 支持预设公共属性和归因信息，移除老版 initialize 接口（含 caid1/caid2 参数） |
| 5.0.24 | 2026-05-28 | 支持更新用户信息 |
| 5.0.23 | 2026-04-16 | 优化初始化信息获取 |
| 5.0.22 | 2026-03-05 | 国内海外域名区分；演练模式接口优化;支持Mac平台 |
| 5.0.20 | 2026-02-09 | 新增获取设备信息方法;支持h5打通 |
| 5.0.19 | 2026-01-29 | 接入优化 |
| 5.0.18 | 2026-01-20 | bug修复 |
| 5.0.17 | 2026-01-09 | caid传参优化 |
| 5.0.16 | 2025-12-17 | 支持设置前台会话阀值,优化AppEnd时间统计 |
| 5.0.15 | 2025-12-09 | 优化idfa获取逻辑 |
| 5.0.14 | 2025-12-09 | 支持演练模式 |
| 5.0.13 | 2025-12-02 | 百度paid归因支持;海外隐私政策适配 |
| 5.0.12 | 2025-11-20 | 性能优化 |
| 5.0.11 | 2025-11-11 | SDK 内部解决网络冲突 |
| 5.0.10 | 2025-11-04 | 性能优化 |
| 5.0.9 | 2025-10-24 | 优化了 att 弹窗的超时处理逻辑 |
| 5.0.8 | 2025-09-29 | 加密传输 |
| 5.0.6 | 2025-09-04 | 性能优化 |
| 5.0.3 | 2025-05-24 | 支持初始化时手动传入 clientID |
| 5.0.2 | 2025-04-23 | 性能优化 |
| 4.8.11 | 2025-04-07 | 报错 catch |
| 4.8.10 | 2025-03-14 | 性能优化 |
| 4.8.9 | 2025-02-28 | 避免客户误用 login 方法 |
| 4.8.6 | 2024-08-28 | 性能优化 |
| 4.8.5 | 2024-08-12 | 支持客户传入 channel，支持越狱渠道排除 |
| 4.8.4 | 2024-08-08 | 支持融合归因 |
| 4.8.3 | 2024-04-25 | 提供简化版 initialize 方法 |
| 4.7.3 | 2024-02-20 | 性能优化 |
| 4.7.2 | 2023-12-11 | 接入流程优化，不再自动采集$AppRegister 事件 |
| 4.6.3 | 2023-11-28 | 支持补报设备 ID 信息 |
| 4.6.2 | 2023-11-09 | 支持历史用户注册 |
| 4.6.1 | 2023-10-10 | 性能优化 |
| 4.5.5 | 2023-09-20 | 支持同步获取归因结果信息 |
| 4.5.2 | 2023-09-14 | 支持获取当前 ClientID |
| 4.5.1 | 2023-08-30 | 支持查询用户信息接口 |
| 4.3.2 | 2023-07-14 | ASA 归因信息自动采集 |
| 4.3.1 | 2023-07-13 | 支持重置 Client ID；支持打通三方数据平台 |
| 4.2.9 | 2023-07-05 | 支持 Unity 打通 |
| 4.2.8 | 2023-06-29 | 性能优化 |
| 4.2.7 | 2023-06-23 | 支持自动采集用户注册事件 |
| 4.2.6 | 2023-06-07 | 修复用户使用时长统计问题 |
| 4.2.5 | 2023-06-02 | 性能优化 |
| 4.2.4 | 2023-05-31 | 支持 ASA 归因 |
| 4.2.3 | 2023-05-28 | 优化初始化、注册、登录、退出登录流程;优化归因参数采集逻辑 |
| 4.2.1 | 2023-05-22 | 初始版本上线 |
# iOS
> 来源：https://help.gravity-engine.com/docs/client-sdk/ios
> iOS SDK索引，汇总快速集成、行为事件上报等主题，便于按功能进入对应的配置、接入或参考说明。
{/* Generated by scripts/generate-docs-routes.mjs. Do not edit. */}
## 目录 [#目录]
* [快速集成](/docs/client-sdk/ios/quickstart)
* [行为事件上报](/docs/client-sdk/ios/track-events)
* [用户属性上报](/docs/client-sdk/ios/user-properties)
* [进阶功能](/docs/client-sdk/ios/advanced) — 子目录
* [AppStore上线指南](/docs/client-sdk/ios/app-store-release)
* [发版记录](/docs/client-sdk/ios/changelog)
# 快速集成
> 来源：https://help.gravity-engine.com/docs/client-sdk/ios/quickstart
> 介绍 Gravity Engine iOS SDK 的安装、初始化、用户注册与事件上报流程，并提供参数说明和调用示例。
本文档为**iOS**接入 [引力引擎](https://gravity-engine.com/) 的技术接入方案，在开始接入前，建议您先阅读 [接入前准备](/docs/getting-started/overview)以了解接入必备的基础概念。
## 1. 获取 AccessToken 和产品 ID [#1-获取-accesstoken-和产品-id]
您可以在[设置-应用管理](https://web.gravity-engine.com/#/manage/appmanage)页面点击 查看参数 按钮获取当前应用的 AccessToken 和产品 APP\_ID，请妥善保存避免泄露。
## 2. 集成引力引擎 SDK [#2-集成引力引擎-sdk]
### 2.1 CocoaPods 自动集成 [#21-cocoapods-自动集成]
**1. 创建并编辑 `Podfile` 内容（如果已有，直接编辑）：**
创建 `Podfile`，项目工程（.xcodeproj）文件同目录下命令行执行命令：
```bash
pod init
```
编辑 `Podfile` 的内容，按您的发行地区选择：
**国内**
```ruby
platform :ios, '9.0'
target 'YourProjectTarget' do
pod 'GravityEngineSDK','${LATEST_VERSION}'
end
```
**海外**
```ruby
platform :ios, '9.0'
target 'YourProjectTarget' do
pod 'GravityEngineOverseaSDK','${LATEST_VERSION}'
end
```
> **注意**
> `${LATEST_VERSION}` 请参见[发版记录](/docs/client-sdk/ios/changelog) 请使用其中最新版本的 version 以保证获得引力及时的更新支持。
**2. 执行安装命令**
```bash
pod install
```
**3. 导入成功，启动工程**
命令执行成功后，会生成 .xcworkspace 文件，说明您已成功导入 iOS SDK。打开 .xcworkspace 文件以启动工程（注意：此时不能同时开启 .xcodeproj 文件）
### 2.2 手动集成 SDK [#22-手动集成-sdk]
下载并解压最新 iOS SDK 包，您可以在[SDK下载](/docs/client-sdk/sdk-overview)页获取最新版本 SDK包
将 `GravityEngineSDK.xcframework` 拖入 XCode Project Workspace 工程项目中
找到 Targets，在 Build Settings 菜单的 `Other linker flags` 选项添加 `-ObjC`
切换到 `Build Phases` 选项卡，在 `Link Binary With Libraries` 栏目下添加如下依赖项：
1. `libz.tbd`（进行数据压缩）
2. `Security.framework`（用于存储设备标识）
3. `AdServices.framework`（Apple Search Ads 归因，optional 形式引入）
4. `SystemConfiguration.framework`（检测网络状况）
5. `libsqlite3.tbd`
6. `AppTrackingTransparency.framework`（获取 idfa 需要）
7. `AdSupport.framework`（获取 idfa 需要）
8. `libc++.tbd`
> **注意**
> **以上依赖项，必须全部添加，否则会导致编译失败！**
## 3. 配置并启动 SDK [#3-配置并启动-sdk]
> **注意**
> **应用每次启动都要执行 `SDK` 的启动逻辑，建议在用户同意隐私政策弹窗之后尽早调用。**
**国内**
**Objective-C**
```objective-c
GEConfig *config = [GEConfig new];
config.appid = "APP_ID";
config.accessToken = "ACCESS_TOKEN";
//预设公共属性
config.presetSuperProperties = @{
@"testSuperKey":@"testSuperValue"
};
[GravityEngineSDK startWithConfig:config];
GravityEngineSDK *instance = [GravityEngineSDK sharedInstanceWithAppid:config.appid];
```
**Swift**
```swift
let config = GEConfig();
config.appid = "APP_ID";
config.accessToken = "ACCESS_TOKEN";
//预设公共属性
config.presetSuperProperties = [
"testSuperKey": "testSuperValue"
];
GravityEngineSDK.start(with: config);
let instance = GravityEngineSDK.sharedInstance(withAppid: config.appid);
```
**海外**
**Objective-C**
```objective-c
GEConfig *config = [GEConfig new];
config.appid = "APP_ID";
config.accessToken = "ACCESS_TOKEN";
//预设公共属性
config.presetSuperProperties = @{
@"testSuperKey":@"testSuperValue"
};
[GravityEngineSDK startWithConfig:config];
config.isGDPRArea = NO;//是否欧盟地区 选调，默认false 如果你的应用在欧盟地区运营，则需要符合欧盟隐私保护法律的规定（关于GDPR），请务必在用户拒绝采集设备敏感信息时设置 isGDPRArea = YES
config.isCoppaEnabled = NO;//是否需要符合《儿童在线隐私权保护法》 选调，默认false 如果您的应用需要符合《儿童在线隐私权保护法》(COPPA) 规定，设置 isCoppaEnabled = YES
config.isKidsAppEnabled = NO;//是否儿童应用 选调，默认false 如果您的应用会定向到不满 13 周岁的儿童，则需要将其标记为儿童应用 (Kids App)，设置 isKidsAppEnabled = YES
GravityEngineSDK *instance = [GravityEngineSDK sharedInstanceWithAppid:config.appid];
```
**Swift**
```swift
let config = GEConfig();
config.appid = "APP_ID";
config.accessToken = "ACCESS_TOKEN";
//预设公共属性
config.presetSuperProperties = [
"testSuperKey": "testSuperValue"
];
config.isGDPRArea = false;//是否欧盟地区 选调，默认false 如果你的应用在欧盟地区运营，则需要符合欧盟隐私保护法律的规定（关于GDPR），请务必在用户拒绝采集设备敏感信息时设置true
config.isCoppaEnabled = false;//是否需要符合《儿童在线隐私权保护法》 选调，默认false 如果您的应用需要符合《儿童在线隐私权保护法》(COPPA) 规定，设置 true
config.isKidsAppEnabled = false;//是否儿童应用 选调，默认false 如果您的应用会定向到不满 13 周岁的儿童，则需要将其标记为儿童应用 (Kids App)，设置true
GravityEngineSDK.start(with: config);
let instance = GravityEngineSDK.sharedInstance(withAppid: config.appid);
```
参数说明：
* `APP_ID` : 在第一步中获取的项目通行证 APP\_ID
* `ACCESS_TOKEN` : 在第一步中获取的项目通行证 AccessToken
## 4. 初始化 [#4-初始化]
在用户可以获取到用户唯一性 `ID` 时调用此方法，推荐首次安装启动时调用，请启动应用之后尽早调用。
### 4.1 添加 att 弹窗描述 [#41-添加-att-弹窗描述]
需要先在 info.plist 文件中添加跟踪权限请求描述文字，如果不添加会导致 `idfa` 获取失败！描述文字内容仅作示例，具体请联系您的产品同学确认！
```xml
NSUserTrackingUsageDescription
此标识符将用于向您推荐个性化广告。
```
### 4.2 调用引力初始化 [#42-调用引力初始化]
> **注意**
> **避免在 ATT 授权弹窗或其他系统权限弹窗的回调中调用初始化方法，这可能导致权限请求阻塞或初始化异常。**
```objective-c
//caidStr 仅为示例
//NSString * caidStr = @"[{\"version\":\"20220111\",\"caid\":\"912ec803b2ce49e4a541068d495ab570\"},{\"version\":\"20211207\",\"caid\":\"e332a76c29654fcb7f6e6b31ced090c7\"}]";
[instance initializeGravityEngineWithClientId:@"" withCaidInfo:caidStr withSyncAttribution:NO withChannel:@"appstore" withAdData:@{@"testAdKey":@"testAdValue"} withSuccessCallback:^(NSDictionary * _Nonnull response) {
NSLog(@"gravity engine initialize success, response is %@", response);
} withErrorCallback:^(NSError * _Nonnull error) {
NSLog(@"gravity engine initialize failed, and error is %@", error);
}];
```
参数说明：
| 参数名称 | 参数含义 | 参数类型 | 是否必传 |
| ------------------------- | ------------------------------------------------------------------------------------------- | -------- | ---- |
| ENABLE\_ASA | 是否开启 ASA 广告归因，传 YES 则开启，引力会自动获取 ASA 归因信息，传 NO 则引力不会获取。5.0.24版本已移除，改为默认采集 | bool | 是 |
| USER\_CLIENT\_ID | 当前用户在引力系统中的唯一标识，如果传空字符串，则引力 sdk 内部会采集一个稳定的 idfv （保存在 keychain 中保持 idfv 稳定）作为用户唯一标识（推荐传空字符串） | NSString | 是 |
| CAID\_STR | 当前用户中广协 ID, 类型为json字符串，数组里面是字典，字典里有version和caid字段(可以为空字符串)。已支持20250325，20260506版本 | NSString | 是 |
| ENABLE\_SYNC\_ATTRIBUTION | 是否开启同步获取归因信息，具体请参考[同步归因](/docs/attribution/synchronous-attribution) | bool | 是 |
| CHANNEL | 当前用户渠道，您可以自行定义传入的参数，如无自定义的需求，可以传入默认值：appstore | NSString | 是 |
| adData | 预设归因信息 | object | 否 |
> **注意**
> * **首次调用后，需要等 `CallbackWithSuccess` 回调成功之后，才能继续调用后续的事件上报方法**
> * **调用成功之后，后续冷启动可以不再调用初始化，只需要正常启动 SDK 即可（多次调用也不会有问题，引力做了兼容）**
> * **以上字符串参数无值时，请传入空字符串，不要传入 `nil`**
### 4.3 最佳实践（推荐） [#43-最佳实践推荐]
引力 sdk 内部在采集 `idfa` 数据之前，会尝试弹出 [App Tracking Transparency(ATT)许可弹窗](https://developer.apple.com/documentation/apptrackingtransparency) （如果之前已经弹出过，则不会重新弹出，会自动复用之前的用户选择），用户点击允许之后，才可以采集到 `idfa` ，引力已经兼容了 iOS14 系统之前和 iOS14 系统之后获取 `idfa` 的代码（引力 ios sdk 5.0.8 及以上支持，unity sdk 5.0.22 及以上支持），并在无论是否获取到 `idfa` 时，都会继续调用引力 SDK 的 `initialize` 函数完成初始化调用。
我们推荐您通过 `withClientId` 传入空字符串，这样引力 sdk 内部会自动获取当前 app 的 `version`、`idfa`、`idfv`，并将首次获取的 `idfv` 保存到keychain中，保证当前设备后续卸载重装之后，能始终获取到最初的 `idfv`，并将这个稳定的 `idfv` 作为 client id 传给引力后台作为唯一用户 ID；
在[混合上报](/docs/client-sdk/hybrid-reporting)的场景下，如您需要获取当前用户的 `clientId`，您可以调用 `getCurrentClientId` 方法获取；代码示例如下：
```objective-c
// instance 为启动 SDK 时获取的引力实例对象
NSString *clientId= [instance getCurrentClientId];
```
SDK 获取 version 的逻辑为：采集 `CFBundleVersion` 字符串，并将小数点去除转换为 int 类型上报给引力后台，代码示例如下；
```objective-c
NSString *buildVersion = [[NSBundle mainBundle] objectForInfoDictionaryKey:@"CFBundleVersion"];
```
## 5. 事件上报 [#5-事件上报]
### 5.1 业务注册事件上报 [#51-业务注册事件上报]
> **注意**
> **如果您的应用不需要追踪用户注册行为，可以跳过此事件接入。此功能仅适用于需要统计业务注册转化数据的场景。**
> **注意**
> 该方法可多次调用，每次调用都会上报一个用户注册事件（计算指标时会去重）
当用户完成应用内业务注册后，您可以调用 `trackRegisterEvent` 方法来上报用户注册事件(`$AppRegister`)给引力，引力会使用该事件统计指标：标准\_注册数
#### 方法示例 [#方法示例]
```objective-c
- (void)trackRegisterEvent;
```
#### 调用示例 [#调用示例]
**Objective-C**
```objective-c
[instance trackRegisterEvent];
```
**Swift**
```swift
instance?.trackRegisterEvent();
```
### 5.2 付费事件上报 [#52-付费事件上报]
> **注意**
> **付费事件上报用于收入统计和分析，如您的应用不涉及内购或付费服务，则无需接入此事件。**
> **注意**
> 如果您需要通过后端 API 方式上报付费事件，请参考 [混合上报模式](/docs/client-sdk/hybrid-reporting) 来接入事件上报接口报送付费事件。
当用户发生付费行为时，需要调用 `trackPayEvent` 方法记录用户付费事件，此事件非常重要，会影响买量和 ROI 统计，请务必重点测试！
#### 方法示例 [#方法示例-1]
```objective-c
- (void)trackPayEventWithAmount:(int)payAmount withPayType:(NSString *)payType withOrderId:(NSString *)orderId withPayReason:(NSString *)payReason withPayMethod:(NSString *)payMethod;
```
#### 参数说明 [#参数说明]
| 参数名称 | 参数含义 | 参数类型 | 是否必传 |
| --------- | ----------------------------------------------------------------------------------------------------------------- | -------- | ---- |
| payAmount | 付费金额 单位为分。请务必注意，传错单位可能会导致买量受到影响！ | int | 是 |
| payType | 货币类型 按照国际标准组织ISO 4217中规范的3位字母，例如CNY人民币、USD美金等，具体请参考：[国际标准组织 ISO 4217 代码表](https://en.wikipedia.org/wiki/ISO_4217) | NSString | 是 |
| orderId | 订单号。引力引擎会通过订单号去重，避免重复上报，请务必准确传入！ | NSString | 是 |
| payReason | 付费原因 例如：购买钻石、办理月卡 | NSString | 是 |
| payMethod | 付费方式 例如：支付宝、微信、银联等 | NSString | 是 |
#### 调用示例 [#调用示例-1]
**Objective-C**
```objective-c
[instance trackPayEventWithAmount:1000 withPayType:@"CNY" withOrderId:@"order_id_xxx1" withPayReason:@"月卡" withPayMethod:@"支付宝"];
```
**Swift**
```swift
instance?.trackPayEvent(withAmount: 1000, withPayType: "CNY", withOrderId: "order_id_xxxx1", withPayReason: "月卡", withPayMethod: "支付宝");
```
### 5.3 广告观看事件上报 [#53-广告观看事件上报]
> **注意**
> **广告观看上报适用于广告变现类应用，若您的应用未集成广告模块，则无需接入此事件。**
若您的产品内有广告变现，则需要在用户点击广告观看的同时上报用户广告观看事件给引力，具体参考如下：
#### 方法示例 [#方法示例-2]
```objective-c
- (void)trackAdShowEventWithUninType:(NSString *)adUnionType withPlacementId:(NSString *)adPlacementId withSourceId:(NSString *)adSourceId withAdType:(NSString *)adType withAdnType:(NSString *)adAdnType withEcpm:(NSNumber *)ecpm;
```
#### 参数说明 [#参数说明-1]
为生成准确的广告收益分析报表，请尽量遵循规范填写下方的广告平台参数。正确的字段是生成有价值报表的基础。
我们为您准备了详细的指引： 👉 [广告聚合平台字段配置说明](/docs/appendix/ad-mediation-fields)
| 参数名称 | 参数含义 | 参数类型 | 是否必传 |
| ------------- | ----------------------------------------------------------------------------------------------------------------------------- | -------- | ---- |
| adUnionType | 广告聚合平台类型 （取值为：topon、gromore、admore、self，分别对应Topon、Gromore、Admore、自建聚合） | NSString | 否 |
| adPlacementId | 广告瀑布流ID（广告位ID） | NSString | 否 |
| adSourceId | 广告源ID（代码位ID） | NSString | 否 |
| adType | 广告类型 （取值为：reward(激励视频广告)、banner(横幅广告)、 native(信息流广告)、interstitial(插屏广告)、 splash(开屏广告) 、video\_feed(视频信息流)、video\_begin(贴片广告)） | NSString | 是 |
| adnType | 广告平台类型（取值为：csj、gdt、ks、 mint 、baidu、other，分别对应为穿山甲、优量汇、快手联盟、Mintegral、百度联盟、其他平台） | NSString | 否 |
| ecpm | 预估ECPM价格（千次展示收入（单位元）） 请务必注意，做好单位转换，传错单位可能会导致买量受到影响！ | NSNumber | 建议填写 |
#### 调用示例 [#调用示例-2]
**Objective-C**
```objective-c
[instance trackAdShowEventWithUninType:@"topon" withPlacementId:@"placement_id" withSourceId:@"ad_source_id" withAdType:@"reward" withAdnType:@"csj" withEcpm:@1000];
```
**Swift**
```swift
instance?.trackAdShowEvent(withUninType: "topon", withPlacementId: "placement_id", withSourceId: "ad_source_id", withAdType: "reward", withAdnType: "csj", withEcpm: 1000);
```
### 5.4 提现事件上报 [#54-提现事件上报]
> **注意**
> **提现事件仅与涉及用户提现功能的平台相关，如无此类业务需求，则无需接入此事件。**
当用户发生应用内提现行为时，需要调用 `trackWithdrawEvent` 方法记录用户提现事件！
#### 方法示例 [#方法示例-3]
```objective-c
- (void)trackWithdrawEvent:(int)payAmount withPayType:(NSString *)payType withOrderId:(NSString *)orderId withPayReason:(NSString *)payReason withPayMethod:(NSString *)payMethod;
```
#### 参数说明 [#参数说明-2]
| 参数名称 | 参数含义 | 参数类型 | 是否必传 |
| --------- | ------------------------------------------------------------------------------------------------------------- | -------- | ---- |
| payAmount | 提现金额 单位为分 | int | 是 |
| payType | 货币类型 按照国际标准组织ISO 4217中规范的3位字母，例如CNY人民币、USD美金等 [国际标准组织 ISO 4217 代码表](https://en.wikipedia.org/wiki/ISO_4217) | NSString | 是 |
| orderId | 订单号。引力引擎会通过订单号去重，避免重复上报，请务必传入！ | NSString | 是 |
| payReason | 提现原因 例如：用户首次提现、用户抽奖提现 | NSString | 是 |
| payMethod | 提现支付方式 例如：支付宝、微信、银联等 | NSString | 是 |
#### 调用示例 [#调用示例-3]
**Objective-C**
```objective-c
[instance trackWithdrawEventWithAmount:@1000 withPayType:@"CNY" withOrderId:@"order_id_xxx1" withPayReason:@"用户首次提现" withPayMethod:@"支付宝"];
```
**Swift**
```swift
instance?.trackWithdrawEvent(withAmount: 300, withPayType: "CNY", withOrderId: "order_id_xxxx1", withPayReason: "用户首次提现", withPayMethod: "支付宝");
```
## 6. 接入验证 [#6-接入验证]
> **注意**
> **正式上线之前，请完成本节的校验，否则可能会导致买量上报异常！**
### 6.1 关键事件验证 [#61-关键事件验证]
在引力后台[事件流](https://web.gravity-engine.com/#/manage/metadata/eventFlow) 界面开启**加载实时数据**，并在产品中触发以下几个事件。事件验收与排错：[接入验收与排错](/docs/getting-started/integration-checklist)
| 事件名 | 事件英文名 | 触发时机 | 采集方式 | 默认映射到媒体事件 | 备注 |
| ---- | --------------- | ---------- | ----------------------- | --------- | ----------------------- |
| 用户注册 | `$AppRegister` | 用户完成业务注册之后 | 调用SDK的**上报业务注册事件**方法采集 | 暂无 | 接入了**业务注册上报事件**的产品均需要校验 |
| 付费 | `$PayEvent` | 用户付费之后 | 调用SDK的**上报用户付费事件**方法采集 | 付费 | 接入了**付费事件上报事件**的产品均需要校验 |
| 广告展示 | `$AdShow` | 用户观看广告之后 | 调用SDK的**上报广告展示事件**方法采集 | 暂无 | 接入了**广告事件上报事件**的产品均需要校验 |
| 用户提现 | `$UserWithdraw` | 用户提现之后 | 调用SDK的**上报用户提现事件** 方法采集 | 暂无 | 接入了**用户提现上报事件**的产品均需要校验 |
触发操作后，请在[事件流](https://web.gravity-engine.com/#/manage/metadata/eventFlow) 界面中筛选测试用户的 Client ID，观察对应事件是否出现在实时入库页面。若事件数据正常显示，则说明接入成功；如出现于错误数据页面请根据页面错误提示进行排查；如未显示对应数据，请及时联系引力运营支持团队获取协助。
### 6.2 避免重复上报 [#62-避免重复上报]
如果您之前单独接了媒体的回传(SDK 或者 API)，则上线之前需要去掉，否则可能会导致重复上报数据！
> **注意**
> 至此验证无误之后，您可以正常上线了。
# 行为事件上报
> 来源：https://help.gravity-engine.com/docs/client-sdk/ios/track-events
> 说明如何使用 Gravity Engine iOS SDK 上报业务事件，并管理事件公共属性。
本文档详细介绍了SDK提供的事件上报功能，帮助开发者全面采集用户行为事件数据，为业务分析和运营决策提供数据支持。
通过上报应用内用户行为事件，您可以：
* **完整记录用户行为**：追踪用户在应用内的关键操作路径
* **支持多维度分析**：通过事件属性丰富分析维度
* **构建数据闭环**：为产品优化和精准运营提供数据基础
## 1. 上报自定义事件 [#1-上报自定义事件]
> **注意**
> **如需上报自定义事件，您必须先在[元事件](https://web.gravity-engine.com/#/manage/metadata/metaEvent)中添加，否则会上报失败！**
> **注意**
> **事件名称是字符串类型，只能以字母开头，可包含数字，字母和下划线 “\_”，长度最大为 50 个字符**
您可以调用 `track` 方法，记录用户自定义事件。
您必须先在[元事件](https://web.gravity-engine.com/#/manage/metadata/metaEvent)中添加自定义事件，然后在游戏中指定位置埋点调用 `track` 方法上报自定义事件，此处以用户购买某商品作为范例。
**Objective-C**
```objective-c
NSDictionary *eventProperties = @{ @"product_name": @"商品名"};
[instance track:@"product_buy" properties:eventProperties];
```
**Swift**
```swift
let properties = ["product_name": "商品名"] as [String: Any]
instance?.track("product_buy", properties: properties)
```
## 2. 设置公共事件属性 [#2-设置公共事件属性]
> **注意**
> **公共属性需要先在[事件属性](https://web.gravity-engine.com/#/manage/metadata/eventProperty)中添加，否则会上报失败!**
对于一些重要的属性，譬如玩家的区服和渠道等，这些属性需要设置在每个事件中，此时您可以将这些属性设置为公共事件属性。公共事件属性指的就是每个事件都会带有的属性，您可以调用 `setSuperProperties` 来设置公共事件属性，我们推荐您在发送事件前，先设置公共事件属性。
**Objective-C**
```objective-c
NSMutableDictionary *superProperties = [NSMutableDictionary new];
[superProperties setValue:@"ta" forKey:@"channel"];//字符串
[superProperties setValue:@1 forKey:@"age"];//数字
[superProperties setValue:@YES forKey:@"isSuccess"];//布尔
[superProperties setValue:[NSDate now] forKey:@"birthday"];//时间
[superProperties setValue:@[@{@"key":@"value"}] forKey:@"object_arr"];//对象组
[superProperties setValue:@[@"value"] forKey:@"arr"];//数组
[instance setSuperProperties:superProperties];//设置公共事件属性
```
**Swift**
```swift
var superProperties: [AnyHashable : Any] = [:]
superProperties["channel"] = "ta" //字符串
superProperties["age"] = 1 //数字
superProperties["isSuccess"] = true //布尔
superProperties["birthday"] = Date() //时间
superProperties["object_arr"] = [["key": "value"]] // 对象组
superProperties["arr"] = ["value"] // 数组
//设置公共事件属性
instance.setSuperProperties(superProperties)
```
公共事件属性将会被保存到缓存中，无需每次启动 APP 时调用。如果调用 `setSuperProperties` 上传了先前已设置过的公共事件属性，则会覆盖之前的属性。如果公共事件属性和 `track()` 上传的某个属性的 Key 重复，则该事件的属性会覆盖公共事件属性。
* 事件的属性是一个 `NSDictionary` 对象，其中每个元素代表一个属性。
* `Key` 为该属性的名称，为字符串类型，规定只能以字母开头，包含数字，字母和下划线 "\_"，长度最大为 50 个字符。
* `Value` 为该属性的值，支持字符串、数字、布尔、时间、对象组、数组。
* 如果您需要上传布尔型的属性，则请以 `@YES` 与 `@NO` 或 `[NSNumber numberWithBool:YES]` 与 `[NSNumber numberWithBool:NO]` 来赋值。不可以使用 `@true`、 `@false`、 `@TRUE` 和 `@FALSE` 赋值布尔型数据。
* 如果您需要删除某个公共事件属性，可以调用 `unsetSuperProperty` 清除其中一个公共事件属性；
* 如果您想要清空所有公共事件属性，则可以调用 `clearSuperProperties`;
## 3. 记录事件时长 [#3-记录事件时长]
如果您需要记录某个事件持续时长，您可以调用 `timeEvent` 来开始计时，配置您想要计时的事件名称，当您上传该事件时，将会自动在您的事件属性中加入 `$event_duration` 这一属性来表示记录的时长，单位为秒。
**Objective-C**
```objective-c
//以下示例，完成用户在某个商品页面停留时长的统计
[instance timeEvent:@"stay_shop"];
/**do someting
.......
**/
//用户离开商品页面，计时结束，"stay_shop" 这一事件中将会带有表示事件时长的属性$event_duration
[instance track:@"stay_shop"];
```
**Swift**
```swift
//以下示例，完成用户在某个商品页面停留时长的统计
instance.timeEvent("stay_shop")
/**do someting
.......
**/
//用户离开商品页面，计时结束，"stay_shop" 这一事件中将会带有表示事件时长的属性$event_duration
instance.track("stay_shop")
```
## 4. 立即上报事件 [#4-立即上报事件]
如果需要立即上报缓存的事件，可以调用 `flush` 来上报所有缓存的事件。
**Objective-C**
```objective-c
[instance flush];
```
**Swift**
```swift
instance?.flush()
```
# 用户属性上报
> 来源：https://help.gravity-engine.com/docs/client-sdk/ios/user-properties
> 说明如何使用 Gravity Engine iOS SDK 设置、追加、累加和删除用户属性，并提供参数要求与调用示例。
本文档详细介绍了SDK提供的用户属性上报功能，帮助开发者高效地收集、更新和维护用户画像数据。
通过本功能，您可以：
* **全面记录用户特征**：存储用户基础信息（如昵称、性别）、行为偏好等关键数据
* **灵活更新用户画像**：支持覆盖、追加、数值计算等多种更新方式
* **构建精准用户模型**：通过属性组合分析，实现用户分群和个性化服务
> **注意**
> **如需上报自定义的用户属性，您必须先在[元数据](https://web.gravity-engine.com/#/manage/metadata/userProperty)中添加对应的用户属性，否则会上报失败！**
## 1. 设置用户属性 [#1-设置用户属性]
对于一般的用户属性，您可以调用 `user_set` 来进行设置，使用该接口上传的属性将会覆盖原有的属性值。
**Objective-C**
```objective-c
// 设置用户属性
//此时"username"为"GravityEngineUser"
[instance user_set:@{@"username": @"GravityEngineUser"}];
//此时"username"为"TestUserName"
[instance user_set:@{@"username": @"TestUserName"}];
```
**Swift**
```swift
// 设置用户属性
//此时"username"为"GravityEngineUser"
instance.user_set(["usernaame": "GravityEngineUser"])
//此时"username"为"TestUserName"
instance.user_set(["usernaame": "TestUserName"])
```
## 2. 初始化用户属性 [#2-初始化用户属性]
对于只在首次设置时有效的属性，我们可以使用 `user_set_once` 记录这些属性。与 `user_set` 方法不同的是，如果被设置的用户属性已存在，则这条记录会被忽略而不会覆盖已有数据。因此，`user_set_once` 适用于为用户设置首次激活时间、首次注册时间等属性。例如：
**Objective-C**
```objective-c
//first_payment_time为2023-01-01 04:43:35.968
[instance user_set_once:@{@"first_payment_time": @"2023-01-01 04:43:35.968"}];
//first_payment_time仍然为2023-01-01 04:43:35.968
[instance user_set_once:@{@"first_payment_time": @"2018-12-31 01:23:45.678"}];
```
**Swift**
```swift
//first_payment_time为2023-01-01 04:43:35.968
instance.user_set_once(["first_payment_time": "2023-01-01 04:43:35.968"])
//first_payment_time仍然为2023-01-01 04:43:35.968
instance.user_set_once(["first_payment_time": "2018-12-31 01:23:45.678"])
```
## 3. 累加用户属性 [#3-累加用户属性]
对于数值型的用户属性，可以使用 `user_increment` 对属性值进行累加。常用于记录用户付费次数、付费额度、积分等属性。例如：
**Objective-C**
```objective-c
//此时$age为30
[instance user_increment:@{@"$age": @30}];
//此时$age为32
[instance user_increment:@{@"$age": @2}];
```
**Swift**
```swift
//此时$age为30
instance.user_increment(["$age": 30])
//此时$age为32
instance.user_increment(["$age": 2])
```
## 4. 用户属性取最大值 [#4-用户属性取最大值]
对于数值型的用户属性，可以使用 `user_number_max` 用来比较数值大小，保存较大的
**Objective-C**
```objective-c
//此时$age为30
[instance user_number_max:@{@"$age": @30}];
//此时$age仍为30
[instance user_number_max:@{@"$age": @27}];
```
**Swift**
```swift
//此时$age为30
instance.user_number_max(["$age": 30])
//此时$age仍为30
instance.user_number_max(["$age": 27])
```
## 5. 用户属性取最小值 [#5-用户属性取最小值]
对于数值型的用户属性，可以使用 `user_number_min` 用来比较数值大小，保存较小的
**Objective-C**
```objective-c
//此时$age为30
[instance user_number_min:@{@"$age": @30}];
//此时$age仍为30
[instance user_number_min:@{@"$age": @100}];
```
**Swift**
```swift
//此时$age为30
instance.user_number_min(["$age": 30])
//此时$age仍为30
instance.user_number_min(["$age": 100])
```
## 6. 用户属性追加（Array） [#6-用户属性追加array]
对用户喜爱的电影、用户点评过的餐厅等属性，可以调用 `user_append` 记录列表型属性，例如：
**Objective-C**
```objective-c
// 调用 user_append 为用户属性 Movies 追加元素。
[instance user_append:@{@"Movies": @[@"Interstellar", @"The Negro Motorist Green Book"]}];
```
**Swift**
```swift
// 调用 user_append 为用户属性 Movies 追加元素。
instance.user_append(["Movies": ["Interstellar", "The Negro Motorist Green Book"]]);
```
## 7. 用户属性去重追加（Array） [#7-用户属性去重追加array]
调用 `user_uniqAppend` 用来对 Array 类型的用户数据去重追加元素，例如：
**Objective-C**
```objective-c
// 调用 user_uniqAppend 为用户属性 Movies 去重追加元素。
[instance user_uniqAppend:@{@"Movies": @[@"Interstellar", @"The Negro Motorist Green Book"]}];
```
**Swift**
```swift
// 调用 user_uniqAppend 为用户属性 Movies 去重追加元素。
instance.user_uniqAppend(["Movies": ["Interstellar", "The Negro Motorist Green Book"]]);
```
## 8. 清空用户属性 [#8-清空用户属性]
调用 `user_delete` 方法，将把当前用户属性清空，您将无法再查询该名用户的用户属性，但该用户产生的事件仍然可以被查询到
**Objective-C**
```objective-c
[instance user_delete];
```
**Swift**
```swift
instance.user_delete()
```
## 9. 重置用户属性 [#9-重置用户属性]
如果需要重置已设置的某个用户属性，可以调用 `user_unset` 进行重置：
**Objective-C**
```objective-c
// 清空该用户的累计付费金额属性值
[instance user_unset:@"total_pay"];
```
**Swift**
```swift
// 清空该用户的累计付费金额属性值
instance.user_unset("total_pay")
```
# Laya
> 来源：https://help.gravity-engine.com/docs/client-sdk/laya
> Laya SDK索引，汇总Laya快速集成、行为事件上报等主题，便于按功能进入对应的配置、接入或参考说明。
{/* Generated by scripts/generate-docs-routes.mjs. Do not edit. */}
## 目录 [#目录]
* [Laya快速集成](/docs/client-sdk/laya/quickstart)
* [行为事件上报](/docs/client-sdk/laya/track-events)
* [用户属性上报](/docs/client-sdk/laya/user-properties)
* [进阶功能](/docs/client-sdk/laya/advanced) — 子目录
# Laya快速集成
> 来源：https://help.gravity-engine.com/docs/client-sdk/laya/quickstart
> 介绍 Gravity Engine Laya SDK 的安装、初始化、用户注册与事件上报流程，并提供参数说明和调用示例。
本文档主要讲述 **Laya** 接入 [引力引擎](https://gravity-engine.com/) 的技术接入方案，在开始接入前，建议您先阅读 [接入前准备](/docs/getting-started/overview) 以了解接入必备的基础概念。
> **注意**
> 本接入方案仅适用于 **Laya** 开发的项目。如果您使用的是其他开发框架，请访问 [引力引擎SDK总览页面](/docs/client-sdk/sdk-overview) 选择对应的框架接入文档。
## 支持平台 [#支持平台]
* 
微信小游戏
* 
快手小游戏（打包成微信小游戏）
* 
抖音/Tiktok 小游戏
* 
支付宝小游戏
* 
OPPO快游戏
* 
VIVO快游戏
* 
华为快游戏
* 
小米快游戏
* 
百度小游戏
* 
淘宝小游戏
* 
Bilibili 小游戏
* 
京东小游戏（打包成微信小游戏）
* 
美团小游戏（打包成微信小游戏）
* 
Android
* 
iOS
### **媒体平台SDK集成说明** [#媒体平台sdk集成说明]
**🎯 集成策略说明：**
Laya SDK **仅针对【微信小游戏】平台** 集成了腾讯广告小游戏SDK。对于Laya项目发布至其他平台（如抖音小游戏、快手小游戏等），**我们未集成任何媒体的SDK**。
#### **微信小游戏平台 ✅** [#微信小游戏平台-]
* **状态**：已集成腾讯广告小游戏SDK
* **上报方式**：需**手动调用**我们提供的方法进行事件上报
* **版本**：自 `4.8.40` 开始支持
> **重要说明**
> 按照《腾讯广告小游戏 SDK 集成》的步骤完成集成后，引力SDK会**自动上报**以下两个基础事件给腾讯：
>
> * REGISTER（用户注册）
> * RE\_ACTIVE（沉默唤起）
>
> 此外，**START\_APP（小游戏启动）**事件由腾讯SDK**自动采集**（引力SDK初始化腾讯SDK时默认开启该功能）。
>
> 除以上事件外，其他所有事件（如付费、自定义行为等）均需**客户端手动调用**我们提供的方法进行上报。
>
> 点击查看详细集成文档：[腾讯广告小游戏 SDK 集成](/docs/client-sdk/mini-games/advanced/tencent-ads-integration)
## 1. 获取 AccessToken [#1-获取-accesstoken]
您可以在 [设置-应用管理](https://web.gravity-engine.com/#/manage/appmanage) 页面点击 **查看参数** 按钮获取当前应用的 AccessToken，请妥善保存避免泄露。
## 2. Native 平台支持 [#2-native-平台支持]
如果您的 Laya 项目需要支持 Android/iOS 原生平台，请分别在 Laya 导出的原生工程中完成对应平台的 SDK 集成，切换下方标签按平台查看：
**Android**
### 接入 Android SDK [#接入-android-sdk]
在 Laya 导出的 Android 项目里，集成 Android 版本的 GravityEngineSDK 即可，参考 [Android 接入文档](/docs/client-sdk/android/quickstart)。
**iOS**
### 导入通道文件 [#导入通道文件]
将下载的 `layasdk/native/iOS` 下的 `GravityEngineCocosCreatorChannel.h` 和 `GravityEngineCocosCreatorChannel.mm` 类文件引入到 Laya 导出的 iOS 项目下。
### 接入 iOS SDK [#接入-ios-sdk]
在 Laya 导出的 iOS 项目里集成 iOS 版本的 GravityEngineSDK，参考 [iOS 接入文档](/docs/client-sdk/ios/quickstart)。
## 3. 配置并启动 SDK [#3-配置并启动-sdk]
开始接入工作之前，您需要先 [下载 SDK](/docs/client-sdk/sdk-overview)。
从 `ge_laya_sdk_version.zip` 中导入 SDK：
### 3.1 导入 SDK [#31-导入-sdk]
**TypeScript 项目**
* 将声明文件 `GravityAnalyticsSDK.d.ts` 放入 `libs` 目录；
* 将 SDK 文件 `gravityengine.mg.layats.min.js` 放入 `bin/js` 目录中；
* 修改 `bin/index.js` 文件，加载 SDK：
```javascript
// sdk必须在bundle.js之前加载
loadLib("js/gravityengine.mg.layats.min.js");
loadLib("js/bundle.js");
```
**JavaScript 项目**
* 将 `gravityengine.mg.laya.min.js` 导入工程：
```javascript
import GravityAnalyticsAPI from "gravityengine.mg.laya.min.js";
```
### 3.2 初始化 SDK [#32-初始化-sdk]
**引入 SDK 后，即可进行 SDK 初始化参数配置：**
> **注意**
> **每次冷启动过程中，`GravityEngine` 的实例化方法 `new GravityAnalyticsAPI()` 与初始化方法 `setupAndStart()` 均只能被调用一次。`clientId` 参数必须在这两个方法的其中一个传入。**
```javascript
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();
```
> **注意**
> 通过 **非自建中台** 的方式导入历史用户到引力时，默认以 Android\_ID 作为 `clientID`。SDK 需将 `mClientIdPriorityOrder` 设为 **Android\_ID 优先**（如 `["ANDROID_ID","OAID"]`），与导入规则保持一致，否则同一设备会被算作两个用户。
> **注意**
> **配置项目合法域名：** 您需要将 `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)
若您的产品内有广告变现，则需要在用户点击广告观看的同时上报用户广告观看事件给引力，具体参考如下：
**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 | 建议填写 |
**小游戏**
```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 | 是 |
## 6. 接入验证 [#6-接入验证]
> **注意**
> **正式上线之前，请完成本节的校验，否则可能会导致买量上报异常！**
### 6.1 关键事件验证 [#61-关键事件验证]
在引力后台[事件流](https://web.gravity-engine.com/#/manage/metadata/eventFlow) 界面开启**加载实时数据**，并在产品中触发以下几个事件。事件验收与排错：[接入验收与排错](/docs/getting-started/integration-checklist)
| 事件名 | 事件英文名 | 触发时机 | 采集方式 | 默认映射到媒体事件 | 备注 |
| ---- | ----------------------------------------- | ---------- | ---------------------- | --------- | ----------------------- |
| 用户注册 | APP:`$AppRegister`
小游戏:`$MPRegister` | 用户完成业务注册之后 | 调用SDK的**上报业务注册事件**方法采集 | 暂无 | 接入了**业务注册上报事件**的产品均需要校验 |
| 付费 | `$PayEvent` | 用户付费之后 | 调用SDK的**上报用户付费事件**方法采集 | 付费 | 接入了**付费事件上报事件**的产品均需要校验 |
| 广告展示 | `$AdShow` | 用户观看广告之后 | 调用SDK的**上报广告展示事件**方法采集 | 暂无 | 接入了**广告事件上报事件**的产品均需要校验 |
触发操作后，请在[事件流](https://web.gravity-engine.com/#/manage/metadata/eventFlow) 界面中筛选测试用户的 Client ID，观察对应事件是否出现在实时入库页面。若事件数据正常显示，则说明接入成功；如出现于错误数据页面请根据页面错误提示进行排查；如未显示对应数据，请及时联系引力运营支持团队获取协助。
### 6.2 避免重复上报 [#62-避免重复上报]
上线前，请按媒体和事件核对回传来源（引力回传、媒体 SDK 自动采集、客户端手动上报、自有服务端 API），确认同一转化不会通过多条链路重复回传。需要切换到引力回传的事件，应在验证新链路正常后停用原有重复链路；媒体 SDK 的其他功能是否保留，请按对应集成文档确认。
> **注意**
> 至此验证无误之后，您可以正常上线了。
# 行为事件上报
> 来源：https://help.gravity-engine.com/docs/client-sdk/laya/track-events
> 说明如何使用 Gravity Engine Laya SDK 上报业务事件，并管理事件公共属性。
本文档详细介绍了SDK提供的事件上报功能，帮助开发者全面采集用户行为事件数据，为业务分析和运营决策提供数据支持。
通过上报应用内用户行为事件，您可以：
* **完整记录用户行为**：追踪用户在应用内的关键操作路径
* **支持多维度分析**：通过事件属性丰富分析维度
* **构建数据闭环**：为产品优化和精准运营提供数据基础
## 1. 上报自定义事件 [#1-上报自定义事件]
> **注意**
> **如需上报自定义事件，您必须先在[元事件](https://web.gravity-engine.com/#/manage/metadata/metaEvent)中添加，否则会上报失败！**
您可以直接调用 `track` 上传自定义事件，建议您根据准备阶段梳理的文档来设置事件的属性以及发送信息的条件，此处以购买商品为范例：
```javascript
ge.track(
"$purchase", // 追踪事件的名称
{
Item: "商品A",
ItemNum: 1,
Cost: 100,
Elements: ["apple", "ball", "cat"],
} // 需要上传的事件属性
);
```
* `track` 接口共有两个参数，第一个参数为事件的名称，第二个参数为事件的属性。
* 事件的名称是字符串，只能以字母开头，可包含数字、字母和下划线 "\_"，长度最大为 50 个字符。
* 事件的属性是 JS 对象，每个元素代表一个属性。
* 元素的 name 对应属性的名称，规定只能以字母开头，包含数字、字母和下划线 "\_"，长度最大为 50 个字符。
* 元素的 Value 为该属性的值，支持 `String`、`Integer`、`Float`、`Boolean`、`Date`、`DateTime` 和 `Array`；`Array` 中的内容可以为 `String`。
## 2. 公共属性 [#2-公共属性]
> **注意**
> **公共属性需要先在[事件属性](https://web.gravity-engine.com/#/manage/metadata/eventProperty)中添加，否则会上报失败!**
公共事件属性是所有事件（包括自动采集事件）都会包含的属性，用户属性中不会包含。
本节会介绍如何设置公共事件属性和动态公共属性。如果公共属性与事件中设置的自定义属性有相同 key 值，则最终的属性会根据下述优先级取值：
用户自定义事件属性 > 动态公共属性 > 事件公共属性
您可以调用 `setSuperProperties` 来设置公共事件属性，公共事件属性的格式要求与事件属性一致。在设置时只能传入常量，适合设置变化不频繁的属性。
根据属性优先级，自定义属性优先级高于事件公共属性，因此事件公共属性也可以作为某个属性的缺省值，在需要修改的事件中设置同名 Key 覆盖缺省值。
### 2.1 设置公共属性 [#21-设置公共属性]
```javascript
// 设置公共事件属性
ge.setSuperProperties({ channel: "渠道" });
// 使用 track 上传事件，此时事件中会带有公共事件属性
ge.track(
"Purchase", // 追踪事件的名称
{
Item: "商品A",
ItemNum: 1,
Cost: 100,
} // 需要上传的事件属性
);
/* 等价于在事件中加入这些公共属性
ge.track(
'Purchase', // 追踪事件的名称
{
Item:'商品A',
ItemNum:1,
Cost:100,
channel:'渠道' // 相当于在事件中加入这个属性
}
);
*/
```
如果多次调用 `setSuperProperties` 设置公共事件属性，则同名字段后面的调用会覆盖之前的同名字段。
### 2.2 删除公共属性 [#22-删除公共属性]
如果您需要删除某个公共事件属性，可以调用 `unsetSuperProperty()` 清除其中一个公共事件属性。
```javascript
// 清除属性名为 CHANNEL 的公共属性
ge.unsetSuperProperty("CHANNEL");
```
### 2.3 清空公共属性 [#23-清空公共属性]
如果您想要清空所有公共事件属性，则可以调用 `clearSuperProperties()`。
```javascript
// 清除公共事件属性
ge.clearSuperProperties();
```
### 2.4 获取公共属性 [#24-获取公共属性]
如果您想要获取所有公共事件属性，可以调用 `getSuperProperties`。
```javascript
// 获取静态公共事件属性
ge.getSuperProperties();
```
## 3. 设置事件上报时间 [#3-设置事件上报时间]
事件触发的时间默认取本机时间，但在一些情况下，可能需要手动设置事件的时间，可以使用以下方法进行调用：
> **注意**
> **第三个参数为事件触发时间，必须是 Date 类型，将会替换事件触发的时间，如果不传该参数，则事件触发时间默认选取用户的本机时间。**
```javascript
// 第三个参数可以输入 Date 类型的参数，替换事件触发时间
ge.track("event", { parakey: "paravalue" }, new Date());
// 如果没有 properties 需要上传，请传入一个空对象
ge.track("event", {}, new Date());
```
## 4. 记录事件时长 [#4-记录事件时长]
您可以调用 `timeEvent` 来开始计时，配置您想要计时的事件名称，当您上传该事件时，将会自动在您的事件属性中加入 `$event_duration` 这一属性来表示记录的时长，单位为秒。
```javascript
// 用户进入商品页面，开始计时，记录的事件为 "Enter_Shop"
ge.timeEvent("Enter_Shop");
// ...
// 上传事件，计时结束，"Enter_Shop" 这一事件中将会带有表示事件时长的属性 $event_duration
ge.track("Enter_Shop", { product_id: "A1354" });
```
## 5. 立即上报事件 [#5-立即上报事件]
如果需要立即上报缓存的事件，可以调用 `flush` 来上报所有缓存的事件。
```javascript
ge.flush();
```
# 用户属性上报
> 来源：https://help.gravity-engine.com/docs/client-sdk/laya/user-properties
> 说明如何使用 Gravity Engine Laya SDK 设置、追加、累加和删除用户属性，并提供参数要求与调用示例。
本文档详细介绍了SDK提供的用户属性上报功能，帮助开发者高效地收集、更新和维护用户画像数据。
通过本功能，您可以：
* **全面记录用户特征**：存储用户基础信息（如昵称、性别）、行为偏好等关键数据
* **灵活更新用户画像**：支持覆盖、追加、数值计算等多种更新方式
* **构建精准用户模型**：通过属性组合分析，实现用户分群和个性化服务
> **注意**
> **如需上报自定义的用户属性，您必须先在[元数据](https://web.gravity-engine.com/#/manage/metadata/userProperty)中添加对应的用户属性，否则会上报失败！**
## 1. 设置用户属性 [#1-设置用户属性]
对于一般的用户属性，您可以调用 `userSet` 来进行设置，使用该接口上传的属性将会覆盖原有的属性值。
```javascript
// 设置用户属性，会员等级
ge.userSet({ vip_level: "钻石会员" });
```
> **注意**
> 属性格式要求与事件属性保持一致。
## 2. 初始化用户属性 [#2-初始化用户属性]
如果您要上传的用户属性只要设置一次，则可以调用 `userSetOnce` 来进行设置，当该属性之前已经有值的时候，将会忽略这条信息。
```javascript
// 以设置用户名为例，如果用户名已设置，则忽略本次设置
ge.userSetOnce({ user_name: "TestUser" });
```
> **注意**
> 属性格式要求与事件属性保持一致。
## 3. 累加用户属性 [#3-累加用户属性]
当您要上传数值型的属性时，您可以调用 `userAdd` 来对该属性进行累加操作。
```javascript
// 以付费为例，用户每次付费时调用此接口，则 'total_revenue' 字段每次会做累加付费金额的处理
ge.userAdd({ total_revenue: 50 });
```
> **注意**
> 设置的属性 key 为字符串，Value 只允许为数值。
## 4. 重置用户属性 [#4-重置用户属性]
当您要清空用户的某个用户属性值时，您可以调用 `userUnset` 来对指定属性进行清空操作。
```javascript
// 清空属性名为 userPropertyKey 的用户属性值，即设置为 NULL
ge.userUnset("userPropertyKey");
```
> **注意**
> `userUnset` 的传入值为被清空属性的 Key 值。
## 5. 清空用户属性 [#5-清空用户属性]
如果您要删除某个用户，可以调用 `userDel` 将这名用户删除，您将无法再查询该名用户的用户属性，但该用户产生的事件仍然可以被查询到。
```javascript
ge.userDel();
```
## 6. 用户属性追加（Array） [#6-用户属性追加array]
您可以调用 `userAppend` 对 Array（List）类型的用户数据追加元素。
```javascript
ge.userAppend({ Movies: ["Interstellar", "The Negro Motorist Green Book"] });
```
## 7. 用户属性去重追加（Array） [#7-用户属性去重追加array]
`userUniqAppend` 用来对 Array（List）类型的用户数据**去重**追加元素。
```javascript
ge.userUniqAppend({
Movies: ["Interstellar", "The Negro Motorist Green Book"],
});
```
## 8. 用户属性取最大值 [#8-用户属性取最大值]
`userNumberMax` 用来比较数值大小，保存较大的。
```javascript
ge.userNumberMax({
ad_ecpm_max: 300,
});
```
## 9. 用户属性取最小值 [#9-用户属性取最小值]
`userNumberMin` 用来比较数值大小，保存较小的。
```javascript
ge.userNumberMin({
ad_ecpm_min: 17,
});
```
# 360小程序快速集成
> 来源：https://help.gravity-engine.com/docs/client-sdk/mini-programs/360-quickstart
> 介绍 Gravity Engine 360小程序 SDK 的安装、初始化、用户注册与事件上报流程，并提供参数说明和调用示例。
本文档主要讲述 **原生 360 小程序** 接入 [引力引擎](https://gravity-engine.com/) 的技术接入方案，在开始接入前，建议您先阅读 [接入前准备](/docs/getting-started/overview) 以了解接入必备的基础概念。
> **注意**
> 本接入方案仅适用于官方 **原生 360 小程序** 开发的项目。如果您使用的是其他开发框架（如 egret、uni-app 等），请访问 [引力引擎 SDK 总览页面](/docs/client-sdk/sdk-overview) 选择对应的框架接入文档。
## 1. 获取 AccessToken [#1-获取-accesstoken]
您可以在[设置-应用管理](https://web.gravity-engine.com/#/manage/appmanage)页面点击"查看参数"按钮获取当前应用的 AccessToken，请妥善保存避免泄露。
## 2. 配置并启动 SDK [#2-配置并启动-sdk]
开始接入工作之前，您需要先[下载 SDK](/docs/client-sdk/sdk-overview)。
将 `ge_mp_sdk_version.zip` 中的 `gravityengine.qh.min.js` 文件导入 360 小程序原生项目中：
```js
import GravityEngine from "./utils/gravityengine.qh.min.js";
```
引入 SDK 后，即可进行 SDK 初始化参数配置：
> **注意**
> **每次冷启动过程中，`GravityEngine` 的实例化方法 `new GravityEngine()` 与初始化方法 `setupAndStart()` 均只能被调用一次。`clientId` 参数必须在这两个方法的其中一个传入。**
```js
const config = {
accessToken: "your_access_token", // 项目通行证，在：网站后台-->设置-->应用列表中找到Access Token列 复制（首次使用可能需要先新增应用）
// clientId如果当前还无法获取，可以不传但是不能传空字符串，等后面获取之后通过setupAndStart设置
clientId: "your_client_id", // 用户唯一标识，如产品为小游戏，则必须填用户openid（注意，不是小游戏的APPID！！！）
//预设公共属性
presetSuperProperties:{
"testSuperKey":"testSuperValue"
}
};
const ge = new GravityEngine(config);
ge.setupAndStart();
```
> **注意**
> **配置项目合法域名：** 您需要将 `https://api.gravity-engine.com` 配置到开发者后台 request 合法域名列表中。
## 3. 初始化 [#3-初始化]
在用户可以获取到用户唯一 ID 时调用此方法，推荐首次启动时调用。
> **注意**
> 首次调用后，需要在 `initialize` 的 `then` 中才能继续调用其他事件上报的方法
>
> 初始化方法调用成功之后，后续冷启动可以不再调用，只需要正常启动 SDK 即可（多次调用也不会有问题，引力做了兼容）
### 方法示例 [#方法示例]
```js
ge.initialize({
name: "your_name",
version: 123,
openid: "your_openid",
enable_sync_attribution: false,
adData:{
"testAdKey":"testAdValue"
}
})
.then((res) => {
console.log("initialize success", res);
})
.catch((err) => {
console.log("initialize failed", err);
});
```
### 参数说明 [#参数说明]
| 参数名称 | 参数含义 | 参数类型 | 是否必传 |
| ------------------------- | -------------------------------------------------------------------------------------------- | ------- | ---- |
| name | 用户名或用户唯一 ID（可理解为业务中的昵称），如果不需要昵称，可以填默认值，但不可以传空字符串！ | string | 是 |
| version | 产品发布版本号，便于后续在引力后台过滤 | number | 是 |
| openid | 用户 openid | string | 是 |
| enable\_sync\_attribution | 是否开启同步获取归因信息（参考[同步归因](/docs/attribution/synchronous-attribution)文档）。在媒体点击下发延迟的情况下会影响归因，请谨慎开启 | boolean | 是 |
| channel | 当前用户来源渠道，对应用户细查中的：客户端渠道 | string | 否 |
| adData | 预设归因信息 | object | 否 |
## 4. 事件上报 [#4-事件上报]
### 4.1 业务注册事件上报 [#41-业务注册事件上报]
> **注意**
> **此功能仅适用于需要统计业务注册转化数据的场景。如果您的应用不需要追踪用户注册行为，可以跳过此事件接入。**
> **注意**
> 该方法可多次调用，每次调用都会上报一个用户注册事件（计算指标时会去重）
当用户完成应用内业务注册后，您可以调用 `registerEvent` 方法来上报用户注册事件（`$MPRegister`）给引力，引力会使用该事件统计指标：标准\_注册数
#### 调用示例 [#调用示例]
```js
ge.registerEvent();
```
### 4.2 付费事件上报 [#42-付费事件上报]
> **注意**
> **付费事件上报用于收入统计和分析，如您的应用不涉及内购或付费服务，则无需接入此事件。**
> **注意**
> 如果您需要通过后端 API 方式上报付费事件，请参考 [混合上报模式](/docs/client-sdk/hybrid-reporting) 来接入事件上报接口报送付费事件。
当用户发生付费行为时，需要调用 `payEvent` 方法记录用户付费事件，此事件非常重要，会影响买量和 ROI 统计，请务必重点测试！
#### 方法示例 [#方法示例-1]
```js
ge.payEvent(payAmount, payType, orderId, payReason, payMethod);
```
#### 参数说明 [#参数说明-1]
| 参数名称 | 参数含义 | 参数类型 | 是否必传 |
| --------- | ------------------------------------------------------------------------------------------------------------------------ | ------ | ---- |
| 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]
```js
ge.payEvent(300, "CNY", "your_order_id", "月卡", "支付宝");
```
## 5. 接入验证 [#5-接入验证]
> **注意**
> **正式上线之前，请完成本节的校验，否则可能会导致买量上报异常！**
### 5.1 关键事件验证 [#51-关键事件验证]
在引力后台[事件流](https://web.gravity-engine.com/#/manage/metadata/eventFlow)界面开启**加载实时数据**，并在产品中触发以下几个事件。事件验收与排错：[接入验收与排错](/docs/getting-started/integration-checklist)
| 事件名 | 事件英文名 | 触发时机 | 采集方式 | 默认映射到媒体事件 | 备注 |
| ---- | ------------- | ---------- | ------------------------ | --------- | ----------------------- |
| 用户注册 | `$MPRegister` | 用户完成业务注册之后 | 调用 SDK 的**上报业务注册事件**方法采集 | 暂无 | 接入了**业务注册上报事件**的产品均需要校验 |
| 付费 | `$PayEvent` | 用户付费之后 | 调用 SDK 的**上报用户付费事件**方法采集 | 付费 | 接入了**付费事件上报事件**的产品均需要校验 |
| 广告展示 | `$AdShow` | 用户观看广告之后 | 调用 SDK 的**上报广告展示事件**方法采集 | 暂无 | 接入了**广告事件上报事件**的产品均需要校验 |
触发操作后，请在[事件流](https://web.gravity-engine.com/#/manage/metadata/eventFlow)界面中筛选测试用户的 Client ID，观察对应事件是否出现在实时入库页面。若事件数据正常显示，则说明接入成功；如出现于错误数据页面请根据页面错误提示进行排查；如未显示对应数据，请及时联系引力运营支持团队获取协助。
### 5.2 避免重复上报 [#52-避免重复上报]
上线前，请按媒体和事件核对回传来源（引力回传、媒体 SDK 自动采集、客户端手动上报、自有服务端 API），确认同一转化不会通过多条链路重复回传。需要切换到引力回传的事件，应在验证新链路正常后停用原有重复链路；媒体 SDK 的其他功能是否保留，请按对应集成文档确认。
> **注意**
> 至此验证无误之后，您可以正常上线了。
以上是 SDK 的基础接入指引。如需使用 **行为事件上报、用户属性上报、进阶功能、自动采集** 等功能，请参考以下文档：
> **注意**
> 这些功能并非所有业务场景都需要，请按需查阅。
* [行为事件上报](/docs/client-sdk/mini-programs/track-events)
* [用户属性上报](/docs/client-sdk/mini-programs/user-properties)
* [进阶功能](/docs/client-sdk/mini-programs/advanced)
* [自动采集](/docs/client-sdk/mini-programs/advanced/automatic-tracking)
# 支付宝小程序快速集成
> 来源：https://help.gravity-engine.com/docs/client-sdk/mini-programs/alipay-quickstart
> 介绍 Gravity Engine 支付宝小程序 SDK 的安装、初始化、用户注册与事件上报流程，并提供参数说明和调用示例。
本文档主要讲述 **原生支付宝小程序** 接入 [引力引擎](https://gravity-engine.com/) 的技术接入方案，在开始接入前，建议您先阅读 [接入前准备](/docs/getting-started/overview) 以了解接入必备的基础概念。
> **注意**
> 本接入方案仅适用于官方 **原生支付宝小程序** 开发的项目。如果您使用的是其他开发框架（如 Taro、uni-app 等），请访问 [引力引擎 SDK 总览页面](/docs/client-sdk/sdk-overview) 选择对应的框架接入文档。
## 1. 获取 AccessToken [#1-获取-accesstoken]
您可以在[设置-应用管理](https://web.gravity-engine.com/#/manage/appmanage)页面点击"查看参数"按钮获取当前应用的 AccessToken，请妥善保存避免泄露。
## 2. 配置并启动 SDK [#2-配置并启动-sdk]
开始接入工作之前，您需要先[下载 SDK](/docs/client-sdk/sdk-overview)。
将 `ge_mp_sdk_version.zip` 中的 `gravityengine.my.min.js` 文件导入支付宝小程序原生项目中：
```js
import GravityEngine from "./utils/gravityengine.my.min.js";
```
引入 SDK 后，即可进行 SDK 初始化参数配置：
> **注意**
> **每次冷启动过程中，`GravityEngine` 的实例化方法 `new GravityEngine()` 与初始化方法 `setupAndStart()` 均只能被调用一次。`clientId` 参数必须在这两个方法的其中一个传入。**
```js
const config = {
accessToken: "your_access_token", // 项目通行证，在：网站后台-->设置-->应用列表中找到Access Token列 复制（首次使用可能需要先新增应用）
// clientId如果当前还无法获取，可以不传但是不能传空字符串，等后面获取之后通过setupAndStart设置
clientId: "your_client_id", // 用户唯一标识，如产品为小游戏，则必须填用户openid（注意，不是小游戏的APPID！！！）
//预设公共属性
presetSuperProperties:{
"testSuperKey":"testSuperValue"
}
};
const ge = new GravityEngine(config);
ge.setupAndStart();
```
> **注意**
> **配置项目合法域名：** 您需要将 `https://api.gravity-engine.com` 配置到开发者后台 request 合法域名列表中。
## 3. 初始化 [#3-初始化]
在用户可以获取到用户唯一 ID 时调用此方法，推荐首次启动时调用。
> **注意**
> 首次调用后，需要在 `initialize` 的 `then` 中才能继续调用其他事件上报的方法
>
> 初始化方法调用成功之后，后续冷启动可以不再调用，只需要正常启动 SDK 即可（多次调用也不会有问题，引力做了兼容）
### 方法示例 [#方法示例]
```js
ge.initialize({
name: "your_name",
version: 123,
openid: "your_openid",
enable_sync_attribution: false,
adData:{
"testAdKey":"testAdValue"
}
})
.then((res) => {
console.log("initialize success", res);
})
.catch((err) => {
console.log("initialize failed", err);
});
```
### 参数说明 [#参数说明]
| 参数名称 | 参数含义 | 参数类型 | 是否必传 |
| ------------------------- | -------------------------------------------------------------------------------------------- | ------- | ---- |
| name | 用户名或用户唯一 ID（可理解为业务中的昵称），如果不需要昵称，可以填默认值，但不可以传空字符串！ | string | 是 |
| version | 产品发布版本号，便于后续在引力后台过滤 | number | 是 |
| openid | 用户 openid | string | 是 |
| enable\_sync\_attribution | 是否开启同步获取归因信息（参考[同步归因](/docs/attribution/synchronous-attribution)文档）。在媒体点击下发延迟的情况下会影响归因，请谨慎开启 | boolean | 是 |
| channel | 当前用户来源渠道，对应用户细查中的：客户端渠道 | string | 否 |
| adData | 预设归因信息 | object | 否 |
## 4. 事件上报 [#4-事件上报]
### 4.1 业务注册事件上报 [#41-业务注册事件上报]
> **注意**
> **此功能仅适用于需要统计业务注册转化数据的场景。如果您的应用不需要追踪用户注册行为，可以跳过此事件接入。**
> **注意**
> 该方法可多次调用，每次调用都会上报一个用户注册事件（计算指标时会去重）
当用户完成应用内业务注册后，您可以调用 `registerEvent` 方法来上报用户注册事件（`$MPRegister`）给引力，引力会使用该事件统计指标：标准\_注册数
#### 调用示例 [#调用示例]
```js
ge.registerEvent();
```
### 4.2 付费事件上报 [#42-付费事件上报]
> **注意**
> **付费事件上报用于收入统计和分析，如您的应用不涉及内购或付费服务，则无需接入此事件。**
> **注意**
> 如果您需要通过后端 API 方式上报付费事件，请参考 [混合上报模式](/docs/client-sdk/hybrid-reporting) 来接入事件上报接口报送付费事件。
当用户发生付费行为时，需要调用 `payEvent` 方法记录用户付费事件，此事件非常重要，会影响买量和 ROI 统计，请务必重点测试！
#### 方法示例 [#方法示例-1]
```js
ge.payEvent(payAmount, payType, orderId, payReason, payMethod);
```
#### 参数说明 [#参数说明-1]
| 参数名称 | 参数含义 | 参数类型 | 是否必传 |
| --------- | ------------------------------------------------------------------------------------------------------------------------ | ------ | ---- |
| 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]
```js
ge.payEvent(300, "CNY", "your_order_id", "月卡", "支付宝");
```
## 5. 接入验证 [#5-接入验证]
> **注意**
> **正式上线之前，请完成本节的校验，否则可能会导致买量上报异常！**
### 5.1 关键事件验证 [#51-关键事件验证]
在引力后台[事件流](https://web.gravity-engine.com/#/manage/metadata/eventFlow)界面开启**加载实时数据**，并在产品中触发以下几个事件。事件验收与排错：[接入验收与排错](/docs/getting-started/integration-checklist)
| 事件名 | 事件英文名 | 触发时机 | 采集方式 | 默认映射到媒体事件 | 备注 |
| ---- | ------------- | ---------- | ------------------------ | --------- | ----------------------- |
| 用户注册 | `$MPRegister` | 用户完成业务注册之后 | 调用 SDK 的**上报业务注册事件**方法采集 | 暂无 | 接入了**业务注册上报事件**的产品均需要校验 |
| 付费 | `$PayEvent` | 用户付费之后 | 调用 SDK 的**上报用户付费事件**方法采集 | 付费 | 接入了**付费事件上报事件**的产品均需要校验 |
| 广告展示 | `$AdShow` | 用户观看广告之后 | 调用 SDK 的**上报广告展示事件**方法采集 | 暂无 | 接入了**广告事件上报事件**的产品均需要校验 |
触发操作后，请在[事件流](https://web.gravity-engine.com/#/manage/metadata/eventFlow)界面中筛选测试用户的 Client ID，观察对应事件是否出现在实时入库页面。若事件数据正常显示，则说明接入成功；如出现于错误数据页面请根据页面错误提示进行排查；如未显示对应数据，请及时联系引力运营支持团队获取协助。
### 5.2 避免重复上报 [#52-避免重复上报]
上线前，请按媒体和事件核对回传来源（引力回传、媒体 SDK 自动采集、客户端手动上报、自有服务端 API），确认同一转化不会通过多条链路重复回传。需要切换到引力回传的事件，应在验证新链路正常后停用原有重复链路；媒体 SDK 的其他功能是否保留，请按对应集成文档确认。
> **注意**
> 至此验证无误之后，您可以正常上线了。
以上是 SDK 的基础接入指引。如需使用 **行为事件上报、用户属性上报、进阶功能、自动采集** 等功能，请参考以下文档：
> **注意**
> 这些功能并非所有业务场景都需要，请按需查阅。
* [行为事件上报](/docs/client-sdk/mini-programs/track-events)
* [用户属性上报](/docs/client-sdk/mini-programs/user-properties)
* [进阶功能](/docs/client-sdk/mini-programs/advanced)
* [自动采集](/docs/client-sdk/mini-programs/advanced/automatic-tracking)
# 百度小程序快速集成
> 来源：https://help.gravity-engine.com/docs/client-sdk/mini-programs/baidu-quickstart
> 介绍 Gravity Engine 百度小程序 SDK 的安装、初始化、用户注册与事件上报流程，并提供参数说明和调用示例。
本文档主要讲述 **原生百度小程序** 接入 [引力引擎](https://gravity-engine.com/) 的技术接入方案，在开始接入前，建议您先阅读 [接入前准备](/docs/getting-started/overview) 以了解接入必备的基础概念。
> **注意**
> 本接入方案仅适用于官方 **原生百度小程序** 开发的项目。如果您使用的是其他开发框架（如 Taro、uni-app 等），请访问 [引力引擎 SDK 总览页面](/docs/client-sdk/sdk-overview) 选择对应的框架接入文档。
## 1. 获取 AccessToken [#1-获取-accesstoken]
您可以在[设置-应用管理](https://web.gravity-engine.com/#/manage/appmanage)页面点击"查看参数"按钮获取当前应用的 AccessToken，请妥善保存避免泄露。
## 2. 配置并启动 SDK [#2-配置并启动-sdk]
开始接入工作之前，您需要先[下载 SDK](/docs/client-sdk/sdk-overview)。
将 `ge_mp_sdk_version.zip` 中的 `gravityengine.swan.min.js` 文件导入百度小程序原生项目中：
```js
import GravityEngine from "./utils/gravityengine.swan.min.js";
```
引入 SDK 后，即可进行 SDK 初始化参数配置：
> **注意**
> **每次冷启动过程中，`GravityEngine` 的实例化方法 `new GravityEngine()` 与初始化方法 `setupAndStart()` 均只能被调用一次。`clientId` 参数必须在这两个方法的其中一个传入。**
```js
const config = {
accessToken: "your_access_token", // 项目通行证，在：网站后台-->设置-->应用列表中找到Access Token列 复制（首次使用可能需要先新增应用）
// clientId如果当前还无法获取，可以不传但是不能传空字符串，等后面获取之后通过setupAndStart设置
clientId: "your_client_id", // 用户唯一标识，如产品为小游戏，则必须填用户openid（注意，不是小游戏的APPID！！！）
//预设公共属性
presetSuperProperties:{
"testSuperKey":"testSuperValue"
}
};
const ge = new GravityEngine(config);
ge.setupAndStart();
```
> **注意**
> **配置项目合法域名：** 您需要将 `https://api.gravity-engine.com` 配置到开发者后台 request 合法域名列表中。
## 3. 初始化 [#3-初始化]
在用户可以获取到用户唯一 ID 时调用此方法，推荐首次启动时调用。
> **注意**
> 首次调用后，需要在 `initialize` 的 `then` 中才能继续调用其他事件上报的方法
>
> 初始化方法调用成功之后，后续冷启动可以不再调用，只需要正常启动 SDK 即可（多次调用也不会有问题，引力做了兼容）
### 方法示例 [#方法示例]
```js
ge.initialize({
name: "your_name",
version: 123,
openid: "your_openid",
enable_sync_attribution: false,
adData:{
"testAdKey":"testAdValue"
}
})
.then((res) => {
console.log("initialize success", res);
})
.catch((err) => {
console.log("initialize failed", err);
});
```
### 参数说明 [#参数说明]
| 参数名称 | 参数含义 | 参数类型 | 是否必传 |
| ------------------------- | -------------------------------------------------------------------------------------------- | ------- | ---- |
| name | 用户名或用户唯一 ID（可理解为业务中的昵称），如果不需要昵称，可以填默认值，但不可以传空字符串！ | string | 是 |
| version | 产品发布版本号，便于后续在引力后台过滤 | number | 是 |
| openid | 用户 openid | string | 是 |
| enable\_sync\_attribution | 是否开启同步获取归因信息（参考[同步归因](/docs/attribution/synchronous-attribution)文档）。在媒体点击下发延迟的情况下会影响归因，请谨慎开启 | boolean | 是 |
| channel | 当前用户来源渠道，对应用户细查中的：客户端渠道 | string | 否 |
| adData | 预设归因信息 | object | 否 |
## 4. 事件上报 [#4-事件上报]
### 4.1 业务注册事件上报 [#41-业务注册事件上报]
> **注意**
> **此功能仅适用于需要统计业务注册转化数据的场景。如果您的应用不需要追踪用户注册行为，可以跳过此事件接入。**
> **注意**
> 该方法可多次调用，每次调用都会上报一个用户注册事件（计算指标时会去重）
当用户完成应用内业务注册后，您可以调用 `registerEvent` 方法来上报用户注册事件（`$MPRegister`）给引力，引力会使用该事件统计指标：标准\_注册数
#### 调用示例 [#调用示例]
```js
ge.registerEvent();
```
### 4.2 付费事件上报 [#42-付费事件上报]
> **注意**
> **付费事件上报用于收入统计和分析，如您的应用不涉及内购或付费服务，则无需接入此事件。**
> **注意**
> 如果您需要通过后端 API 方式上报付费事件，请参考 [混合上报模式](/docs/client-sdk/hybrid-reporting) 来接入事件上报接口报送付费事件。
当用户发生付费行为时，需要调用 `payEvent` 方法记录用户付费事件，此事件非常重要，会影响买量和 ROI 统计，请务必重点测试！
#### 方法示例 [#方法示例-1]
```js
ge.payEvent(payAmount, payType, orderId, payReason, payMethod);
```
#### 参数说明 [#参数说明-1]
| 参数名称 | 参数含义 | 参数类型 | 是否必传 |
| --------- | ------------------------------------------------------------------------------------------------------------------------ | ------ | ---- |
| 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]
```js
ge.payEvent(300, "CNY", "your_order_id", "月卡", "支付宝");
```
## 5. 接入验证 [#5-接入验证]
> **注意**
> **正式上线之前，请完成本节的校验，否则可能会导致买量上报异常！**
### 5.1 关键事件验证 [#51-关键事件验证]
在引力后台[事件流](https://web.gravity-engine.com/#/manage/metadata/eventFlow)界面开启**加载实时数据**，并在产品中触发以下几个事件。事件验收与排错：[接入验收与排错](/docs/getting-started/integration-checklist)
| 事件名 | 事件英文名 | 触发时机 | 采集方式 | 默认映射到媒体事件 | 备注 |
| ---- | ------------- | ---------- | ------------------------ | --------- | ----------------------- |
| 用户注册 | `$MPRegister` | 用户完成业务注册之后 | 调用 SDK 的**上报业务注册事件**方法采集 | 暂无 | 接入了**业务注册上报事件**的产品均需要校验 |
| 付费 | `$PayEvent` | 用户付费之后 | 调用 SDK 的**上报用户付费事件**方法采集 | 付费 | 接入了**付费事件上报事件**的产品均需要校验 |
| 广告展示 | `$AdShow` | 用户观看广告之后 | 调用 SDK 的**上报广告展示事件**方法采集 | 暂无 | 接入了**广告事件上报事件**的产品均需要校验 |
触发操作后，请在[事件流](https://web.gravity-engine.com/#/manage/metadata/eventFlow)界面中筛选测试用户的 Client ID，观察对应事件是否出现在实时入库页面。若事件数据正常显示，则说明接入成功；如出现于错误数据页面请根据页面错误提示进行排查；如未显示对应数据，请及时联系引力运营支持团队获取协助。
### 5.2 避免重复上报 [#52-避免重复上报]
上线前，请按媒体和事件核对回传来源（引力回传、媒体 SDK 自动采集、客户端手动上报、自有服务端 API），确认同一转化不会通过多条链路重复回传。需要切换到引力回传的事件，应在验证新链路正常后停用原有重复链路；媒体 SDK 的其他功能是否保留，请按对应集成文档确认。
> **注意**
> 至此验证无误之后，您可以正常上线了。
以上是 SDK 的基础接入指引。如需使用 **行为事件上报、用户属性上报、进阶功能、自动采集** 等功能，请参考以下文档：
> **注意**
> 这些功能并非所有业务场景都需要，请按需查阅。
* [行为事件上报](/docs/client-sdk/mini-programs/track-events)
* [用户属性上报](/docs/client-sdk/mini-programs/user-properties)
* [进阶功能](/docs/client-sdk/mini-programs/advanced)
* [自动采集](/docs/client-sdk/mini-programs/advanced/automatic-tracking)
# 钉钉小程序快速集成
> 来源：https://help.gravity-engine.com/docs/client-sdk/mini-programs/dingtalk-quickstart
> 介绍 Gravity Engine 钉钉小程序 SDK 的安装、初始化、用户注册与事件上报流程，并提供参数说明和调用示例。
本文档主要讲述 **原生钉钉小程序** 接入 [引力引擎](https://gravity-engine.com/) 的技术接入方案，在开始接入前，建议您先阅读 [接入前准备](/docs/getting-started/overview) 以了解接入必备的基础概念。
> **注意**
> 本接入方案仅适用于官方 **原生钉钉小程序** 开发的项目。如果您使用的是其他开发框架（如 Taro、uni-app 等），请访问 [引力引擎 SDK 总览页面](/docs/client-sdk/sdk-overview) 选择对应的框架接入文档。
## 1. 获取 AccessToken [#1-获取-accesstoken]
您可以在[设置-应用管理](https://web.gravity-engine.com/#/manage/appmanage)页面点击"查看参数"按钮获取当前应用的 AccessToken，请妥善保存避免泄露。
## 2. 配置并启动 SDK [#2-配置并启动-sdk]
开始接入工作之前，您需要先[下载 SDK](/docs/client-sdk/sdk-overview)。
将 `ge_mp_sdk_version.zip` 中的 `gravityengine.dd.min.js` 文件导入钉钉小程序原生项目中：
```js
import GravityEngine from "./utils/gravityengine.dd.min.js";
```
引入 SDK 后，即可进行 SDK 初始化参数配置：
> **注意**
> **每次冷启动过程中，`GravityEngine` 的实例化方法 `new GravityEngine()` 与初始化方法 `setupAndStart()` 均只能被调用一次。`clientId` 参数必须在这两个方法的其中一个传入。**
```js
const config = {
accessToken: "your_access_token", // 项目通行证，在：网站后台-->设置-->应用列表中找到Access Token列 复制（首次使用可能需要先新增应用）
// clientId如果当前还无法获取，可以不传但是不能传空字符串，等后面获取之后通过setupAndStart设置
clientId: "your_client_id", // 用户唯一标识，如产品为小游戏，则必须填用户openid（注意，不是小游戏的APPID！！！）
//预设公共属性
presetSuperProperties:{
"testSuperKey":"testSuperValue"
}
};
const ge = new GravityEngine(config);
ge.setupAndStart();
```
> **注意**
> **配置项目合法域名：** 您需要将 `https://api.gravity-engine.com` 配置到开发者后台 request 合法域名列表中。
## 3. 初始化 [#3-初始化]
在用户可以获取到用户唯一 ID 时调用此方法，推荐首次启动时调用。
> **注意**
> 首次调用后，需要在 `initialize` 的 `then` 中才能继续调用其他事件上报的方法
>
> 初始化方法调用成功之后，后续冷启动可以不再调用，只需要正常启动 SDK 即可（多次调用也不会有问题，引力做了兼容）
### 方法示例 [#方法示例]
```js
ge.initialize({
name: "your_name",
version: 123,
openid: "your_openid",
enable_sync_attribution: false,
adData:{
"testAdKey":"testAdValue"
}
})
.then((res) => {
console.log("initialize success", res);
})
.catch((err) => {
console.log("initialize failed", err);
});
```
### 参数说明 [#参数说明]
| 参数名称 | 参数含义 | 参数类型 | 是否必传 |
| ------------------------- | -------------------------------------------------------------------------------------------- | ------- | ---- |
| name | 用户名或用户唯一 ID（可理解为业务中的昵称），如果不需要昵称，可以填默认值，但不可以传空字符串！ | string | 是 |
| version | 产品发布版本号，便于后续在引力后台过滤 | number | 是 |
| openid | 用户 openid | string | 是 |
| enable\_sync\_attribution | 是否开启同步获取归因信息（参考[同步归因](/docs/attribution/synchronous-attribution)文档）。在媒体点击下发延迟的情况下会影响归因，请谨慎开启 | boolean | 是 |
| channel | 当前用户来源渠道，对应用户细查中的：客户端渠道 | string | 否 |
| adData | 预设归因信息 | object | 否 |
## 4. 事件上报 [#4-事件上报]
### 4.1 业务注册事件上报 [#41-业务注册事件上报]
> **注意**
> **此功能仅适用于需要统计业务注册转化数据的场景。如果您的应用不需要追踪用户注册行为，可以跳过此事件接入。**
> **注意**
> 该方法可多次调用，每次调用都会上报一个用户注册事件（计算指标时会去重）
当用户完成应用内业务注册后，您可以调用 `registerEvent` 方法来上报用户注册事件（`$MPRegister`）给引力，引力会使用该事件统计指标：标准\_注册数
#### 调用示例 [#调用示例]
```js
ge.registerEvent();
```
### 4.2 付费事件上报 [#42-付费事件上报]
> **注意**
> **付费事件上报用于收入统计和分析，如您的应用不涉及内购或付费服务，则无需接入此事件。**
> **注意**
> 如果您需要通过后端 API 方式上报付费事件，请参考 [混合上报模式](/docs/client-sdk/hybrid-reporting) 来接入事件上报接口报送付费事件。
当用户发生付费行为时，需要调用 `payEvent` 方法记录用户付费事件，此事件非常重要，会影响买量和 ROI 统计，请务必重点测试！
#### 方法示例 [#方法示例-1]
```js
ge.payEvent(payAmount, payType, orderId, payReason, payMethod);
```
#### 参数说明 [#参数说明-1]
| 参数名称 | 参数含义 | 参数类型 | 是否必传 |
| --------- | ------------------------------------------------------------------------------------------------------------------------ | ------ | ---- |
| 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]
```js
ge.payEvent(300, "CNY", "your_order_id", "月卡", "支付宝");
```
## 5. 接入验证 [#5-接入验证]
> **注意**
> **正式上线之前，请完成本节的校验，否则可能会导致买量上报异常！**
### 5.1 关键事件验证 [#51-关键事件验证]
在引力后台[事件流](https://web.gravity-engine.com/#/manage/metadata/eventFlow)界面开启**加载实时数据**，并在产品中触发以下几个事件。事件验收与排错：[接入验收与排错](/docs/getting-started/integration-checklist)
| 事件名 | 事件英文名 | 触发时机 | 采集方式 | 默认映射到媒体事件 | 备注 |
| ---- | ------------- | ---------- | ------------------------ | --------- | ----------------------- |
| 用户注册 | `$MPRegister` | 用户完成业务注册之后 | 调用 SDK 的**上报业务注册事件**方法采集 | 暂无 | 接入了**业务注册上报事件**的产品均需要校验 |
| 付费 | `$PayEvent` | 用户付费之后 | 调用 SDK 的**上报用户付费事件**方法采集 | 付费 | 接入了**付费事件上报事件**的产品均需要校验 |
| 广告展示 | `$AdShow` | 用户观看广告之后 | 调用 SDK 的**上报广告展示事件**方法采集 | 暂无 | 接入了**广告事件上报事件**的产品均需要校验 |
触发操作后，请在[事件流](https://web.gravity-engine.com/#/manage/metadata/eventFlow)界面中筛选测试用户的 Client ID，观察对应事件是否出现在实时入库页面。若事件数据正常显示，则说明接入成功；如出现于错误数据页面请根据页面错误提示进行排查；如未显示对应数据，请及时联系引力运营支持团队获取协助。
### 5.2 避免重复上报 [#52-避免重复上报]
上线前，请按媒体和事件核对回传来源（引力回传、媒体 SDK 自动采集、客户端手动上报、自有服务端 API），确认同一转化不会通过多条链路重复回传。需要切换到引力回传的事件，应在验证新链路正常后停用原有重复链路；媒体 SDK 的其他功能是否保留，请按对应集成文档确认。
> **注意**
> 至此验证无误之后，您可以正常上线了。
以上是 SDK 的基础接入指引。如需使用 **行为事件上报、用户属性上报、进阶功能、自动采集** 等功能，请参考以下文档：
> **注意**
> 这些功能并非所有业务场景都需要，请按需查阅。
* [行为事件上报](/docs/client-sdk/mini-programs/track-events)
* [用户属性上报](/docs/client-sdk/mini-programs/user-properties)
* [进阶功能](/docs/client-sdk/mini-programs/advanced)
* [自动采集](/docs/client-sdk/mini-programs/advanced/automatic-tracking)
# 抖音小程序快速集成
> 来源：https://help.gravity-engine.com/docs/client-sdk/mini-programs/douyin-quickstart
> 介绍 Gravity Engine 抖音小程序 SDK 的安装、初始化、用户注册与事件上报流程，并提供参数说明和调用示例。
本文档主要讲述 **原生抖音小程序** 接入 [引力引擎](https://gravity-engine.com/) 的技术接入方案，在开始接入前，建议您先阅读 [接入前准备](/docs/getting-started/overview) 以了解接入必备的基础概念。
> **注意**
> 本接入方案仅适用于官方 **原生抖音小程序** 开发的项目。如果您使用的是其他开发框架（如 Taro、uni-app 等），请访问 [引力引擎 SDK 总览页面](/docs/client-sdk/sdk-overview) 选择对应的框架接入文档。
## 1. 获取 AccessToken [#1-获取-accesstoken]
您可以在[设置-应用管理](https://web.gravity-engine.com/#/manage/appmanage)页面点击"查看参数"按钮获取当前应用的 AccessToken，请妥善保存避免泄露。
## 2. 配置并启动 SDK [#2-配置并启动-sdk]
开始接入工作之前，您需要先[下载 SDK](/docs/client-sdk/sdk-overview)。
将 `ge_mp_sdk_version.zip` 中的 `gravityengine.tt.min.js` 导入工程，并初始化 SDK：
> **注意**
> **每次冷启动过程中，`GravityEngine` 的实例化方法 `new GravityEngine()` 与初始化方法 `setupAndStart()` 均只能被调用一次。`clientId` 参数必须在这两个方法的其中一个传入。**
```js
import GravityEngine from "./js/utils/gravityengine.tt.min.js";
const config = {
accessToken: "your_access_token", // 项目通行证，在：网站后台-->设置-->应用列表中找到Access Token列 复制（首次使用可能需要先新增应用）
// clientId如果当前还无法获取，可以不传但是不能传空字符串，等后面获取之后通过setupAndStart设置
clientId: "your_client_id", // 用户唯一标识，如产品为小程序，则必须填用户openid（注意，不是小程序的APPID！！！）
name: "ge", // 全局变量名称, 默认为 gravityengine
//预设公共属性
presetSuperProperties:{
"testSuperKey":"testSuperValue"
}
};
const ge = new GravityEngine(config);
ge.setupAndStart();
```
> **注意**
> **配置项目合法域名：** 您需要将 `https://backend.gravity-engine.com` 和 `https://api.gravity-engine.com` 配置到开发者后台 request 合法域名列表中。
> **注意**
> **如果您是从低版本引力 sdk 升级到高版本的，请一定记得添加 `https://api.gravity-engine.com` 域名到合法域名列表中，否则将导致事件采集失效，影响您的使用！**
## 3. 初始化 [#3-初始化]
在用户可以获取到用户唯一 ID 时调用此方法，推荐首次启动时调用。
> **注意**
> 首次调用后，需要在 `initialize` 的 `then` 中才能继续调用其他事件上报的方法
>
> 初始化方法调用成功之后，后续冷启动可以不再调用，只需要正常启动 SDK 即可（多次调用也不会有问题，引力做了兼容）
### 方法示例 [#方法示例]
```js
ge.initialize({
name: "your_name",
version: 123,
openid: "your_openid",
enable_sync_attribution: false,
adData:{
"testAdKey":"testAdValue"
}
})
.then((res) => {
console.log("initialize success", res);
})
.catch((err) => {
console.log("initialize failed", err);
});
```
### 参数说明 [#参数说明]
| 参数名称 | 参数含义 | 参数类型 | 是否必传 |
| ------------------------- | -------------------------------------------------------------------------------------------- | ------- | ---- |
| name | 用户名或用户唯一 ID（可理解为业务中的昵称），如果不需要昵称，可以填默认值，但不可以传空字符串！ | string | 是 |
| version | 产品发布版本号，便于后续在引力后台过滤 | number | 是 |
| openid | 用户 openid | string | 是 |
| enable\_sync\_attribution | 是否开启同步获取归因信息（参考[同步归因](/docs/attribution/synchronous-attribution)文档）。在媒体点击下发延迟的情况下会影响归因，请谨慎开启 | boolean | 是 |
| channel | 当前用户来源渠道，对应用户细查中的：客户端渠道 | string | 否 |
| adData | 预设归因信息 | object | 否 |
## 4. 事件上报 [#4-事件上报]
### 4.1 业务注册事件上报 [#41-业务注册事件上报]
> **注意**
> **此功能仅适用于需要统计业务注册转化数据的场景。如果您的应用不需要追踪用户注册行为，可以跳过此事件接入。**
> **注意**
> 该方法可多次调用，每次调用都会上报一个用户注册事件（计算指标时会去重）
当用户完成应用内业务注册后，您可以调用 `registerEvent` 方法来上报用户注册事件（`$MPRegister`）给引力，引力会使用该事件统计指标：标准\_注册数
#### 调用示例 [#调用示例]
```js
ge.registerEvent();
```
### 4.2 付费事件上报 [#42-付费事件上报]
> **注意**
> **付费事件上报用于收入统计和分析，如您的应用不涉及内购或付费服务，则无需接入此事件。**
> **注意**
> 如果您需要通过后端 API 方式上报付费事件，请参考 [混合上报模式](/docs/client-sdk/hybrid-reporting) 来接入事件上报接口报送付费事件。
当用户发生付费行为时，需要调用 `payEvent` 方法记录用户付费事件，此事件非常重要，会影响买量和 ROI 统计，请务必重点测试！
#### 方法示例 [#方法示例-1]
```js
ge.payEvent(payAmount, payType, orderId, payReason, payMethod);
```
#### 参数说明 [#参数说明-1]
| 参数名称 | 参数含义 | 参数类型 | 是否必传 |
| --------- | ------------------------------------------------------------------------------------------------------------------------ | ------ | ---- |
| 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]
```js
ge.payEvent(300, "CNY", "your_order_id", "月卡", "支付宝");
```
## 5. 接入验证 [#5-接入验证]
> **注意**
> **正式上线之前，请完成本节的校验，否则可能会导致买量上报异常！**
### 5.1 关键事件验证 [#51-关键事件验证]
在引力后台[事件流](https://web.gravity-engine.com/#/manage/metadata/eventFlow)界面开启**加载实时数据**，并在产品中触发以下几个事件。事件验收与排错：[接入验收与排错](/docs/getting-started/integration-checklist)
| 事件名 | 事件英文名 | 触发时机 | 采集方式 | 默认映射到媒体事件 | 备注 |
| ---- | ------------- | ---------- | ------------------------ | --------- | ----------------------- |
| 用户注册 | `$MPRegister` | 用户完成业务注册之后 | 调用 SDK 的**上报业务注册事件**方法采集 | 暂无 | 接入了**业务注册上报事件**的产品均需要校验 |
| 付费 | `$PayEvent` | 用户付费之后 | 调用 SDK 的**上报用户付费事件**方法采集 | 付费 | 接入了**付费事件上报事件**的产品均需要校验 |
触发操作后，请在[事件流](https://web.gravity-engine.com/#/manage/metadata/eventFlow)界面中筛选测试用户的 Client ID，观察对应事件是否出现在实时入库页面。若事件数据正常显示，则说明接入成功；如出现于错误数据页面请根据页面错误提示进行排查；如未显示对应数据，请及时联系引力运营支持团队获取协助。
### 5.2 避免重复上报 [#52-避免重复上报]
上线前，请按媒体和事件核对回传来源（引力回传、媒体 SDK 自动采集、客户端手动上报、自有服务端 API），确认同一转化不会通过多条链路重复回传。需要切换到引力回传的事件，应在验证新链路正常后停用原有重复链路；媒体 SDK 的其他功能是否保留，请按对应集成文档确认。
> **注意**
> 至此验证无误之后，您可以正常上线了。
以上是 SDK 的基础接入指引。如需使用 **行为事件上报、用户属性上报、进阶功能、自动采集** 等功能，请参考以下文档：
> **注意**
> 这些功能并非所有业务场景都需要，请按需查阅。
* [行为事件上报](/docs/client-sdk/mini-programs/track-events)
* [用户属性上报](/docs/client-sdk/mini-programs/user-properties)
* [进阶功能](/docs/client-sdk/mini-programs/advanced)
* [自动采集](/docs/client-sdk/mini-programs/advanced/automatic-tracking)
# 小程序
> 来源：https://help.gravity-engine.com/docs/client-sdk/mini-programs
> 小程序 SDK索引，汇总微信小程序快速集成、抖音小程序快速集成等主题，便于按功能进入对应的配置、接入或参考说明。
{/* Generated by scripts/generate-docs-routes.mjs. Do not edit. */}
## 目录 [#目录]
* [微信小程序快速集成](/docs/client-sdk/mini-programs/wechat-quickstart)
* [抖音小程序快速集成](/docs/client-sdk/mini-programs/douyin-quickstart)
* [TikTok小程序快速集成](/docs/client-sdk/mini-programs/tiktok-quickstart)
* [支付宝小程序快速集成](/docs/client-sdk/mini-programs/alipay-quickstart)
* [百度小程序快速集成](/docs/client-sdk/mini-programs/baidu-quickstart)
* [钉钉小程序快速集成](/docs/client-sdk/mini-programs/dingtalk-quickstart)
* [快手小程序快速集成](/docs/client-sdk/mini-programs/kuaishou-quickstart)
* [京东小程序快速集成](/docs/client-sdk/mini-programs/jd-quickstart)
* [360小程序快速集成](/docs/client-sdk/mini-programs/360-quickstart)
* [行为事件上报](/docs/client-sdk/mini-programs/track-events)
* [用户属性上报](/docs/client-sdk/mini-programs/user-properties)
* [进阶功能](/docs/client-sdk/mini-programs/advanced) — 子目录
# 京东小程序快速集成
> 来源：https://help.gravity-engine.com/docs/client-sdk/mini-programs/jd-quickstart
> 介绍 Gravity Engine 京东小程序 SDK 的安装、初始化、用户注册与事件上报流程，并提供参数说明和调用示例。
本文档主要讲述 **原生京东小程序** 接入 [引力引擎](https://gravity-engine.com/) 的技术接入方案，在开始接入前，建议您先阅读 [接入前准备](/docs/getting-started/overview) 以了解接入必备的基础概念。
> **注意**
> 本接入方案仅适用于官方 **原生京东小程序** 开发的项目。如果您使用的是其他开发框架（如 Taro、uni-app 等），请访问 [引力引擎 SDK 总览页面](/docs/client-sdk/sdk-overview) 选择对应的框架接入文档。
## 1. 获取 AccessToken [#1-获取-accesstoken]
您可以在[设置-应用管理](https://web.gravity-engine.com/#/manage/appmanage)页面点击"查看参数"按钮获取当前应用的 AccessToken，请妥善保存避免泄露。
## 2. 配置并启动 SDK [#2-配置并启动-sdk]
开始接入工作之前，您需要先[下载 SDK](/docs/client-sdk/sdk-overview)。
将 `ge_mp_sdk_version.zip` 中的 `gravityengine.jd.min.js` 文件导入京东小程序原生项目中：
```js
import GravityEngine from "./utils/gravityengine.jd.min.js";
```
引入 SDK 后，即可进行 SDK 初始化参数配置：
> **注意**
> **每次冷启动过程中，`GravityEngine` 的实例化方法 `new GravityEngine()` 与初始化方法 `setupAndStart()` 均只能被调用一次。`clientId` 参数必须在这两个方法的其中一个传入。**
```js
const config = {
accessToken: "your_access_token", // 项目通行证，在：网站后台-->设置-->应用列表中找到Access Token列 复制（首次使用可能需要先新增应用）
// clientId如果当前还无法获取，可以不传但是不能传空字符串，等后面获取之后通过setupAndStart设置
clientId: "your_client_id", // 用户唯一标识，如产品为小游戏，则必须填用户openid（注意，不是小游戏的APPID！！！）
//预设公共属性
presetSuperProperties:{
"testSuperKey":"testSuperValue"
}
};
const ge = new GravityEngine(config);
ge.setupAndStart();
```
> **注意**
> **配置项目合法域名：** 您需要将 `https://api.gravity-engine.com` 配置到开发者后台 request 合法域名列表中。
## 3. 初始化 [#3-初始化]
在用户可以获取到用户唯一 ID 时调用此方法，推荐首次启动时调用。
> **注意**
> 首次调用后，需要在 `initialize` 的 `then` 中才能继续调用其他事件上报的方法
>
> 初始化方法调用成功之后，后续冷启动可以不再调用，只需要正常启动 SDK 即可（多次调用也不会有问题，引力做了兼容）
### 方法示例 [#方法示例]
```js
ge.initialize({
name: "your_name",
version: 123,
openid: "your_openid",
enable_sync_attribution: false,
adData:{
"testAdKey":"testAdValue"
}
})
.then((res) => {
console.log("initialize success", res);
})
.catch((err) => {
console.log("initialize failed", err);
});
```
### 参数说明 [#参数说明]
| 参数名称 | 参数含义 | 参数类型 | 是否必传 |
| ------------------------- | -------------------------------------------------------------------------------------------- | ------- | ---- |
| name | 用户名或用户唯一 ID（可理解为业务中的昵称），如果不需要昵称，可以填默认值，但不可以传空字符串！ | string | 是 |
| version | 产品发布版本号，便于后续在引力后台过滤 | number | 是 |
| openid | 用户 openid | string | 是 |
| enable\_sync\_attribution | 是否开启同步获取归因信息（参考[同步归因](/docs/attribution/synchronous-attribution)文档）。在媒体点击下发延迟的情况下会影响归因，请谨慎开启 | boolean | 是 |
| channel | 当前用户来源渠道，对应用户细查中的：客户端渠道 | string | 否 |
| adData | 预设归因信息 | object | 否 |
## 4. 事件上报 [#4-事件上报]
### 4.1 业务注册事件上报 [#41-业务注册事件上报]
> **注意**
> **此功能仅适用于需要统计业务注册转化数据的场景。如果您的应用不需要追踪用户注册行为，可以跳过此事件接入。**
> **注意**
> 该方法可多次调用，每次调用都会上报一个用户注册事件（计算指标时会去重）
当用户完成应用内业务注册后，您可以调用 `registerEvent` 方法来上报用户注册事件（`$MPRegister`）给引力，引力会使用该事件统计指标：标准\_注册数
#### 调用示例 [#调用示例]
```js
ge.registerEvent();
```
### 4.2 付费事件上报 [#42-付费事件上报]
> **注意**
> **付费事件上报用于收入统计和分析，如您的应用不涉及内购或付费服务，则无需接入此事件。**
> **注意**
> 如果您需要通过后端 API 方式上报付费事件，请参考 [混合上报模式](/docs/client-sdk/hybrid-reporting) 来接入事件上报接口报送付费事件。
当用户发生付费行为时，需要调用 `payEvent` 方法记录用户付费事件，此事件非常重要，会影响买量和 ROI 统计，请务必重点测试！
#### 方法示例 [#方法示例-1]
```js
ge.payEvent(payAmount, payType, orderId, payReason, payMethod);
```
#### 参数说明 [#参数说明-1]
| 参数名称 | 参数含义 | 参数类型 | 是否必传 |
| --------- | ------------------------------------------------------------------------------------------------------------------------ | ------ | ---- |
| 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]
```js
ge.payEvent(300, "CNY", "your_order_id", "月卡", "支付宝");
```
## 5. 接入验证 [#5-接入验证]
> **注意**
> **正式上线之前，请完成本节的校验，否则可能会导致买量上报异常！**
### 5.1 关键事件验证 [#51-关键事件验证]
在引力后台[事件流](https://web.gravity-engine.com/#/manage/metadata/eventFlow)界面开启**加载实时数据**，并在产品中触发以下几个事件。事件验收与排错：[接入验收与排错](/docs/getting-started/integration-checklist)
| 事件名 | 事件英文名 | 触发时机 | 采集方式 | 默认映射到媒体事件 | 备注 |
| ---- | ------------- | ---------- | ------------------------ | --------- | ----------------------- |
| 用户注册 | `$MPRegister` | 用户完成业务注册之后 | 调用 SDK 的**上报业务注册事件**方法采集 | 暂无 | 接入了**业务注册上报事件**的产品均需要校验 |
| 付费 | `$PayEvent` | 用户付费之后 | 调用 SDK 的**上报用户付费事件**方法采集 | 付费 | 接入了**付费事件上报事件**的产品均需要校验 |
| 广告展示 | `$AdShow` | 用户观看广告之后 | 调用 SDK 的**上报广告展示事件**方法采集 | 暂无 | 接入了**广告事件上报事件**的产品均需要校验 |
触发操作后，请在[事件流](https://web.gravity-engine.com/#/manage/metadata/eventFlow)界面中筛选测试用户的 Client ID，观察对应事件是否出现在实时入库页面。若事件数据正常显示，则说明接入成功；如出现于错误数据页面请根据页面错误提示进行排查；如未显示对应数据，请及时联系引力运营支持团队获取协助。
### 5.2 避免重复上报 [#52-避免重复上报]
上线前，请按媒体和事件核对回传来源（引力回传、媒体 SDK 自动采集、客户端手动上报、自有服务端 API），确认同一转化不会通过多条链路重复回传。需要切换到引力回传的事件，应在验证新链路正常后停用原有重复链路；媒体 SDK 的其他功能是否保留，请按对应集成文档确认。
> **注意**
> 至此验证无误之后，您可以正常上线了。
以上是 SDK 的基础接入指引。如需使用 **行为事件上报、用户属性上报、进阶功能、自动采集** 等功能，请参考以下文档：
> **注意**
> 这些功能并非所有业务场景都需要，请按需查阅。
* [行为事件上报](/docs/client-sdk/mini-programs/track-events)
* [用户属性上报](/docs/client-sdk/mini-programs/user-properties)
* [进阶功能](/docs/client-sdk/mini-programs/advanced)
* [自动采集](/docs/client-sdk/mini-programs/advanced/automatic-tracking)
# 快手小程序快速集成
> 来源：https://help.gravity-engine.com/docs/client-sdk/mini-programs/kuaishou-quickstart
> 介绍 Gravity Engine 快手小程序 SDK 的安装、初始化、用户注册与事件上报流程，并提供参数说明和调用示例。
本文档主要讲述 **原生快手小程序** 接入 [引力引擎](https://gravity-engine.com/) 的技术接入方案，在开始接入前，建议您先阅读 [接入前准备](/docs/getting-started/overview) 以了解接入必备的基础概念。
> **注意**
> 本接入方案仅适用于官方 **原生快手小程序** 开发的项目。如果您使用的是其他开发框架（如 Taro、uni-app 等），请访问 [引力引擎 SDK 总览页面](/docs/client-sdk/sdk-overview) 选择对应的框架接入文档。
## 1. 获取 AccessToken [#1-获取-accesstoken]
您可以在[设置-应用管理](https://web.gravity-engine.com/#/manage/appmanage)页面点击"查看参数"按钮获取当前应用的 AccessToken，请妥善保存避免泄露。
## 2. 配置并启动 SDK [#2-配置并启动-sdk]
开始接入工作之前，您需要先[下载 SDK](/docs/client-sdk/sdk-overview)。
将 `ge_mp_sdk_version.zip` 中的 `gravityengine.mp.ks.min.js` 文件导入快手小程序原生项目中：
```js
import GravityEngine from "./utils/gravityengine.mp.ks.min.js";
```
引入 SDK 后，即可进行 SDK 初始化参数配置：
> **注意**
> **每次冷启动过程中，`GravityEngine` 的实例化方法 `new GravityEngine()` 与初始化方法 `setupAndStart()` 均只能被调用一次。`clientId` 参数必须在这两个方法的其中一个传入。**
```js
const config = {
accessToken: "your_access_token", // 项目通行证，在：网站后台-->设置-->应用列表中找到Access Token列 复制（首次使用可能需要先新增应用）
// clientId如果当前还无法获取，可以不传但是不能传空字符串，等后面获取之后通过setupAndStart设置
clientId: "your_client_id", // 用户唯一标识，如产品为小游戏，则必须填用户openid（注意，不是小游戏的APPID！！！）
//预设公共属性
presetSuperProperties:{
"testSuperKey":"testSuperValue"
}
};
const ge = new GravityEngine(config);
ge.setupAndStart();
```
> **注意**
> **配置项目合法域名：** 您需要将 `https://api.gravity-engine.com` 配置到开发者后台 request 合法域名列表中。
## 3. 初始化 [#3-初始化]
在用户可以获取到用户唯一 ID 时调用此方法，推荐首次启动时调用。
> **注意**
> 首次调用后，需要在 `initialize` 的 `then` 中才能继续调用其他事件上报的方法
>
> 初始化方法调用成功之后，后续冷启动可以不再调用，只需要正常启动 SDK 即可（多次调用也不会有问题，引力做了兼容）
### 方法示例 [#方法示例]
```js
ge.initialize({
name: "your_name",
version: 123,
openid: "your_openid",
enable_sync_attribution: false,
adData:{
"testAdKey":"testAdValue"
}
})
.then((res) => {
console.log("initialize success", res);
})
.catch((err) => {
console.log("initialize failed", err);
});
```
### 参数说明 [#参数说明]
| 参数名称 | 参数含义 | 参数类型 | 是否必传 |
| ------------------------- | -------------------------------------------------------------------------------------------- | ------- | ---- |
| name | 用户名或用户唯一 ID（可理解为业务中的昵称），如果不需要昵称，可以填默认值，但不可以传空字符串！ | string | 是 |
| version | 产品发布版本号，便于后续在引力后台过滤 | number | 是 |
| openid | 用户 openid | string | 是 |
| enable\_sync\_attribution | 是否开启同步获取归因信息（参考[同步归因](/docs/attribution/synchronous-attribution)文档）。在媒体点击下发延迟的情况下会影响归因，请谨慎开启 | boolean | 是 |
| channel | 当前用户来源渠道，对应用户细查中的：客户端渠道 | string | 否 |
| adData | 预设归因信息 | object | 否 |
## 4. 事件上报 [#4-事件上报]
### 4.1 业务注册事件上报 [#41-业务注册事件上报]
> **注意**
> **此功能仅适用于需要统计业务注册转化数据的场景。如果您的应用不需要追踪用户注册行为，可以跳过此事件接入。**
> **注意**
> 该方法可多次调用，每次调用都会上报一个用户注册事件（计算指标时会去重）
当用户完成应用内业务注册后，您可以调用 `registerEvent` 方法来上报用户注册事件（`$MPRegister`）给引力，引力会使用该事件统计指标：标准\_注册数
#### 调用示例 [#调用示例]
```js
ge.registerEvent();
```
### 4.2 付费事件上报 [#42-付费事件上报]
> **注意**
> **付费事件上报用于收入统计和分析，如您的应用不涉及内购或付费服务，则无需接入此事件。**
> **注意**
> 如果您需要通过后端 API 方式上报付费事件，请参考 [混合上报模式](/docs/client-sdk/hybrid-reporting) 来接入事件上报接口报送付费事件。
当用户发生付费行为时，需要调用 `payEvent` 方法记录用户付费事件，此事件非常重要，会影响买量和 ROI 统计，请务必重点测试！
#### 方法示例 [#方法示例-1]
```js
ge.payEvent(payAmount, payType, orderId, payReason, payMethod);
```
#### 参数说明 [#参数说明-1]
| 参数名称 | 参数含义 | 参数类型 | 是否必传 |
| --------- | ------------------------------------------------------------------------------------------------------------------------ | ------ | ---- |
| 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]
```js
ge.payEvent(300, "CNY", "your_order_id", "月卡", "支付宝");
```
## 5. 接入验证 [#5-接入验证]
> **注意**
> **正式上线之前，请完成本节的校验，否则可能会导致买量上报异常！**
### 5.1 关键事件验证 [#51-关键事件验证]
在引力后台[事件流](https://web.gravity-engine.com/#/manage/metadata/eventFlow)界面开启**加载实时数据**，并在产品中触发以下几个事件。事件验收与排错：[接入验收与排错](/docs/getting-started/integration-checklist)
| 事件名 | 事件英文名 | 触发时机 | 采集方式 | 默认映射到媒体事件 | 备注 |
| ---- | ------------- | ---------- | ------------------------ | --------- | ----------------------- |
| 用户注册 | `$MPRegister` | 用户完成业务注册之后 | 调用 SDK 的**上报业务注册事件**方法采集 | 暂无 | 接入了**业务注册上报事件**的产品均需要校验 |
| 付费 | `$PayEvent` | 用户付费之后 | 调用 SDK 的**上报用户付费事件**方法采集 | 付费 | 接入了**付费事件上报事件**的产品均需要校验 |
触发操作后，请在[事件流](https://web.gravity-engine.com/#/manage/metadata/eventFlow)界面中筛选测试用户的 Client ID，观察对应事件是否出现在实时入库页面。若事件数据正常显示，则说明接入成功；如出现于错误数据页面请根据页面错误提示进行排查；如未显示对应数据，请及时联系引力运营支持团队获取协助。
### 5.2 避免重复上报 [#52-避免重复上报]
上线前，请按媒体和事件核对回传来源（引力回传、媒体 SDK 自动采集、客户端手动上报、自有服务端 API），确认同一转化不会通过多条链路重复回传。需要切换到引力回传的事件，应在验证新链路正常后停用原有重复链路；媒体 SDK 的其他功能是否保留，请按对应集成文档确认。
> **注意**
> 至此验证无误之后，您可以正常上线了。
以上是 SDK 的基础接入指引。如需使用 **行为事件上报、用户属性上报、进阶功能、自动采集** 等功能，请参考以下文档：
> **注意**
> 这些功能并非所有业务场景都需要，请按需查阅。
* [行为事件上报](/docs/client-sdk/mini-programs/track-events)
* [用户属性上报](/docs/client-sdk/mini-programs/user-properties)
* [进阶功能](/docs/client-sdk/mini-programs/advanced)
* [自动采集](/docs/client-sdk/mini-programs/advanced/automatic-tracking)
# TikTok小程序快速集成
> 来源：https://help.gravity-engine.com/docs/client-sdk/mini-programs/tiktok-quickstart
> 介绍 Gravity Engine TikTok 小程序 SDK 的安装、初始化、用户注册与事件上报流程，并提供参数说明和调用示例。
本文档主要讲述 **原生 TikTok 小程序** 接入 [引力引擎](https://gravity-engine.com/) 的技术接入方案，在开始接入前，建议您先阅读 [接入前准备](/docs/getting-started/overview) 以了解接入必备的基础概念。
> **注意**
> 本接入方案仅适用于官方 **原生 TikTok 小程序** 开发的项目。如果您使用的是其他开发框架（如 Taro、uni-app 等），请访问 [引力引擎 SDK 总览页面](/docs/client-sdk/sdk-overview) 选择对应的框架接入文档。
>
> 如需接入抖音（国内）小程序，请参考 [抖音小程序快速集成](/docs/client-sdk/mini-programs/douyin-quickstart)。
## 1. 获取 AccessToken [#1-获取-accesstoken]
您可以在[设置-应用管理](https://web.gravity-engine.com/#/manage/appmanage)页面点击"查看参数"按钮获取当前应用的 AccessToken，请妥善保存避免泄露。
## 2. 配置并启动 SDK [#2-配置并启动-sdk]
开始接入工作之前，您需要先[下载 SDK](/docs/client-sdk/sdk-overview)。
将 `ge_mp_sdk_version.zip` 中的 `gravityengine.tt.min.js` 导入工程，并初始化 SDK：
> **注意**
> **每次冷启动过程中，`GravityEngine` 的实例化方法 `new GravityEngine()` 与初始化方法 `setupAndStart()` 均只能被调用一次。`clientId` 参数必须在这两个方法的其中一个传入。**
```js
import GravityEngine from "./js/utils/gravityengine.tt.min.js";
const config = {
accessToken: "your_access_token", // 项目通行证，在：网站后台-->设置-->应用列表中找到Access Token列 复制（首次使用可能需要先新增应用）
// clientId如果当前还无法获取，可以不传但是不能传空字符串，等后面获取之后通过setupAndStart设置
clientId: "your_client_id", // 用户唯一标识，如产品为小程序，则必须填用户openid（注意，不是小程序的APPID！！！）
name: "ge", // 全局变量名称, 默认为 gravityengine
isChina: false, // 是否使用国内域名，TikTok 需设置为 false
//预设公共属性
presetSuperProperties:{
"testSuperKey":"testSuperValue"
}
};
const ge = new GravityEngine(config);
ge.setupAndStart();
```
> **注意**
> **配置项目合法域名：** 您需要将 `https://global-api.gravity-engine.com` 配置到开发者后台 request 合法域名列表中。
## 3. 初始化 [#3-初始化]
在用户可以获取到用户唯一 ID 时调用此方法，推荐首次启动时调用。
> **注意**
> 首次调用后，需要在 `initialize` 的 `then` 中才能继续调用其他事件上报的方法
>
> 初始化方法调用成功之后，后续冷启动可以不再调用，只需要正常启动 SDK 即可（多次调用也不会有问题，引力做了兼容）
### 方法示例 [#方法示例]
```js
ge.initialize({
name: "your_name",
version: 123,
openid: "your_openid",
enable_sync_attribution: false,
adData:{
"testAdKey":"testAdValue"
}
})
.then((res) => {
console.log("initialize success", res);
})
.catch((err) => {
console.log("initialize failed", err);
});
```
### 参数说明 [#参数说明]
| 参数名称 | 参数含义 | 参数类型 | 是否必传 |
| ------------------------- | -------------------------------------------------------------------------------------------- | ------- | ---- |
| name | 用户名或用户唯一 ID（可理解为业务中的昵称），如果不需要昵称，可以填默认值，但不可以传空字符串！ | string | 是 |
| version | 产品发布版本号，便于后续在引力后台过滤 | number | 是 |
| openid | 用户 openid | string | 是 |
| enable\_sync\_attribution | 是否开启同步获取归因信息（参考[同步归因](/docs/attribution/synchronous-attribution)文档）。在媒体点击下发延迟的情况下会影响归因，请谨慎开启 | boolean | 是 |
| channel | 当前用户来源渠道，对应用户细查中的：客户端渠道 | string | 否 |
| adData | 预设归因信息 | object | 否 |
## 4. 事件上报 [#4-事件上报]
### 4.1 业务注册事件上报 [#41-业务注册事件上报]
> **注意**
> **此功能仅适用于需要统计业务注册转化数据的场景。如果您的应用不需要追踪用户注册行为，可以跳过此事件接入。**
> **注意**
> 该方法可多次调用，每次调用都会上报一个用户注册事件（计算指标时会去重）
当用户完成应用内业务注册后，您可以调用 `registerEvent` 方法来上报用户注册事件（`$MPRegister`）给引力，引力会使用该事件统计指标：标准\_注册数
#### 调用示例 [#调用示例]
```js
ge.registerEvent();
```
### 4.2 付费事件上报 [#42-付费事件上报]
> **注意**
> **付费事件上报用于收入统计和分析，如您的应用不涉及内购或付费服务，则无需接入此事件。**
> **注意**
> 如果您需要通过后端 API 方式上报付费事件，请参考 [混合上报模式](/docs/client-sdk/hybrid-reporting) 来接入事件上报接口报送付费事件。
当用户发生付费行为时，需要调用 `payEvent` 方法记录用户付费事件，此事件非常重要，会影响买量和 ROI 统计，请务必重点测试！
#### 方法示例 [#方法示例-1]
```js
ge.payEvent(payAmount, payType, orderId, payReason, payMethod);
```
#### 参数说明 [#参数说明-1]
| 参数名称 | 参数含义 | 参数类型 | 是否必传 |
| --------- | ------------------------------------------------------------------------------------------------------------------------ | ------ | ---- |
| 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]
```js
ge.payEvent(300, "CNY", "your_order_id", "月卡", "支付宝");
```
## 5. 接入验证 [#5-接入验证]
> **注意**
> **正式上线之前，请完成本节的校验，否则可能会导致买量上报异常！**
### 5.1 关键事件验证 [#51-关键事件验证]
在引力后台[事件流](https://web.gravity-engine.com/#/manage/metadata/eventFlow)界面开启**加载实时数据**，并在产品中触发以下几个事件。事件验收与排错：[接入验收与排错](/docs/getting-started/integration-checklist)
| 事件名 | 事件英文名 | 触发时机 | 采集方式 | 默认映射到媒体事件 | 备注 |
| ---- | ------------- | ---------- | ------------------------ | --------- | ----------------------- |
| 用户注册 | `$MPRegister` | 用户完成业务注册之后 | 调用 SDK 的**上报业务注册事件**方法采集 | 暂无 | 接入了**业务注册上报事件**的产品均需要校验 |
| 付费 | `$PayEvent` | 用户付费之后 | 调用 SDK 的**上报用户付费事件**方法采集 | 付费 | 接入了**付费事件上报事件**的产品均需要校验 |
触发操作后，请在[事件流](https://web.gravity-engine.com/#/manage/metadata/eventFlow)界面中筛选测试用户的 Client ID，观察对应事件是否出现在实时入库页面。若事件数据正常显示，则说明接入成功；如出现于错误数据页面请根据页面错误提示进行排查；如未显示对应数据，请及时联系引力运营支持团队获取协助。
### 5.2 避免重复上报 [#52-避免重复上报]
上线前，请按媒体和事件核对回传来源（引力回传、媒体 SDK 自动采集、客户端手动上报、自有服务端 API），确认同一转化不会通过多条链路重复回传。需要切换到引力回传的事件，应在验证新链路正常后停用原有重复链路；媒体 SDK 的其他功能是否保留，请按对应集成文档确认。
> **注意**
> 至此验证无误之后，您可以正常上线了。
以上是 SDK 的基础接入指引。如需使用 **行为事件上报、用户属性上报、进阶功能、自动采集** 等功能，请参考以下文档：
> **注意**
> 这些功能并非所有业务场景都需要，请按需查阅。
* [行为事件上报](/docs/client-sdk/mini-programs/track-events)
* [用户属性上报](/docs/client-sdk/mini-programs/user-properties)
* [进阶功能](/docs/client-sdk/mini-programs/advanced)
* [自动采集](/docs/client-sdk/mini-programs/advanced/automatic-tracking)
# 行为事件上报
> 来源：https://help.gravity-engine.com/docs/client-sdk/mini-programs/track-events
> 说明如何使用 Gravity Engine 小程序 SDK 上报业务事件，并管理事件公共属性。
本文档详细介绍了 SDK 提供的事件上报功能，帮助开发者全面采集用户行为事件数据，为业务分析和运营决策提供数据支持。
通过上报应用内用户行为事件，您可以：
* **完整记录用户行为**：追踪用户在应用内的关键操作路径
* **支持多维度分析**：通过事件属性丰富分析维度
* **构建数据闭环**：为产品优化和精准运营提供数据基础
## 1. 自定义事件上报 [#1-自定义事件上报]
> **注意**
> **如需上报自定义事件，您必须先在[元事件](https://web.gravity-engine.com/#/manage/metadata/metaEvent)中添加，否则会上报失败！**
您可以直接调用 `track` 上传自定义事件，建议您根据准备阶段梳理的文档来设置事件的属性以及发送信息的条件，此处以购买商品为范例：
```js
ge.track(
"$purchase", // 追踪事件的名称
{
Item: "商品A",
ItemNum: 1,
Cost: 100,
Elements: ["apple", "ball", "cat"],
} // 需要上传的事件属性
);
```
* `track` 接口共有两个参数，第一个参数为事件的名称，第二个参数为事件的属性。
* 事件的名称是字符串，只能以字母开头，可包含数字、字母和下划线（\_），长度最大为 50 个字符。
* 事件的属性是 JS 对象，每个元素代表一个属性。
* 元素的 name 对应属性的名称，规定只能以字母开头，包含数字、字母和下划线（\_），长度最大为 50 个字符。
* 元素的 Value 为该属性的值，支持 `String`、`Integer`、`Float`、`Boolean`、`Date`、`DateTime` 和 `Array`；`Array` 中的内容可以为 `String`。
## 2. 公共属性 [#2-公共属性]
> **注意**
> **公共属性需要先在[事件属性](https://web.gravity-engine.com/#/manage/metadata/eventProperty)中添加，否则会上报失败！**
公共事件属性是所有事件（包括自动采集事件）都会包含的属性，用户属性中不会包含。
本节会介绍如何设置公共事件属性和动态公共属性。如果公共属性与事件中设置的自定义属性有相同 key 值，则最终的属性会根据下述优先级取值：
用户自定义事件属性 > 动态公共属性 > 事件公共属性
您可以调用 `setSuperProperties` 来设置公共事件属性，公共事件属性的格式要求与事件属性一致。在设置时只能传入常量，适合设置变化不频繁的属性。
根据属性优先级，自定义属性优先级高于事件公共属性，因此事件公共属性也可以作为某个属性的缺省值，在需要修改的事件中设置同名 Key 覆盖缺省值。
### 设置公共属性 [#设置公共属性]
```js
// 设置公共事件属性
ge.setSuperProperties({ channel: "渠道" });
// 使用 track 上传事件，此时事件中会带有公共事件属性
ge.track(
"Purchase", // 追踪事件的名称
{
Item: "商品A",
ItemNum: 1,
Cost: 100,
} // 需要上传的事件属性
);
/* 等价于在事件中加入这些公共属性
ge.track(
"Purchase", // 追踪事件的名称
{
Item: "商品A",
ItemNum: 1,
Cost: 100,
channel: "渠道" // 相当于在事件中加入这个属性
}
);
*/
```
如果多次调用 `setSuperProperties` 设置公共事件属性，则同名字段后面的调用会覆盖之前的同名字段。
### 删除公共属性 [#删除公共属性]
如果您需要删除某个公共事件属性，可以调用 `unsetSuperProperty()` 清除其中一个公共事件属性：
```js
// 清除属性名为 CHANNEL 的公共属性
ge.unsetSuperProperty("CHANNEL");
```
### 清空公共属性 [#清空公共属性]
如果您想要清空所有公共事件属性，则可以调用 `clearSuperProperties()`：
```js
// 清除公共事件属性
ge.clearSuperProperties();
```
### 获取公共属性 [#获取公共属性]
如果您想要获取所有公共事件属性，可以调用 `getSuperProperties()`：
```js
// 获取静态公共事件属性
ge.getSuperProperties();
```
## 3. 设置事件上报时间 [#3-设置事件上报时间]
事件触发的时间默认取本机时间，但在一些情况下，可能需要手动设置事件的时间，可以使用以下方法进行调用：
> **注意**
> **第三个参数为事件触发时间，必须是 `Date` 类型，将会替换事件触发的时间，如果不传该参数，则事件触发时间默认选取用户的本机时间**
```js
// 第三个参数可以输入 Date 类型的参数，替换事件触发时间
ge.track("event", { parakey: "paravalue" }, new Date());
// 如果没有 properties 需要上传，请传入一个空对象
ge.track("event", {}, new Date());
```
## 4. 记录事件时长 [#4-记录事件时长]
您可以调用 `timeEvent` 来开始计时，配置您想要计时的事件名称，当您上传该事件时，将会自动在您的事件属性中加入 `$event_duration` 这一属性来表示记录的时长，单位为秒。
```js
// 用户进入商品页面，开始计时，记录的事件为 "Enter_Shop"
ge.timeEvent("Enter_Shop");
// ...
// 上传事件，计时结束，"Enter_Shop" 这一事件中将会带有表示事件时长的属性 $event_duration
ge.track("Enter_Shop", { product_id: "A1354" });
```
## 5. 立即上报事件 [#5-立即上报事件]
如果需要立即上报缓存的事件，可以调用 `flush` 来上报所有缓存的事件。
```js
ge.flush()
```
# 用户属性上报
> 来源：https://help.gravity-engine.com/docs/client-sdk/mini-programs/user-properties
> 说明如何使用 Gravity Engine 小程序 SDK 设置、追加、累加和删除用户属性，并提供参数要求与调用示例。
本文档详细介绍了 SDK 提供的用户属性上报功能，帮助开发者高效地收集、更新和维护用户画像数据。
通过本功能，您可以：
* **全面记录用户特征**：存储用户基础信息（如昵称、性别）、行为偏好等关键数据
* **灵活更新用户画像**：支持覆盖、追加、数值计算等多种更新方式
* **构建精准用户模型**：通过属性组合分析，实现用户分群和个性化服务
> **注意**
> **如需上报自定义的用户属性，您必须先在[元数据](https://web.gravity-engine.com/#/manage/metadata/userProperty)中添加对应的用户属性，否则会上报失败！**
## 1. 设置用户属性 [#1-设置用户属性]
对于一般的用户属性，您可以调用 `userSet` 来进行设置，使用该接口上传的属性将会覆盖原有的属性值。
```js
// 设置用户属性，会员等级
ge.userSet({ vip_level: "钻石会员" });
```
> **注意**
> 属性格式要求与事件属性保持一致。
## 2. 初始化用户属性 [#2-初始化用户属性]
如果您要上传的用户属性只要设置一次，则可以调用 `userSetOnce` 来进行设置，当该属性之前已经有值的时候，将会忽略这条信息。
```js
// 以设置用户名为例，如果用户名已设置，则忽略本次设置
ge.userSetOnce({ user_name: "TestUser" });
```
> **注意**
> 属性格式要求与事件属性保持一致。
## 3. 累加用户属性 [#3-累加用户属性]
对于数值型的用户属性，可以调用 `userAdd` 进行累加操作。
```js
// 以付费为例，用户每次付费时调用此接口，则 total_revenue 字段每次会做累加付费金额的处理
ge.userAdd({ total_revenue: 50 });
```
> **注意**
> 设置的属性 key 为字符串，Value 只允许为数值。
## 4. 重置用户属性 [#4-重置用户属性]
当您要清空用户的某个用户属性值时，可以调用 `userUnset` 来对指定属性进行清空操作。
```js
// 清空指定 key 的用户属性值，即设置为 null
ge.userUnset("userPropertyKey");
```
> **注意**
> `userUnset` 的传入值为被清空属性的 Key 值。
## 5. 清空用户属性 [#5-清空用户属性]
如果您要删除某个用户，可以调用 `userDel` 将这名用户删除，您将无法再查询该名用户的用户属性，但该用户产生的事件仍然可以被查询到：
```js
ge.userDel();
```
## 6. 用户属性追加（Array） [#6-用户属性追加array]
您可以调用 `userAppend` 对 Array（List）类型的用户数据追加元素。
```js
ge.userAppend({ Movies: ["Interstellar", "The Negro Motorist Green Book"] });
```
## 7. 用户属性去重追加（Array） [#7-用户属性去重追加array]
`userUniqAppend` 用来对 Array（List）类型的用户数据**去重**追加元素。
```js
ge.userUniqAppend({
Movies: ["Interstellar", "The Negro Motorist Green Book"],
});
```
## 8. 用户属性取最大值 [#8-用户属性取最大值]
对于数值型的用户属性，可以使用 `userNumberMax` 用来比较数值大小，保存较大的。
```js
ge.userNumberMax({
ad_ecpm_max: 300,
});
```
## 9. 用户属性取最小值 [#9-用户属性取最小值]
对于数值型的用户属性，可以使用 `userNumberMin` 用来比较数值大小，保存较小的。
```js
ge.userNumberMin({
ad_ecpm_min: 17,
});
```
# 微信小程序快速集成
> 来源：https://help.gravity-engine.com/docs/client-sdk/mini-programs/wechat-quickstart
> 介绍 Gravity Engine 微信小程序 SDK 的安装、初始化、用户注册与事件上报流程，并提供参数说明和调用示例。
本文档主要讲述 **原生微信小程序** 接入 [引力引擎](https://gravity-engine.com/) 的技术接入方案，在开始接入前，建议您先阅读 [接入前准备](/docs/getting-started/overview) 以了解接入必备的基础概念。
> **注意**
> 本接入方案仅适用于官方 **原生微信小程序** 开发的项目。如果您使用的是其他开发框架（如 Taro、uni-app 等），请访问 [引力引擎 SDK 总览页面](/docs/client-sdk/sdk-overview) 选择对应的框架接入文档。
## 1. 获取 AccessToken [#1-获取-accesstoken]
您可以在[设置-应用管理](https://web.gravity-engine.com/#/manage/appmanage)页面点击"查看参数"按钮获取当前应用的 AccessToken，请妥善保存避免泄露。
## 2. 配置并启动 SDK [#2-配置并启动-sdk]
开始接入工作之前，您需要先[下载 SDK](/docs/client-sdk/sdk-overview)。
将 `ge_mp_sdk_version.zip` 中的 `gravityengine.wx.min.js` 导入工程，并初始化 SDK：
> **注意**
> **每次冷启动过程中，`GravityEngine` 的实例化方法 `new GravityEngine()` 与初始化方法 `setupAndStart()` 均只能被调用一次。`clientId` 参数必须在这两个方法的其中一个传入。**
```js
import GravityEngine from "./utils/gravityengine.wx.min.js";
const config = {
accessToken: "your_access_token", // 项目通行证，在：网站后台-->设置-->应用列表中找到Access Token列 复制（首次使用可能需要先新增应用）
// clientId如果当前还无法获取，可以不传但是不能传空字符串，等后面获取之后通过setupAndStart设置
clientId: "your_client_id", // 用户唯一标识，如产品为小游戏，则必须填用户openid（注意，不是小游戏的APPID！！！）
name: "ge", // 全局变量名称, 默认为 gravityengine
//预设公共属性
presetSuperProperties:{
"testSuperKey":"testSuperValue"
}
};
const ge = new GravityEngine(config);
ge.setupAndStart();
```
> **注意**
> **配置项目合法域名：** 您需要将 `https://backend.gravity-engine.com` 和 `https://api.gravity-engine.com` 配置到开发者后台 request 合法域名列表中。
> **注意**
> **如果您是从低版本引力 SDK 升级到高版本的，请一定记得添加 `https://api.gravity-engine.com` 域名到合法域名列表中，否则将导致事件采集失效，影响您的使用！**
## 3. 初始化 [#3-初始化]
在用户可以获取到用户唯一 ID 时调用此方法，推荐首次启动时调用。
> **注意**
> 首次调用后，需要在 `initialize` 的 `then` 中才能继续调用其他事件上报的方法
>
> 初始化方法调用成功之后，后续冷启动可以不再调用，只需要正常启动 SDK 即可（多次调用也不会有问题，引力做了兼容）
### 方法示例 [#方法示例]
```js
ge.initialize({
name: "your_name",
version: 123,
openid: "your_openid",
enable_sync_attribution: false,
adData:{
"testAdKey":"testAdValue"
}
})
.then((res) => {
console.log("initialize success", res);
})
.catch((err) => {
console.log("initialize failed", err);
});
```
### 参数说明 [#参数说明]
| 参数名称 | 参数含义 | 参数类型 | 是否必传 |
| ------------------------- | -------------------------------------------------------------------------------------------- | ------- | ---- |
| name | 用户名或用户唯一 ID（可理解为业务中的昵称），如果不需要昵称，可以填默认值，但不可以传空字符串！ | string | 是 |
| version | 产品发布版本号，便于后续在引力后台过滤 | number | 是 |
| openid | 用户 openid | string | 是 |
| enable\_sync\_attribution | 是否开启同步获取归因信息（参考[同步归因](/docs/attribution/synchronous-attribution)文档）。在媒体点击下发延迟的情况下会影响归因，请谨慎开启 | boolean | 是 |
| channel | 当前用户来源渠道，对应用户细查中的：客户端渠道 | string | 否 |
| adData | 预设归因信息 | object | 否 |
## 4. 事件上报 [#4-事件上报]
### 4.1 业务注册事件上报 [#41-业务注册事件上报]
> **注意**
> **此功能仅适用于需要统计业务注册转化数据的场景。如果您的应用不需要追踪用户注册行为，可以跳过此事件接入。**
> **注意**
> 该方法可多次调用，每次调用都会上报一个用户注册事件（计算指标时会去重）
当用户完成应用内业务注册后，您可以调用 `registerEvent` 方法来上报用户注册事件（`$MPRegister`）给引力，引力会使用该事件统计指标：标准\_注册数
#### 调用示例 [#调用示例]
```js
ge.registerEvent();
```
### 4.2 付费事件上报 [#42-付费事件上报]
> **注意**
> **付费事件上报用于收入统计和分析，如您的应用不涉及内购或付费服务，则无需接入此事件。**
> **注意**
> 如果您需要通过后端 API 方式上报付费事件，请参考 [混合上报模式](/docs/client-sdk/hybrid-reporting) 来接入事件上报接口报送付费事件。
当用户发生付费行为时，需要调用 `payEvent` 方法记录用户付费事件，此事件非常重要，会影响买量和 ROI 统计，请务必重点测试！
#### 方法示例 [#方法示例-1]
```js
ge.payEvent(payAmount, payType, orderId, payReason, payMethod);
```
#### 参数说明 [#参数说明-1]
| 参数名称 | 参数含义 | 参数类型 | 是否必传 |
| --------- | ------------------------------------------------------------------------------------------------------------------------ | ------ | ---- |
| 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]
```js
ge.payEvent(300, "CNY", "your_order_id", "月卡", "支付宝");
```
### 4.3 广告观看事件上报 [#43-广告观看事件上报]
> **注意**
> **广告观看上报适用于广告变现类应用，若您的应用未集成广告模块，则无需接入此事件。**
> **注意**
> **微信小程序产品需要参照 [微信广告变现实时统计](/docs/server-integration/mini-game-tokens/wechat-monetization-stats) 一文，检查是否正确配置微信 `access_token`，配置错误将无法正确获取微信小程序广告变现数据！**
若您的产品内有广告变现，则需要在用户点击广告观看的同时上报用户广告观看事件给引力，具体参考如下：
#### 方法示例 [#方法示例-2]
```js
ge.miniGameAdShowEvent(adType, adUnitId, otherProperties)
```
#### 参数说明 [#参数说明-2]
| 参数名称 | 参数含义 | 参数类型 | 是否必传 |
| --------------- | ---------------------------------------------------------------------------------------------------------------------------- | ------ | ---- |
| 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 | 是 |
#### 调用示例 [#调用示例-2]
```js
ge.miniGameAdShowEvent("reward", "your_ad_unit_id", { custom_param: "12345" });
```
## 5. 接入验证 [#5-接入验证]
> **注意**
> **正式上线之前，请完成本节的校验，否则可能会导致买量上报异常！**
### 5.1 关键事件验证 [#51-关键事件验证]
在引力后台[事件流](https://web.gravity-engine.com/#/manage/metadata/eventFlow)界面开启**加载实时数据**，并在产品中触发以下几个事件。事件验收与排错：[接入验收与排错](/docs/getting-started/integration-checklist)
| 事件名 | 事件英文名 | 触发时机 | 采集方式 | 默认映射到媒体事件 | 备注 |
| ---- | ------------- | ---------- | ------------------------ | --------- | ----------------------- |
| 用户注册 | `$MPRegister` | 用户完成业务注册之后 | 调用 SDK 的**上报业务注册事件**方法采集 | 暂无 | 接入了**业务注册上报事件**的产品均需要校验 |
| 付费 | `$PayEvent` | 用户付费之后 | 调用 SDK 的**上报用户付费事件**方法采集 | 付费 | 接入了**付费事件上报事件**的产品均需要校验 |
触发操作后，请在[事件流](https://web.gravity-engine.com/#/manage/metadata/eventFlow)界面中筛选测试用户的 Client ID，观察对应事件是否出现在实时入库页面。若事件数据正常显示，则说明接入成功；如出现于错误数据页面请根据页面错误提示进行排查；如未显示对应数据，请及时联系引力运营支持团队获取协助。
### 5.2 避免重复上报 [#52-避免重复上报]
上线前，请按媒体和事件核对回传来源（引力回传、媒体 SDK 自动采集、客户端手动上报、自有服务端 API），确认同一转化不会通过多条链路重复回传。需要切换到引力回传的事件，应在验证新链路正常后停用原有重复链路；媒体 SDK 的其他功能是否保留，请按对应集成文档确认。
> **注意**
> 至此验证无误之后，您可以正常上线了。
以上是 SDK 的基础接入指引。如需使用 **行为事件上报、用户属性上报、进阶功能、自动采集** 等功能，请参考以下文档：
> **注意**
> 这些功能并非所有业务场景都需要，请按需查阅。
* [行为事件上报](/docs/client-sdk/mini-programs/track-events)
* [用户属性上报](/docs/client-sdk/mini-programs/user-properties)
* [进阶功能](/docs/client-sdk/mini-programs/advanced)
* [自动采集](/docs/client-sdk/mini-programs/advanced/automatic-tracking)
# 支付宝小游戏快速集成
> 来源：https://help.gravity-engine.com/docs/client-sdk/mini-games/alipay-quickstart
> 介绍 Gravity Engine 支付宝小游戏 SDK 的安装、初始化、用户注册与事件上报流程，并提供参数说明和调用示例。
本文档主要讲述 **原生支付宝小游戏** 接入 [引力引擎](https://gravity-engine.com/) 的技术接入方案，在开始接入前，建议您先阅读 [接入前准备](/docs/getting-started/overview)以了解接入必备的基础概念。
> **注意**
> 本接入方案仅适用于官方**原生支付宝小游戏**开发的项目。如果您使用的是其他游戏引擎（如 Unity、CocosCreator、Laya、Egret 等），请访问[引力引擎 SDK 总览页面](/docs/client-sdk/sdk-overview)选择对应的框架接入文档。
## 1. 获取 AccessToken [#1-获取-accesstoken]
您可以在[设置-应用管理](https://web.gravity-engine.com/#/manage/appmanage)页面点击"查看参数"按钮获取当前应用的 AccessToken，请妥善保存避免泄露。
## 2. 配置并启动 SDK [#2-配置并启动-sdk]
开始接入工作之前，您需要先[下载 SDK](/docs/client-sdk/sdk-overview)。
将 `ge_mg_sdk_version.zip` 中的 `gravityengine.mg.my.min.js` 文件导入支付宝小游戏原生项目中。
```js
import GravityEngine from "./utils/gravityengine.mg.my.min.js";
```
引入 SDK 后，即可进行 SDK 初始化参数配置：
> **注意**
> **每次冷启动过程中，`GravityEngine` 的实例化方法 `new GravityEngine()` 与初始化方法 `setupAndStart()` 均只能被调用一次。`clientId` 参数必须在这两个方法的其中一个传入。**
```js
const config = {
accessToken: "your_access_token", // 项目通行证，在：网站后台-->设置-->应用列表中找到Access Token列 复制（首次使用可能需要先新增应用）
// clientId如果当前还无法获取，可以不传但是不能传空字符串，等后面获取之后通过setupAndStart设置
clientId: "your_client_id", // 用户唯一标识，如产品为小游戏，则必须填用户openid（注意，不是小游戏的APPID！！！）
//预设公共属性
presetSuperProperties:{
"testSuperKey":"testSuperValue"
}
};
const ge = new GravityEngine(config);
ge.setupAndStart();
```
> **注意**
> **配置项目合法域名：** 您需要将 `https://api.gravity-engine.com` 配置到开发者后台 request 合法域名列表中。
## 3. 初始化 [#3-初始化]
在用户可以获取到用户唯一 ID 时调用此方法，推荐首次启动时调用。
> **注意**
> 首次调用后，需要在 `initialize` 的 `then` 中才能继续调用其他事件上报的方法
>
> 初始化方法调用成功之后，后续冷启动可以不再调用，只需要正常启动 SDK 即可（多次调用也不会有问题，引力做了兼容）
### 方法示例 [#方法示例]
```js
ge.initialize({
name: "your_name",
version: 123,
openid: "your_openid",
enable_sync_attribution: false,
adData:{
"testAdKey":"testAdValue"
}
})
.then((res) => {
console.log("initialize success", res);
})
.catch((err) => {
console.log("initialize failed", err);
});
```
### 参数说明 [#参数说明]
| 参数名称 | 参数含义 | 参数类型 | 是否必传 |
| ------------------------- | -------------------------------------------------------------------------------------------- | ------- | ---- |
| name | 用户名或用户唯一 ID（可理解为业务中的昵称），如果不需要昵称，可以填默认值，但不可以传空字符串！ | string | 是 |
| version | 产品发布版本号，便于后续在引力后台过滤 | number | 是 |
| openid | 用户 openid | string | 是 |
| enable\_sync\_attribution | 是否开启同步获取归因信息（参考[同步归因](/docs/attribution/synchronous-attribution)文档）。在媒体点击下发延迟的情况下会影响归因，请谨慎开启 | boolean | 是 |
| channel | 当前用户来源渠道，对应用户细查中的：客户端渠道 | string | 否 |
| adData | 预设归因信息 | object | 否 |
## 4. 事件上报 [#4-事件上报]
### 4.1 业务注册事件上报 [#41-业务注册事件上报]
> **注意**
> **此功能仅适用于需要统计业务注册转化数据的场景。如果您的应用不需要追踪用户注册行为，可以跳过此事件接入。**
> **注意**
> 该方法可多次调用，每次调用都会上报一个用户注册事件（计算指标时会去重）
当用户完成应用内业务注册后，您可以调用 `registerEvent` 方法来上报用户注册事件(`$MPRegister`)给引力，引力会使用该事件统计指标：标准\_注册数
#### 调用示例 [#调用示例]
```js
ge.registerEvent();
```
### 4.2 付费事件上报 [#42-付费事件上报]
> **注意**
> **付费事件上报用于收入统计和分析，如您的应用不涉及内购或付费服务，则无需接入此事件。**
> **注意**
> 如果您需要通过后端 API 方式上报付费事件，请参考 [混合上报模式](/docs/client-sdk/hybrid-reporting) 来接入事件上报接口报送付费事件。
当用户发生付费行为时，需要调用 `payEvent` 方法记录用户付费事件，此事件非常重要，会影响买量和 ROI 统计，请务必重点测试！
#### 方法示例 [#方法示例-1]
```js
ge.payEvent(payAmount, payType, orderId, payReason, payMethod);
```
#### 参数说明 [#参数说明-1]
| 参数名称 | 参数含义 | 参数类型 | 是否必传 |
| --------- | ------------------------------------------------------------------------------------------------------------------------ | ------ | ---- |
| 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]
```js
ge.payEvent(300, "CNY", "your_order_id", "月卡", "支付宝");
```
### 4.3 广告观看事件上报 [#43-广告观看事件上报]
> **注意**
> **广告观看上报适用于广告变现类应用，若您的应用未集成广告模块，则无需接入此事件。**
若您的产品内有广告变现，则需要在用户点击广告观看的同时上报用户广告观看事件给引力。
#### 方法示例 [#方法示例-2]
```js
ge.miniGameAdShowEvent(adType, adUnitId, otherProperties)
```
#### 参数说明 [#参数说明-2]
| 参数名称 | 参数含义 | 参数类型 | 是否必传 |
| --------------- | ----------------------------------------------------------------------------------------------------------------------------- | ------ | ---- |
| 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 | 是 |
#### 调用示例 [#调用示例-2]
```js
ge.miniGameAdShowEvent("reward", "your_ad_unit_id", { custom_param: "12345" });
```
## 5. 接入验证 [#5-接入验证]
> **注意**
> **正式上线之前，请完成本节的校验，否则可能会导致买量上报异常！**
### 5.1 关键事件验证 [#51-关键事件验证]
在引力后台[事件流](https://web.gravity-engine.com/#/manage/metadata/eventFlow)界面开启**加载实时数据**，并在产品中触发以下几个事件。事件验收与排错：[接入验收与排错](/docs/getting-started/integration-checklist)
| 事件名 | 事件英文名 | 触发时机 | 采集方式 | 默认映射到媒体事件 | 备注 |
| ---- | ------------- | ---------- | ------------------------ | --------- | ----------------------- |
| 用户注册 | `$MPRegister` | 用户完成业务注册之后 | 调用 SDK 的**上报业务注册事件**方法采集 | 暂无 | 接入了**业务注册上报事件**的产品均需要校验 |
| 付费 | `$PayEvent` | 用户付费之后 | 调用 SDK 的**上报用户付费事件**方法采集 | 付费 | 接入了**付费事件上报事件**的产品均需要校验 |
| 广告展示 | `$AdShow` | 用户观看广告之后 | 调用 SDK 的**上报广告展示事件**方法采集 | 暂无 | 接入了**广告事件上报事件**的产品均需要校验 |
触发操作后，请在[事件流](https://web.gravity-engine.com/#/manage/metadata/eventFlow)界面中筛选测试用户的 Client ID，观察对应事件是否出现在实时入库页面。若事件数据正常显示，则说明接入成功；如出现于错误数据页面请根据页面错误提示进行排查；如未显示对应数据，请及时联系引力运营支持团队获取协助。
### 5.2 避免重复上报 [#52-避免重复上报]
上线前，请按媒体和事件核对回传来源（引力回传、媒体 SDK 自动采集、客户端手动上报、自有服务端 API），确认同一转化不会通过多条链路重复回传。需要切换到引力回传的事件，应在验证新链路正常后停用原有重复链路；媒体 SDK 的其他功能是否保留，请按对应集成文档确认。
> **注意**
> 至此验证无误之后，您可以正常上线了。
以上是 SDK 的基础接入指引。如需使用 **行为事件上报、用户属性上报、进阶功能、自动采集** 等功能，请参考以下文档：
> **注意**
> 这些功能并非所有业务场景都需要，请按需查阅。
* [行为事件上报](/docs/client-sdk/mini-games/track-events)
* [用户属性上报](/docs/client-sdk/mini-games/user-properties)
* [进阶功能](/docs/client-sdk/mini-games/advanced)
* [自动采集](/docs/client-sdk/mini-games/advanced/automatic-tracking)
# 百度小游戏快速集成
> 来源：https://help.gravity-engine.com/docs/client-sdk/mini-games/baidu-quickstart
> 介绍 Gravity Engine 百度小游戏 SDK 的安装、初始化、用户注册与事件上报流程，并提供参数说明和调用示例。
本文档主要讲述 **原生百度小游戏** 接入 [引力引擎](https://gravity-engine.com/) 的技术接入方案，在开始接入前，建议您先阅读 [接入前准备](/docs/getting-started/overview)以了解接入必备的基础概念。
> **注意**
> 本接入方案仅适用于官方**原生百度小游戏**开发的项目。如果您使用的是其他游戏引擎（如 Unity、CocosCreator、Laya、Egret 等），请访问[引力引擎 SDK 总览页面](/docs/client-sdk/sdk-overview)选择对应的框架接入文档。
## 1. 获取 AccessToken [#1-获取-accesstoken]
您可以在[设置-应用管理](https://web.gravity-engine.com/#/manage/appmanage)页面点击"查看参数"按钮获取当前应用的 AccessToken，请妥善保存避免泄露。
## 2. 配置并启动 SDK [#2-配置并启动-sdk]
开始接入工作之前，您需要先[下载 SDK](/docs/client-sdk/sdk-overview)。
将 `ge_mg_sdk_version.zip` 中的 `gravityengine.mg.swan.min.js` 文件导入百度小游戏原生项目中。
```js
import GravityEngine from "./utils/gravityengine.mg.swan.min";
```
引入 SDK 后，即可进行 SDK 初始化参数配置：
> **注意**
> **每次冷启动过程中，`GravityEngine` 的实例化方法 `new GravityEngine()` 与初始化方法 `setupAndStart()` 均只能被调用一次。`clientId` 参数必须在这两个方法的其中一个传入。**
```js
const config = {
accessToken: "your_access_token", // 项目通行证，在：网站后台-->设置-->应用列表中找到Access Token列 复制（首次使用可能需要先新增应用）
// clientId如果当前还无法获取，可以不传但是不能传空字符串，等后面获取之后通过setupAndStart设置
clientId: "your_client_id", // 用户唯一标识，如产品为小游戏，则必须填用户openid（注意，不是小游戏的APPID！！！）
//预设公共属性
presetSuperProperties:{
"testSuperKey":"testSuperValue"
}
};
const ge = new GravityEngine(config);
ge.setupAndStart();
```
> **注意**
> **配置项目合法域名：** 您需要将 `https://api.gravity-engine.com` 配置到开发者后台 request 合法域名列表中。
## 3. 初始化 [#3-初始化]
在用户可以获取到用户唯一 ID 时调用此方法，推荐首次启动时调用。
> **注意**
> 首次调用后，需要在 `initialize` 的 `then` 中才能继续调用其他事件上报的方法
>
> 初始化方法调用成功之后，后续冷启动可以不再调用，只需要正常启动 SDK 即可（多次调用也不会有问题，引力做了兼容）
### 方法示例 [#方法示例]
```js
ge.initialize({
name: "your_name",
version: 123,
openid: "your_openid",
enable_sync_attribution: false,
adData:{
"testAdKey":"testAdValue"
}
})
.then((res) => {
console.log("initialize success", res);
})
.catch((err) => {
console.log("initialize failed", err);
});
```
### 参数说明 [#参数说明]
| 参数名称 | 参数含义 | 参数类型 | 是否必传 |
| ------------------------- | -------------------------------------------------------------------------------------------- | ------- | ---- |
| name | 用户名或用户唯一 ID（可理解为业务中的昵称），如果不需要昵称，可以填默认值，但不可以传空字符串！ | string | 是 |
| version | 产品发布版本号，便于后续在引力后台过滤 | number | 是 |
| openid | 用户 openid | string | 是 |
| enable\_sync\_attribution | 是否开启同步获取归因信息（参考[同步归因](/docs/attribution/synchronous-attribution)文档）。在媒体点击下发延迟的情况下会影响归因，请谨慎开启 | boolean | 是 |
| channel | 当前用户来源渠道，对应用户细查中的：客户端渠道 | string | 否 |
| adData | 预设归因信息 | object | 否 |
## 4. 事件上报 [#4-事件上报]
### 4.1 业务注册事件上报 [#41-业务注册事件上报]
> **注意**
> **此功能仅适用于需要统计业务注册转化数据的场景。如果您的应用不需要追踪用户注册行为，可以跳过此事件接入。**
> **注意**
> 该方法可多次调用，每次调用都会上报一个用户注册事件（计算指标时会去重）
当用户完成应用内业务注册后，您可以调用 `registerEvent` 方法来上报用户注册事件(`$MPRegister`)给引力，引力会使用该事件统计指标：标准\_注册数
#### 调用示例 [#调用示例]
```js
ge.registerEvent();
```
### 4.2 付费事件上报 [#42-付费事件上报]
> **注意**
> **付费事件上报用于收入统计和分析，如您的应用不涉及内购或付费服务，则无需接入此事件。**
> **注意**
> 如果您需要通过后端 API 方式上报付费事件，请参考 [混合上报模式](/docs/client-sdk/hybrid-reporting) 来接入事件上报接口报送付费事件。
当用户发生付费行为时，需要调用 `payEvent` 方法记录用户付费事件，此事件非常重要，会影响买量和 ROI 统计，请务必重点测试！
#### 方法示例 [#方法示例-1]
```js
ge.payEvent(payAmount, payType, orderId, payReason, payMethod);
```
#### 参数说明 [#参数说明-1]
| 参数名称 | 参数含义 | 参数类型 | 是否必传 |
| --------- | ------------------------------------------------------------------------------------------------------------------------ | ------ | ---- |
| 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]
```js
ge.payEvent(300, "CNY", "your_order_id", "月卡", "支付宝");
```
## 5. 接入验证 [#5-接入验证]
> **注意**
> **正式上线之前，请完成本节的校验，否则可能会导致买量上报异常！**
### 5.1 关键事件验证 [#51-关键事件验证]
在引力后台[事件流](https://web.gravity-engine.com/#/manage/metadata/eventFlow)界面开启**加载实时数据**，并在产品中触发以下几个事件。事件验收与排错：[接入验收与排错](/docs/getting-started/integration-checklist)
| 事件名 | 事件英文名 | 触发时机 | 采集方式 | 默认映射到媒体事件 | 备注 |
| ---- | ------------- | ---------- | ------------------------ | --------- | ----------------------- |
| 用户注册 | `$MPRegister` | 用户完成业务注册之后 | 调用 SDK 的**上报业务注册事件**方法采集 | 暂无 | 接入了**业务注册上报事件**的产品均需要校验 |
| 付费 | `$PayEvent` | 用户付费之后 | 调用 SDK 的**上报用户付费事件**方法采集 | 付费 | 接入了**付费事件上报事件**的产品均需要校验 |
| 广告展示 | `$AdShow` | 用户观看广告之后 | 调用 SDK 的**上报广告展示事件**方法采集 | 暂无 | 接入了**广告事件上报事件**的产品均需要校验 |
触发操作后，请在[事件流](https://web.gravity-engine.com/#/manage/metadata/eventFlow)界面中筛选测试用户的 Client ID，观察对应事件是否出现在实时入库页面。若事件数据正常显示，则说明接入成功；如出现于错误数据页面请根据页面错误提示进行排查；如未显示对应数据，请及时联系引力运营支持团队获取协助。
### 5.2 避免重复上报 [#52-避免重复上报]
上线前，请按媒体和事件核对回传来源（引力回传、媒体 SDK 自动采集、客户端手动上报、自有服务端 API），确认同一转化不会通过多条链路重复回传。需要切换到引力回传的事件，应在验证新链路正常后停用原有重复链路；媒体 SDK 的其他功能是否保留，请按对应集成文档确认。
> **注意**
> 至此验证无误之后，您可以正常上线了。
以上是 SDK 的基础接入指引。如需使用 **行为事件上报、用户属性上报、进阶功能、自动采集** 等功能，请参考以下文档：
> **注意**
> 这些功能并非所有业务场景都需要，请按需查阅。
* [行为事件上报](/docs/client-sdk/mini-games/track-events)
* [用户属性上报](/docs/client-sdk/mini-games/user-properties)
* [进阶功能](/docs/client-sdk/mini-games/advanced)
* [自动采集](/docs/client-sdk/mini-games/advanced/automatic-tracking)
# B站小游戏快速集成
> 来源：https://help.gravity-engine.com/docs/client-sdk/mini-games/bilibili-quickstart
> 介绍 Gravity Engine B站小游戏 SDK 的安装、初始化、用户注册与事件上报流程，并提供参数说明和调用示例。
本文档主要讲述 **原生B站小游戏** 接入 [引力引擎](https://gravity-engine.com/) 的技术接入方案，在开始接入前，建议您先阅读 [接入前准备](/docs/getting-started/overview)以了解接入必备的基础概念。
> **注意**
> 本接入方案仅适用于官方**原生B站小游戏**开发的项目。如果您使用的是其他游戏引擎，请访问[引力引擎 SDK 总览页面](/docs/client-sdk/sdk-overview)选择对应的框架接入文档。
## 1. 获取 AccessToken [#1-获取-accesstoken]
您可以在[设置-应用管理](https://web.gravity-engine.com/#/manage/appmanage)页面点击"查看参数"按钮获取当前应用的 AccessToken，请妥善保存避免泄露。
## 2. 配置并启动 SDK [#2-配置并启动-sdk]
开始接入工作之前，您需要先[下载 SDK](/docs/client-sdk/sdk-overview)。
将 `ge_mg_sdk_version.zip` 中的 `gravityengine.mg.bl.min.js` 导入工程，并初始化 SDK：
> **注意**
> **每次冷启动过程中，`GravityEngine` 的实例化方法 `new GravityEngine()` 与初始化方法 `setupAndStart()` 均只能被调用一次。`clientId` 参数必须在这两个方法的其中一个传入。**
```js
import GravityEngine from "./js/utils/gravityengine.mg.bl.min";
const config = {
accessToken: "your_access_token", // 项目通行证，在：网站后台-->设置-->应用列表中找到Access Token列 复制（首次使用可能需要先新增应用）
// clientId如果当前还无法获取，可以不传但是不能传空字符串，等后面获取之后通过setupAndStart设置
clientId: "your_client_id", // 用户唯一标识，如产品为小游戏，则必须填用户openid（注意，不是小游戏的APPID！！！）
name: "ge", // 全局变量名称, 默认为 gravityengine
//预设公共属性
presetSuperProperties:{
"testSuperKey":"testSuperValue"
}
};
const ge = new GravityEngine(config);
ge.setupAndStart();
```
> **注意**
> **无法自行获取 `openid`？** 没有自建后端时，可使用引力 SDK 内置的快捷获取方法，详见[快捷获取 openid](/docs/client-sdk/mini-games/advanced/quick-get-openid)。
> **注意**
> **配置项目合法域名：** 您需要将 `https://api.gravity-engine.com` 配置到开发者后台 request 合法域名列表中。
## 3. 初始化 [#3-初始化]
在用户可以获取到用户唯一 ID 时调用此方法，推荐首次启动时调用。
> **注意**
> 首次调用后，需要在 `initialize` 的 `then` 中才能继续调用其他事件上报的方法
>
> 初始化方法调用成功之后，后续冷启动可以不再调用，只需要正常启动 SDK 即可（多次调用也不会有问题，引力做了兼容）
### 方法示例 [#方法示例]
```js
ge.initialize({
name: "your_name",
version: 123,
openid: "your_openid",
enable_sync_attribution: false,
})
.then((res) => {
console.log("initialize success", res);
})
.catch((err) => {
console.log("initialize failed", err);
});
```
### 参数说明 [#参数说明]
| 参数名称 | 参数含义 | 参数类型 | 是否必传 |
| ------------------------- | -------------------------------------------------------------------------------------------- | ------- | ---- |
| name | 用户名或用户唯一 ID（可理解为业务中的昵称），如果不需要昵称，可以填默认值，但不可以传空字符串！ | string | 是 |
| version | 产品发布版本号，便于后续在引力后台过滤 | number | 是 |
| openid | 用户 openid | string | 是 |
| enable\_sync\_attribution | 是否开启同步获取归因信息（参考[同步归因](/docs/attribution/synchronous-attribution)文档）。在媒体点击下发延迟的情况下会影响归因，请谨慎开启 | boolean | 是 |
| channel | 当前用户来源渠道，对应用户细查中的：客户端渠道 | string | 否 |
| adData | 预设归因信息 | object | 否 |
## 4. 事件上报 [#4-事件上报]
### 4.1 业务注册事件上报 [#41-业务注册事件上报]
> **注意**
> **此功能仅适用于需要统计业务注册转化数据的场景。如果您的应用不需要追踪用户注册行为，可以跳过此事件接入。**
> **注意**
> 该方法可多次调用，每次调用都会上报一个用户注册事件（计算指标时会去重）
当用户完成应用内业务注册后，您可以调用 `registerEvent` 方法来上报用户注册事件(`$MPRegister`)给引力，引力会使用该事件统计指标：标准\_注册数
#### 调用示例 [#调用示例]
```js
ge.registerEvent();
```
### 4.2 付费事件上报 [#42-付费事件上报]
> **注意**
> **付费事件上报用于收入统计和分析，如您的应用不涉及内购或付费服务，则无需接入此事件。**
> **注意**
> 如果您需要通过后端 API 方式上报付费事件，请参考 [混合上报模式](/docs/client-sdk/hybrid-reporting) 来接入事件上报接口报送付费事件。
当用户发生付费行为时，需要调用 `payEvent` 方法记录用户付费事件，此事件非常重要，会影响买量和 ROI 统计，请务必重点测试！
#### 方法示例 [#方法示例-1]
```js
ge.payEvent(payAmount, payType, orderId, payReason, payMethod);
```
#### 参数说明 [#参数说明-1]
| 参数名称 | 参数含义 | 参数类型 | 是否必传 |
| --------- | ------------------------------------------------------------------------------------------------------------------------ | ------ | ---- |
| 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]
```js
ge.payEvent(300, "CNY", "your_order_id", "月卡", "支付宝");
```
### 4.3 广告观看事件上报 [#43-广告观看事件上报]
> **注意**
> **广告观看上报适用于广告变现类应用，若您的应用未集成广告模块，则无需接入此事件。**
> **注意**
> **启动 SDK 时传入的 clientId 必须为 B站小游戏的 openid 的原值，否则会拉不到广告数据！**
> **注意**
> **B站小游戏广告模块对接无需客户端 SDK 接入，请直接在引力后台配置，配置好后会由引力后端负责自动拉取。具体配置如下：**
**1.** [设置-应用管理](https://web.gravity-engine.com/#/manage/appmanage)页面中显示的 B站小游戏数据版本必须为 1006 及以上
**2.** 参考[媒体文档](https://ad.bilibili.com/effect-ads/#/school/school-detail?articleId=373\&type=1)配置 Secret Key
**3.** 在[设置-应用管理-配置-B站营销](https://web.gravity-engine.com/#/manage/appmanage)配置项中开启「自动拉取 ecpm」开关，并填入上一步获取的 Secret Key 后保存
## 5. 接入验证 [#5-接入验证]
> **注意**
> **正式上线之前，请完成本节的校验，否则可能会导致买量上报异常！**
### 5.1 关键事件验证 [#51-关键事件验证]
在引力后台[事件流](https://web.gravity-engine.com/#/manage/metadata/eventFlow)界面开启**加载实时数据**，并在产品中触发以下几个事件。事件验收与排错：[接入验收与排错](/docs/getting-started/integration-checklist)
| 事件名 | 事件英文名 | 触发时机 | 采集方式 | 默认映射到媒体事件 | 备注 |
| ---- | ------------- | ---------- | ------------------------ | --------- | ----------------------- |
| 用户注册 | `$MPRegister` | 用户完成业务注册之后 | 调用 SDK 的**上报业务注册事件**方法采集 | 暂无 | 接入了**业务注册上报事件**的产品均需要校验 |
| 付费 | `$PayEvent` | 用户付费之后 | 调用 SDK 的**上报用户付费事件**方法采集 | 付费 | 接入了**付费事件上报事件**的产品均需要校验 |
触发操作后，请在[事件流](https://web.gravity-engine.com/#/manage/metadata/eventFlow)界面中筛选测试用户的 Client ID，观察对应事件是否出现在实时入库页面。若事件数据正常显示，则说明接入成功；如出现于错误数据页面请根据页面错误提示进行排查；如未显示对应数据，请及时联系引力运营支持团队获取协助。
### 5.2 避免重复上报 [#52-避免重复上报]
上线前，请按媒体和事件核对回传来源（引力回传、媒体 SDK 自动采集、客户端手动上报、自有服务端 API），确认同一转化不会通过多条链路重复回传。需要切换到引力回传的事件，应在验证新链路正常后停用原有重复链路；媒体 SDK 的其他功能是否保留，请按对应集成文档确认。
> **注意**
> 至此验证无误之后，您可以正常上线了。
以上是 SDK 的基础接入指引。如需使用 **行为事件上报、用户属性上报、进阶功能、自动采集** 等功能，请参考以下文档：
> **注意**
> 这些功能并非所有业务场景都需要，请按需查阅。
* [行为事件上报](/docs/client-sdk/mini-games/track-events)
* [用户属性上报](/docs/client-sdk/mini-games/user-properties)
* [进阶功能](/docs/client-sdk/mini-games/advanced)
* [自动采集](/docs/client-sdk/mini-games/advanced/automatic-tracking)
# 抖音小游戏快速集成
> 来源：https://help.gravity-engine.com/docs/client-sdk/mini-games/douyin-quickstart
> 介绍 Gravity Engine 抖音小游戏 SDK 的安装、初始化、用户注册与事件上报流程，并提供参数说明和调用示例。
本文档主要讲述 **原生抖音小游戏** 接入 [引力引擎](https://gravity-engine.com/) 的技术接入方案，在开始接入前，建议您先阅读 [接入前准备](/docs/getting-started/overview)以了解接入必备的基础概念。
> **注意**
> 本接入方案仅适用于官方**原生抖音小游戏**开发的项目。如果您使用的是其他游戏引擎（如 Unity、CocosCreator、Laya、Egret 等），请访问[引力引擎 SDK 总览页面](/docs/client-sdk/sdk-overview)选择对应的框架接入文档。
## 1. 获取 AccessToken [#1-获取-accesstoken]
您可以在[设置-应用管理](https://web.gravity-engine.com/#/manage/appmanage)页面点击"查看参数"按钮获取当前应用的 AccessToken，请妥善保存避免泄露。
## 2. 配置并启动 SDK [#2-配置并启动-sdk]
开始接入工作之前，您需要先[下载 SDK](/docs/client-sdk/sdk-overview)。
将 `ge_mg_sdk_version.zip` 中的 `gravityengine.mg.tt.min.js` 导入工程，并初始化 SDK：
> **注意**
> **每次冷启动过程中，`GravityEngine` 的实例化方法 `new GravityEngine()` 与初始化方法 `setupAndStart()` 均只能被调用一次。`clientId` 参数必须在这两个方法的其中一个传入。**
```js
import GravityEngine from "./js/utils/gravityengine.mg.tt.min";
const config = {
accessToken: "your_access_token", // 项目通行证，在：网站后台-->设置-->应用列表中找到Access Token列 复制（首次使用可能需要先新增应用）
// clientId如果当前还无法获取，可以不传但是不能传空字符串，等后面获取之后通过setupAndStart设置
clientId: "your_client_id", // 用户唯一标识，如产品为小游戏，则必须填用户openid（注意，不是小游戏的APPID！！！）
name: "ge", // 全局变量名称, 默认为 gravityengine
//预设公共属性
presetSuperProperties:{
"testSuperKey":"testSuperValue"
}
};
const ge = new GravityEngine(config);
ge.setupAndStart();
```
> **注意**
> **无法自行获取 `openid`？** 没有自建后端时，可使用引力 SDK 内置的快捷获取方法，详见[快捷获取 openid](/docs/client-sdk/mini-games/advanced/quick-get-openid)。
> **注意**
> **配置项目合法域名：** 您需要将 `https://backend.gravity-engine.com` 和 `https://api.gravity-engine.com` 配置到开发者后台 request 合法域名列表中。
> **注意**
> **如果您是从低版本引力 SDK 升级到高版本的，请一定记得添加 `https://api.gravity-engine.com` 域名到合法域名列表中，否则将导致事件采集失效，影响您的使用！**
## 3. 初始化 [#3-初始化]
在用户可以获取到用户唯一 ID 时调用此方法，推荐首次启动时调用。
> **注意**
> 首次调用后，需要在 `initialize` 的 `then` 中才能继续调用其他事件上报的方法
>
> 初始化方法调用成功之后，后续冷启动可以不再调用，只需要正常启动 SDK 即可（多次调用也不会有问题，引力做了兼容）
### 方法示例 [#方法示例]
```js
ge.initialize({
name: "your_name",
version: 123,
openid: "your_openid",
enable_sync_attribution: false,
})
.then((res) => {
console.log("initialize success", res);
})
.catch((err) => {
console.log("initialize failed", err);
});
```
### 参数说明 [#参数说明]
| 参数名称 | 参数含义 | 参数类型 | 是否必传 |
| ------------------------- | -------------------------------------------------------------------------------------------- | ------- | ---- |
| name | 用户名或用户唯一 ID（可理解为业务中的昵称），如果不需要昵称，可以填默认值，但不可以传空字符串！ | string | 是 |
| version | 产品发布版本号，便于后续在引力后台过滤 | number | 是 |
| openid | 用户 openid | string | 是 |
| enable\_sync\_attribution | 是否开启同步获取归因信息（参考[同步归因](/docs/attribution/synchronous-attribution)文档）。在媒体点击下发延迟的情况下会影响归因，请谨慎开启 | boolean | 是 |
| channel | 当前用户来源渠道，对应用户细查中的：客户端渠道 | string | 否 |
| adData | 预设归因信息 | object | 否 |
## 4. 事件上报 [#4-事件上报]
### 4.1 业务注册事件上报 [#41-业务注册事件上报]
> **注意**
> **此功能仅适用于需要统计业务注册转化数据的场景。如果您的应用不需要追踪用户注册行为，可以跳过此事件接入。**
> **注意**
> 该方法可多次调用，每次调用都会上报一个用户注册事件（计算指标时会去重）
当用户完成应用内业务注册后，您可以调用 `registerEvent` 方法来上报用户注册事件(`$MPRegister`)给引力，引力会使用该事件统计指标：标准\_注册数
#### 调用示例 [#调用示例]
```js
ge.registerEvent();
```
### 4.2 付费事件上报 [#42-付费事件上报]
> **注意**
> **付费事件上报用于收入统计和分析，如您的应用不涉及内购或付费服务，则无需接入此事件。**
> **注意**
> 如果您需要通过后端 API 方式上报付费事件，请参考 [混合上报模式](/docs/client-sdk/hybrid-reporting) 来接入事件上报接口报送付费事件。
当用户发生付费行为时，需要调用 `payEvent` 方法记录用户付费事件，此事件非常重要，会影响买量和 ROI 统计，请务必重点测试！
#### 方法示例 [#方法示例-1]
```js
ge.payEvent(payAmount, payType, orderId, payReason, payMethod);
```
#### 参数说明 [#参数说明-1]
| 参数名称 | 参数含义 | 参数类型 | 是否必传 |
| --------- | ------------------------------------------------------------------------------------------------------------------------ | ------ | ---- |
| 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]
```js
ge.payEvent(300, "CNY", "your_order_id", "月卡", "支付宝");
```
### 4.3 广告观看事件上报 [#43-广告观看事件上报]
> **注意**
> **广告观看上报适用于广告变现类应用，若您的应用未集成广告模块，则无需接入此事件。**
> **注意**
> **启动 SDK 时传入的 clientId 必须为抖音小游戏的 openid 的原值，否则会拉不到广告数据！**
> **注意**
> **受限于媒体接口，引力仅能获取信息流买量用户的 eCPM 及广告总数。因此需通过小额买量验证广告变现效果。**
>
> **抖音小游戏广告模块对接无需客户端 SDK 接入，请直接在引力后台配置，配置好后会由引力后端负责自动拉取，具体配置如下：**
**1.** [设置-应用管理-配置-抖音开发者](https://web.gravity-engine.com/#/manage/appmanage)配置项中的 access token 状态需为有效。具体的 token 接入方式可参考：[抖音 access token 获取](/docs/server-integration/mini-game-tokens/douyin-access-token)
**2.** [设置-应用管理-配置-抖音开发者](https://web.gravity-engine.com/#/manage/appmanage)配置项中的自动拉取 ecpm 开关需开启
## 5. 接入验证 [#5-接入验证]
> **注意**
> **正式上线之前，请完成本节的校验，否则可能会导致买量上报异常！**
### 5.1 关键事件验证 [#51-关键事件验证]
在引力后台[事件流](https://web.gravity-engine.com/#/manage/metadata/eventFlow)界面开启**加载实时数据**，并在产品中触发以下几个事件。事件验收与排错：[接入验收与排错](/docs/getting-started/integration-checklist)
| 事件名 | 事件英文名 | 触发时机 | 采集方式 | 默认映射到媒体事件 | 备注 |
| ---- | ------------- | ---------- | ------------------------ | --------- | ----------------------- |
| 用户注册 | `$MPRegister` | 用户完成业务注册之后 | 调用 SDK 的**上报业务注册事件**方法采集 | 暂无 | 接入了**业务注册上报事件**的产品均需要校验 |
| 付费 | `$PayEvent` | 用户付费之后 | 调用 SDK 的**上报用户付费事件**方法采集 | 付费 | 接入了**付费事件上报事件**的产品均需要校验 |
触发操作后，请在[事件流](https://web.gravity-engine.com/#/manage/metadata/eventFlow)界面中筛选测试用户的 Client ID，观察对应事件是否出现在实时入库页面。若事件数据正常显示，则说明接入成功；如出现于错误数据页面请根据页面错误提示进行排查；如未显示对应数据，请及时联系引力运营支持团队获取协助。
### 5.2 避免重复上报 [#52-避免重复上报]
上线前，请按媒体和事件核对回传来源（引力回传、媒体 SDK 自动采集、客户端手动上报、自有服务端 API），确认同一转化不会通过多条链路重复回传。需要切换到引力回传的事件，应在验证新链路正常后停用原有重复链路；媒体 SDK 的其他功能是否保留，请按对应集成文档确认。
> **注意**
> 至此验证无误之后，您可以正常上线了。
以上是 SDK 的基础接入指引。如需使用 **行为事件上报、用户属性上报、进阶功能、自动采集** 等功能，请参考以下文档：
> **注意**
> 这些功能并非所有业务场景都需要，请按需查阅。
* [行为事件上报](/docs/client-sdk/mini-games/track-events)
* [用户属性上报](/docs/client-sdk/mini-games/user-properties)
* [进阶功能](/docs/client-sdk/mini-games/advanced)
* [自动采集](/docs/client-sdk/mini-games/advanced/automatic-tracking)
# 闲鱼小游戏快速集成
> 来源：https://help.gravity-engine.com/docs/client-sdk/mini-games/goofish-quickstart
> 介绍 Gravity Engine 闲鱼小游戏 SDK 的安装、初始化、用户注册与事件上报流程，并提供参数说明和调用示例。
本文档主要讲述 **原生闲鱼小游戏** 接入 [引力引擎](https://gravity-engine.com/) 的技术接入方案，在开始接入前，建议您先阅读 [接入前准备](/docs/getting-started/overview)以了解接入必备的基础概念。
> **注意**
> 本接入方案仅适用于官方**原生闲鱼小游戏**开发的项目。如果您使用的是其他游戏引擎（如 Unity、CocosCreator、Laya、Egret 等），请访问[引力引擎 SDK 总览页面](/docs/client-sdk/sdk-overview)选择对应的框架接入文档。
## 1. 获取 AccessToken [#1-获取-accesstoken]
您可以在[设置-应用管理](https://web.gravity-engine.com/#/manage/appmanage)页面点击"查看参数"按钮获取当前应用的 AccessToken，请妥善保存避免泄露。
## 2. 配置并启动 SDK [#2-配置并启动-sdk]
开始接入工作之前，您需要先[下载 SDK](/docs/client-sdk/sdk-overview)。
将 `ge_mg_sdk_version.zip` 中的 `gravityengine.mg.goofish.min.js` 文件导入闲鱼小游戏原生项目中。
```js
import GravityEngine from "./utils/gravityengine.mg.goofish.min.js";
```
引入 SDK 后，即可进行 SDK 初始化参数配置：
> **注意**
> **每次冷启动过程中，`GravityEngine` 的实例化方法 `new GravityEngine()` 与初始化方法 `setupAndStart()` 均只能被调用一次。`clientId` 参数必须在这两个方法的其中一个传入。**
```js
const config = {
accessToken: "your_access_token", // 项目通行证，在：网站后台-->设置-->应用列表中找到Access Token列 复制（首次使用可能需要先新增应用）
// clientId如果当前还无法获取，可以不传但是不能传空字符串，等后面获取之后通过setupAndStart设置
clientId: "your_client_id", // 用户唯一标识，如产品为小游戏，则必须填用户openid（注意，不是小游戏的APPID！！！）
//预设公共属性
presetSuperProperties:{
"testSuperKey":"testSuperValue"
}
};
const ge = new GravityEngine(config);
ge.setupAndStart();
```
> **注意**
> **配置项目合法域名：** 您需要将 `https://api.gravity-engine.com` 配置到开发者后台 request 合法域名列表中。
## 3. 初始化 [#3-初始化]
在用户可以获取到用户唯一 ID 时调用此方法，推荐首次启动时调用。
> **注意**
> 首次调用后，需要在 `initialize` 的 `then` 中才能继续调用其他事件上报的方法
>
> 初始化方法调用成功之后，后续冷启动可以不再调用，只需要正常启动 SDK 即可（多次调用也不会有问题，引力做了兼容）
### 方法示例 [#方法示例]
```js
ge.initialize({
name: "your_name",
version: 123,
openid: "your_openid",
enable_sync_attribution: false,
adData:{
"testAdKey":"testAdValue"
}
})
.then((res) => {
console.log("initialize success", res);
})
.catch((err) => {
console.log("initialize failed", err);
});
```
### 参数说明 [#参数说明]
| 参数名称 | 参数含义 | 参数类型 | 是否必传 |
| ------------------------- | -------------------------------------------------------------------------------------------- | ------- | ---- |
| name | 用户名或用户唯一 ID（可理解为业务中的昵称），如果不需要昵称，可以填默认值，但不可以传空字符串！ | string | 是 |
| version | 产品发布版本号，便于后续在引力后台过滤 | number | 是 |
| openid | 用户 openid | string | 是 |
| enable\_sync\_attribution | 是否开启同步获取归因信息（参考[同步归因](/docs/attribution/synchronous-attribution)文档）。在媒体点击下发延迟的情况下会影响归因，请谨慎开启 | boolean | 是 |
| channel | 当前用户来源渠道，对应用户细查中的：客户端渠道 | string | 否 |
| adData | 预设归因信息 | object | 否 |
## 4. 事件上报 [#4-事件上报]
### 4.1 业务注册事件上报 [#41-业务注册事件上报]
> **注意**
> **此功能仅适用于需要统计业务注册转化数据的场景。如果您的应用不需要追踪用户注册行为，可以跳过此事件接入。**
> **注意**
> 该方法可多次调用，每次调用都会上报一个用户注册事件（计算指标时会去重）
当用户完成应用内业务注册后，您可以调用 `registerEvent` 方法来上报用户注册事件(`$MPRegister`)给引力，引力会使用该事件统计指标：标准\_注册数
#### 调用示例 [#调用示例]
```js
ge.registerEvent();
```
### 4.2 付费事件上报 [#42-付费事件上报]
> **注意**
> **付费事件上报用于收入统计和分析，如您的应用不涉及内购或付费服务，则无需接入此事件。**
> **注意**
> 如果您需要通过后端 API 方式上报付费事件，请参考 [混合上报模式](/docs/client-sdk/hybrid-reporting) 来接入事件上报接口报送付费事件。
当用户发生付费行为时，需要调用 `payEvent` 方法记录用户付费事件，此事件非常重要，会影响买量和 ROI 统计，请务必重点测试！
#### 方法示例 [#方法示例-1]
```js
ge.payEvent(payAmount, payType, orderId, payReason, payMethod);
```
#### 参数说明 [#参数说明-1]
| 参数名称 | 参数含义 | 参数类型 | 是否必传 |
| --------- | ------------------------------------------------------------------------------------------------------------------------ | ------ | ---- |
| 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]
```js
ge.payEvent(300, "CNY", "your_order_id", "月卡", "支付宝");
```
## 5. 接入验证 [#5-接入验证]
> **注意**
> **正式上线之前，请完成本节的校验，否则可能会导致买量上报异常！**
### 5.1 关键事件验证 [#51-关键事件验证]
在引力后台[事件流](https://web.gravity-engine.com/#/manage/metadata/eventFlow)界面开启**加载实时数据**，并在产品中触发以下几个事件。事件验收与排错：[接入验收与排错](/docs/getting-started/integration-checklist)
| 事件名 | 事件英文名 | 触发时机 | 采集方式 | 默认映射到媒体事件 | 备注 |
| ---- | ------------- | ---------- | ------------------------ | --------- | ----------------------- |
| 用户注册 | `$MPRegister` | 用户完成业务注册之后 | 调用 SDK 的**上报业务注册事件**方法采集 | 暂无 | 接入了**业务注册上报事件**的产品均需要校验 |
| 付费 | `$PayEvent` | 用户付费之后 | 调用 SDK 的**上报用户付费事件**方法采集 | 付费 | 接入了**付费事件上报事件**的产品均需要校验 |
| 广告展示 | `$AdShow` | 用户观看广告之后 | 调用 SDK 的**上报广告展示事件**方法采集 | 暂无 | 接入了**广告事件上报事件**的产品均需要校验 |
触发操作后，请在[事件流](https://web.gravity-engine.com/#/manage/metadata/eventFlow)界面中筛选测试用户的 Client ID，观察对应事件是否出现在实时入库页面。若事件数据正常显示，则说明接入成功；如出现于错误数据页面请根据页面错误提示进行排查；如未显示对应数据，请及时联系引力运营支持团队获取协助。
### 5.2 避免重复上报 [#52-避免重复上报]
上线前，请按媒体和事件核对回传来源（引力回传、媒体 SDK 自动采集、客户端手动上报、自有服务端 API），确认同一转化不会通过多条链路重复回传。需要切换到引力回传的事件，应在验证新链路正常后停用原有重复链路；媒体 SDK 的其他功能是否保留，请按对应集成文档确认。
> **注意**
> 至此验证无误之后，您可以正常上线了。
以上是 SDK 的基础接入指引。如需使用 **行为事件上报、用户属性上报、进阶功能、自动采集** 等功能，请参考以下文档：
> **注意**
> 这些功能并非所有业务场景都需要，请按需查阅。
* [行为事件上报](/docs/client-sdk/mini-games/track-events)
* [用户属性上报](/docs/client-sdk/mini-games/user-properties)
* [进阶功能](/docs/client-sdk/mini-games/advanced)
* [自动采集](/docs/client-sdk/mini-games/advanced/automatic-tracking)
# 小游戏
> 来源：https://help.gravity-engine.com/docs/client-sdk/mini-games
> 小游戏 SDK索引，汇总微信小游戏快速集成、抖音小游戏快速集成等主题，便于按功能进入对应的配置、接入或参考说明。
{/* Generated by scripts/generate-docs-routes.mjs. Do not edit. */}
## 目录 [#目录]
* [微信小游戏快速集成](/docs/client-sdk/mini-games/wechat-quickstart)
* [抖音小游戏快速集成](/docs/client-sdk/mini-games/douyin-quickstart)
* [TikTok小游戏快速集成](/docs/client-sdk/mini-games/tiktok-quickstart)
* [快手小游戏快速集成](/docs/client-sdk/mini-games/kuaishou-quickstart)
* [QQ小游戏快速集成](/docs/client-sdk/mini-games/qq-quickstart)
* [支付宝小游戏快速集成](/docs/client-sdk/mini-games/alipay-quickstart)
* [百度小游戏快速集成](/docs/client-sdk/mini-games/baidu-quickstart)
* [B站小游戏快速集成](/docs/client-sdk/mini-games/bilibili-quickstart)
* [taptap小游戏快速集成](/docs/client-sdk/mini-games/taptap-quickstart)
* [芒果TV小游戏快速集成](/docs/client-sdk/mini-games/mgtv-quickstart)
* [淘宝小游戏快速集成](/docs/client-sdk/mini-games/taobao-quickstart)
* [京东小游戏快速集成](/docs/client-sdk/mini-games/jd-quickstart)
* [美团小游戏快速集成](/docs/client-sdk/mini-games/meituan-quickstart)
* [闲鱼小游戏快速集成](/docs/client-sdk/mini-games/goofish-quickstart)
* [行为事件上报](/docs/client-sdk/mini-games/track-events)
* [用户属性上报](/docs/client-sdk/mini-games/user-properties)
* [进阶功能](/docs/client-sdk/mini-games/advanced) — 子目录
# 京东小游戏快速集成
> 来源：https://help.gravity-engine.com/docs/client-sdk/mini-games/jd-quickstart
> 说明引力 SDK 在京东小游戏的游戏引擎接入方式，并指引使用 Cocos Creator、Laya 或 Egret 对应文档完成集成。
京东小游戏目前不支持原生框架开发，只支持游戏引擎开发打包，请您访问[引力引擎 SDK 总览页面](/docs/client-sdk/sdk-overview)选择对应的游戏引擎框架接入文档来完成对接，目前引力支持以下游戏引擎对接：
1. CocosCreator
2. Laya
3. Egret
# 快手小游戏快速集成
> 来源：https://help.gravity-engine.com/docs/client-sdk/mini-games/kuaishou-quickstart
> 介绍 Gravity Engine 快手小游戏 SDK 的安装、初始化、用户注册与事件上报流程，并提供参数说明和调用示例。
本文档主要讲述 **原生快手小游戏** 接入 [引力引擎](https://gravity-engine.com/) 的技术接入方案，在开始接入前，建议您先阅读 [接入前准备](/docs/getting-started/overview)以了解接入必备的基础概念。
> **注意**
> 本接入方案仅适用于官方**原生快手小游戏**开发的项目。如果您使用的是其他游戏引擎（如 Unity、CocosCreator、Laya、Egret 等），请访问[引力引擎 SDK 总览页面](/docs/client-sdk/sdk-overview)选择对应的框架接入文档。
## 1. 获取 AccessToken [#1-获取-accesstoken]
您可以在[设置-应用管理](https://web.gravity-engine.com/#/manage/appmanage)页面点击"查看参数"按钮获取当前应用的 AccessToken，请妥善保存避免泄露。
## 2. 配置并启动 SDK [#2-配置并启动-sdk]
开始接入工作之前，您需要先[下载 SDK](/docs/client-sdk/sdk-overview)。
将 `ge_mg_sdk_version.zip` 中的 `gravityengine.mg.ks.min.js` 文件导入快手小游戏原生项目中。
```js
const GravityEngine = require("./gravityengine.mg.ks.min");
```
引入 SDK 后，即可进行 SDK 初始化参数配置：
> **注意**
> **每次冷启动过程中，`GravityEngine` 的实例化方法 `new GravityEngine()` 与初始化方法 `setupAndStart()` 均只能被调用一次。`clientId` 参数必须在这两个方法的其中一个传入。**
```js
const config = {
accessToken: "your_access_token", // 项目通行证，在：网站后台-->设置-->应用列表中找到Access Token列 复制（首次使用可能需要先新增应用）
// clientId如果当前还无法获取，可以不传但是不能传空字符串，等后面获取之后通过setupAndStart设置
clientId: "your_client_id", // 用户唯一标识，如产品为小游戏，则必须填用户openid（注意，不是小游戏的APPID！！！）
//预设公共属性
presetSuperProperties:{
"testSuperKey":"testSuperValue"
}
};
const ge = new GravityEngine(config);
ge.setupAndStart();
```
> **注意**
> **无法自行获取 `openid`？** 没有自建后端时，可使用引力 SDK 内置的快捷获取方法，详见[快捷获取 openid](/docs/client-sdk/mini-games/advanced/quick-get-openid)。
> **注意**
> **配置项目合法域名：** 您需要将 `https://backend.gravity-engine.com` 和 `https://api.gravity-engine.com` 配置到开发者后台 request 合法域名列表中。
> **注意**
> **如果您是从低版本引力 SDK 升级到高版本的，请一定记得添加 `https://api.gravity-engine.com` 域名到合法域名列表中，否则将导致事件采集失效，影响您的使用！**
## 3. 初始化 [#3-初始化]
在用户可以获取到用户唯一 ID 时调用此方法，推荐首次启动时调用。
> **注意**
> 首次调用后，需要在 `initialize` 的 `then` 中才能继续调用其他事件上报的方法
>
> 初始化方法调用成功之后，后续冷启动可以不再调用，只需要正常启动 SDK 即可（多次调用也不会有问题，引力做了兼容）
### 方法示例 [#方法示例]
```js
ge.initialize({
name: "your_name",
version: 123,
openid: "your_openid",
enable_sync_attribution: false,
})
.then((res) => {
console.log("initialize success", res);
})
.catch((err) => {
console.log("initialize failed", err);
});
```
### 参数说明 [#参数说明]
| 参数名称 | 参数含义 | 参数类型 | 是否必传 |
| ------------------------- | -------------------------------------------------------------------------------------------- | ------- | ---- |
| name | 用户名或用户唯一 ID（可理解为业务中的昵称），如果不需要昵称，可以填默认值，但不可以传空字符串！ | string | 是 |
| version | 产品发布版本号，便于后续在引力后台过滤 | number | 是 |
| openid | 用户 openid | string | 是 |
| enable\_sync\_attribution | 是否开启同步获取归因信息（参考[同步归因](/docs/attribution/synchronous-attribution)文档）。在媒体点击下发延迟的情况下会影响归因，请谨慎开启 | boolean | 是 |
| channel | 当前用户来源渠道，对应用户细查中的：客户端渠道 | string | 否 |
| adData | 预设归因信息 | object | 否 |
## 4. 事件上报 [#4-事件上报]
### 4.1 业务注册事件上报 [#41-业务注册事件上报]
> **注意**
> **此功能仅适用于需要统计业务注册转化数据的场景。如果您的应用不需要追踪用户注册行为，可以跳过此事件接入。**
> **注意**
> 该方法可多次调用，每次调用都会上报一个用户注册事件（计算指标时会去重）
当用户完成应用内业务注册后，您可以调用 `registerEvent` 方法来上报用户注册事件(`$MPRegister`)给引力，引力会使用该事件统计指标：标准\_注册数
#### 调用示例 [#调用示例]
```js
ge.registerEvent();
```
### 4.2 付费事件上报 [#42-付费事件上报]
> **注意**
> **付费事件上报用于收入统计和分析，如您的应用不涉及内购或付费服务，则无需接入此事件。**
> **注意**
> 如果您需要通过后端 API 方式上报付费事件，请参考 [混合上报模式](/docs/client-sdk/hybrid-reporting) 来接入事件上报接口报送付费事件。
当用户发生付费行为时，需要调用 `payEvent` 方法记录用户付费事件，此事件非常重要，会影响买量和 ROI 统计，请务必重点测试！
#### 方法示例 [#方法示例-1]
```js
ge.payEvent(payAmount, payType, orderId, payReason, payMethod);
```
#### 参数说明 [#参数说明-1]
| 参数名称 | 参数含义 | 参数类型 | 是否必传 |
| --------- | ------------------------------------------------------------------------------------------------------------------------ | ------ | ---- |
| 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]
```js
ge.payEvent(300, "CNY", "your_order_id", "月卡", "支付宝");
```
### 4.3 广告观看事件上报 [#43-广告观看事件上报]
> **注意**
> **广告观看上报适用于广告变现类应用，若您的应用未集成广告模块，则无需接入此事件。**
> **注意**
> **启动 SDK 时传入的 clientId 必须为快手小游戏的 openid 的原值，否则会拉不到广告数据！**
> **注意**
> **受限于媒体接口，引力仅能获取信息流买量用户的 eCPM 及广告总数。因此需通过小额买量验证广告变现效果。**
>
> **快手小游戏广告模块对接无需客户端 SDK 接入，请直接在引力后台配置，配置好后会由引力后端负责自动拉取，具体配置如下：**
**1.** 确认投放该产品的磁力账户已在[引力账户管理授权](https://web.gravity-engine.com/#/promotion/account/kuaishou)并绑定产品，若最初没有完成账户授权，中途授权账户后，引力会拉取过去 1 个小时内的数据。具体授权请参考：[磁力账户授权指引 - 飞书云文档](https://gravityengine.feishu.cn/wiki/ZuvHwYsDwipxrbk142mcx16Wnhe)
**2.** [设置-应用管理-配置-快手开发者](https://web.gravity-engine.com/#/manage/appmanage)配置项中的自动拉取 ecpm 开关需开启
## 5. 接入验证 [#5-接入验证]
> **注意**
> **正式上线之前，请完成本节的校验，否则可能会导致买量上报异常！**
### 5.1 关键事件验证 [#51-关键事件验证]
在引力后台[事件流](https://web.gravity-engine.com/#/manage/metadata/eventFlow)界面开启**加载实时数据**，并在产品中触发以下几个事件。事件验收与排错：[接入验收与排错](/docs/getting-started/integration-checklist)
| 事件名 | 事件英文名 | 触发时机 | 采集方式 | 默认映射到媒体事件 | 备注 |
| ---- | ------------- | ---------- | ------------------------ | --------- | ----------------------- |
| 用户注册 | `$MPRegister` | 用户完成业务注册之后 | 调用 SDK 的**上报业务注册事件**方法采集 | 暂无 | 接入了**业务注册上报事件**的产品均需要校验 |
| 付费 | `$PayEvent` | 用户付费之后 | 调用 SDK 的**上报用户付费事件**方法采集 | 付费 | 接入了**付费事件上报事件**的产品均需要校验 |
触发操作后，请在[事件流](https://web.gravity-engine.com/#/manage/metadata/eventFlow)界面中筛选测试用户的 Client ID，观察对应事件是否出现在实时入库页面。若事件数据正常显示，则说明接入成功；如出现于错误数据页面请根据页面错误提示进行排查；如未显示对应数据，请及时联系引力运营支持团队获取协助。
### 5.2 避免重复上报 [#52-避免重复上报]
上线前，请按媒体和事件核对回传来源（引力回传、媒体 SDK 自动采集、客户端手动上报、自有服务端 API），确认同一转化不会通过多条链路重复回传。需要切换到引力回传的事件，应在验证新链路正常后停用原有重复链路；媒体 SDK 的其他功能是否保留，请按对应集成文档确认。
> **注意**
> 至此验证无误之后，您可以正常上线了。
以上是 SDK 的基础接入指引。如需使用 **行为事件上报、用户属性上报、进阶功能、自动采集** 等功能，请参考以下文档：
> **注意**
> 这些功能并非所有业务场景都需要，请按需查阅。
* [行为事件上报](/docs/client-sdk/mini-games/track-events)
* [用户属性上报](/docs/client-sdk/mini-games/user-properties)
* [进阶功能](/docs/client-sdk/mini-games/advanced)
* [自动采集](/docs/client-sdk/mini-games/advanced/automatic-tracking)
# 美团小游戏快速集成
> 来源：https://help.gravity-engine.com/docs/client-sdk/mini-games/meituan-quickstart
> 说明引力 SDK 在美团小游戏的游戏引擎接入方式，并指引使用 Cocos Creator、Laya 或 Egret 对应文档完成集成。
美团小游戏目前不支持原生框架开发，只支持游戏引擎开发打包，请您访问[引力引擎 SDK 总览页面](/docs/client-sdk/sdk-overview)选择对应的游戏引擎框架接入文档来完成对接，目前引力支持以下游戏引擎对接：
1. Unity
2. CocosCreator
3. Laya
4. Egret
# 芒果TV小游戏快速集成
> 来源：https://help.gravity-engine.com/docs/client-sdk/mini-games/mgtv-quickstart
> 介绍 Gravity Engine 芒果TV小游戏 SDK 的安装、初始化、用户注册与事件上报流程，并提供参数说明和调用示例。
本文档主要讲述 **原生芒果TV小游戏** 接入 [引力引擎](https://gravity-engine.com/) 的技术接入方案，在开始接入前，建议您先阅读 [接入前准备](/docs/getting-started/overview)以了解接入必备的基础概念。
> **注意**
> 本接入方案仅适用于官方**原生芒果TV小游戏**开发的项目。如果您使用的是其他游戏引擎（如 Unity、CocosCreator、Laya、Egret 等），请访问[引力引擎 SDK 总览页面](/docs/client-sdk/sdk-overview)选择对应的框架接入文档。
## 1. 获取 AccessToken [#1-获取-accesstoken]
您可以在[设置-应用管理](https://web.gravity-engine.com/#/manage/appmanage)页面点击"查看参数"按钮获取当前应用的 AccessToken，请妥善保存避免泄露。
## 2. 配置并启动 SDK [#2-配置并启动-sdk]
开始接入工作之前，您需要先[下载 SDK](/docs/client-sdk/sdk-overview)。
将 `ge_mg_sdk_version.zip` 中的 `gravityengine.mg.mgtv.min.js` 文件导入芒果TV小游戏原生项目中。
```js
import GravityEngine from "./utils/gravityengine.mg.mgtv.min.js";
```
引入 SDK 后，即可进行 SDK 初始化参数配置：
> **注意**
> **每次冷启动过程中，`GravityEngine` 的实例化方法 `new GravityEngine()` 与初始化方法 `setupAndStart()` 均只能被调用一次。`clientId` 参数必须在这两个方法的其中一个传入。**
```js
const config = {
accessToken: "your_access_token", // 项目通行证，在：网站后台-->设置-->应用列表中找到Access Token列 复制（首次使用可能需要先新增应用）
// clientId如果当前还无法获取，可以不传但是不能传空字符串，等后面获取之后通过setupAndStart设置
clientId: "your_client_id", // 用户唯一标识，如产品为小游戏，则必须填用户openid（注意，不是小游戏的APPID！！！）
//预设公共属性
presetSuperProperties:{
"testSuperKey":"testSuperValue"
}
};
const ge = new GravityEngine(config);
ge.setupAndStart();
```
> **注意**
> **配置项目合法域名：** 您需要将 `https://api.gravity-engine.com` 配置到开发者后台 request 合法域名列表中。
## 3. 初始化 [#3-初始化]
在用户可以获取到用户唯一 ID 时调用此方法，推荐首次启动时调用。
> **注意**
> 首次调用后，需要在 `initialize` 的 `then` 中才能继续调用其他事件上报的方法
>
> 初始化方法调用成功之后，后续冷启动可以不再调用，只需要正常启动 SDK 即可（多次调用也不会有问题，引力做了兼容）
### 方法示例 [#方法示例]
```js
ge.initialize({
name: "your_name",
version: 123,
openid: "your_openid",
enable_sync_attribution: false,
})
.then((res) => {
console.log("initialize success", res);
})
.catch((err) => {
console.log("initialize failed", err);
});
```
### 参数说明 [#参数说明]
| 参数名称 | 参数含义 | 参数类型 | 是否必传 |
| ------------------------- | -------------------------------------------------------------------------------------------- | ------- | ---- |
| name | 用户名或用户唯一 ID（可理解为业务中的昵称），如果不需要昵称，可以填默认值，但不可以传空字符串！ | string | 是 |
| version | 产品发布版本号，便于后续在引力后台过滤 | number | 是 |
| openid | 用户 openid | string | 是 |
| enable\_sync\_attribution | 是否开启同步获取归因信息（参考[同步归因](/docs/attribution/synchronous-attribution)文档）。在媒体点击下发延迟的情况下会影响归因，请谨慎开启 | boolean | 是 |
| channel | 当前用户来源渠道，对应用户细查中的：客户端渠道 | string | 否 |
| adData | 预设归因信息 | object | 否 |
## 4. 事件上报 [#4-事件上报]
### 4.1 业务注册事件上报 [#41-业务注册事件上报]
> **注意**
> **此功能仅适用于需要统计业务注册转化数据的场景。如果您的应用不需要追踪用户注册行为，可以跳过此事件接入。**
> **注意**
> 该方法可多次调用，每次调用都会上报一个用户注册事件（计算指标时会去重）
当用户完成应用内业务注册后，您可以调用 `registerEvent` 方法来上报用户注册事件(`$MPRegister`)给引力，引力会使用该事件统计指标：标准\_注册数
#### 调用示例 [#调用示例]
```js
ge.registerEvent();
```
### 4.2 付费事件上报 [#42-付费事件上报]
> **注意**
> **付费事件上报用于收入统计和分析，如您的应用不涉及内购或付费服务，则无需接入此事件。**
> **注意**
> 如果您需要通过后端 API 方式上报付费事件，请参考 [混合上报模式](/docs/client-sdk/hybrid-reporting) 来接入事件上报接口报送付费事件。
当用户发生付费行为时，需要调用 `payEvent` 方法记录用户付费事件，此事件非常重要，会影响买量和 ROI 统计，请务必重点测试！
#### 方法示例 [#方法示例-1]
```js
ge.payEvent(payAmount, payType, orderId, payReason, payMethod);
```
#### 参数说明 [#参数说明-1]
| 参数名称 | 参数含义 | 参数类型 | 是否必传 |
| --------- | ------------------------------------------------------------------------------------------------------------------------ | ------ | ---- |
| 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]
```js
ge.payEvent(300, "CNY", "your_order_id", "月卡", "支付宝");
```
## 5. 接入验证 [#5-接入验证]
> **注意**
> **正式上线之前，请完成本节的校验，否则可能会导致买量上报异常！**
### 5.1 关键事件验证 [#51-关键事件验证]
在引力后台[事件流](https://web.gravity-engine.com/#/manage/metadata/eventFlow)界面开启**加载实时数据**，并在产品中触发以下几个事件。事件验收与排错：[接入验收与排错](/docs/getting-started/integration-checklist)
| 事件名 | 事件英文名 | 触发时机 | 采集方式 | 默认映射到媒体事件 | 备注 |
| ---- | ------------- | ---------- | ------------------------ | --------- | ----------------------- |
| 用户注册 | `$MPRegister` | 用户完成业务注册之后 | 调用 SDK 的**上报业务注册事件**方法采集 | 暂无 | 接入了**业务注册上报事件**的产品均需要校验 |
| 付费 | `$PayEvent` | 用户付费之后 | 调用 SDK 的**上报用户付费事件**方法采集 | 付费 | 接入了**付费事件上报事件**的产品均需要校验 |
| 广告展示 | `$AdShow` | 用户观看广告之后 | 调用 SDK 的**上报广告展示事件**方法采集 | 暂无 | 接入了**广告事件上报事件**的产品均需要校验 |
触发操作后，请在[事件流](https://web.gravity-engine.com/#/manage/metadata/eventFlow)界面中筛选测试用户的 Client ID，观察对应事件是否出现在实时入库页面。若事件数据正常显示，则说明接入成功；如出现于错误数据页面请根据页面错误提示进行排查；如未显示对应数据，请及时联系引力运营支持团队获取协助。
### 5.2 避免重复上报 [#52-避免重复上报]
上线前，请按媒体和事件核对回传来源（引力回传、媒体 SDK 自动采集、客户端手动上报、自有服务端 API），确认同一转化不会通过多条链路重复回传。需要切换到引力回传的事件，应在验证新链路正常后停用原有重复链路；媒体 SDK 的其他功能是否保留，请按对应集成文档确认。
> **注意**
> 至此验证无误之后，您可以正常上线了。
以上是 SDK 的基础接入指引。如需使用 **行为事件上报、用户属性上报、进阶功能、自动采集** 等功能，请参考以下文档：
> **注意**
> 这些功能并非所有业务场景都需要，请按需查阅。
* [行为事件上报](/docs/client-sdk/mini-games/track-events)
* [用户属性上报](/docs/client-sdk/mini-games/user-properties)
* [进阶功能](/docs/client-sdk/mini-games/advanced)
* [自动采集](/docs/client-sdk/mini-games/advanced/automatic-tracking)
# QQ小游戏快速集成
> 来源：https://help.gravity-engine.com/docs/client-sdk/mini-games/qq-quickstart
> 介绍 Gravity Engine QQ小游戏 SDK 的安装、初始化、用户注册与事件上报流程，并提供参数说明和调用示例。
本文档主要讲述 **原生QQ小游戏** 接入 [引力引擎](https://gravity-engine.com/) 的技术接入方案，在开始接入前，建议您先阅读 [接入前准备](/docs/getting-started/overview)以了解接入必备的基础概念。
> **注意**
> 本接入方案仅适用于官方**原生QQ小游戏**开发的项目。如果您使用的是其他游戏引擎（如 Unity、CocosCreator、Laya、Egret 等），请访问[引力引擎 SDK 总览页面](/docs/client-sdk/sdk-overview)选择对应的框架接入文档。
## 1. 获取 AccessToken [#1-获取-accesstoken]
您可以在[设置-应用管理](https://web.gravity-engine.com/#/manage/appmanage)页面点击"查看参数"按钮获取当前应用的 AccessToken，请妥善保存避免泄露。
## 2. 配置并启动 SDK [#2-配置并启动-sdk]
开始接入工作之前，您需要先[下载 SDK](/docs/client-sdk/sdk-overview)。
将 `ge_mg_sdk_version.zip` 中的 `gravityengine.mg.qq.min.js` 文件导入 QQ 小游戏原生项目中。
```js
import GravityEngine from "./utils/gravityengine.mg.qq.min";
```
引入 SDK 后，即可进行 SDK 初始化参数配置：
> **注意**
> **每次冷启动过程中，`GravityEngine` 的实例化方法 `new GravityEngine()` 与初始化方法 `setupAndStart()` 均只能被调用一次。`clientId` 参数必须在这两个方法的其中一个传入。**
```js
const config = {
accessToken: "your_access_token", // 项目通行证，在：网站后台-->设置-->应用列表中找到Access Token列 复制（首次使用可能需要先新增应用）
// clientId如果当前还无法获取，可以不传但是不能传空字符串，等后面获取之后通过setupAndStart设置
clientId: "your_client_id", // 用户唯一标识，如产品为小游戏，则必须填用户openid（注意，不是小游戏的APPID！！！）
//预设公共属性
presetSuperProperties:{
"testSuperKey":"testSuperValue"
}
};
const ge = new GravityEngine(config);
ge.setupAndStart();
```
> **注意**
> **配置项目合法域名：** 您需要将 `https://api.gravity-engine.com` 配置到开发者后台 request 合法域名列表中。
## 3. 初始化 [#3-初始化]
在用户可以获取到用户唯一 ID 时调用此方法，推荐首次启动时调用。
> **注意**
> 首次调用后，需要在 `initialize` 的 `then` 中才能继续调用其他事件上报的方法
>
> 初始化方法调用成功之后，后续冷启动可以不再调用，只需要正常启动 SDK 即可（多次调用也不会有问题，引力做了兼容）
### 方法示例 [#方法示例]
```js
ge.initialize({
name: "your_name",
version: 123,
openid: "your_openid",
enable_sync_attribution: false,
adData:{
"testAdKey":"testAdValue"
}
})
.then((res) => {
console.log("initialize success", res);
})
.catch((err) => {
console.log("initialize failed", err);
});
```
### 参数说明 [#参数说明]
| 参数名称 | 参数含义 | 参数类型 | 是否必传 |
| ------------------------- | -------------------------------------------------------------------------------------------- | ------- | ---- |
| name | 用户名或用户唯一 ID（可理解为业务中的昵称），如果不需要昵称，可以填默认值，但不可以传空字符串！ | string | 是 |
| version | 产品发布版本号，便于后续在引力后台过滤 | number | 是 |
| openid | 用户 openid | string | 是 |
| enable\_sync\_attribution | 是否开启同步获取归因信息（参考[同步归因](/docs/attribution/synchronous-attribution)文档）。在媒体点击下发延迟的情况下会影响归因，请谨慎开启 | boolean | 是 |
| channel | 当前用户来源渠道，对应用户细查中的：客户端渠道 | string | 否 |
| adData | 预设归因信息 | object | 否 |
## 4. 事件上报 [#4-事件上报]
### 4.1 业务注册事件上报 [#41-业务注册事件上报]
> **注意**
> **此功能仅适用于需要统计业务注册转化数据的场景。如果您的应用不需要追踪用户注册行为，可以跳过此事件接入。**
> **注意**
> 该方法可多次调用，每次调用都会上报一个用户注册事件（计算指标时会去重）
当用户完成应用内业务注册后，您可以调用 `registerEvent` 方法来上报用户注册事件(`$MPRegister`)给引力，引力会使用该事件统计指标：标准\_注册数
#### 调用示例 [#调用示例]
```js
ge.registerEvent();
```
### 4.2 付费事件上报 [#42-付费事件上报]
> **注意**
> **付费事件上报用于收入统计和分析，如您的应用不涉及内购或付费服务，则无需接入此事件。**
> **注意**
> 如果您需要通过后端 API 方式上报付费事件，请参考 [混合上报模式](/docs/client-sdk/hybrid-reporting) 来接入事件上报接口报送付费事件。
当用户发生付费行为时，需要调用 `payEvent` 方法记录用户付费事件，此事件非常重要，会影响买量和 ROI 统计，请务必重点测试！
#### 方法示例 [#方法示例-1]
```js
ge.payEvent(payAmount, payType, orderId, payReason, payMethod);
```
#### 参数说明 [#参数说明-1]
| 参数名称 | 参数含义 | 参数类型 | 是否必传 |
| --------- | ------------------------------------------------------------------------------------------------------------------------ | ------ | ---- |
| 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]
```js
ge.payEvent(300, "CNY", "your_order_id", "月卡", "支付宝");
```
## 5. 接入验证 [#5-接入验证]
> **注意**
> **正式上线之前，请完成本节的校验，否则可能会导致买量上报异常！**
### 5.1 关键事件验证 [#51-关键事件验证]
在引力后台[事件流](https://web.gravity-engine.com/#/manage/metadata/eventFlow)界面开启**加载实时数据**，并在产品中触发以下几个事件。事件验收与排错：[接入验收与排错](/docs/getting-started/integration-checklist)
| 事件名 | 事件英文名 | 触发时机 | 采集方式 | 默认映射到媒体事件 | 备注 |
| ---- | ------------- | ---------- | ------------------------ | --------- | ----------------------- |
| 用户注册 | `$MPRegister` | 用户完成业务注册之后 | 调用 SDK 的**上报业务注册事件**方法采集 | 暂无 | 接入了**业务注册上报事件**的产品均需要校验 |
| 付费 | `$PayEvent` | 用户付费之后 | 调用 SDK 的**上报用户付费事件**方法采集 | 付费 | 接入了**付费事件上报事件**的产品均需要校验 |
| 广告展示 | `$AdShow` | 用户观看广告之后 | 调用 SDK 的**上报广告展示事件**方法采集 | 暂无 | 接入了**广告事件上报事件**的产品均需要校验 |
触发操作后，请在[事件流](https://web.gravity-engine.com/#/manage/metadata/eventFlow)界面中筛选测试用户的 Client ID，观察对应事件是否出现在实时入库页面。若事件数据正常显示，则说明接入成功；如出现于错误数据页面请根据页面错误提示进行排查；如未显示对应数据，请及时联系引力运营支持团队获取协助。
### 5.2 避免重复上报 [#52-避免重复上报]
上线前，请按媒体和事件核对回传来源（引力回传、媒体 SDK 自动采集、客户端手动上报、自有服务端 API），确认同一转化不会通过多条链路重复回传。需要切换到引力回传的事件，应在验证新链路正常后停用原有重复链路；媒体 SDK 的其他功能是否保留，请按对应集成文档确认。
> **注意**
> 至此验证无误之后，您可以正常上线了。
以上是 SDK 的基础接入指引。如需使用 **行为事件上报、用户属性上报、进阶功能、自动采集** 等功能，请参考以下文档：
> **注意**
> 这些功能并非所有业务场景都需要，请按需查阅。
* [行为事件上报](/docs/client-sdk/mini-games/track-events)
* [用户属性上报](/docs/client-sdk/mini-games/user-properties)
* [进阶功能](/docs/client-sdk/mini-games/advanced)
* [自动采集](/docs/client-sdk/mini-games/advanced/automatic-tracking)
# 淘宝小游戏快速集成
> 来源：https://help.gravity-engine.com/docs/client-sdk/mini-games/taobao-quickstart
> 说明引力 SDK 在淘宝小游戏的游戏引擎接入方式，并指引使用 Cocos Creator、Laya 或 Egret 对应文档完成集成。
淘宝小游戏目前不支持原生框架开发，只支持游戏引擎开发打包，请您访问[引力引擎 SDK 总览页面](/docs/client-sdk/sdk-overview)选择对应的游戏引擎框架接入文档来完成对接，目前引力支持以下游戏引擎对接：
1. CocosCreator
2. Laya
3. Egret
# taptap小游戏快速集成
> 来源：https://help.gravity-engine.com/docs/client-sdk/mini-games/taptap-quickstart
> 介绍 Gravity Engine TapTap 小游戏 SDK 的安装、初始化、用户注册与事件上报流程，并提供参数说明和调用示例。
本文档主要讲述 **原生taptap小游戏** 接入 [引力引擎](https://gravity-engine.com/) 的技术接入方案，在开始接入前，建议您先阅读 [接入前准备](/docs/getting-started/overview)以了解接入必备的基础概念。
> **注意**
> 本接入方案仅适用于官方**原生taptap小游戏**开发的项目。如果您使用的是其他游戏引擎（如 Unity、CocosCreator、Laya、Egret 等），请访问[引力引擎 SDK 总览页面](/docs/client-sdk/sdk-overview)选择对应的框架接入文档。
## 1. 获取 AccessToken [#1-获取-accesstoken]
您可以在[设置-应用管理](https://web.gravity-engine.com/#/manage/appmanage)页面点击"查看参数"按钮获取当前应用的 AccessToken，请妥善保存避免泄露。
## 2. 配置并启动 SDK [#2-配置并启动-sdk]
开始接入工作之前，您需要先[下载 SDK](/docs/client-sdk/sdk-overview)。
将 `ge_mg_sdk_version.zip` 中的 `gravityengine.mg.tap.min.js` 文件导入 taptap 小游戏原生项目中。
```js
import GravityEngine from "./utils/gravityengine.mg.tap.min.js";
```
引入 SDK 后，即可进行 SDK 初始化参数配置：
> **注意**
> **每次冷启动过程中，`GravityEngine` 的实例化方法 `new GravityEngine()` 与初始化方法 `setupAndStart()` 均只能被调用一次。`clientId` 参数必须在这两个方法的其中一个传入。**
```js
const config = {
accessToken: "your_access_token", // 项目通行证，在：网站后台-->设置-->应用列表中找到Access Token列 复制（首次使用可能需要先新增应用）
// clientId如果当前还无法获取，可以不传但是不能传空字符串，等后面获取之后通过setupAndStart设置
clientId: "your_client_id", // 用户唯一标识，如产品为小游戏，则必须填用户openid（注意，不是小游戏的APPID！！！）
//预设公共属性
presetSuperProperties:{
"testSuperKey":"testSuperValue"
}
};
const ge = new GravityEngine(config);
ge.setupAndStart();
```
> **注意**
> **配置项目合法域名：** 您需要将 `https://api.gravity-engine.com` 配置到开发者后台 request 合法域名列表中。
## 3. 初始化 [#3-初始化]
在用户可以获取到用户唯一 ID 时调用此方法，推荐首次启动时调用。
> **注意**
> 首次调用后，需要在 `initialize` 的 `then` 中才能继续调用其他事件上报的方法
>
> 初始化方法调用成功之后，后续冷启动可以不再调用，只需要正常启动 SDK 即可（多次调用也不会有问题，引力做了兼容）
### 方法示例 [#方法示例]
```js
ge.initialize({
name: "your_name",
version: 123,
openid: "your_openid",
enable_sync_attribution: false,
})
.then((res) => {
console.log("initialize success", res);
})
.catch((err) => {
console.log("initialize failed", err);
});
```
### 参数说明 [#参数说明]
| 参数名称 | 参数含义 | 参数类型 | 是否必传 |
| ------------------------- | -------------------------------------------------------------------------------------------- | ------- | ---- |
| name | 用户名或用户唯一 ID（可理解为业务中的昵称），如果不需要昵称，可以填默认值，但不可以传空字符串！ | string | 是 |
| version | 产品发布版本号，便于后续在引力后台过滤 | number | 是 |
| openid | 用户 openid | string | 是 |
| enable\_sync\_attribution | 是否开启同步获取归因信息（参考[同步归因](/docs/attribution/synchronous-attribution)文档）。在媒体点击下发延迟的情况下会影响归因，请谨慎开启 | boolean | 是 |
| channel | 当前用户来源渠道，对应用户细查中的：客户端渠道 | string | 否 |
| adData | 预设归因信息 | object | 否 |
## 4. 事件上报 [#4-事件上报]
### 4.1 业务注册事件上报 [#41-业务注册事件上报]
> **注意**
> **此功能仅适用于需要统计业务注册转化数据的场景。如果您的应用不需要追踪用户注册行为，可以跳过此事件接入。**
> **注意**
> 该方法可多次调用，每次调用都会上报一个用户注册事件（计算指标时会去重）
当用户完成应用内业务注册后，您可以调用 `registerEvent` 方法来上报用户注册事件(`$MPRegister`)给引力，引力会使用该事件统计指标：标准\_注册数
#### 调用示例 [#调用示例]
```js
ge.registerEvent();
```
### 4.2 付费事件上报 [#42-付费事件上报]
> **注意**
> **付费事件上报用于收入统计和分析，如您的应用不涉及内购或付费服务，则无需接入此事件。**
> **注意**
> 如果您需要通过后端 API 方式上报付费事件，请参考 [混合上报模式](/docs/client-sdk/hybrid-reporting) 来接入事件上报接口报送付费事件。
当用户发生付费行为时，需要调用 `payEvent` 方法记录用户付费事件，此事件非常重要，会影响买量和 ROI 统计，请务必重点测试！
#### 方法示例 [#方法示例-1]
```js
ge.payEvent(payAmount, payType, orderId, payReason, payMethod);
```
#### 参数说明 [#参数说明-1]
| 参数名称 | 参数含义 | 参数类型 | 是否必传 |
| --------- | ------------------------------------------------------------------------------------------------------------------------ | ------ | ---- |
| 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]
```js
ge.payEvent(300, "CNY", "your_order_id", "月卡", "支付宝");
```
## 5. 接入验证 [#5-接入验证]
> **注意**
> **正式上线之前，请完成本节的校验，否则可能会导致买量上报异常！**
### 5.1 关键事件验证 [#51-关键事件验证]
在引力后台[事件流](https://web.gravity-engine.com/#/manage/metadata/eventFlow)界面开启**加载实时数据**，并在产品中触发以下几个事件。事件验收与排错：[接入验收与排错](/docs/getting-started/integration-checklist)
| 事件名 | 事件英文名 | 触发时机 | 采集方式 | 默认映射到媒体事件 | 备注 |
| ---- | ------------- | ---------- | ------------------------ | --------- | ----------------------- |
| 用户注册 | `$MPRegister` | 用户完成业务注册之后 | 调用 SDK 的**上报业务注册事件**方法采集 | 暂无 | 接入了**业务注册上报事件**的产品均需要校验 |
| 付费 | `$PayEvent` | 用户付费之后 | 调用 SDK 的**上报用户付费事件**方法采集 | 付费 | 接入了**付费事件上报事件**的产品均需要校验 |
触发操作后，请在[事件流](https://web.gravity-engine.com/#/manage/metadata/eventFlow)界面中筛选测试用户的 Client ID，观察对应事件是否出现在实时入库页面。若事件数据正常显示，则说明接入成功；如出现于错误数据页面请根据页面错误提示进行排查；如未显示对应数据，请及时联系引力运营支持团队获取协助。
### 5.2 避免重复上报 [#52-避免重复上报]
上线前，请按媒体和事件核对回传来源（引力回传、媒体 SDK 自动采集、客户端手动上报、自有服务端 API），确认同一转化不会通过多条链路重复回传。需要切换到引力回传的事件，应在验证新链路正常后停用原有重复链路；媒体 SDK 的其他功能是否保留，请按对应集成文档确认。
> **注意**
> 至此验证无误之后，您可以正常上线了。
以上是 SDK 的基础接入指引。如需使用 **行为事件上报、用户属性上报、进阶功能、自动采集** 等功能，请参考以下文档：
> **注意**
> 这些功能并非所有业务场景都需要，请按需查阅。
* [行为事件上报](/docs/client-sdk/mini-games/track-events)
* [用户属性上报](/docs/client-sdk/mini-games/user-properties)
* [进阶功能](/docs/client-sdk/mini-games/advanced)
* [自动采集](/docs/client-sdk/mini-games/advanced/automatic-tracking)
# TikTok小游戏快速集成
> 来源：https://help.gravity-engine.com/docs/client-sdk/mini-games/tiktok-quickstart
> 介绍 Gravity Engine TikTok 小游戏 SDK 的安装、初始化、用户注册与事件上报流程，并提供参数说明和调用示例。
本文档主要讲述 **原生 TikTok 小游戏** 接入 [引力引擎](https://gravity-engine.com/) 的技术接入方案，在开始接入前，建议您先阅读 [接入前准备](/docs/getting-started/overview)以了解接入必备的基础概念。
> **注意**
> 本接入方案仅适用于官方**原生 TikTok 小游戏**开发的项目。如果您使用的是其他游戏引擎（如 Unity、CocosCreator、Laya、Egret 等），请访问[引力引擎 SDK 总览页面](/docs/client-sdk/sdk-overview)选择对应的框架接入文档。
>
> 如需接入抖音（国内）小游戏，请参考[抖音小游戏快速集成](/docs/client-sdk/mini-games/douyin-quickstart)。
## 1. 获取 AccessToken [#1-获取-accesstoken]
您可以在[设置-应用管理](https://web.gravity-engine.com/#/manage/appmanage)页面点击"查看参数"按钮获取当前应用的 AccessToken，请妥善保存避免泄露。
## 2. 配置并启动 SDK [#2-配置并启动-sdk]
开始接入工作之前，您需要先[下载 SDK](/docs/client-sdk/sdk-overview)。
将 `ge_mg_sdk_version.zip` 中的 `gravityengine.mg.tt.min.js` 导入工程，并初始化 SDK：
> **注意**
> **每次冷启动过程中，`GravityEngine` 的实例化方法 `new GravityEngine()` 与初始化方法 `setupAndStart()` 均只能被调用一次。`clientId` 参数必须在这两个方法的其中一个传入。**
```js
import GravityEngine from "./js/utils/gravityengine.mg.tt.min";
const config = {
accessToken: "your_access_token", // 项目通行证，在：网站后台-->设置-->应用列表中找到Access Token列 复制（首次使用可能需要先新增应用）
// clientId如果当前还无法获取，可以不传但是不能传空字符串，等后面获取之后通过setupAndStart设置
clientId: "your_client_id", // 用户唯一标识，如产品为小游戏，则必须填用户openid（注意，不是小游戏的APPID！！！）
name: "ge", // 全局变量名称, 默认为 gravityengine
isChina: false, // 是否使用国内域名，TikTok 需设置为 false
//预设公共属性
presetSuperProperties:{
"testSuperKey":"testSuperValue"
}
};
const ge = new GravityEngine(config);
ge.setupAndStart();
```
> **注意**
> **无法自行获取 `openid`？** 没有自建后端时，可使用引力 SDK 内置的快捷获取方法，详见[快捷获取 openid](/docs/client-sdk/mini-games/advanced/quick-get-openid)。
> **注意**
> **配置项目合法域名：** 您需要将 `https://global-api.gravity-engine.com` 配置到开发者后台 request 合法域名列表中。
## 3. 初始化 [#3-初始化]
在用户可以获取到用户唯一 ID 时调用此方法，推荐首次启动时调用。
> **注意**
> 首次调用后，需要在 `initialize` 的 `then` 中才能继续调用其他事件上报的方法
>
> 初始化方法调用成功之后，后续冷启动可以不再调用，只需要正常启动 SDK 即可（多次调用也不会有问题，引力做了兼容）
### 方法示例 [#方法示例]
```js
ge.initialize({
name: "your_name",
version: 123,
openid: "your_openid",
enable_sync_attribution: false,
})
.then((res) => {
console.log("initialize success", res);
})
.catch((err) => {
console.log("initialize failed", err);
});
```
### 参数说明 [#参数说明]
| 参数名称 | 参数含义 | 参数类型 | 是否必传 |
| ------------------------- | -------------------------------------------------------------------------------------------- | ------- | ---- |
| name | 用户名或用户唯一 ID（可理解为业务中的昵称），如果不需要昵称，可以填默认值，但不可以传空字符串！ | string | 是 |
| version | 产品发布版本号，便于后续在引力后台过滤 | number | 是 |
| openid | 用户 openid | string | 是 |
| enable\_sync\_attribution | 是否开启同步获取归因信息（参考[同步归因](/docs/attribution/synchronous-attribution)文档）。在媒体点击下发延迟的情况下会影响归因，请谨慎开启 | boolean | 是 |
| channel | 当前用户来源渠道，对应用户细查中的：客户端渠道 | string | 否 |
| adData | 预设归因信息 | object | 否 |
## 4. 事件上报 [#4-事件上报]
### 4.1 业务注册事件上报 [#41-业务注册事件上报]
> **注意**
> **此功能仅适用于需要统计业务注册转化数据的场景。如果您的应用不需要追踪用户注册行为，可以跳过此事件接入。**
> **注意**
> 该方法可多次调用，每次调用都会上报一个用户注册事件（计算指标时会去重）
当用户完成应用内业务注册后，您可以调用 `registerEvent` 方法来上报用户注册事件(`$MPRegister`)给引力，引力会使用该事件统计指标：标准\_注册数
#### 调用示例 [#调用示例]
```js
ge.registerEvent();
```
### 4.2 付费事件上报 [#42-付费事件上报]
> **注意**
> **付费事件上报用于收入统计和分析，如您的应用不涉及内购或付费服务，则无需接入此事件。**
> **注意**
> 如果您需要通过后端 API 方式上报付费事件，请参考 [混合上报模式](/docs/client-sdk/hybrid-reporting) 来接入事件上报接口报送付费事件。
当用户发生付费行为时，需要调用 `payEvent` 方法记录用户付费事件，此事件非常重要，会影响买量和 ROI 统计，请务必重点测试！
#### 方法示例 [#方法示例-1]
```js
ge.payEvent(payAmount, payType, orderId, payReason, payMethod);
```
#### 参数说明 [#参数说明-1]
| 参数名称 | 参数含义 | 参数类型 | 是否必传 |
| --------- | ------------------------------------------------------------------------------------------------------------------------ | ------ | ---- |
| 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]
```js
ge.payEvent(300, "CNY", "your_order_id", "月卡", "支付宝");
```
### 4.3 广告观看事件上报 [#43-广告观看事件上报]
> **注意**
> **广告观看上报适用于广告变现类应用，若您的应用未集成广告模块，则无需接入此事件。**
> **注意**
> **启动 SDK 时传入的 clientId 必须为 TikTok 小游戏的 openid 的原值，否则会拉不到广告数据！**
> **注意**
> **受限于媒体接口，引力仅能获取信息流买量用户的 eCPM 及广告总数。因此需通过小额买量验证广告变现效果。**
>
> **TikTok 小游戏广告模块对接无需客户端 SDK 接入，请直接在引力后台配置，配置好后会由引力后端负责自动拉取，AccessToken 的具体接入方式请参考[小游戏 AccessToken 接入](/docs/server-integration/mini-game-tokens)。**
## 5. 接入验证 [#5-接入验证]
> **注意**
> **正式上线之前，请完成本节的校验，否则可能会导致买量上报异常！**
### 5.1 关键事件验证 [#51-关键事件验证]
在引力后台[事件流](https://web.gravity-engine.com/#/manage/metadata/eventFlow)界面开启**加载实时数据**，并在产品中触发以下几个事件。事件验收与排错：[接入验收与排错](/docs/getting-started/integration-checklist)
| 事件名 | 事件英文名 | 触发时机 | 采集方式 | 默认映射到媒体事件 | 备注 |
| ---- | ------------- | ---------- | ------------------------ | --------- | ----------------------- |
| 用户注册 | `$MPRegister` | 用户完成业务注册之后 | 调用 SDK 的**上报业务注册事件**方法采集 | 暂无 | 接入了**业务注册上报事件**的产品均需要校验 |
| 付费 | `$PayEvent` | 用户付费之后 | 调用 SDK 的**上报用户付费事件**方法采集 | 付费 | 接入了**付费事件上报事件**的产品均需要校验 |
触发操作后，请在[事件流](https://web.gravity-engine.com/#/manage/metadata/eventFlow)界面中筛选测试用户的 Client ID，观察对应事件是否出现在实时入库页面。若事件数据正常显示，则说明接入成功；如出现于错误数据页面请根据页面错误提示进行排查；如未显示对应数据，请及时联系引力运营支持团队获取协助。
### 5.2 避免重复上报 [#52-避免重复上报]
上线前，请按媒体和事件核对回传来源（引力回传、媒体 SDK 自动采集、客户端手动上报、自有服务端 API），确认同一转化不会通过多条链路重复回传。需要切换到引力回传的事件，应在验证新链路正常后停用原有重复链路；媒体 SDK 的其他功能是否保留，请按对应集成文档确认。
> **注意**
> 至此验证无误之后，您可以正常上线了。
以上是 SDK 的基础接入指引。如需使用 **行为事件上报、用户属性上报、进阶功能、自动采集** 等功能，请参考以下文档：
> **注意**
> 这些功能并非所有业务场景都需要，请按需查阅。
* [行为事件上报](/docs/client-sdk/mini-games/track-events)
* [用户属性上报](/docs/client-sdk/mini-games/user-properties)
* [进阶功能](/docs/client-sdk/mini-games/advanced)
* [自动采集](/docs/client-sdk/mini-games/advanced/automatic-tracking)
# 行为事件上报
> 来源：https://help.gravity-engine.com/docs/client-sdk/mini-games/track-events
> 说明如何使用 Gravity Engine 小游戏 SDK 上报业务事件，并管理事件公共属性。
本文档详细介绍了 SDK 提供的事件上报功能，帮助开发者全面采集用户行为事件数据，为业务分析和运营决策提供数据支持。
通过上报应用内用户行为事件，您可以：
* **完整记录用户行为**：追踪用户在应用内的关键操作路径
* **支持多维度分析**：通过事件属性丰富分析维度
* **构建数据闭环**：为产品优化和精准运营提供数据基础
## 1. 自定义事件上报 [#1-自定义事件上报]
> **注意**
> **如需上报自定义事件，您必须先在[元事件](https://web.gravity-engine.com/#/manage/metadata/metaEvent)中添加，否则会上报失败！**
您可以直接调用 `track` 上传自定义事件，建议您根据准备阶段梳理的文档来设置事件的属性以及发送信息的条件，此处以购买商品为范例：
```js
ge.track(
"$purchase", // 追踪事件的名称
{
Item: "商品A",
ItemNum: 1,
Cost: 100,
Elements: ["apple", "ball", "cat"],
} // 需要上传的事件属性
);
```
* `track` 接口共有两个参数，第一个参数为事件的名称，第二个参数为事件的属性。
* 事件的名称是字符串，只能以字母开头，可包含数字、字母和下划线（\_），长度最大为 50 个字符。
* 事件的属性是 JS 对象，每个元素代表一个属性。
* 元素的 name 对应属性的名称，规定只能以字母开头，包含数字、字母和下划线（\_），长度最大为 50 个字符。
* 元素的 Value 为该属性的值，支持 `String`、`Integer`、`Float`、`Boolean`、`Date`、`DateTime` 和 `Array`；`Array` 中的内容可以为 `String`。
## 2. 公共属性 [#2-公共属性]
> **注意**
> **公共属性需要先在[事件属性](https://web.gravity-engine.com/#/manage/metadata/eventProperty)中添加，否则会上报失败！**
公共事件属性是所有事件（包括自动采集事件）都会包含的属性，用户属性中不会包含。
本节会介绍如何设置公共事件属性和动态公共属性。如果公共属性与事件中设置的自定义属性有相同 key 值，则最终的属性会根据下述优先级取值：
用户自定义事件属性 > 动态公共属性 > 事件公共属性
您可以调用 `setSuperProperties` 来设置公共事件属性，公共事件属性的格式要求与事件属性一致。在设置时只能传入常量，适合设置变化不频繁的属性。
根据属性优先级，自定义属性优先级高于事件公共属性，因此事件公共属性也可以作为某个属性的缺省值，在需要修改的事件中设置同名 Key 覆盖缺省值。
### 设置公共属性 [#设置公共属性]
```js
// 设置公共事件属性
ge.setSuperProperties({ channel: "渠道" });
// 使用 track 上传事件，此时事件中会带有公共事件属性
ge.track(
"Purchase", // 追踪事件的名称
{
Item: "商品A",
ItemNum: 1,
Cost: 100,
} // 需要上传的事件属性
);
/* 等价于在事件中加入这些公共属性
ge.track(
"Purchase", // 追踪事件的名称
{
Item: "商品A",
ItemNum: 1,
Cost: 100,
channel: "渠道" // 相当于在事件中加入这个属性
}
);
*/
```
如果多次调用 `setSuperProperties` 设置公共事件属性，则同名字段后面的调用会覆盖之前的同名字段。
### 删除公共属性 [#删除公共属性]
如果您需要删除某个公共事件属性，可以调用 `unsetSuperProperty()` 清除其中一个公共事件属性：
```js
// 清除属性名为 CHANNEL 的公共属性
ge.unsetSuperProperty("CHANNEL");
```
### 清空公共属性 [#清空公共属性]
如果您想要清空所有公共事件属性，则可以调用 `clearSuperProperties()`：
```js
// 清除公共事件属性
ge.clearSuperProperties();
```
### 获取公共属性 [#获取公共属性]
如果您想要获取所有公共事件属性，可以调用 `getSuperProperties()`：
```js
// 获取静态公共事件属性
ge.getSuperProperties();
```
## 3. 设置事件上报时间 [#3-设置事件上报时间]
事件触发的时间默认取本机时间，但在一些情况下，可能需要手动设置事件的时间，可以使用以下方法进行调用：
> **注意**
> **第三个参数为事件触发时间，必须是 `Date` 类型，将会替换事件触发的时间，如果不传该参数，则事件触发时间默认选取用户的本机时间**
```js
// 第三个参数可以输入 Date 类型的参数，替换事件触发时间
ge.track("event", { parakey: "paravalue" }, new Date());
// 如果没有 properties 需要上传，请传入一个空对象
ge.track("event", {}, new Date());
```
## 4. 记录事件时长 [#4-记录事件时长]
您可以调用 `timeEvent` 来开始计时，配置您想要计时的事件名称，当您上传该事件时，将会自动在您的事件属性中加入 `$event_duration` 这一属性来表示记录的时长，单位为秒。
```js
// 用户进入商品页面，开始计时，记录的事件为 "Enter_Shop"
ge.timeEvent("Enter_Shop");
// ...
// 上传事件，计时结束，"Enter_Shop" 这一事件中将会带有表示事件时长的属性 $event_duration
ge.track("Enter_Shop", { product_id: "A1354" });
```
## 5. 立即上报事件 [#5-立即上报事件]
如果需要立即上报缓存的事件，可以调用 `flush` 来上报所有缓存的事件。
```js
ge.flush()
```
# 用户属性上报
> 来源：https://help.gravity-engine.com/docs/client-sdk/mini-games/user-properties
> 说明如何使用 Gravity Engine 小游戏 SDK 设置、追加、累加和删除用户属性，并提供参数要求与调用示例。
本文档详细介绍了 SDK 提供的用户属性上报功能，帮助开发者高效地收集、更新和维护用户画像数据。
通过本功能，您可以：
* **全面记录用户特征**：存储用户基础信息（如昵称、性别）、行为偏好等关键数据
* **灵活更新用户画像**：支持覆盖、追加、数值计算等多种更新方式
* **构建精准用户模型**：通过属性组合分析，实现用户分群和个性化服务
> **注意**
> **如需上报自定义的用户属性，您必须先在[元数据](https://web.gravity-engine.com/#/manage/metadata/userProperty)中添加对应的用户属性，否则会上报失败！**
## 1. 设置用户属性 [#1-设置用户属性]
对于一般的用户属性，您可以调用 `userSet` 来进行设置，使用该接口上传的属性将会覆盖原有的属性值。
```js
// 设置用户属性，会员等级
ge.userSet({ vip_level: "钻石会员" });
```
> **注意**
> 属性格式要求与事件属性保持一致。
## 2. 初始化用户属性 [#2-初始化用户属性]
如果您要上传的用户属性只要设置一次，则可以调用 `userSetOnce` 来进行设置，当该属性之前已经有值的时候，将会忽略这条信息。
```js
// 以设置用户名为例，如果用户名已设置，则忽略本次设置
ge.userSetOnce({ user_name: "TestUser" });
```
> **注意**
> 属性格式要求与事件属性保持一致。
## 3. 累加用户属性 [#3-累加用户属性]
对于数值型的用户属性，可以调用 `userAdd` 进行累加操作。
```js
// 以付费为例，用户每次付费时调用此接口，则 total_revenue 字段每次会做累加付费金额的处理
ge.userAdd({ total_revenue: 50 });
```
> **注意**
> 设置的属性 key 为字符串，Value 只允许为数值。
## 4. 重置用户属性 [#4-重置用户属性]
当您要清空用户的某个用户属性值时，可以调用 `userUnset` 来对指定属性进行清空操作。
```js
// 清空指定 key 的用户属性值，即设置为 null
ge.userUnset("userPropertyKey");
```
> **注意**
> `userUnset` 的传入值为被清空属性的 Key 值。
## 5. 清空用户属性 [#5-清空用户属性]
如果您要删除某个用户，可以调用 `userDel` 将这名用户删除，您将无法再查询该名用户的用户属性，但该用户产生的事件仍然可以被查询到：
```js
ge.userDel();
```
## 6. 用户属性追加（Array） [#6-用户属性追加array]
您可以调用 `userAppend` 对 Array（List）类型的用户数据追加元素。
```js
ge.userAppend({ Movies: ["Interstellar", "The Negro Motorist Green Book"] });
```
## 7. 用户属性去重追加（Array） [#7-用户属性去重追加array]
`userUniqAppend` 用来对 Array（List）类型的用户数据**去重**追加元素。
```js
ge.userUniqAppend({
Movies: ["Interstellar", "The Negro Motorist Green Book"],
});
```
## 8. 用户属性取最大值 [#8-用户属性取最大值]
对于数值型的用户属性，可以使用 `userNumberMax` 用来比较数值大小，保存较大的。
```js
ge.userNumberMax({
ad_ecpm_max: 300,
});
```
## 9. 用户属性取最小值 [#9-用户属性取最小值]
对于数值型的用户属性，可以使用 `userNumberMin` 用来比较数值大小，保存较小的。
```js
ge.userNumberMin({
ad_ecpm_min: 17,
});
```
# 微信小游戏快速集成
> 来源：https://help.gravity-engine.com/docs/client-sdk/mini-games/wechat-quickstart
> 介绍 Gravity Engine 微信小游戏 SDK 的安装、初始化、用户注册与事件上报流程，并提供参数说明和调用示例。
本文档主要讲述 **原生微信小游戏** 接入 [引力引擎](https://gravity-engine.com/) 的技术接入方案，在开始接入前，建议您先阅读 [接入前准备](/docs/getting-started/overview)以了解接入必备的基础概念。
> **注意**
> 本接入方案仅适用于官方**原生微信小游戏**开发的项目。如果您使用的是其他游戏引擎（如 Unity、CocosCreator、Laya、Egret 等），请访问[引力引擎 SDK 总览页面](/docs/client-sdk/sdk-overview)选择对应的框架接入文档。
## 腾讯广告 SDK 集成说明 [#腾讯广告-sdk-集成说明]
自 **4.8.40** 版本起，引力**原生微信小游戏 SDK** 已集成**腾讯广告小游戏 SDK**，开发者可通过我们提供的方法上报相关事件。
> **重要说明**
> 按照《腾讯广告小游戏 SDK 集成》的步骤完成集成后，引力 SDK 会**自动上报**以下两个基础事件给腾讯：
>
> * REGISTER（用户注册）
> * RE\_ACTIVE（沉默唤起）
>
> 此外，**START\_APP（小游戏启动）事件**由腾讯 SDK **自动采集**（引力 SDK 初始化腾讯 SDK 时默认开启该功能）。
>
> 除以上事件外，其他所有事件（如付费、自定义行为等）均需**客户端手动调用**我们提供的方法进行上报。
>
> 点击查看详细集成文档：[腾讯广告小游戏 SDK 集成](/docs/client-sdk/mini-games/advanced/tencent-ads-integration)
## 1. 获取 AccessToken [#1-获取-accesstoken]
您可以在[设置-应用管理](https://web.gravity-engine.com/#/manage/appmanage)页面点击"查看参数"按钮获取当前应用的 AccessToken，请妥善保存避免泄露。
## 2. 配置并启动 SDK [#2-配置并启动-sdk]
开始接入工作之前，您需要先[下载 SDK](/docs/client-sdk/sdk-overview)。
将 `ge_mg_sdk_version.zip` 中的 `gravityengine.mg.wx.min.js` 导入工程，并初始化 SDK：
> **注意**
> **每次冷启动过程中，`GravityEngine` 的实例化方法 `new GravityEngine()` 与初始化方法 `setupAndStart()` 均只能被调用一次。`clientId` 参数必须在这两个方法的其中一个传入。**
```js
import GravityEngine from "./js/utils/gravityengine.mg.wx.min";
const config = {
accessToken: "your_access_token", // 项目通行证，在：网站后台-->设置-->应用列表中找到Access Token列 复制（首次使用可能需要先新增应用）
// clientId如果当前还无法获取，可以不传但是不能传空字符串，等后面获取之后通过setupAndStart设置
clientId: "your_client_id", // 用户唯一标识，如产品为小游戏，则必须填用户openid（注意，不是小游戏的APPID！！！）
name: "ge", // 全局变量名称, 默认为 gravityengine
//预设公共属性
presetSuperProperties:{
"testSuperKey":"testSuperValue"
}
};
const ge = new GravityEngine(config);
ge.setupAndStart();
```
> **注意**
> **无法自行获取 `openid`？** 没有自建后端时，可使用引力 SDK 内置的快捷获取方法，详见[快捷获取 openid](/docs/client-sdk/mini-games/advanced/quick-get-openid)。
> **注意**
> **配置项目合法域名：** 您需要将 `https://backend.gravity-engine.com` 和 `https://api.gravity-engine.com` 配置到开发者后台 request 合法域名列表中。
> **注意**
> **如果您是从低版本引力 SDK 升级到高版本的，请一定记得添加 `https://api.gravity-engine.com` 域名到合法域名列表中，否则将导致事件采集失效，影响您的使用！**
## 3. 初始化 [#3-初始化]
在用户可以获取到用户唯一 ID 时调用此方法，推荐首次启动时调用。
> **注意**
> 首次调用后，需要在 `initialize` 的 `then` 中才能继续调用其他事件上报的方法
>
> 初始化方法调用成功之后，后续冷启动可以不再调用，只需要正常启动 SDK 即可（多次调用也不会有问题，引力做了兼容）
### 方法示例 [#方法示例]
```js
ge.initialize({
name: "your_name",
version: 123,
openid: "your_openid",
enable_sync_attribution: false,
adData:{
"testAdKey":"testAdValue"
}
})
.then((res) => {
console.log("initialize success", res);
})
.catch((err) => {
console.log("initialize failed", err);
});
```
### 参数说明 [#参数说明]
| 参数名称 | 参数含义 | 参数类型 | 是否必传 |
| ------------------------- | -------------------------------------------------------------------------------------------- | ------- | ---- |
| name | 用户名或用户唯一 ID（可理解为业务中的昵称），如果不需要昵称，可以填默认值，但不可以传空字符串！ | string | 是 |
| version | 产品发布版本号，便于后续在引力后台过滤 | number | 是 |
| openid | 用户 openid | string | 是 |
| enable\_sync\_attribution | 是否开启同步获取归因信息（参考[同步归因](/docs/attribution/synchronous-attribution)文档）。在媒体点击下发延迟的情况下会影响归因，请谨慎开启 | boolean | 是 |
| channel | 当前用户来源渠道，对应用户细查中的：客户端渠道 | string | 否 |
| adData | 预设归因信息 | object | 否 |
## 4. 事件上报 [#4-事件上报]
### 4.1 业务注册事件上报 [#41-业务注册事件上报]
> **注意**
> **此功能仅适用于需要统计业务注册转化数据的场景。如果您的应用不需要追踪用户注册行为，可以跳过此事件接入。**
> **注意**
> 该方法可多次调用，每次调用都会上报一个用户注册事件（计算指标时会去重）
当用户完成应用内业务注册后，您可以调用 `registerEvent` 方法来上报用户注册事件(`$MPRegister`)给引力，引力会使用该事件统计指标：标准\_注册数
#### 调用示例 [#调用示例]
```js
ge.registerEvent();
```
### 4.2 付费事件上报 [#42-付费事件上报]
> **注意**
> **付费事件上报用于收入统计和分析，如您的应用不涉及内购或付费服务，则无需接入此事件。**
> **注意**
> 如果您需要通过后端 API 方式上报付费事件，请参考 [混合上报模式](/docs/client-sdk/hybrid-reporting) 来接入事件上报接口报送付费事件。
当用户发生付费行为时，需要调用 `payEvent` 方法记录用户付费事件，此事件非常重要，会影响买量和 ROI 统计，请务必重点测试！
#### 方法示例 [#方法示例-1]
```js
ge.payEvent(payAmount, payType, orderId, payReason, payMethod);
```
#### 参数说明 [#参数说明-1]
| 参数名称 | 参数含义 | 参数类型 | 是否必传 |
| --------- | ------------------------------------------------------------------------------------------------------------------------ | ------ | ---- |
| 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]
```js
ge.payEvent(300, "CNY", "your_order_id", "月卡", "支付宝");
```
### 4.3 广告观看事件上报 [#43-广告观看事件上报]
> **注意**
> **广告观看上报适用于广告变现类应用，若您的应用未集成广告模块，则无需接入此事件。**
> **注意**
> **微信小游戏产品需要参照 [微信广告变现实时统计](/docs/server-integration/mini-game-tokens/wechat-monetization-stats) 一文，检查是否正确配置微信 `access_token`，配置错误将无法正确获取微信小游戏广告变现数据！**
若您的产品内有广告变现，则需要在用户点击广告观看的同时上报用户广告观看事件给引力，建议在微信接口返回 `onClose` 回调后上报，不管 `isEnded` 是否为 true 都要上报（上报时机参考媒体[接口文档](https://developers.weixin.qq.com/minigame/dev/api/ad/RewardedVideoAd.onClose.html)）。具体上报代码参考如下：
#### 方法示例 [#方法示例-2]
```js
ge.miniGameAdShowEvent(adType, adUnitId, otherProperties)
```
#### 参数说明 [#参数说明-2]
| 参数名称 | 参数含义 | 参数类型 | 是否必传 |
| --------------- | ----------------------------------------------------------------------------------------------------------------------------- | ------ | ---- |
| 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 | 是 |
#### 调用示例 [#调用示例-2]
```js
ge.miniGameAdShowEvent("reward", "your_ad_unit_id", { custom_param: "12345" });
```
## 5. 接入验证 [#5-接入验证]
> **注意**
> **正式上线之前，请完成本节的校验，否则可能会导致买量上报异常！**
### 5.1 关键事件验证 [#51-关键事件验证]
在引力后台[事件流](https://web.gravity-engine.com/#/manage/metadata/eventFlow)界面开启**加载实时数据**，并在产品中触发以下几个事件。事件验收与排错：[接入验收与排错](/docs/getting-started/integration-checklist)
| 事件名 | 事件英文名 | 触发时机 | 采集方式 | 默认映射到媒体事件 | 备注 |
| ---- | ------------- | ---------- | ------------------------ | --------- | ----------------------- |
| 用户注册 | `$MPRegister` | 用户完成业务注册之后 | 调用 SDK 的**上报业务注册事件**方法采集 | 暂无 | 接入了**业务注册上报事件**的产品均需要校验 |
| 付费 | `$PayEvent` | 用户付费之后 | 调用 SDK 的**上报用户付费事件**方法采集 | 付费 | 接入了**付费事件上报事件**的产品均需要校验 |
| 广告展示 | `$AdShow` | 用户观看广告之后 | 调用 SDK 的**上报广告展示事件**方法采集 | 暂无 | 接入了**广告事件上报事件**的产品均需要校验 |
触发操作后，请在[事件流](https://web.gravity-engine.com/#/manage/metadata/eventFlow)界面中筛选测试用户的 Client ID，观察对应事件是否出现在实时入库页面。若事件数据正常显示，则说明接入成功；如出现于错误数据页面请根据页面错误提示进行排查；如未显示对应数据，请及时联系引力运营支持团队获取协助。
### 5.2 避免重复上报 [#52-避免重复上报]
上线前，请按媒体和事件核对回传来源（引力回传、媒体 SDK 自动采集、客户端手动上报、自有服务端 API），确认同一转化不会通过多条链路重复回传。需要切换到引力回传的事件，应在验证新链路正常后停用原有重复链路；媒体 SDK 的其他功能是否保留，请按对应集成文档确认。
> **注意**
> 至此验证无误之后，您可以正常上线了。
以上是 SDK 的基础接入指引。如需使用 **行为事件上报、用户属性上报、进阶功能、自动采集** 等功能，请参考以下文档：
> **注意**
> 这些功能并非所有业务场景都需要，请按需查阅。
* [行为事件上报](/docs/client-sdk/mini-games/track-events)
* [用户属性上报](/docs/client-sdk/mini-games/user-properties)
* [进阶功能](/docs/client-sdk/mini-games/advanced)
* [自动采集](/docs/client-sdk/mini-games/advanced/automatic-tracking)
# 其他开发框架
> 来源：https://help.gravity-engine.com/docs/client-sdk/other-frameworks
> 跨框架 SDK索引，汇总Taro快速集成、Uni-APP快速集成等主题，便于按功能进入对应的配置、接入或参考说明。
{/* Generated by scripts/generate-docs-routes.mjs. Do not edit. */}
## 目录 [#目录]
* [Taro快速集成](/docs/client-sdk/other-frameworks/taro-quickstart)
* [Uni-APP快速集成](/docs/client-sdk/other-frameworks/uni-app-quickstart)
* [行为事件上报](/docs/client-sdk/other-frameworks/track-events)
* [用户属性上报](/docs/client-sdk/other-frameworks/user-properties)
* [进阶功能](/docs/client-sdk/other-frameworks/advanced) — 子目录
# Taro快速集成
> 来源：https://help.gravity-engine.com/docs/client-sdk/other-frameworks/taro-quickstart
> 介绍 Gravity Engine Taro SDK 的安装、初始化、用户注册与事件上报流程，并提供参数说明和调用示例。
本文档主要讲述 **Taro** 接入 [引力引擎](https://gravity-engine.com/) 的技术接入方案，在开始接入前，建议您先阅读 [接入前准备](/docs/getting-started/overview) 以了解接入必备的基础概念。
> **注意**
> 本接入方案仅适用于 **Taro** 开发的项目。如果您使用的是其他开发框架，请访问 [引力引擎SDK总览页面](/docs/client-sdk/sdk-overview) 选择对应的框架接入文档。
## 支持平台 [#支持平台]
* 
微信小程序
* 
支付宝小程序
* 
字节小程序
* 
百度小程序
* 
QQ小程序
* 
京东小程序
## 1. 获取 AccessToken [#1-获取-accesstoken]
您可以在 [设置-应用管理](https://web.gravity-engine.com/#/manage/appmanage) 页面点击 **查看参数** 按钮获取当前应用的 AccessToken，请妥善保存避免泄露。
## 2. 配置并启动 SDK [#2-配置并启动-sdk]
开始接入工作之前，您需要先 [下载 SDK](/docs/client-sdk/sdk-overview)。
将 `ge_mp_sdk_version.zip` 中的 `gravityengine.taro.js` 导入工程，并初始化 SDK：
> **注意**
> **每次冷启动过程中，`GravityEngine` 的实例化方法 `new GravityAnalyticsAPI()` 与初始化方法 `setupAndStart()` 均只能被调用一次。`clientId` 参数必须在这两个方法的其中一个传入。**
```javascript
import GravityAnalyticsAPI from "./utils/gravityengine.taro.js";
const config = {
accessToken: "your_access_token", // 项目通行证，在：网站后台-->设置-->应用列表中找到Access Token列 复制（首次使用可能需要先新增应用）
clientId: "your_client_id", // 用户唯一标识，如产品为小游戏，则必须填用户openid（注意，不是小游戏的APPID！！！）
name: "ge",
// 预设公共属性
presetSuperProperties:{
"testSuperKey":"testSuperValue"
}
};
const ge = new GravityAnalyticsAPI(config);
ge.setupAndStart();
```
> **注意**
> **小程序项目需要配置项目合法域名：** 您需要将 `https://api.gravity-engine.com` 配置到开发者后台 request 合法域名列表中。
## 3. 初始化 [#3-初始化]
在用户可以获取到用户唯一 ID 时调用此方法，推荐首次启动时调用。
> **注意**
> 首次调用后，需要在 `initialize` 的 `then` 回调中才能继续调用其他事件上报的方法。
>
> 初始化方法调用成功之后，后续冷启动可以不再调用，只需要正常启动 SDK 即可（多次调用也不会有问题，引力做了兼容）。
### 3.1 方法示例 [#31-方法示例]
```javascript
ge.initialize({
name: "your_name",
version: 123,
openid: "your_openid",
enable_sync_attribution: false,
adData:{
"testAdKey":"testAdValue"
}
})
.then((res) => {
console.log("initialize success", res);
})
.catch((err) => {
console.log("initialize failed", err);
});
```
### 3.2 参数说明 [#32-参数说明]
| **参数名称** | **参数含义** | **参数类型** | **是否必传** |
| ------------------------- | ---------------------------------------------------------------------------------------------- | -------- | -------- |
| name | 用户名或用户唯一ID（可理解为业务中的昵称），如果不需要昵称，可以填：默认值，但是不可以传空字符串！ | string | 是 |
| version | 产品发布版本号，便于后续在引力后台过滤 | number | 是 |
| openid | 用户openid | string | 是 |
| enable\_sync\_attribution | 是否开启同步获取归因信息（参考 [同步归因](/docs/attribution/synchronous-attribution) 文档），在媒体点击下发延迟的情况下会影响归因，请谨慎开启 | boolean | 是 |
| channel | 当前用户来源渠道，对应用户细查中的：客户端渠道 | string | 否 |
| adData | 预设归因信息 | object | 否 |
## 4. 事件上报 [#4-事件上报]
### 4.1 业务注册事件上报 [#41-业务注册事件上报]
> **注意**
> **此功能仅适用于需要统计业务注册转化数据的场景。如果您的应用不需要追踪用户注册行为，可以跳过此事件接入。**
> **注意**
> 该方法可多次调用，每次调用都会上报一个用户注册事件（计算指标时会去重）。
当用户完成应用内业务注册后，您可以调用 `registerEvent` 方法来上报用户注册事件（`$MPRegister`）给引力，引力会使用该事件统计指标：标准\_注册数。
#### 调用示例 [#调用示例]
```javascript
ge.registerEvent();
```
### 4.2 付费事件上报 [#42-付费事件上报]
> **注意**
> **付费事件上报用于收入统计和分析，如您的应用不涉及内购或付费服务，则无需接入此事件。**
> **注意**
> 如果您需要通过后端 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", "月卡", "支付宝");
```
### 4.3 广告观看事件上报 [#43-广告观看事件上报]
> **注意**
> **广告观看上报适用于广告变现类应用，若您的应用未集成广告模块，则无需接入此事件。**
> **注意**
> **抖音小游戏、快手小游戏、B站小游戏无需接入，会由引力后端自动拉取，具体配置，请参考[这里](https://gravityengine.feishu.cn/wiki/SBsxwmeb5iNrPKkUtzCcmisXnzd#OwM8doB35oKDTrxsHKkcvr9Bnqe)**
若您的产品内有广告变现，则需要在用户点击广告观看的同时上报用户广告观看事件给引力，具体参考如下：
#### 方法示例 [#方法示例-1]
```javascript
ge.miniGameAdShowEvent(adType, adUnitId, otherProperties);
```
#### 参数说明 [#参数说明-1]
为生成准确的广告收益分析报表，请尽量遵循规范填写下方的广告平台参数。正确的字段是生成有价值报表的基础。
我们为您准备了详细的指引：👉 [广告聚合平台字段配置说明](/docs/appendix/ad-mediation-fields)
| **参数名称** | **参数含义** | **参数类型** | **是否必传** |
| --------------- | ------------------------------------------------------------------------------------------------------------------------- | -------- | -------- |
| adType | 广告类型（取值为：reward(激励视频广告)、banner(横幅广告)、native(信息流广告)、interstitial(插屏广告)、splash(开屏广告)、video\_feed(视频信息流)、video\_begin(贴片广告)） | string | 是 |
| adUnitId | 广告位ID。一般以 adunit 开头，注意不要填错 | string | 是 |
| otherProperties | 自定义参数。其他需要携带的自定义参数，需要提前在引力后台元数据中针对 AdShow 事件配置好属性 | object | 是 |
#### 调用示例 [#调用示例-2]
```javascript
ge.miniGameAdShowEvent("reward", "your_ad_unit_id", { custom_param: "12345" });
```
## 5. 接入验证 [#5-接入验证]
> **注意**
> **正式上线之前，请完成本节的校验，否则可能会导致买量上报异常！**
### 5.1 关键事件验证 [#51-关键事件验证]
在引力后台[事件流](https://web.gravity-engine.com/#/manage/metadata/eventFlow) 界面开启**加载实时数据**，并在产品中触发以下几个事件。事件验收与排错：[接入验收与排错](/docs/getting-started/integration-checklist)
| 事件名 | 事件英文名 | 触发时机 | 采集方式 | 默认映射到媒体事件 | 备注 |
| ---- | ------------- | ---------- | ---------------------- | --------- | ----------------------- |
| 用户注册 | `$MPRegister` | 用户完成业务注册之后 | 调用SDK的**上报业务注册事件**方法采集 | 暂无 | 接入了**业务注册上报事件**的产品均需要校验 |
| 付费 | `$PayEvent` | 用户付费之后 | 调用SDK的**上报用户付费事件**方法采集 | 付费 | 接入了**付费事件上报事件**的产品均需要校验 |
| 广告展示 | `$AdShow` | 用户观看广告之后 | 调用SDK的**上报广告展示事件**方法采集 | 暂无 | 接入了**广告事件上报事件**的产品均需要校验 |
触发操作后，请在[事件流](https://web.gravity-engine.com/#/manage/metadata/eventFlow) 界面中筛选测试用户的 Client ID，观察对应事件是否出现在实时入库页面。若事件数据正常显示，则说明接入成功；如出现于错误数据页面请根据页面错误提示进行排查；如未显示对应数据，请及时联系引力运营支持团队获取协助。
### 5.2 避免重复上报 [#52-避免重复上报]
上线前，请按媒体和事件核对回传来源（引力回传、媒体 SDK 自动采集、客户端手动上报、自有服务端 API），确认同一转化不会通过多条链路重复回传。需要切换到引力回传的事件，应在验证新链路正常后停用原有重复链路；媒体 SDK 的其他功能是否保留，请按对应集成文档确认。
> **注意**
> 至此验证无误之后，您可以正常上线了。
# 行为事件上报
> 来源：https://help.gravity-engine.com/docs/client-sdk/other-frameworks/track-events
> 说明如何使用 Gravity Engine 跨框架 SDK 上报业务事件，并管理事件公共属性。
本文档详细介绍了SDK提供的事件上报功能，帮助开发者全面采集用户行为事件数据，为业务分析和运营决策提供数据支持。
通过上报应用内用户行为事件，您可以：
* **完整记录用户行为**：追踪用户在应用内的关键操作路径
* **支持多维度分析**：通过事件属性丰富分析维度
* **构建数据闭环**：为产品优化和精准运营提供数据基础
## 1. 上报自定义事件 [#1-上报自定义事件]
> **注意**
> **如需上报自定义事件，您必须先在[元事件](https://web.gravity-engine.com/#/manage/metadata/metaEvent)中添加，否则会上报失败！**
您可以直接调用 `track` 上传自定义事件，建议您根据准备阶段梳理的文档来设置事件的属性以及发送信息的条件，此处以购买商品为范例：
```javascript
ge.track(
"$purchase", // 追踪事件的名称
{
Item: "商品A",
ItemNum: 1,
Cost: 100,
Elements: ["apple", "ball", "cat"],
} // 需要上传的事件属性
);
```
* `track` 接口共有两个参数，第一个参数为事件的名称，第二个参数为事件的属性。
* 事件的名称是字符串，只能以字母开头，可包含数字、字母和下划线 "\_"，长度最大为 50 个字符。
* 事件的属性是 JS 对象，每个元素代表一个属性。
* 元素的 name 对应属性的名称，规定只能以字母开头，包含数字、字母和下划线 "\_"，长度最大为 50 个字符。
* 元素的 Value 为该属性的值，支持 `String`、`Integer`、`Float`、`Boolean`、`Date`、`DateTime` 和 `Array`；`Array` 中的内容可以为 `String`。
## 2. 公共属性 [#2-公共属性]
> **注意**
> **公共属性需要先在[事件属性](https://web.gravity-engine.com/#/manage/metadata/eventProperty)中添加，否则会上报失败!**
公共事件属性是所有事件（包括自动采集事件）都会包含的属性，用户属性中不会包含。
本节会介绍如何设置公共事件属性和动态公共属性。如果公共属性与事件中设置的自定义属性有相同 key 值，则最终的属性会根据下述优先级取值：
用户自定义事件属性 > 动态公共属性 > 事件公共属性
您可以调用 `setSuperProperties` 来设置公共事件属性，公共事件属性的格式要求与事件属性一致。在设置时只能传入常量，适合设置变化不频繁的属性。
根据属性优先级，自定义属性优先级高于事件公共属性，因此事件公共属性也可以作为某个属性的缺省值，在需要修改的事件中设置同名 Key 覆盖缺省值。
### 2.1 设置公共属性 [#21-设置公共属性]
```javascript
// 设置公共事件属性
ge.setSuperProperties({ channel: "渠道" });
// 使用 track 上传事件，此时事件中会带有公共事件属性
ge.track(
"Purchase", // 追踪事件的名称
{
Item: "商品A",
ItemNum: 1,
Cost: 100,
} // 需要上传的事件属性
);
/* 等价于在事件中加入这些公共属性
ge.track(
'Purchase', // 追踪事件的名称
{
Item:'商品A',
ItemNum:1,
Cost:100,
channel:'渠道' // 相当于在事件中加入这个属性
}
);
*/
```
如果多次调用 `setSuperProperties` 设置公共事件属性，则同名字段后面的调用会覆盖之前的同名字段。
### 2.2 删除公共属性 [#22-删除公共属性]
如果您需要删除某个公共事件属性，可以调用 `unsetSuperProperty()` 清除其中一个公共事件属性。
```javascript
// 清除属性名为 CHANNEL 的公共属性
ge.unsetSuperProperty("CHANNEL");
```
### 2.3 清空公共属性 [#23-清空公共属性]
如果您想要清空所有公共事件属性，则可以调用 `clearSuperProperties()`。
```javascript
// 清除公共事件属性
ge.clearSuperProperties();
```
### 2.4 获取公共属性 [#24-获取公共属性]
如果您想要获取所有公共事件属性，可以调用 `getSuperProperties`。
```javascript
// 获取静态公共事件属性
ge.getSuperProperties();
```
## 3. 设置事件上报时间 [#3-设置事件上报时间]
事件触发的时间默认取本机时间，但在一些情况下，可能需要手动设置事件的时间，可以使用以下方法进行调用：
> **注意**
> **第三个参数为事件触发时间，必须是 Date 类型，将会替换事件触发的时间，如果不传该参数，则事件触发时间默认选取用户的本机时间。**
```javascript
// 第三个参数可以输入 Date 类型的参数，替换事件触发时间
ge.track("event", { parakey: "paravalue" }, new Date());
// 如果没有 properties 需要上传，请传入一个空对象
ge.track("event", {}, new Date());
```
## 4. 记录事件时长 [#4-记录事件时长]
您可以调用 `timeEvent` 来开始计时，配置您想要计时的事件名称，当您上传该事件时，将会自动在您的事件属性中加入 `$event_duration` 这一属性来表示记录的时长，单位为秒。
```javascript
// 用户进入商品页面，开始计时，记录的事件为 "Enter_Shop"
ge.timeEvent("Enter_Shop");
// ...
// 上传事件，计时结束，"Enter_Shop" 这一事件中将会带有表示事件时长的属性 $event_duration
ge.track("Enter_Shop", { product_id: "A1354" });
```
## 5. 立即上报事件 [#5-立即上报事件]
如果需要立即上报缓存的事件，可以调用 `flush` 来上报所有缓存的事件。
```javascript
ge.flush();
```
# Uni-APP快速集成
> 来源：https://help.gravity-engine.com/docs/client-sdk/other-frameworks/uni-app-quickstart
> 介绍 Gravity Engine Uni-APP SDK 的安装、初始化、用户注册与事件上报流程，并提供参数说明和调用示例。
本文档主要讲述 **Uni-APP** 接入 [引力引擎](https://gravity-engine.com/) 的技术接入方案，在开始接入前，建议您先阅读 [接入前准备](/docs/getting-started/overview) 以了解接入必备的基础概念。
> **注意**
> 本接入方案仅适用于 **Uni-APP** 开发的项目。如果您使用的是其他开发框架，请访问 [引力引擎SDK总览页面](/docs/client-sdk/sdk-overview) 选择对应的框架接入文档。
## 支持平台 [#支持平台]
* 
微信小程序
* 
支付宝小程序
* 
字节小程序
* 
百度小程序
* 
360小程序
* 
快手小程序
* 
QQ小程序
* 
京东小程序
* 
Android
* 
iOS
## 1. 获取 AccessToken [#1-获取-accesstoken]
您可以在 [设置-应用管理](https://web.gravity-engine.com/#/manage/appmanage) 页面点击 **查看参数** 按钮获取当前应用的 AccessToken，请妥善保存避免泄露。
## 2. Native 平台支持 [#2-native-平台支持]
如果您的 Uni-APP 项目需要支持 Android/iOS 原生平台，请分别在 Uni-APP 导出的原生工程中完成对应平台的 SDK 集成，切换下方标签按平台查看：
**Android**
### 接入 Android SDK [#接入-android-sdk]
在 Uni-APP 导出的 Android 项目里，集成 Android 版本的 GravityEngineSDK 即可，参考 [Android 接入文档](/docs/client-sdk/android/quickstart)。
**iOS**
### 接入 iOS SDK [#接入-ios-sdk]
在 Uni-APP 导出的 iOS 项目里集成 iOS 版本的 GravityEngineSDK，参考 [iOS 接入文档](/docs/client-sdk/ios/quickstart)。
## 3. 配置并启动 SDK [#3-配置并启动-sdk]
开始接入工作之前，您需要先 [下载 SDK](/docs/client-sdk/sdk-overview)。
将 `ge_mp_sdk_version.zip` 中的 `gravityengine.uniapp.js` 导入工程，并初始化 SDK：
> **注意**
> **每次冷启动过程中，`GravityEngine` 的实例化方法 `new GravityAnalyticsAPI()` 与初始化方法 `setupAndStart()` 均只能被调用一次。`clientId` 参数必须在这两个方法的其中一个传入。**
```javascript
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();
```
> **注意**
> 通过 **非自建中台** 的方式导入历史用户到引力时，默认以 Android\_ID 作为 `clientID`。SDK 需将 `mClientIdPriorityOrder` 设为 **Android\_ID 优先**（如 `["ANDROID_ID","OAID"]`），与导入规则保持一致，否则同一设备会被算作两个用户。
> **注意**
> **小程序项目需要配置项目合法域名：** 您需要将 `https://api.gravity-engine.com` 配置到开发者后台 request 合法域名列表中。
## 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)
若您的产品内有广告变现，则需要在用户点击广告观看的同时上报用户广告观看事件给引力，具体参考如下：
**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 | 建议填写 |
**小游戏**
```javascript
ge.miniGameAdShowEvent(adType, adUnitId, 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 | 是 |
## 6. 接入验证 [#6-接入验证]
> **注意**
> **正式上线之前，请完成本节的校验，否则可能会导致买量上报异常！**
### 6.1 关键事件验证 [#61-关键事件验证]
在引力后台[事件流](https://web.gravity-engine.com/#/manage/metadata/eventFlow) 界面开启**加载实时数据**，并在产品中触发以下几个事件。事件验收与排错：[接入验收与排错](/docs/getting-started/integration-checklist)
| 事件名 | 事件英文名 | 触发时机 | 采集方式 | 默认映射到媒体事件 | 备注 |
| ---- | ----------------------------------------- | ---------- | ---------------------- | --------- | ----------------------- |
| 用户注册 | APP:`$AppRegister`
小游戏:`$MPRegister` | 用户完成业务注册之后 | 调用SDK的**上报业务注册事件**方法采集 | 暂无 | 接入了**业务注册上报事件**的产品均需要校验 |
| 付费 | `$PayEvent` | 用户付费之后 | 调用SDK的**上报用户付费事件**方法采集 | 付费 | 接入了**付费事件上报事件**的产品均需要校验 |
| 广告展示 | `$AdShow` | 用户观看广告之后 | 调用SDK的**上报广告展示事件**方法采集 | 暂无 | 接入了**广告事件上报事件**的产品均需要校验 |
触发操作后，请在[事件流](https://web.gravity-engine.com/#/manage/metadata/eventFlow) 界面中筛选测试用户的 Client ID，观察对应事件是否出现在实时入库页面。若事件数据正常显示，则说明接入成功；如出现于错误数据页面请根据页面错误提示进行排查；如未显示对应数据，请及时联系引力运营支持团队获取协助。
### 6.2 避免重复上报 [#62-避免重复上报]
上线前，请按媒体和事件核对回传来源（引力回传、媒体 SDK 自动采集、客户端手动上报、自有服务端 API），确认同一转化不会通过多条链路重复回传。需要切换到引力回传的事件，应在验证新链路正常后停用原有重复链路；媒体 SDK 的其他功能是否保留，请按对应集成文档确认。
> **注意**
> 至此验证无误之后，您可以正常上线了。
# 用户属性上报
> 来源：https://help.gravity-engine.com/docs/client-sdk/other-frameworks/user-properties
> 说明如何使用 Gravity Engine 跨框架 SDK 设置、追加、累加和删除用户属性，并提供参数要求与调用示例。
本文档详细介绍了SDK提供的用户属性上报功能，帮助开发者高效地收集、更新和维护用户画像数据。
通过本功能，您可以：
* **全面记录用户特征**：存储用户基础信息（如昵称、性别）、行为偏好等关键数据
* **灵活更新用户画像**：支持覆盖、追加、数值计算等多种更新方式
* **构建精准用户模型**：通过属性组合分析，实现用户分群和个性化服务
> **注意**
> **如需上报自定义的用户属性，您必须先在[元数据](https://web.gravity-engine.com/#/manage/metadata/userProperty)中添加对应的用户属性，否则会上报失败！**
## 1. 设置用户属性 [#1-设置用户属性]
对于一般的用户属性，您可以调用 `userSet` 来进行设置，使用该接口上传的属性将会覆盖原有的属性值。
```javascript
// 设置用户属性，会员等级
ge.userSet({ vip_level: "钻石会员" });
```
> **注意**
> 属性格式要求与事件属性保持一致。
## 2. 初始化用户属性 [#2-初始化用户属性]
如果您要上传的用户属性只要设置一次，则可以调用 `userSetOnce` 来进行设置，当该属性之前已经有值的时候，将会忽略这条信息。
```javascript
// 以设置用户名为例，如果用户名已设置，则忽略本次设置
ge.userSetOnce({ user_name: "TestUser" });
```
> **注意**
> 属性格式要求与事件属性保持一致。
## 3. 累加用户属性 [#3-累加用户属性]
当您要上传数值型的属性时，您可以调用 `userAdd` 来对该属性进行累加操作。
```javascript
// 以付费为例，用户每次付费时调用此接口，则 'total_revenue' 字段每次会做累加付费金额的处理
ge.userAdd({ total_revenue: 50 });
```
> **注意**
> 设置的属性 key 为字符串，Value 只允许为数值。
## 4. 重置用户属性 [#4-重置用户属性]
当您要清空用户的某个用户属性值时，您可以调用 `userUnset` 来对指定属性进行清空操作。
```javascript
// 清空属性名为 userPropertyKey 的用户属性值，即设置为 NULL
ge.userUnset("userPropertyKey");
```
> **注意**
> `userUnset` 的传入值为被清空属性的 Key 值。
## 5. 清空用户属性 [#5-清空用户属性]
如果您要删除某个用户，可以调用 `userDel` 将这名用户删除，您将无法再查询该名用户的用户属性，但该用户产生的事件仍然可以被查询到。
```javascript
ge.userDel();
```
## 6. 用户属性追加（Array） [#6-用户属性追加array]
您可以调用 `userAppend` 对 Array (List) 类型的用户数据追加元素。
```javascript
ge.userAppend({ Movies: ["Interstellar", "The Negro Motorist Green Book"] });
```
## 7. 用户属性去重追加（Array） [#7-用户属性去重追加array]
`userUniqAppend` 用来对 Array (List) 类型的用户数据**去重**追加元素。
```javascript
ge.userUniqAppend({
Movies: ["Interstellar", "The Negro Motorist Green Book"],
});
```
## 8. 用户属性取最大值 [#8-用户属性取最大值]
`userNumberMax` 用来比较数值大小，保存较大的。
```javascript
ge.userNumberMax({
ad_ecpm_max: 300,
});
```
## 9. 用户属性取最小值 [#9-用户属性取最小值]
`userNumberMin` 用来比较数值大小，保存较小的。
```javascript
ge.userNumberMin({
ad_ecpm_min: 17,
});
```
# 快应用
> 来源：https://help.gravity-engine.com/docs/client-sdk/quick-apps
> 快应用 SDK索引，汇总快应用快速集成、行为事件上报等主题，便于按功能进入对应的配置、接入或参考说明。
{/* Generated by scripts/generate-docs-routes.mjs. Do not edit. */}
## 目录 [#目录]
* [快应用快速集成](/docs/client-sdk/quick-apps/quickstart)
* [行为事件上报](/docs/client-sdk/quick-apps/track-events)
* [用户属性上报](/docs/client-sdk/quick-apps/user-properties)
* [进阶功能](/docs/client-sdk/quick-apps/advanced) — 子目录
# 快应用快速集成
> 来源：https://help.gravity-engine.com/docs/client-sdk/quick-apps/quickstart
> 介绍 Gravity Engine 快应用 SDK 的安装、初始化、用户注册与事件上报流程，并提供参数说明和调用示例。
本文档主要讲述 **原生快应用** 接入 [引力引擎](https://gravity-engine.com/) 的技术接入方案，在开始接入前，建议您先阅读 [接入前准备](/docs/getting-started/overview) 以了解接入必备的基础概念。
> **注意**
> 本接入方案仅适用于官方 **原生快应用** 开发的项目。如果您使用的是其他开发框架（如 Taro、uni-app 等），请访问 [引力引擎 SDK 总览页面](/docs/client-sdk/sdk-overview) 选择对应的框架接入文档。
## 1. 获取 AccessToken [#1-获取-accesstoken]
您可以在[设置-应用管理](https://web.gravity-engine.com/#/manage/appmanage)页面点击“查看参数”按钮获取当前应用的 AccessToken，请妥善保存避免泄露。
## 2. 配置并启动 SDK [#2-配置并启动-sdk]
开始接入工作之前，您需要先[下载 SDK](/docs/client-sdk/sdk-overview)。
将 `ge_mp_sdk_version.zip` 中的 `gravityengine.quick.min.js` 文件导入快应用项目中：
```js
import GravityEngine from "./helper/gravityengine.quick.min";
```
引入 SDK 后，即可进行 SDK 初始化参数配置：
```js
const config = {
accessToken: "your_access_token", // 项目通行证，在：网站后台-->设置-->应用列表中找到Access Token列 复制（首次使用可能需要先新增应用）
clientId: "your_client_id", // 用户唯一标识
gravityQuery: {}, // 从 onInit 方法中提取的启动参数，巨量线索归因会依赖此参数的传入，正确传入能极大提升归因率，建议传入
//预设公共属性
presetSuperProperties:{
"testSuperKey":"testSuperValue"
}
};
const ge = new GravityEngine(config);
ge.setupAndStart();
```
> **注意**
> **由于快应用获取启动参数必须放在 onInit 函数调用中，引力 SDK 无法自动采集，故需要您采集之后手动传入到 `gravityQuery`，采集方式如下图：**
## 3. 初始化 [#3-初始化]
在用户可以获取到用户唯一 ID 时调用此方法，推荐首次启动时调用。
> **注意**
> 首次调用后，需要在 `initialize` 的 `then` 中才能继续调用其他事件上报的方法
>
> 初始化方法调用成功之后，后续冷启动可以不再调用，只需要正常启动 SDK 即可（多次调用也不会有问题，引力做了兼容）
### 方法示例 [#方法示例]
```js
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 | 是否开启同步获取归因信息（参考[同步归因](/docs/attribution/synchronous-attribution)文档）。在媒体点击下发延迟的情况下会影响归因，请谨慎开启 | boolean | 是 |
| channel | 当前用户来源渠道，对应用户细查中的：客户端渠道 | string | 否 |
| adData | 预设归因信息 | object | 否 |
## 4. 事件上报 [#4-事件上报]
### 4.1 业务注册事件上报 [#41-业务注册事件上报]
> **注意**
> **此功能仅适用于需要统计业务注册转化数据的场景。如果您的应用不需要追踪用户注册行为，可以跳过此事件接入。**
> **注意**
> 该方法可多次调用，每次调用都会上报一个用户注册事件（计算指标时会去重）
当用户完成应用内业务注册后，您可以调用 `registerEvent` 方法来上报用户注册事件（`$AppRegister`）给引力，引力会使用该事件统计指标：标准\_注册数
#### 调用示例 [#调用示例]
```js
ge.registerEvent();
```
### 4.2 付费事件上报 [#42-付费事件上报]
> **注意**
> **付费事件上报用于收入统计和分析，如您的应用不涉及内购或付费服务，则无需接入此事件。**
> **注意**
> 如果您需要通过后端 API 方式上报付费事件，请参考 [混合上报模式](/docs/client-sdk/hybrid-reporting) 来接入事件上报接口报送付费事件。
当用户发生付费行为时，需要调用 `payEvent` 方法记录用户付费事件，此事件非常重要，会影响买量和 ROI 统计，请务必重点测试！
#### 方法示例 [#方法示例-1]
```js
ge.payEvent(payAmount, payType, orderId, payReason, payMethod);
```
#### 参数说明 [#参数说明-1]
| 参数名称 | 参数含义 | 参数类型 | 是否必传 |
| --------- | ------------------------------------------------------------------------------------------------------------------------ | ------ | ---- |
| 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]
```js
ge.payEvent(300, "CNY", "your_order_id", "月卡", "支付宝");
```
### 4.3 广告观看事件上报 [#43-广告观看事件上报]
> **注意**
> **广告观看上报适用于广告变现类应用，若您的应用未集成广告模块，则无需接入此事件。**
若您的产品内有广告变现，则需要在用户点击广告观看的同时上报用户广告观看事件给引力，具体参考如下：
#### 方法示例 [#方法示例-2]
```js
ge.miniGameAdShowEvent(adType, adUnitId, otherProperties);
```
#### 参数说明 [#参数说明-2]
为生成准确的广告收益分析报表，请尽量遵循规范填写下方的广告平台参数。正确的字段是生成有价值报表的基础。
我们为您准备了详细的指引：[广告聚合平台字段配置说明](/docs/appendix/ad-mediation-fields)
| 参数名称 | 参数含义 | 参数类型 | 是否必传 |
| --------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------ | ---- |
| 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）事件配置好相关属性，比如快应用上报广告 ecpm，可以使用引力预置好的属性字段：$ecpm，具体见下发代码示例。 | object | 是 |
#### 调用示例 [#调用示例-2]
```js
ge.miniGameAdShowEvent("reward", "your_ad_unit_id", { custom_param: "12345" });
// 如果需要上报当次广告曝光的 ECPM，代码示例如下
ge.miniGameAdShowEvent("reward", "your_ad_unit_id", { $ecpm: 1000 });
```
## 5. 接入验证 [#5-接入验证]
> **注意**
> **正式上线之前，请完成本节的校验，否则可能会导致买量上报异常！**
### 5.1 关键事件验证 [#51-关键事件验证]
在引力后台[事件流](https://web.gravity-engine.com/#/manage/metadata/eventFlow)界面开启**加载实时数据**，并在产品中触发以下几个事件。事件验收与排错：[接入验收与排错](/docs/getting-started/integration-checklist)
| 事件名 | 事件英文名 | 触发时机 | 采集方式 | 默认映射到媒体事件 | 备注 |
| ---- | -------------- | ---------- | ------------------------ | --------- | ----------------------- |
| 用户注册 | `$AppRegister` | 用户完成业务注册之后 | 调用 SDK 的**上报业务注册事件**方法采集 | 暂无 | 接入了**业务注册上报事件**的产品均需要校验 |
| 付费 | `$PayEvent` | 用户付费之后 | 调用 SDK 的**上报用户付费事件**方法采集 | 付费 | 接入了**付费事件上报事件**的产品均需要校验 |
| 广告展示 | `$AdShow` | 用户观看广告之后 | 调用 SDK 的**上报广告展示事件**方法采集 | 暂无 | 接入了**广告事件上报事件**的产品均需要校验 |
触发操作后，请在[事件流](https://web.gravity-engine.com/#/manage/metadata/eventFlow)界面中筛选测试用户的 Client ID，观察对应事件是否出现在实时入库页面。若事件数据正常显示，则说明接入成功；如出现于错误数据页面请根据页面错误提示进行排查；如未显示对应数据，请及时联系引力运营支持团队获取协助。
### 5.2 避免重复上报 [#52-避免重复上报]
上线前，请按媒体和事件核对回传来源（引力回传、媒体 SDK 自动采集、客户端手动上报、自有服务端 API），确认同一转化不会通过多条链路重复回传。需要切换到引力回传的事件，应在验证新链路正常后停用原有重复链路；媒体 SDK 的其他功能是否保留，请按对应集成文档确认。
> **注意**
> 至此验证无误之后，您可以正常上线了。
以上是 SDK 的基础接入指引。如需使用 **行为事件上报、用户属性上报、进阶功能、自动采集** 等功能，请参考以下文档：
> **注意**
> 这些功能并非所有业务场景都需要，请按需查阅。
* [行为事件上报](/docs/client-sdk/quick-apps/track-events)
* [用户属性上报](/docs/client-sdk/quick-apps/user-properties)
* [进阶功能](/docs/client-sdk/quick-apps/advanced)
* [自动采集](/docs/client-sdk/quick-apps/advanced/automatic-tracking)
# 行为事件上报
> 来源：https://help.gravity-engine.com/docs/client-sdk/quick-apps/track-events
> 说明如何使用 Gravity Engine 快应用 SDK 上报业务事件，并管理事件公共属性。
本文档详细介绍了 SDK 提供的事件上报功能，帮助开发者全面采集用户行为事件数据，为业务分析和运营决策提供数据支持。
通过上报应用内用户行为事件，您可以：
* **完整记录用户行为**：追踪用户在应用内的关键操作路径
* **支持多维度分析**：通过事件属性丰富分析维度
* **构建数据闭环**：为产品优化和精准运营提供数据基础
## 1. 自定义事件上报 [#1-自定义事件上报]
> **注意**
> **如需上报自定义事件，您必须先在[元事件](https://web.gravity-engine.com/#/manage/metadata/metaEvent)中添加，否则会上报失败！**
您可以直接调用 `track` 上传自定义事件，建议您根据准备阶段梳理的文档来设置事件的属性以及发送信息的条件，此处以购买商品为范例：
```js
ge.track(
"$purchase", // 追踪事件的名称
{
Item: "商品A",
ItemNum: 1,
Cost: 100,
Elements: ["apple", "ball", "cat"],
} // 需要上传的事件属性
);
```
* `track` 接口共有两个参数，第一个参数为事件的名称，第二个参数为事件的属性。
* 事件的名称是字符串，只能以字母开头，可包含数字、字母和下划线（\_），长度最大为 50 个字符。
* 事件的属性是 JS 对象，每个元素代表一个属性。
* 元素的 name 对应属性的名称，规定只能以字母开头，包含数字、字母和下划线（\_），长度最大为 50 个字符。
* 元素的 Value 为该属性的值，支持 `String`、`Integer`、`Float`、`Boolean`、`Date`、`DateTime` 和 `Array`；`Array` 中的内容可以为 `String`。
## 2. 公共属性 [#2-公共属性]
> **注意**
> **公共属性需要先在[事件属性](https://web.gravity-engine.com/#/manage/metadata/eventProperty)中添加，否则会上报失败！**
公共事件属性是所有事件（包括自动采集事件）都会包含的属性，用户属性中不会包含。
本节会介绍如何设置公共事件属性和动态公共属性。如果公共属性与事件中设置的自定义属性有相同 key 值，则最终的属性会根据下述优先级取值：
用户自定义事件属性 > 动态公共属性 > 事件公共属性
您可以调用 `setSuperProperties` 来设置公共事件属性，公共事件属性的格式要求与事件属性一致。在设置时只能传入常量，适合设置变化不频繁的属性。
根据属性优先级，自定义属性优先级高于事件公共属性，因此事件公共属性也可以作为某个属性的缺省值，在需要修改的事件中设置同名 Key 覆盖缺省值。
### 设置公共属性 [#设置公共属性]
```js
// 设置公共事件属性
ge.setSuperProperties({ channel: "渠道" });
// 使用 track 上传事件，此时事件中会带有公共事件属性
ge.track(
"Purchase", // 追踪事件的名称
{
Item: "商品A",
ItemNum: 1,
Cost: 100,
} // 需要上传的事件属性
);
/* 等价于在事件中加入这些公共属性
ge.track(
"Purchase", // 追踪事件的名称
{
Item: "商品A",
ItemNum: 1,
Cost: 100,
channel: "渠道" // 相当于在事件中加入这个属性
}
);
*/
```
如果多次调用 `setSuperProperties` 设置公共事件属性，则同名字段后面的调用会覆盖之前的同名字段。
### 删除公共属性 [#删除公共属性]
如果您需要删除某个公共事件属性，可以调用 `unsetSuperProperty()` 清除其中一个公共事件属性：
```js
// 清除属性名为 CHANNEL 的公共属性
ge.unsetSuperProperty("CHANNEL");
```
### 清空公共属性 [#清空公共属性]
如果您想要清空所有公共事件属性，则可以调用 `clearSuperProperties()`：
```js
// 清除公共事件属性
ge.clearSuperProperties();
```
### 获取公共属性 [#获取公共属性]
如果您想要获取所有公共事件属性，可以调用 `getSuperProperties()`：
```js
// 获取静态公共事件属性
ge.getSuperProperties();
```
## 3. 设置事件上报时间 [#3-设置事件上报时间]
事件触发的时间默认取本机时间，但在一些情况下，可能需要手动设置事件的时间，可以使用以下方法进行调用：
> **注意**
> **第三个参数为事件触发时间，必须是 `Date` 类型，将会替换事件触发的时间，如果不传该参数，则事件触发时间默认选取用户的本机时间**
```js
// 第三个参数可以输入 Date 类型的参数，替换事件触发时间
ge.track("event", { parakey: "paravalue" }, new Date());
// 如果没有 properties 需要上传，请传入一个空对象
ge.track("event", {}, new Date());
```
## 4. 记录事件时长 [#4-记录事件时长]
您可以调用 `timeEvent` 来开始计时，配置您想要计时的事件名称，当您上传该事件时，将会自动在您的事件属性中加入 `$event_duration` 这一属性来表示记录的时长，单位为秒。
```js
// 用户进入商品页面，开始计时，记录的事件为 "Enter_Shop"
ge.timeEvent("Enter_Shop");
// ...
// 上传事件，计时结束，"Enter_Shop" 这一事件中将会带有表示事件时长的属性 $event_duration
ge.track("Enter_Shop", { product_id: "A1354" });
```
## 5. 立即上报事件 [#5-立即上报事件]
如果需要立即上报缓存的事件，可以调用 `flush` 来上报所有缓存的事件。
```js
ge.flush()
```
# 用户属性上报
> 来源：https://help.gravity-engine.com/docs/client-sdk/quick-apps/user-properties
> 说明如何使用 Gravity Engine 快应用 SDK 设置、追加、累加和删除用户属性，并提供参数要求与调用示例。
本文档详细介绍了 SDK 提供的用户属性上报功能，帮助开发者高效地收集、更新和维护用户画像数据。
通过本功能，您可以：
* **全面记录用户特征**：存储用户基础信息（如昵称、性别）、行为偏好等关键数据
* **灵活更新用户画像**：支持覆盖、追加、数值计算等多种更新方式
* **构建精准用户模型**：通过属性组合分析，实现用户分群和个性化服务
> **注意**
> **如需上报自定义的用户属性，您必须先在[元数据](https://web.gravity-engine.com/#/manage/metadata/userProperty)中添加对应的用户属性，否则会上报失败！**
## 1. 设置用户属性 [#1-设置用户属性]
对于一般的用户属性，您可以调用 `userSet` 来进行设置，使用该接口上传的属性将会覆盖原有的属性值。
```js
// 设置用户属性，会员等级
ge.userSet({ vip_level: "钻石会员" });
```
> **注意**
> 属性格式要求与事件属性保持一致。
## 2. 初始化用户属性 [#2-初始化用户属性]
如果您要上传的用户属性只要设置一次，则可以调用 `userSetOnce` 来进行设置，当该属性之前已经有值的时候，将会忽略这条信息。
```js
// 以设置用户名为例，如果用户名已设置，则忽略本次设置
ge.userSetOnce({ user_name: "TestUser" });
```
> **注意**
> 属性格式要求与事件属性保持一致。
## 3. 累加用户属性 [#3-累加用户属性]
对于数值型的用户属性，可以调用 `userAdd` 进行累加操作。
```js
// 以付费为例，用户每次付费时调用此接口，则 total_revenue 字段每次会做累加付费金额的处理
ge.userAdd({ total_revenue: 50 });
```
> **注意**
> 设置的属性 key 为字符串，Value 只允许为数值。
## 4. 重置用户属性 [#4-重置用户属性]
当您要清空用户的某个用户属性值时，可以调用 `userUnset` 来对指定属性进行清空操作。
```js
// 清空指定 key 的用户属性值，即设置为 null
ge.userUnset("userPropertyKey");
```
> **注意**
> `userUnset` 的传入值为被清空属性的 Key 值。
## 5. 清空用户属性 [#5-清空用户属性]
如果您要删除某个用户，可以调用 `userDel` 将这名用户删除，您将无法再查询该名用户的用户属性，但该用户产生的事件仍然可以被查询到：
```js
ge.userDel();
```
## 6. 用户属性追加（Array） [#6-用户属性追加array]
您可以调用 `userAppend` 对 Array（List）类型的用户数据追加元素。
```js
ge.userAppend({ Movies: ["Interstellar", "The Negro Motorist Green Book"] });
```
## 7. 用户属性去重追加（Array） [#7-用户属性去重追加array]
`userUniqAppend` 用来对 Array（List）类型的用户数据**去重**追加元素。
```js
ge.userUniqAppend({
Movies: ["Interstellar", "The Negro Motorist Green Book"],
});
```
## 8. 用户属性取最大值 [#8-用户属性取最大值]
对于数值型的用户属性，可以使用 `userNumberMax` 用来比较数值大小，保存较大的。
```js
ge.userNumberMax({
ad_ecpm_max: 300,
});
```
## 9. 用户属性取最小值 [#9-用户属性取最小值]
对于数值型的用户属性，可以使用 `userNumberMin` 用来比较数值大小，保存较小的。
```js
ge.userNumberMin({
ad_ecpm_min: 17,
});
```
# 荣耀快游戏快速集成
> 来源：https://help.gravity-engine.com/docs/client-sdk/quick-games/honor-quickstart
> 说明引力 SDK 在荣耀快游戏的游戏引擎接入方式，并指引使用 Cocos Creator 对应文档完成集成。
荣耀快游戏目前不支持原生框架开发，只支持游戏引擎开发打包，请您访问 [引力引擎 SDK 总览页面](/docs/client-sdk/sdk-overview) 选择对应的游戏引擎框架接入文档来完成对接，目前引力只支持：CocosCreator 引擎对接。
# 华为快游戏快速集成
> 来源：https://help.gravity-engine.com/docs/client-sdk/quick-games/huawei-quickstart
> 说明引力 SDK 在华为快游戏的游戏引擎接入方式，并指引使用 Unity、Cocos Creator、Laya 或 Egret 对应文档完成集成。
华为快游戏目前不支持原生框架开发，只支持游戏引擎开发打包，请您访问 [引力引擎 SDK 总览页面](/docs/client-sdk/sdk-overview) 选择对应的游戏引擎框架接入文档来完成对接，目前引力支持以下游戏引擎对接：
1. Unity
2. CocosCreator
3. Laya
4. Egret
# 快游戏
> 来源：https://help.gravity-engine.com/docs/client-sdk/quick-games
> 快游戏 SDK索引，汇总快速集成、华为快游戏快速集成等主题，便于按功能进入对应的配置、接入或参考说明。
{/* Generated by scripts/generate-docs-routes.mjs. Do not edit. */}
## 目录 [#目录]
* [快速集成](/docs/client-sdk/quick-games/quickstart)
* [华为快游戏快速集成](/docs/client-sdk/quick-games/huawei-quickstart)
* [荣耀快游戏快速集成](/docs/client-sdk/quick-games/honor-quickstart)
* [oppo快游戏快速集成](/docs/client-sdk/quick-games/oppo-quickstart)
* [vivo快游戏快速集成](/docs/client-sdk/quick-games/vivo-quickstart)
* [小米快游戏快速集成](/docs/client-sdk/quick-games/xiaomi-quickstart)
* [魅族快游戏快速集成](/docs/client-sdk/quick-games/meizu-quickstart)
* [行为事件上报](/docs/client-sdk/quick-games/track-events)
* [用户属性上报](/docs/client-sdk/quick-games/user-properties)
* [进阶功能](/docs/client-sdk/quick-games/advanced) — 子目录
# 魅族快游戏快速集成
> 来源：https://help.gravity-engine.com/docs/client-sdk/quick-games/meizu-quickstart
> 介绍 Gravity Engine 魅族快游戏 SDK 的安装、初始化、用户注册与事件上报流程，并提供参数说明和调用示例。
本文档主要讲述 **原生魅族快游戏** 接入 [引力引擎](https://gravity-engine.com/) 的技术接入方案，在开始接入前，建议您先阅读 [接入前准备](/docs/getting-started/overview) 以了解接入必备的基础概念。
> **注意**
> 本接入方案仅适用于官方 **原生魅族快游戏** 开发的项目。如果您使用的是其他游戏引擎，请访问 [引力引擎 SDK 总览页面](/docs/client-sdk/sdk-overview) 选择对应的框架接入文档。
## 1. 获取 AccessToken [#1-获取-accesstoken]
您可以在[设置-应用管理](https://web.gravity-engine.com/#/manage/appmanage)页面点击"查看参数"按钮获取当前应用的 AccessToken，请妥善保存避免泄露。
## 2. 配置并启动 SDK [#2-配置并启动-sdk]
开始接入工作之前，您需要先[下载 SDK](/docs/client-sdk/sdk-overview)。
将 `ge_mg_sdk_version.zip` 中的 `gravityengine.mg.mz.min.js` 导入工程，并初始化 SDK：
> **注意**
> **每次冷启动过程中，`GravityEngine` 的实例化方法 `new GravityEngine()` 与初始化方法 `setupAndStart()` 均只能被调用一次。`clientId` 参数必须在这两个方法的其中一个传入。**
```js
import GravityEngine from "./js/utils/gravityengine.mg.mz.min";
const config = {
accessToken: "your_access_token", // 项目通行证，在：网站后台-->设置-->应用列表中找到Access Token列 复制（首次使用可能需要先新增应用）
clientId: "your_client_id", // 用户唯一标识，如产品为小游戏，则必须填用户openid（注意，不是小游戏的APPID！！！）
name: "ge", // 全局变量名称, 默认为 gravityengine
//预设公共属性
presetSuperProperties: {
testSuperKey: "testSuperValue",
},
};
const ge = new GravityEngine(config);
ge.setupAndStart();
```
## 3. 初始化 [#3-初始化]
在用户可以获取到用户唯一 ID 时调用此方法，推荐首次启动时调用。
> **注意**
> 首次调用后，需要在 `initialize` 的 `then` 中才能继续调用其他事件上报的方法
>
> 初始化方法调用成功之后，后续冷启动可以不再调用，只需要正常启动 SDK 即可（多次调用也不会有问题，引力做了兼容）
### 方法示例 [#方法示例]
```js
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 | 是否开启同步获取归因信息（参考[同步归因](/docs/attribution/synchronous-attribution)文档）。在媒体点击下发延迟的情况下会影响归因，请谨慎开启 | boolean | 是 |
| channel | 当前用户来源渠道，对应用户细查中的：客户端渠道 | string | 否 |
| adData | 预设归因信息 | object | 否 |
## 4. 事件上报 [#4-事件上报]
### 4.1 业务注册事件上报 [#41-业务注册事件上报]
> **注意**
> **此功能仅适用于需要统计业务注册转化数据的场景。如果您的应用不需要追踪用户注册行为，可以跳过此事件接入。**
> **注意**
> 该方法可多次调用，每次调用都会上报一个用户注册事件（计算指标时会去重）
当用户完成应用内业务注册后，您可以调用 `registerEvent` 方法来上报用户注册事件（`$MPRegister`）给引力，引力会使用该事件统计指标：标准\_注册数
#### 调用示例 [#调用示例]
```js
ge.registerEvent();
```
### 4.2 付费事件上报 [#42-付费事件上报]
> **注意**
> **付费事件上报用于收入统计和分析，如您的应用不涉及内购或付费服务，则无需接入此事件。**
> **注意**
> 如果您需要通过后端 API 方式上报付费事件，请参考 [混合上报模式](/docs/client-sdk/hybrid-reporting) 来接入事件上报接口报送付费事件。
当用户发生付费行为时，需要调用 `payEvent` 方法记录用户付费事件，此事件非常重要，会影响买量和 ROI 统计，请务必重点测试！
#### 方法示例 [#方法示例-1]
```js
ge.payEvent(payAmount, payType, orderId, payReason, payMethod);
```
#### 参数说明 [#参数说明-1]
| 参数名称 | 参数含义 | 参数类型 | 是否必传 |
| --------- | ------------------------------------------------------------------------------------------------------------------------ | ------ | ---- |
| 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]
```js
ge.payEvent(300, "CNY", "your_order_id", "月卡", "支付宝");
```
### 4.3 广告观看事件上报 [#43-广告观看事件上报]
> **注意**
> **广告观看上报适用于广告变现类应用，若您的应用未集成广告模块，则无需接入此事件。**
若您的产品内有广告变现，则需要在用户点击广告观看的同时上报用户广告观看事件给引力，具体参考如下：
#### 方法示例 [#方法示例-2]
```js
ge.miniGameAdShowEvent(adType, adUnitId, otherProperties);
```
#### 参数说明 [#参数说明-2]
为生成准确的广告收益分析报表，请尽量遵循规范填写下方的广告平台参数。正确的字段是生成有价值报表的基础。
我们为您准备了详细的指引：[广告聚合平台字段配置说明](/docs/appendix/ad-mediation-fields)
| 参数名称 | 参数含义 | 参数类型 | 是否必传 |
| --------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------ | ---- |
| 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）事件配置好相关属性，比如快游戏上报广告 ecpm，可以使用引力预置好的属性字段：$ecpm，具体见下发代码示例。 | object | 是 |
#### 调用示例 [#调用示例-2]
```js
ge.miniGameAdShowEvent("reward", "your_ad_unit_id", { custom_param: "12345" });
// 如果需要上报当次广告曝光的 ECPM，代码示例如下
ge.miniGameAdShowEvent("reward", "your_ad_unit_id", { $ecpm: 1000 });
```
## 5. 接入验证 [#5-接入验证]
> **注意**
> **正式上线之前，请完成本节的校验，否则可能会导致买量上报异常！**
### 5.1 关键事件验证 [#51-关键事件验证]
在引力后台[事件流](https://web.gravity-engine.com/#/manage/metadata/eventFlow)界面开启**加载实时数据**，并在产品中触发以下几个事件。事件验收与排错：[接入验收与排错](/docs/getting-started/integration-checklist)
| 事件名 | 事件英文名 | 触发时机 | 采集方式 | 默认映射到媒体事件 | 备注 |
| ---- | ------------- | ---------- | ------------------------ | --------- | ----------------------- |
| 用户注册 | `$MPRegister` | 用户完成业务注册之后 | 调用 SDK 的**上报业务注册事件**方法采集 | 暂无 | 接入了**业务注册上报事件**的产品均需要校验 |
| 付费 | `$PayEvent` | 用户付费之后 | 调用 SDK 的**上报用户付费事件**方法采集 | 付费 | 接入了**付费事件上报事件**的产品均需要校验 |
| 广告展示 | `$AdShow` | 用户观看广告之后 | 调用 SDK 的**上报广告展示事件**方法采集 | 暂无 | 接入了**广告事件上报事件**的产品均需要校验 |
触发操作后，请在[事件流](https://web.gravity-engine.com/#/manage/metadata/eventFlow)界面中筛选测试用户的 Client ID，观察对应事件是否出现在实时入库页面。若事件数据正常显示，则说明接入成功；如出现于错误数据页面请根据页面错误提示进行排查；如未显示对应数据，请及时联系引力运营支持团队获取协助。
### 5.2 避免重复上报 [#52-避免重复上报]
上线前，请按媒体和事件核对回传来源（引力回传、媒体 SDK 自动采集、客户端手动上报、自有服务端 API），确认同一转化不会通过多条链路重复回传。需要切换到引力回传的事件，应在验证新链路正常后停用原有重复链路；媒体 SDK 的其他功能是否保留，请按对应集成文档确认。
> **注意**
> 至此验证无误之后，您可以正常上线了。
以上是 SDK 的基础接入指引。如需使用 **行为事件上报、用户属性上报、进阶功能、自动采集** 等功能，请参考以下文档：
> **注意**
> 这些功能并非所有业务场景都需要，请按需查阅。
* [行为事件上报](/docs/client-sdk/quick-games/track-events)
* [用户属性上报](/docs/client-sdk/quick-games/user-properties)
* [进阶功能](/docs/client-sdk/quick-games/advanced)
* [自动采集](/docs/client-sdk/quick-games/advanced/automatic-tracking)
# oppo快游戏快速集成
> 来源：https://help.gravity-engine.com/docs/client-sdk/quick-games/oppo-quickstart
> 介绍 Gravity Engine OPPO 快游戏 SDK 的安装、初始化、用户注册与事件上报流程，并提供参数说明和调用示例。
本文档主要讲述 **原生 oppo 快游戏** 接入 [引力引擎](https://gravity-engine.com/) 的技术接入方案，在开始接入前，建议您先阅读 [接入前准备](/docs/getting-started/overview) 以了解接入必备的基础概念。
> **注意**
> 本接入方案仅适用于官方 **原生 oppo 快游戏** 开发的项目。如果您使用的是其他游戏引擎，请访问 [引力引擎 SDK 总览页面](/docs/client-sdk/sdk-overview) 选择对应的框架接入文档。
## 1. 获取 AccessToken [#1-获取-accesstoken]
您可以在[设置-应用管理](https://web.gravity-engine.com/#/manage/appmanage)页面点击"查看参数"按钮获取当前应用的 AccessToken，请妥善保存避免泄露。
## 2. 配置并启动 SDK [#2-配置并启动-sdk]
开始接入工作之前，您需要先[下载 SDK](/docs/client-sdk/sdk-overview)。
将 `ge_mg_sdk_version.zip` 中的 `gravityengine.mg.oppo.min.js` 导入工程，并初始化 SDK：
> **注意**
> **每次冷启动过程中，`GravityEngine` 的实例化方法 `new GravityEngine()` 与初始化方法 `setupAndStart()` 均只能被调用一次。`clientId` 参数必须在这两个方法的其中一个传入。**
```js
import GravityEngine from "./js/utils/gravityengine.mg.oppo.min";
const config = {
accessToken: "your_access_token", // 项目通行证，在：网站后台-->设置-->应用列表中找到Access Token列 复制（首次使用可能需要先新增应用）
clientId: "your_client_id", // 用户唯一标识，如产品为小游戏，则必须填用户openid（注意，不是小游戏的APPID！！！）
name: "ge", // 全局变量名称, 默认为 gravityengine
//预设公共属性
presetSuperProperties: {
testSuperKey: "testSuperValue",
},
};
const ge = new GravityEngine(config);
ge.setupAndStart();
```
## 3. 初始化 [#3-初始化]
在用户可以获取到用户唯一 ID 时调用此方法，推荐首次启动时调用。
> **注意**
> 首次调用后，需要在 `initialize` 的 `then` 中才能继续调用其他事件上报的方法
>
> 初始化方法调用成功之后，后续冷启动可以不再调用，只需要正常启动 SDK 即可（多次调用也不会有问题，引力做了兼容）
### 方法示例 [#方法示例]
```js
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 | 是否开启同步获取归因信息（参考[同步归因](/docs/attribution/synchronous-attribution)文档）。在媒体点击下发延迟的情况下会影响归因，请谨慎开启 | boolean | 是 |
| channel | 当前用户来源渠道，对应用户细查中的：客户端渠道 | string | 否 |
| adData | 预设归因信息 | object | 否 |
## 4. 事件上报 [#4-事件上报]
### 4.1 业务注册事件上报 [#41-业务注册事件上报]
> **注意**
> **此功能仅适用于需要统计业务注册转化数据的场景。如果您的应用不需要追踪用户注册行为，可以跳过此事件接入。**
> **注意**
> 该方法可多次调用，每次调用都会上报一个用户注册事件（计算指标时会去重）
当用户完成应用内业务注册后，您可以调用 `registerEvent` 方法来上报用户注册事件（`$MPRegister`）给引力，引力会使用该事件统计指标：标准\_注册数
#### 调用示例 [#调用示例]
```js
ge.registerEvent();
```
### 4.2 付费事件上报 [#42-付费事件上报]
> **注意**
> **付费事件上报用于收入统计和分析，如您的应用不涉及内购或付费服务，则无需接入此事件。**
> **注意**
> 如果您需要通过后端 API 方式上报付费事件，请参考 [混合上报模式](/docs/client-sdk/hybrid-reporting) 来接入事件上报接口报送付费事件。
当用户发生付费行为时，需要调用 `payEvent` 方法记录用户付费事件，此事件非常重要，会影响买量和 ROI 统计，请务必重点测试！
#### 方法示例 [#方法示例-1]
```js
ge.payEvent(payAmount, payType, orderId, payReason, payMethod);
```
#### 参数说明 [#参数说明-1]
| 参数名称 | 参数含义 | 参数类型 | 是否必传 |
| --------- | ------------------------------------------------------------------------------------------------------------------------ | ------ | ---- |
| 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]
```js
ge.payEvent(300, "CNY", "your_order_id", "月卡", "支付宝");
```
### 4.3 广告观看事件上报 [#43-广告观看事件上报]
> **注意**
> **广告观看上报适用于广告变现类应用，若您的应用未集成广告模块，则无需接入此事件。**
若您的产品内有广告变现，则需要在用户点击广告观看的同时上报用户广告观看事件给引力，具体参考如下：
#### 方法示例 [#方法示例-2]
```js
ge.miniGameAdShowEvent(adType, adUnitId, otherProperties);
```
#### 参数说明 [#参数说明-2]
为生成准确的广告收益分析报表，请尽量遵循规范填写下方的广告平台参数。正确的字段是生成有价值报表的基础。
我们为您准备了详细的指引：[广告聚合平台字段配置说明](/docs/appendix/ad-mediation-fields)
| 参数名称 | 参数含义 | 参数类型 | 是否必传 |
| --------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------ | ---- |
| 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）事件配置好相关属性，比如快游戏上报广告 ecpm，可以使用引力预置好的属性字段：$ecpm，具体见下发代码示例。 | object | 是 |
#### 调用示例 [#调用示例-2]
```js
ge.miniGameAdShowEvent("reward", "your_ad_unit_id", { custom_param: "12345" });
// 如果需要上报当次广告曝光的 ECPM，代码示例如下
ge.miniGameAdShowEvent("reward", "your_ad_unit_id", { $ecpm: 1000 });
```
## 5. 接入验证 [#5-接入验证]
> **注意**
> **正式上线之前，请完成本节的校验，否则可能会导致买量上报异常！**
### 5.1 关键事件验证 [#51-关键事件验证]
在引力后台[事件流](https://web.gravity-engine.com/#/manage/metadata/eventFlow)界面开启**加载实时数据**，并在产品中触发以下几个事件。事件验收与排错：[接入验收与排错](/docs/getting-started/integration-checklist)
| 事件名 | 事件英文名 | 触发时机 | 采集方式 | 默认映射到媒体事件 | 备注 |
| ---- | ------------- | ---------- | ------------------------ | --------- | ----------------------- |
| 用户注册 | `$MPRegister` | 用户完成业务注册之后 | 调用 SDK 的**上报业务注册事件**方法采集 | 暂无 | 接入了**业务注册上报事件**的产品均需要校验 |
| 付费 | `$PayEvent` | 用户付费之后 | 调用 SDK 的**上报用户付费事件**方法采集 | 付费 | 接入了**付费事件上报事件**的产品均需要校验 |
| 广告展示 | `$AdShow` | 用户观看广告之后 | 调用 SDK 的**上报广告展示事件**方法采集 | 暂无 | 接入了**广告事件上报事件**的产品均需要校验 |
触发操作后，请在[事件流](https://web.gravity-engine.com/#/manage/metadata/eventFlow)界面中筛选测试用户的 Client ID，观察对应事件是否出现在实时入库页面。若事件数据正常显示，则说明接入成功；如出现于错误数据页面请根据页面错误提示进行排查；如未显示对应数据，请及时联系引力运营支持团队获取协助。
### 5.2 避免重复上报 [#52-避免重复上报]
上线前，请按媒体和事件核对回传来源（引力回传、媒体 SDK 自动采集、客户端手动上报、自有服务端 API），确认同一转化不会通过多条链路重复回传。需要切换到引力回传的事件，应在验证新链路正常后停用原有重复链路；媒体 SDK 的其他功能是否保留，请按对应集成文档确认。
> **注意**
> 至此验证无误之后，您可以正常上线了。
以上是 SDK 的基础接入指引。如需使用 **行为事件上报、用户属性上报、进阶功能、自动采集** 等功能，请参考以下文档：
> **注意**
> 这些功能并非所有业务场景都需要，请按需查阅。
* [行为事件上报](/docs/client-sdk/quick-games/track-events)
* [用户属性上报](/docs/client-sdk/quick-games/user-properties)
* [进阶功能](/docs/client-sdk/quick-games/advanced)
* [自动采集](/docs/client-sdk/quick-games/advanced/automatic-tracking)
# 快速集成
> 来源：https://help.gravity-engine.com/docs/client-sdk/quick-games/quickstart
> 介绍 Gravity Engine 快游戏 SDK 的安装、初始化、用户注册与事件上报流程，并提供参数说明和调用示例。
在开始 SDK 接入前，我们建议您：
1. 确认项目使用的开发引擎版本
2. 了解快游戏平台的技术规范
3. 准备好开发者账号和必要的权限
4. 阅读 [接入前准备](/docs/getting-started) 文档掌握基础概念
## SDK 选择说明 [#sdk-选择说明]
请根据项目实际使用的开发引擎选择 SDK，并在对应快速集成文档中确认目标平台和引擎版本要求。原生框架接入请从 [SDK 总览](/docs/client-sdk/sdk-overview) 进入具体平台页面；下面的表格用于选择游戏引擎适配方案。
## 适配详情 [#适配详情]
以下是引力各游戏引擎 SDK 在快游戏平台的适配情况：
| 游戏引擎 | OPPO小游戏 | 华为快游戏 | vivo小游戏 | 小米快游戏 | 快速跳转 |
| ------------- | ------- | ----- | ------- | ----- | --------------------------------------------------------------- |
| LayaAir | ✅ 支持 | ✅ 支持 | ✅ 支持 | ✅ 支持 | [LayaAir 快速集成](/docs/client-sdk/laya/quickstart) |
| Cocos Creator | ✅ 支持 | ✅ 支持 | ✅ 支持 | ✅ 支持 | [Cocos Creator 快速集成](/docs/client-sdk/cocos-creator/quickstart) |
| Egret | ✅ 支持 | ✅ 支持 | ✅ 支持 | ✅ 支持 | [Egret 快速集成](/docs/client-sdk/egret/quickstart) |
| Unity | ✅ 支持 | ✅ 支持 | ✅ 支持 | ✅ 支持 | [Unity 快速集成](/docs/client-sdk/unity/quickstart) |
[点击查看引力引擎 SDK 总览](/docs/client-sdk/sdk-overview)
如果您不确定应该选择哪个版本的 SDK，或者遇到任何接入问题，我们的技术团队和运营团队随时为您提供支持。选择合适的引擎 SDK 将帮助您更高效地完成接入工作，并获得最佳的数据采集效果。
# 行为事件上报
> 来源：https://help.gravity-engine.com/docs/client-sdk/quick-games/track-events
> 说明如何使用 Gravity Engine 快游戏 SDK 上报业务事件，并管理事件公共属性。
本文档详细介绍了 SDK 提供的事件上报功能，帮助开发者全面采集用户行为事件数据，为业务分析和运营决策提供数据支持。
通过上报应用内用户行为事件，您可以：
* **完整记录用户行为**：追踪用户在应用内的关键操作路径
* **支持多维度分析**：通过事件属性丰富分析维度
* **构建数据闭环**：为产品优化和精准运营提供数据基础
## 1. 自定义事件上报 [#1-自定义事件上报]
> **注意**
> **如需上报自定义事件，您必须先在[元事件](https://web.gravity-engine.com/#/manage/metadata/metaEvent)中添加，否则会上报失败！**
您可以直接调用 `track` 上传自定义事件，建议您根据准备阶段梳理的文档来设置事件的属性以及发送信息的条件，此处以购买商品为范例：
```js
ge.track(
"$purchase", // 追踪事件的名称
{
Item: "商品A",
ItemNum: 1,
Cost: 100,
Elements: ["apple", "ball", "cat"],
} // 需要上传的事件属性
);
```
* `track` 接口共有两个参数，第一个参数为事件的名称，第二个参数为事件的属性。
* 事件的名称是字符串，只能以字母开头，可包含数字、字母和下划线（\_），长度最大为 50 个字符。
* 事件的属性是 JS 对象，每个元素代表一个属性。
* 元素的 name 对应属性的名称，规定只能以字母开头，包含数字、字母和下划线（\_），长度最大为 50 个字符。
* 元素的 Value 为该属性的值，支持 `String`、`Integer`、`Float`、`Boolean`、`Date`、`DateTime` 和 `Array`；`Array` 中的内容可以为 `String`。
## 2. 公共属性 [#2-公共属性]
> **注意**
> **公共属性需要先在[事件属性](https://web.gravity-engine.com/#/manage/metadata/eventProperty)中添加，否则会上报失败！**
公共事件属性是所有事件（包括自动采集事件）都会包含的属性，用户属性中不会包含。
本节会介绍如何设置公共事件属性和动态公共属性。如果公共属性与事件中设置的自定义属性有相同 key 值，则最终的属性会根据下述优先级取值：
用户自定义事件属性 > 动态公共属性 > 事件公共属性
您可以调用 `setSuperProperties` 来设置公共事件属性，公共事件属性的格式要求与事件属性一致。在设置时只能传入常量，适合设置变化不频繁的属性。
根据属性优先级，自定义属性优先级高于事件公共属性，因此事件公共属性也可以作为某个属性的缺省值，在需要修改的事件中设置同名 Key 覆盖缺省值。
### 设置公共属性 [#设置公共属性]
```js
// 设置公共事件属性
ge.setSuperProperties({ channel: "渠道" });
// 使用 track 上传事件，此时事件中会带有公共事件属性
ge.track(
"Purchase", // 追踪事件的名称
{
Item: "商品A",
ItemNum: 1,
Cost: 100,
} // 需要上传的事件属性
);
/* 等价于在事件中加入这些公共属性
ge.track(
"Purchase", // 追踪事件的名称
{
Item: "商品A",
ItemNum: 1,
Cost: 100,
channel: "渠道" // 相当于在事件中加入这个属性
}
);
*/
```
如果多次调用 `setSuperProperties` 设置公共事件属性，则同名字段后面的调用会覆盖之前的同名字段。
### 删除公共属性 [#删除公共属性]
如果您需要删除某个公共事件属性，可以调用 `unsetSuperProperty()` 清除其中一个公共事件属性：
```js
// 清除属性名为 CHANNEL 的公共属性
ge.unsetSuperProperty("CHANNEL");
```
### 清空公共属性 [#清空公共属性]
如果您想要清空所有公共事件属性，则可以调用 `clearSuperProperties()`：
```js
// 清除公共事件属性
ge.clearSuperProperties();
```
### 获取公共属性 [#获取公共属性]
如果您想要获取所有公共事件属性，可以调用 `getSuperProperties()`：
```js
// 获取静态公共事件属性
ge.getSuperProperties();
```
## 3. 设置事件上报时间 [#3-设置事件上报时间]
事件触发的时间默认取本机时间，但在一些情况下，可能需要手动设置事件的时间，可以使用以下方法进行调用：
> **注意**
> **第三个参数为事件触发时间，必须是 `Date` 类型，将会替换事件触发的时间，如果不传该参数，则事件触发时间默认选取用户的本机时间**
```js
// 第三个参数可以输入 Date 类型的参数，替换事件触发时间
ge.track("event", { parakey: "paravalue" }, new Date());
// 如果没有 properties 需要上传，请传入一个空对象
ge.track("event", {}, new Date());
```
## 4. 记录事件时长 [#4-记录事件时长]
您可以调用 `timeEvent` 来开始计时，配置您想要计时的事件名称，当您上传该事件时，将会自动在您的事件属性中加入 `$event_duration` 这一属性来表示记录的时长，单位为秒。
```js
// 用户进入商品页面，开始计时，记录的事件为 "Enter_Shop"
ge.timeEvent("Enter_Shop");
// ...
// 上传事件，计时结束，"Enter_Shop" 这一事件中将会带有表示事件时长的属性 $event_duration
ge.track("Enter_Shop", { product_id: "A1354" });
```
## 5. 立即上报事件 [#5-立即上报事件]
如果需要立即上报缓存的事件，可以调用 `flush` 来上报所有缓存的事件。
```js
ge.flush()
```
# 用户属性上报
> 来源：https://help.gravity-engine.com/docs/client-sdk/quick-games/user-properties
> 说明如何使用 Gravity Engine 快游戏 SDK 设置、追加、累加和删除用户属性，并提供参数要求与调用示例。
本文档详细介绍了 SDK 提供的用户属性上报功能，帮助开发者高效地收集、更新和维护用户画像数据。
通过本功能，您可以：
* **全面记录用户特征**：存储用户基础信息（如昵称、性别）、行为偏好等关键数据
* **灵活更新用户画像**：支持覆盖、追加、数值计算等多种更新方式
* **构建精准用户模型**：通过属性组合分析，实现用户分群和个性化服务
> **注意**
> **如需上报自定义的用户属性，您必须先在[元数据](https://web.gravity-engine.com/#/manage/metadata/userProperty)中添加对应的用户属性，否则会上报失败！**
## 1. 设置用户属性 [#1-设置用户属性]
对于一般的用户属性，您可以调用 `userSet` 来进行设置，使用该接口上传的属性将会覆盖原有的属性值。
```js
// 设置用户属性，会员等级
ge.userSet({ vip_level: "钻石会员" });
```
> **注意**
> 属性格式要求与事件属性保持一致。
## 2. 初始化用户属性 [#2-初始化用户属性]
如果您要上传的用户属性只要设置一次，则可以调用 `userSetOnce` 来进行设置，当该属性之前已经有值的时候，将会忽略这条信息。
```js
// 以设置用户名为例，如果用户名已设置，则忽略本次设置
ge.userSetOnce({ user_name: "TestUser" });
```
> **注意**
> 属性格式要求与事件属性保持一致。
## 3. 累加用户属性 [#3-累加用户属性]
对于数值型的用户属性，可以调用 `userAdd` 进行累加操作。
```js
// 以付费为例，用户每次付费时调用此接口，则 total_revenue 字段每次会做累加付费金额的处理
ge.userAdd({ total_revenue: 50 });
```
> **注意**
> 设置的属性 key 为字符串，Value 只允许为数值。
## 4. 重置用户属性 [#4-重置用户属性]
当您要清空用户的某个用户属性值时，可以调用 `userUnset` 来对指定属性进行清空操作。
```js
// 清空指定 key 的用户属性值，即设置为 null
ge.userUnset("userPropertyKey");
```
> **注意**
> `userUnset` 的传入值为被清空属性的 Key 值。
## 5. 清空用户属性 [#5-清空用户属性]
如果您要删除某个用户，可以调用 `userDel` 将这名用户删除，您将无法再查询该名用户的用户属性，但该用户产生的事件仍然可以被查询到：
```js
ge.userDel();
```
## 6. 用户属性追加（Array） [#6-用户属性追加array]
您可以调用 `userAppend` 对 Array（List）类型的用户数据追加元素。
```js
ge.userAppend({ Movies: ["Interstellar", "The Negro Motorist Green Book"] });
```
## 7. 用户属性去重追加（Array） [#7-用户属性去重追加array]
`userUniqAppend` 用来对 Array（List）类型的用户数据**去重**追加元素。
```js
ge.userUniqAppend({
Movies: ["Interstellar", "The Negro Motorist Green Book"],
});
```
## 8. 用户属性取最大值 [#8-用户属性取最大值]
对于数值型的用户属性，可以使用 `userNumberMax` 用来比较数值大小，保存较大的。
```js
ge.userNumberMax({
ad_ecpm_max: 300,
});
```
## 9. 用户属性取最小值 [#9-用户属性取最小值]
对于数值型的用户属性，可以使用 `userNumberMin` 用来比较数值大小，保存较小的。
```js
ge.userNumberMin({
ad_ecpm_min: 17,
});
```
# vivo快游戏快速集成
> 来源：https://help.gravity-engine.com/docs/client-sdk/quick-games/vivo-quickstart
> 介绍 Gravity Engine vivo 快游戏 SDK 的安装、初始化、用户注册与事件上报流程，并提供参数说明和调用示例。
本文档主要讲述 **原生 vivo 快游戏** 接入 [引力引擎](https://gravity-engine.com/) 的技术接入方案，在开始接入前，建议您先阅读 [接入前准备](/docs/getting-started/overview) 以了解接入必备的基础概念。
> **注意**
> 本接入方案仅适用于官方 **原生 vivo 快游戏** 开发的项目。如果您使用的是其他游戏引擎，请访问 [引力引擎 SDK 总览页面](/docs/client-sdk/sdk-overview) 选择对应的框架接入文档。
## 1. 获取 AccessToken [#1-获取-accesstoken]
您可以在[设置-应用管理](https://web.gravity-engine.com/#/manage/appmanage)页面点击"查看参数"按钮获取当前应用的 AccessToken，请妥善保存避免泄露。
## 2. 配置并启动 SDK [#2-配置并启动-sdk]
开始接入工作之前，您需要先[下载 SDK](/docs/client-sdk/sdk-overview)。
将 `ge_mg_sdk_version.zip` 中的 `gravityengine.mg.vivo.min.js` 导入工程，并初始化 SDK：
> **注意**
> **每次冷启动过程中，`GravityEngine` 的实例化方法 `new GravityEngine()` 与初始化方法 `setupAndStart()` 均只能被调用一次。`clientId` 参数必须在这两个方法的其中一个传入。**
```js
import GravityEngine from "./js/utils/gravityengine.mg.vivo.min";
const config = {
accessToken: "your_access_token", // 项目通行证，在：网站后台-->设置-->应用列表中找到Access Token列 复制（首次使用可能需要先新增应用）
clientId: "your_client_id", // 用户唯一标识，如产品为小游戏，则必须填用户openid（注意，不是小游戏的APPID！！！）
name: "ge", // 全局变量名称, 默认为 gravityengine
//预设公共属性
presetSuperProperties: {
testSuperKey: "testSuperValue",
},
};
const ge = new GravityEngine(config);
ge.setupAndStart();
```
## 3. 初始化 [#3-初始化]
在用户可以获取到用户唯一 ID 时调用此方法，推荐首次启动时调用。
> **注意**
> 首次调用后，需要在 `initialize` 的 `then` 中才能继续调用其他事件上报的方法
>
> 初始化方法调用成功之后，后续冷启动可以不再调用，只需要正常启动 SDK 即可（多次调用也不会有问题，引力做了兼容）
### 方法示例 [#方法示例]
```js
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 | 是否开启同步获取归因信息（参考[同步归因](/docs/attribution/synchronous-attribution)文档）。在媒体点击下发延迟的情况下会影响归因，请谨慎开启 | boolean | 是 |
| channel | 当前用户来源渠道，对应用户细查中的：客户端渠道 | string | 否 |
| adData | 预设归因信息 | object | 否 |
## 4. 事件上报 [#4-事件上报]
### 4.1 业务注册事件上报 [#41-业务注册事件上报]
> **注意**
> **此功能仅适用于需要统计业务注册转化数据的场景。如果您的应用不需要追踪用户注册行为，可以跳过此事件接入。**
> **注意**
> 该方法可多次调用，每次调用都会上报一个用户注册事件（计算指标时会去重）
当用户完成应用内业务注册后，您可以调用 `registerEvent` 方法来上报用户注册事件（`$MPRegister`）给引力，引力会使用该事件统计指标：标准\_注册数
#### 调用示例 [#调用示例]
```js
ge.registerEvent();
```
### 4.2 付费事件上报 [#42-付费事件上报]
> **注意**
> **付费事件上报用于收入统计和分析，如您的应用不涉及内购或付费服务，则无需接入此事件。**
> **注意**
> 如果您需要通过后端 API 方式上报付费事件，请参考 [混合上报模式](/docs/client-sdk/hybrid-reporting) 来接入事件上报接口报送付费事件。
当用户发生付费行为时，需要调用 `payEvent` 方法记录用户付费事件，此事件非常重要，会影响买量和 ROI 统计，请务必重点测试！
#### 方法示例 [#方法示例-1]
```js
ge.payEvent(payAmount, payType, orderId, payReason, payMethod);
```
#### 参数说明 [#参数说明-1]
| 参数名称 | 参数含义 | 参数类型 | 是否必传 |
| --------- | ------------------------------------------------------------------------------------------------------------------------ | ------ | ---- |
| 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]
```js
ge.payEvent(300, "CNY", "your_order_id", "月卡", "支付宝");
```
### 4.3 广告观看事件上报 [#43-广告观看事件上报]
> **注意**
> **广告观看上报适用于广告变现类应用，若您的应用未集成广告模块，则无需接入此事件。**
若您的产品内有广告变现，则需要在用户点击广告观看的同时上报用户广告观看事件给引力，具体参考如下：
#### 方法示例 [#方法示例-2]
```js
ge.miniGameAdShowEvent(adType, adUnitId, otherProperties);
```
#### 参数说明 [#参数说明-2]
为生成准确的广告收益分析报表，请尽量遵循规范填写下方的广告平台参数。正确的字段是生成有价值报表的基础。
我们为您准备了详细的指引：[广告聚合平台字段配置说明](/docs/appendix/ad-mediation-fields)
| 参数名称 | 参数含义 | 参数类型 | 是否必传 |
| --------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------ | ---- |
| 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）事件配置好相关属性，比如快游戏上报广告 ecpm，可以使用引力预置好的属性字段：$ecpm，具体见下发代码示例。 | object | 是 |
#### 调用示例 [#调用示例-2]
```js
ge.miniGameAdShowEvent("reward", "your_ad_unit_id", { custom_param: "12345" });
// 如果需要上报当次广告曝光的 ECPM，代码示例如下
ge.miniGameAdShowEvent("reward", "your_ad_unit_id", { $ecpm: 1000 });
```
## 5. 接入验证 [#5-接入验证]
> **注意**
> **正式上线之前，请完成本节的校验，否则可能会导致买量上报异常！**
### 5.1 关键事件验证 [#51-关键事件验证]
在引力后台[事件流](https://web.gravity-engine.com/#/manage/metadata/eventFlow)界面开启**加载实时数据**，并在产品中触发以下几个事件。事件验收与排错：[接入验收与排错](/docs/getting-started/integration-checklist)
| 事件名 | 事件英文名 | 触发时机 | 采集方式 | 默认映射到媒体事件 | 备注 |
| ---- | ------------- | ---------- | ------------------------ | --------- | ----------------------- |
| 用户注册 | `$MPRegister` | 用户完成业务注册之后 | 调用 SDK 的**上报业务注册事件**方法采集 | 暂无 | 接入了**业务注册上报事件**的产品均需要校验 |
| 付费 | `$PayEvent` | 用户付费之后 | 调用 SDK 的**上报用户付费事件**方法采集 | 付费 | 接入了**付费事件上报事件**的产品均需要校验 |
| 广告展示 | `$AdShow` | 用户观看广告之后 | 调用 SDK 的**上报广告展示事件**方法采集 | 暂无 | 接入了**广告事件上报事件**的产品均需要校验 |
触发操作后，请在[事件流](https://web.gravity-engine.com/#/manage/metadata/eventFlow)界面中筛选测试用户的 Client ID，观察对应事件是否出现在实时入库页面。若事件数据正常显示，则说明接入成功；如出现于错误数据页面请根据页面错误提示进行排查；如未显示对应数据，请及时联系引力运营支持团队获取协助。
### 5.2 避免重复上报 [#52-避免重复上报]
上线前，请按媒体和事件核对回传来源（引力回传、媒体 SDK 自动采集、客户端手动上报、自有服务端 API），确认同一转化不会通过多条链路重复回传。需要切换到引力回传的事件，应在验证新链路正常后停用原有重复链路；媒体 SDK 的其他功能是否保留，请按对应集成文档确认。
> **注意**
> 至此验证无误之后，您可以正常上线了。
以上是 SDK 的基础接入指引。如需使用 **行为事件上报、用户属性上报、进阶功能、自动采集** 等功能，请参考以下文档：
> **注意**
> 这些功能并非所有业务场景都需要，请按需查阅。
* [行为事件上报](/docs/client-sdk/quick-games/track-events)
* [用户属性上报](/docs/client-sdk/quick-games/user-properties)
* [进阶功能](/docs/client-sdk/quick-games/advanced)
* [自动采集](/docs/client-sdk/quick-games/advanced/automatic-tracking)
# 小米快游戏快速集成
> 来源：https://help.gravity-engine.com/docs/client-sdk/quick-games/xiaomi-quickstart
> 介绍 Gravity Engine 小米快游戏 SDK 的安装、初始化、用户注册与事件上报流程，并提供参数说明和调用示例。
本文档主要讲述 **原生小米快游戏** 接入 [引力引擎](https://gravity-engine.com/) 的技术接入方案，在开始接入前，建议您先阅读 [接入前准备](/docs/getting-started/overview) 以了解接入必备的基础概念。
> **注意**
> 本接入方案仅适用于官方 **原生小米快游戏** 开发的项目。如果您使用的是其他游戏引擎，请访问 [引力引擎 SDK 总览页面](/docs/client-sdk/sdk-overview) 选择对应的框架接入文档。
## 1. 获取 AccessToken [#1-获取-accesstoken]
您可以在[设置-应用管理](https://web.gravity-engine.com/#/manage/appmanage)页面点击"查看参数"按钮获取当前应用的 AccessToken，请妥善保存避免泄露。
## 2. 配置并启动 SDK [#2-配置并启动-sdk]
开始接入工作之前，您需要先[下载 SDK](/docs/client-sdk/sdk-overview)。
将 `ge_mg_sdk_version.zip` 中的 `gravityengine.mg.xiaomi.min.js` 导入工程，并初始化 SDK：
> **注意**
> **每次冷启动过程中，`GravityEngine` 的实例化方法 `new GravityEngine()` 与初始化方法 `setupAndStart()` 均只能被调用一次。`clientId` 参数必须在这两个方法的其中一个传入。**
```js
import GravityEngine from "./js/utils/gravityengine.mg.xiaomi.min";
const config = {
accessToken: "your_access_token", // 项目通行证，在：网站后台-->设置-->应用列表中找到Access Token列 复制（首次使用可能需要先新增应用）
clientId: "your_client_id", // 用户唯一标识，如产品为小游戏，则必须填用户openid（注意，不是小游戏的APPID！！！）
name: "ge", // 全局变量名称, 默认为 gravityengine
//预设公共属性
presetSuperProperties: {
testSuperKey: "testSuperValue",
},
};
const ge = new GravityEngine(config);
ge.setupAndStart();
```
## 3. 初始化 [#3-初始化]
在用户可以获取到用户唯一 ID 时调用此方法，推荐首次启动时调用。
> **注意**
> 首次调用后，需要在 `initialize` 的 `then` 中才能继续调用其他事件上报的方法
>
> 初始化方法调用成功之后，后续冷启动可以不再调用，只需要正常启动 SDK 即可（多次调用也不会有问题，引力做了兼容）
### 方法示例 [#方法示例]
```js
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 | 是否开启同步获取归因信息（参考[同步归因](/docs/attribution/synchronous-attribution)文档）。在媒体点击下发延迟的情况下会影响归因，请谨慎开启 | boolean | 是 |
| channel | 当前用户来源渠道，对应用户细查中的：客户端渠道 | string | 否 |
| adData | 预设归因信息 | object | 否 |
## 4. 事件上报 [#4-事件上报]
### 4.1 业务注册事件上报 [#41-业务注册事件上报]
> **注意**
> **此功能仅适用于需要统计业务注册转化数据的场景。如果您的应用不需要追踪用户注册行为，可以跳过此事件接入。**
> **注意**
> 该方法可多次调用，每次调用都会上报一个用户注册事件（计算指标时会去重）
当用户完成应用内业务注册后，您可以调用 `registerEvent` 方法来上报用户注册事件（`$MPRegister`）给引力，引力会使用该事件统计指标：标准\_注册数
#### 调用示例 [#调用示例]
```js
ge.registerEvent();
```
### 4.2 付费事件上报 [#42-付费事件上报]
> **注意**
> **付费事件上报用于收入统计和分析，如您的应用不涉及内购或付费服务，则无需接入此事件。**
> **注意**
> 如果您需要通过后端 API 方式上报付费事件，请参考 [混合上报模式](/docs/client-sdk/hybrid-reporting) 来接入事件上报接口报送付费事件。
当用户发生付费行为时，需要调用 `payEvent` 方法记录用户付费事件，此事件非常重要，会影响买量和 ROI 统计，请务必重点测试！
#### 方法示例 [#方法示例-1]
```js
ge.payEvent(payAmount, payType, orderId, payReason, payMethod);
```
#### 参数说明 [#参数说明-1]
| 参数名称 | 参数含义 | 参数类型 | 是否必传 |
| --------- | ------------------------------------------------------------------------------------------------------------------------ | ------ | ---- |
| 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]
```js
ge.payEvent(300, "CNY", "your_order_id", "月卡", "支付宝");
```
### 4.3 广告观看事件上报 [#43-广告观看事件上报]
> **注意**
> **广告观看上报适用于广告变现类应用，若您的应用未集成广告模块，则无需接入此事件。**
若您的产品内有广告变现，则需要在用户点击广告观看的同时上报用户广告观看事件给引力，具体参考如下：
#### 方法示例 [#方法示例-2]
```js
ge.miniGameAdShowEvent(adType, adUnitId, otherProperties);
```
#### 参数说明 [#参数说明-2]
为生成准确的广告收益分析报表，请尽量遵循规范填写下方的广告平台参数。正确的字段是生成有价值报表的基础。
我们为您准备了详细的指引：[广告聚合平台字段配置说明](/docs/appendix/ad-mediation-fields)
| 参数名称 | 参数含义 | 参数类型 | 是否必传 |
| --------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------ | ---- |
| 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）事件配置好相关属性，比如快游戏上报广告 ecpm，可以使用引力预置好的属性字段：$ecpm，具体见下发代码示例。 | object | 是 |
#### 调用示例 [#调用示例-2]
```js
ge.miniGameAdShowEvent("reward", "your_ad_unit_id", { custom_param: "12345" });
// 如果需要上报当次广告曝光的 ECPM，代码示例如下
ge.miniGameAdShowEvent("reward", "your_ad_unit_id", { $ecpm: 1000 });
```
## 5. 接入验证 [#5-接入验证]
> **注意**
> **正式上线之前，请完成本节的校验，否则可能会导致买量上报异常！**
### 5.1 关键事件验证 [#51-关键事件验证]
在引力后台[事件流](https://web.gravity-engine.com/#/manage/metadata/eventFlow)界面开启**加载实时数据**，并在产品中触发以下几个事件。事件验收与排错：[接入验收与排错](/docs/getting-started/integration-checklist)
| 事件名 | 事件英文名 | 触发时机 | 采集方式 | 默认映射到媒体事件 | 备注 |
| ---- | ------------- | ---------- | ------------------------ | --------- | ----------------------- |
| 用户注册 | `$MPRegister` | 用户完成业务注册之后 | 调用 SDK 的**上报业务注册事件**方法采集 | 暂无 | 接入了**业务注册上报事件**的产品均需要校验 |
| 付费 | `$PayEvent` | 用户付费之后 | 调用 SDK 的**上报用户付费事件**方法采集 | 付费 | 接入了**付费事件上报事件**的产品均需要校验 |
| 广告展示 | `$AdShow` | 用户观看广告之后 | 调用 SDK 的**上报广告展示事件**方法采集 | 暂无 | 接入了**广告事件上报事件**的产品均需要校验 |
触发操作后，请在[事件流](https://web.gravity-engine.com/#/manage/metadata/eventFlow)界面中筛选测试用户的 Client ID，观察对应事件是否出现在实时入库页面。若事件数据正常显示，则说明接入成功；如出现于错误数据页面请根据页面错误提示进行排查；如未显示对应数据，请及时联系引力运营支持团队获取协助。
### 5.2 避免重复上报 [#52-避免重复上报]
上线前，请按媒体和事件核对回传来源（引力回传、媒体 SDK 自动采集、客户端手动上报、自有服务端 API），确认同一转化不会通过多条链路重复回传。需要切换到引力回传的事件，应在验证新链路正常后停用原有重复链路；媒体 SDK 的其他功能是否保留，请按对应集成文档确认。
> **注意**
> 至此验证无误之后，您可以正常上线了。
以上是 SDK 的基础接入指引。如需使用 **行为事件上报、用户属性上报、进阶功能、自动采集** 等功能，请参考以下文档：
> **注意**
> 这些功能并非所有业务场景都需要，请按需查阅。
* [行为事件上报](/docs/client-sdk/quick-games/track-events)
* [用户属性上报](/docs/client-sdk/quick-games/user-properties)
* [进阶功能](/docs/client-sdk/quick-games/advanced)
* [自动采集](/docs/client-sdk/quick-games/advanced/automatic-tracking)
# 抖音云游戏 APK 打包配置指南
> 来源：https://help.gravity-engine.com/docs/client-sdk/unity/douyin-cloud-game-apk
> 介绍在使用引力SDK开发抖音云游戏项目时，如何正确配置并导出 Android APK 包。
本文档主要介绍在使用引力 SDK 开发抖音云游戏项目时，如何正确配置并导出 Android APK 包。
## 一、配置宏定义 [#一配置宏定义]
在 Unity 中设置编译宏，使引力 SDK 进入云游戏模式。
添加步骤如下：
* 打开 Project Settings 界面；
* 找到 `Scripting Define Symbols`，新增一行输入 `GRAVITY_BYTEDANCE_CLOUD_MODE`，然后点击 Apply 按钮完成设置
## 二、关闭底层 SDK [#二关闭底层-sdk]
导出抖音云游戏 APK 时，需手动关闭引力 Android 底层 SDK 的自动接入。
**操作入口：** Unity 顶部菜单栏 → **引力引擎 → 不使用底层 SDK**。勾选后，打包时将不会集成底层 Native SDK。
## 三、注意事项 [#三注意事项]
1. **宏恢复**：打完云游戏包后，如需打普通 Android 包或其他平台包，记得删除 `GRAVITY_BYTEDANCE_CLOUD_MODE` 宏，并重新开启底层 SDK。
2. **SDK 版本**：确保引力引擎 Unity SDK 版本支持该宏，低于 5.0.34 版本无此功能。
3. **验证**：打包后建议在云游戏测试环境中验证初始化及事件上报是否正常。
# Unity
> 来源：https://help.gravity-engine.com/docs/client-sdk/unity
> Unity SDK索引，汇总快速集成、行为事件上报等主题，便于按功能进入对应的配置、接入或参考说明。
{/* Generated by scripts/generate-docs-routes.mjs. Do not edit. */}
## 目录 [#目录]
* [快速集成](/docs/client-sdk/unity/quickstart)
* [行为事件上报](/docs/client-sdk/unity/track-events)
* [用户属性上报](/docs/client-sdk/unity/user-properties)
* [进阶功能](/docs/client-sdk/unity/advanced) — 子目录
* [抖音云游戏 APK 打包配置指南](/docs/client-sdk/unity/douyin-cloud-game-apk)
* [Unity SDK升级方案](/docs/client-sdk/unity/sdk-upgrade)
# 快速集成
> 来源：https://help.gravity-engine.com/docs/client-sdk/unity/quickstart
> 介绍 Gravity Engine Unity SDK 的安装、初始化、用户注册与事件上报流程，并提供参数说明和调用示例。
本文档为**Unity**接入 [引力引擎](https://gravity-engine.com/)的技术接入方案，具体 Demo 请参考[GitHub](https://github.com/GravityInfinite/GravityEngine-Unity-Demo)开源项目，Demo 工程中可以参考 `GravityEngineDemo.cs` 脚本中对每一个方法的调用示例。
在开始接入前，建议您先阅读 [接入前准备](/docs/getting-started/overview)以了解接入必备的基础概念。
## 1. SDK 基础配置 [#1-sdk-基础配置]
> **注意**
> **微信小游戏：需要先参考微信团队发布的**[微信小游戏适配方案](https://developers.weixin.qq.com/minigame/dev/guide/game-engine/unity-webgl-transform.html)。
>
> **抖音小游戏：需要先接入头条提供的**[StarkSDK 插件](https://bytedance.feishu.cn/docx/doxcnTom4J47auHMnkjGYMBaNnZ)。
>
> **快手小游戏：需要先接入快手提供的 SDK 插件**，[详情参考](https://docs.qingque.cn/d/home/eZQCBgxB_tDpuSKJUAmmgeUcW?identityId=1oEEcs7JzPQ#section=h.sh36jfgvy7tb)。
### 1.1 接入步骤 [#11-接入步骤]
#### 1.1.1 导入UnityPackage [#111-导入unitypackage]
> **注意**
> **使用低版本(5.0.24及之前)插件的客户, 要升级到5.0.25(或以上版本)，可参考[UnitySDK 升级方案](/docs/client-sdk/unity/sdk-upgrade)**
下载最新的 [`GravityEngine.unitypackage`](/docs/client-sdk/sdk-overview)，通过 `Assets > Import Package > Custom Package`导入。
#### 1.1.2 SDK配置 [#112-sdk配置]
**国内**：默认为国内。如需切换，可在unity菜单->引力引擎->使用国内SDK进行切换\*\*海外：\*\*导入unitypackage后，unity菜单->引力引擎->使用海外SDK
#### 1.1.3 插件自动集成 [#113-插件自动集成]
**详细操作请参考：**《[EDM4U插件使用说明](/docs-assets/attachments/NbeTxLdb/EDM4U%E8%87%AA%E5%8A%A8%E9%9B%86%E6%88%90%E4%BD%BF%E7%94%A8%E4%BA%8B%E9%A1%B9.zip "EDM4U自动集成使用事项")》文档
导入后包含以下关键文件夹：
**📁 `Assets/ExternalDependencyManager`**
* **作用**：[EDM4U](https://github.com/googlesamples/unity-jar-resolver)插件（用于自动依赖管理）
* **处理**：如果项目已使用该插件，导入时可跳过此文件夹
**📁 `Assets/GravityNet`**
* **作用**：[EDM4U](https://github.com/googlesamples/unity-jar-resolver)插件自动接入底层SDK的配置
* **处理**：如果明确不需要[EDM4U](https://github.com/googlesamples/unity-jar-resolver)插件方式，可不导入此文件夹，但需要参照[iOS](/docs/client-sdk/ios/quickstart#2-%E9%9B%86%E6%88%90%E5%BC%95%E5%8A%9B%E5%BC%95%E6%93%8E-sdk)和[Android](/docs/client-sdk/android/quickstart#22-%E6%89%8B%E5%8A%A8%E9%9B%86%E6%88%90)的接入文档手动导入底层SDK
* **特殊情况**：使用[EDM4U](https://github.com/googlesamples/unity-jar-resolver)插件自动接入失败（如unity版本不支持该插件,iOS没有cocoapods环境等），也需要参照[iOS](/docs/client-sdk/ios/quickstart#2-%E9%9B%86%E6%88%90%E5%BC%95%E5%8A%9B%E5%BC%95%E6%93%8E-sdk)和[Android](/docs/client-sdk/android/quickstart#22-%E6%89%8B%E5%8A%A8%E9%9B%86%E6%88%90)的接入文档手动导入底层SDK。
#### 1.1.4 手动集成 [#114-手动集成]
参考[UnitySDK 升级方案](/docs/client-sdk/unity/sdk-upgrade) 里的非插件引入方式
#### 1.1.5 SDK冲突说明 [#115-sdk冲突说明]
如果原工程已经接入了华为或荣耀SDK，导致接入我们SDK后出现编译失败，可以编辑`Assets/GravityNet/GravityPlugins/Oaid/Editor/Dependencies.xml`文件，移除对应冲突的SDK
### 1.2 iOS配置（仅iOS应用需要配置） [#12-ios配置仅ios应用需要配置]
找到 Targets，在 Build Settings 菜单的 `Other linker flags` 选项添加 `-ObjC`
切换到 `Build Phases` 选项卡，在 `Link Binary With Libraries` 栏目下添加如下依赖项：
1. `libz.tbd`
2. `Security.framework`
3. `AdServices.framework`（optional 形式引入）
4. `SystemConfiguration.framework`
5. `libsqlite3.tbd`
6. `AppTrackingTransparency.framework`（获取 idfa 需要）
7. `AdSupport.framework`（获取 idfa 需要）
> **注意**
> **以上依赖项，必须全部添加，否则会导致编译失败！**
### 1.3 Harmony配置 [#13-harmony配置]
* 鸿蒙只支持国内，unity必须使用unity国内版 《团结引擎》
* 鸿蒙底层SDK，需要手动集成SDK
1. 方式一：集成方式参考[HarmonyOS接入文档](/docs/client-sdk/harmonyos/quickstart) 第一步下载安装
2. 方式二：下载鸿蒙底层har包，放到`/Assets/Plugins/OpenHarmony/gravityengine.har`目录下
* TuanjiePlayerAbilityBase 类里，onCreate方法（可选，仅支持接入方式一，如果需要[元服务App Linking跟踪](https://developer.huawei.com/consumer/cn/doc/promotion/ads-applink-0000002131566034)（want.parameters）需设置）
```ts
import { GravityEngineUnityChannel } from '../GravityEngineUnityChannel';
export class TuanjiePlayerAbilityBase extends UIAbility {
onCreate(want: Want, launchParam: AbilityConstant.LaunchParam): void {
GravityEngineUnityChannel.onUnityAppStart(this.context,want.parameters);
}
}
```
### 1.4 添加全局宏参数 [#14-添加全局宏参数]
正式接入之前，您需要针对不同的平台添加不同的全局宏参数，目前引力 Unity SDK 支持以下平台：
| **支持平台** | **宏参数** | **备注** |
| ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 
微信小游戏 | GRAVITY\_WECHAT\_GAME\_MODE | |
| 
抖音小游戏 | GRAVITY\_BYTEDANCE\_GAME\_MODE | |
| 
抖音小游戏 TT SDK 模式/Tiktok | GRAVITY\_BYTEDANCE\_TT\_GAME\_MODE | 如您已升级到 TT SDK，使用本模式，详情请参考[抖音小游戏 SDK 官方文档](https://developer.open-douyin.com/docs/resource/zh-CN/mini-game/develop/guide/game-engine/rd-to-SCgame/unity-game-access/starksdk-migration-guide) |
| 抖音云游戏 | GRAVITY\_BYTEDANCE\_CLOUD\_MODE | |
| 
快手小游戏 | GRAVITY\_KUAISHOU\_GAME\_MODE | |
| 
快手小游戏 WEBGL | GRAVITY\_KUAISHOU\_WEBGL\_GAME\_MODE | 如果使用的老版本webGLSDK，请添加宏 **KUAISHOU\_WEBGL\_BELOW\_TUANJIE\_VERSION** 建议更新到最新版本的快手webGLSDK 更新参考：[快手官方文档](https://docs.qingque.cn/d/home/eZQAIID-S92Rd6hhqyS-jkXnK?identityId=2G5RW70GDUS#section=h.ld785qehdds5) |
| 
支付宝小游戏 | GRAVITY\_ALIPAY\_GAME\_MODE | |
| 
美团小游戏 | GRAVITY\_MEITUAN\_GAME\_MODE | |
| 
Bilibili 小游戏 | GRAVITY\_BILIBILI\_GAME\_MODE | |
| 
TapTap小游戏 | GRAVITY\_TAPTAP\_GAME\_MODE | |
| 
华为快游戏 | GRAVITY\_HUAWEI\_GAME\_MODE | |
| 
OPPO 快游戏 | GRAVITY\_OPPO\_GAME\_MODE | 其他修改请参考[这篇文档](https://gravityengine.feishu.cn/docx/IYwmdeEsho9XxGxSVhEcXJ7JnEf) |
| 
小米快游戏 | GRAVITY\_XIAOMI\_GAME\_MODE | 其他修改请参考[这篇文档](https://dev.mi.com/xiaomihyperos/documentation/detail?pId=1991) |
| VIVO快游戏 | GRAVITY\_VIVO\_GAME\_MODE | |
| 
Android | 无需配置宏参数 | |
| 
iOS | 无需配置宏参数 | |
| 
Harmony | 无需配置宏参数 | |
| 
Windows | 无需配置宏参数 | |
1. 手动添加，添加步骤如下：
* 打开 Project Settings 界面；
* 找到 `Scripting Define Symbols`，新增一行输入对应平台的全局宏参数，然后点击 Apply 按钮完成设置
2. 通过可视化界面添加
> **注意**
> **请确保正式打包上线时，选中的宏参数依然正常生效，否则会影响到对应平台的事件上报，影响买量效果！**
## 2. 配置并启动 SDK [#2-配置并启动-sdk]
请参考以下代码来进行 SDK 的初始化，建议在能够获取到用户唯一 ID，如小游戏的`openId`、Android 设备的`oaid`、iOS 设备的`IDFV`时，尽早的进行初始化。
### 通用启动方法 [#通用启动方法]
> **注意**
> **配置项目合法域名**
>
> **如果您的项目为小游戏，您需要将** `https://backend.gravity-engine.com` **和** `https://api.gravity-engine.com` **配置到后台 request 合法域名列表中。**
>
> **tiktok 海外合法域名：`https://global-api.gravity-engine.com`**
> **注意**
> **如果您是从低版本引力 sdk 升级到高版本的，请一定记得添加**`https://api.gravity-engine.com`**域名到合法域名列表中，否则将导致事件采集失效，影响您的使用！**
**方法 1（代码创建配置）**
```csharp
// 手动初始化（动态挂载 GravityEngineAPI 脚本）
new GameObject("GravityEngine", typeof(GravityEngineAPI));
// Android原生应用示例
//设置实例参数并启动引擎，将以下三个参数修改成您应用对应的参数，参数可以在引力后台--设置--应用管理中查看
string accessToken = "your_access_token"; // 项目通行证，在：网站后台-->设置-->应用列表中找到Access Token列 复制（首次使用可能需要先新增应用）
string clientId = "default_placeholder"; // Android/iOS 传入固定值：default_placeholder，小游戏为用户OpenID
string channel = "base_channel"; // 安装包渠道来源，比如xiaomi、huawei、应用宝
GravityEngineAPI.Token token = new GravityEngineAPI.Token(accessToken, clientId,channel );
//token配置
token.isChina = true;// 是否使用国内域名，默认为true
token.enableImei = true; // 是否采集imei，仅支持Android，默认true（选填,5.0.23 以上版本支持）
token.enableOaid = true; // 是否采集oaid，仅支持Android，默认true（选填,5.0.23 以上版本支持）
token.enableAndroidId = true; // 是否采集android_id，仅支持Android，默认true（选填,5.0.23 以上版本支持）
token.enableMac = true; // 是否采集mac，仅支持Android，默认true（选填,5.0.24 以上版本支持）
//预设公共属性
token.presetSuperProperties = new Dictionary()
{
{"testSuperKey", "testSuperValue"}
};
//Android设备clientID优先级顺序，默认优先取 OAID 为clientId
token.mClientIdPriorityOrder = new List(){
GravityEngineAPI.AndroidClientIdType.OAID, GravityEngineAPI.AndroidClientIdType.ANDROID_ID};
// 启动引力引擎
GravityEngineAPI.StartGravityEngine(token);
```
> **注意**
> 通过 **非自建中台** 的方式导入历史用户到引力时，默认以 Android\_ID 作为 `clientID`。SDK 需通过 `mClientIdPriorityOrder` 将 `clientID` 生成顺序设为 **ANDROID\_ID 优先**，与导入规则保持一致，否则同一设备会被算作两个用户。
##### Token可选参数 [#token可选参数]
| **参数名** | **说明** | **是否必需** | **默认值** | **地区** | **适用平台** | **版本要求/备注** |
| -------------------------- | -------------------- | -------- | ------- | ------ | ----------- | ----------- |
| isChina | 是否使用国内域名 | 否 | TRUE | 通用 | 全平台 | 5.0.35+ |
| enableImei | 是否采集IMEI | 否 | TRUE | 国内 | Android | 5.0.23+ |
| enableOaid | 是否采集OAID | 否 | TRUE | 国内 | Android | 5.0.23+ |
| enableAndroidId | 是否采集Android ID | 否 | TRUE | 国内 | Android | 5.0.23+ |
| enableMac | 是否采集MAC地址 | 否 | TRUE | 国内 | Android | 5.0.24+ |
| presetSuperProperties | 预设公共属性 | 否 | - | 通用 | 全平台 | 5.0.42+ |
| mClientIdPriorityOrder | Android ClientID取值顺序 | 否 | - | 通用 | Android | 5.0.30+ |
| foregroundSessionThreshold | 前台会话阀值 | 否 | 0 | 通用 | Android/iOS | 设置前台会话阀值 |
| isGDPRArea | 是否欧盟地区（GDPR合规） | 否 | FALSE | 海外 | Android/iOS | 欧盟地区需设为true |
| isCoppaEnabled | 是否COPPA法案合规 | 否 | FALSE | 海外 | Android/iOS | 美国儿童应用合规 |
| isKidsAppEnabled | 是否儿童应用 | 否 | FALSE | 海外 | Android/iOS | 目标用户\<13周岁 |
| adPersonalizationEnabled | 是否允许个性化广告 | 否 | FALSE | 海外 | Android | Google广告相关 |
| adUserDataEnabled | 是否允许数据发送到Google | 否 | FALSE | 海外 | Android | Google广告相关 |
| fbAppID | Facebook应用ID | 否 | 空字符串 | 海外 | Android | Facebook归因 |
**方法 2（可视化界面配置）**
```csharp
// 手动初始化（动态挂载 GravityEngineAPI 脚本）
new GameObject("GravityEngine", typeof(GravityEngineAPI));
// Android原生应用示例
//设置实例参数并启动引擎，将以下三个参数修改成您应用对应的参数，参数可以在引力后台--设置--应用管理中查看
string clientId = "default_placeholder"; // Android/iOS 传入固定值：default_placeholder，小游戏为用户OpenID
// 启动引力引擎,国内
GravityEngineAPI.AutoStartGravityEngine(clientId);
// 启动引力引擎,海外
//如果你的应用在欧盟地区运营并且在Google投放您的应用，请务必将用户是否允许Google将其数据用于个性化广告的意见结果传入该属性，以确保您符合Google对欧盟用户意见征求政策的新政策仅支持 （选填）仅支持Android
//bool adPersonalizationEnabled = false;
//如果你的应用在欧盟地区运营并且在Google投放您的应用，请务必将用户是否同意将其数据发送到Google的意见结果传入该属性，以确保您符合Google对欧盟用户意见征求政策的新政策（选填）仅支持 Android
//bool adUserDataEnabled = false;
//GravityEngineAPI.AutoStartGravityEngine(clientId , adPersonalizationEnabled ,adUserDataEnabled);
```
### 非通用启动方法 [#非通用启动方法]
**小游戏/快游戏/Windows**
```csharp
// 手动初始化（动态挂载 GravityEngineAPI 脚本）
new GameObject("GravityEngine", typeof(GravityEngineAPI));
// 小游戏应用示例
//设置实例参数并启动引擎，将以下三个参数修改成您应用对应的参数，参数可以在引力后台--设置--应用管理中查看
string accessToken = "your_access_token"; // 项目通行证，在：网站后台-->设置-->应用列表中找到Access Token列 复制（首次使用可能需要先新增应用）
string clientId = "your_user_id"; // 通常是某一个用户的唯一标识，如产品为小游戏，则必须填用户的的 openId
// 启动引力引擎
GravityEngineAPI.StartGravityEngine(accessToken, clientId, GravityEngineAPI.SDKRunMode.NORMAL);
```
> **注意**
> **配置项目合法域名**
>
> **如果您的项目为小游戏，您需要将** `https://backend.gravity-engine.com` **和** `https://api.gravity-engine.com` **配置到后台 request 合法域名列表中。**
>
> **tiktok 海外合法域名：`https://global-api.gravity-engine.com`**
> **注意**
> **如果您是从低版本引力 sdk 升级到高版本的，请一定记得添加**`https://api.gravity-engine.com`**域名到合法域名列表中，否则将导致事件采集失效，影响您的使用！**
**Android（国内）**
```csharp
// 手动初始化（动态挂载 GravityEngineAPI 脚本）
new GameObject("GravityEngine", typeof(GravityEngineAPI));
// Android原生应用示例
//设置实例参数并启动引擎，将以下三个参数修改成您应用对应的参数，参数可以在引力后台--设置--应用管理中查看
string accessToken = "your_access_token"; // 项目通行证，在：网站后台-->设置-->应用列表中找到Access Token列 复制（首次使用可能需要先新增应用）
string clientId = "default_placeholder"; // 固定值：default_placeholder
string channel = "xiaomi"; // 安装包渠道来源，比如xiaomi、huawei、应用宝
bool enableImei = true; // 是否采集imei，仅支持Android，默认true（选填,5.0.23 以上版本支持）
bool enableOaid = true; // 是否采集oaid，仅支持Android，默认true（选填,5.0.23 以上版本支持）
bool enableAndroidId = true; // 是否采集android_id，仅支持Android，默认true（选填,5.0.23 以上版本支持）
bool enableMac = true; // 是否采集mac，仅支持Android，默认true（选填,5.0.24 以上版本支持）
// 启动引力引擎
GravityEngineAPI.StartGravityEngine(accessToken, clientId, GravityEngineAPI.SDKRunMode.NORMAL, channel, enableImei, enableOaid, enableAndroidId,enableMac );
```
**Android（海外）**
```csharp
// 手动初始化（动态挂载 GravityEngineAPI 脚本）
new GameObject("GravityEngine", typeof(GravityEngineAPI));
// Android原生应用示例
//设置实例参数并启动引擎，将以下三个参数修改成您应用对应的参数，参数可以在引力后台--设置--应用管理中查看
string accessToken = "your_access_token"; // 项目通行证，在：网站后台-->设置-->应用列表中找到Access Token列 复制（首次使用可能需要先新增应用）
string clientId = "default_placeholder"; // 固定值：default_placeholder
string channel = "xiaomi"; // 安装包渠道来源，比如xiaomi、huawei、应用宝
bool isGDPRArea = false; //是否欧盟地区 选调，默认false 如果你的应用在欧盟地区运营，则需要符合欧盟隐私保护法律的规定（关于GDPR），请务必在用户拒绝采集设备敏感信息时设置
bool isCoppaEnabled = false; //是否需要符合《儿童在线隐私权保护法》 选调，默认false 如果您的应用需要符合《儿童在线隐私权保护法》(COPPA) 规定，设置 isCoppaEnabled = true（选填）
bool isKidsAppEnabled = false; //是否儿童应用 选调，默认false 如果您的应用会定向到不满 13 周岁的儿童，则需要将其标记为儿童应用 (Kids App)，设置 isKidsAppEnabled = true（选填）
bool adPersonalizationEnabled = false; //户是否允许Google将其数据用于个性化广告的意见结果 选调，默认false 如果你的应用在欧盟地区运营并且在Google投放您的应用，请务必将用户是否允许Google将其数据用于个性化广告的意见结果传入该属性，以确保您符合Google对欧盟用户意见征求政策的新政策
bool adUserDataEnabled = false; //用户是否同意将其数据发送到Google的意见结果 选调，默认false 如果你的应用在欧盟地区运营并且在Google投放您的应用，请务必将用户是否同意将其数据发送到Google的意见结果传入该属性，以确保您符合Google对欧盟用户意见征求政策的新政策
string fbAppID = ""; //应用Facebook appId 选调，默认"" 如果您的应用需要进行Facebook归因，请设置你的FacebookID
// 启动引力引擎
GravityEngineAPI.StartOverseaGravityEngine(accessToken, clientId, GravityEngineAPI.SDKRunMode.NORMAL, channel, isGDPRArea, isCoppaEnabled, isKidsAppEnabled,adPersonalizationEnabled,adUserDataEnabled,fbAppID);
```
**iOS（国内）**
```csharp
// 手动初始化（动态挂载 GravityEngineAPI 脚本）
new GameObject("GravityEngine", typeof(GravityEngineAPI));
// iOS原生应用示例
//设置实例参数并启动引擎，将以下参数修改成您应用对应的参数，参数可以在引力后台--设置--应用管理中查看
string accessToken = "your_access_token";
string clientId = "default_placeholder"; // 固定值：default_placeholder
// 启动引力引擎
GravityEngineAPI.StartGravityEngine(accessToken, clientId, GravityEngineAPI.SDKRunMode.NORMAL, "appstore");
```
**iOS（海外）**
```csharp
// 手动初始化（动态挂载 GravityEngineAPI 脚本）
new GameObject("GravityEngine", typeof(GravityEngineAPI));
// iOS原生应用示例
//设置实例参数并启动引擎，将以下参数修改成您应用对应的参数，参数可以在引力后台--设置--应用管理中查看
string accessToken = "your_access_token";
string clientId = "default_placeholder"; // 固定值：default_placeholder
bool isGDPRArea = false; //是否欧盟地区 选调，默认false 如果你的应用在欧盟地区运营，则需要符合欧盟隐私保护法律的规定（关于GDPR），请务必在用户拒绝采集设备敏感信息时设置
bool isCoppaEnabled = false; //是否需要符合《儿童在线隐私权保护法》 选调，默认false 如果您的应用需要符合《儿童在线隐私权保护法》(COPPA) 规定，设置 isCoppaEnabled = true（选填）
bool isKidsAppEnabled = false; //是否儿童应用 选调，默认false 如果您的应用会定向到不满 13 周岁的儿童，则需要将其标记为儿童应用 (Kids App)，设置 isKidsAppEnabled = true（选填）
// 启动引力引擎
GravityEngineAPI.StartOverseaGravityEngine(accessToken, clientId, GravityEngineAPI.SDKRunMode.NORMAL, "appstore", isGDPRArea, isCoppaEnabled, isKidsAppEnabled);
```
> **注意**
> **请一定注意，不要忘记第一步挂载脚本！很多接入报错都是这个原因导致！**
## 3. 初始化 [#3-初始化]
在可以获取到用户唯一性信息时调用本方法，推荐首次安装启动时调用，后续其他方法均需在本方法回调成功之后才可正常使用。
**Android/小游戏/快游戏/Windows**
```csharp
public class InitializeCallbackImpl : IInitializeCallback
{
// 初始化失败之后回调，errorMsg为报错信息
public void onFailed(string errorMsg)
{
Debug.Log("initialize failed with message " + errorMsg);
}
// 初始化成功之后回调
public void onSuccess()
{
Debug.Log("initialize success");
Debug.Log("initialize call end");
// 建议在此执行一次Flush
GravityEngineAPI.Flush();
}
}
///
/// 在引力引擎初始化，后续其他方法均需在本方法回调成功之后才可正常使用
///
/// 用户唯一标识
/// 用户昵称
/// 用户注册的程序版本，比如当前小游戏的版本号
/// open id (小程序/小游戏必填)
/// 是否开启同步获取归因信息，在媒体点击下发延迟的情况下会影响归因，请谨慎开启。具体请参考同步归因：/docs/attribution/synchronous-attribution
/// 网络回调，其他方法均需在回调成功之后才可正常使用
///
GravityEngineAPI.Initialize("your_user_client_id", "name_123", 1, "your_openid_111", false, new InitializeCallbackImpl());
```
> **注意**
> **针对 clientId 参数，您需要特殊注意**
>
> 1. **如果产品为小游戏：则必须填用户的 openid （如传空，则使用调用 StartGravityEngine 时传入的 clientId）**
> 2. **如果产品为 Android：则传入用户唯一ID，例如 UID 或者设备 ID（如传空(需unity SDK版本大于5.0.31)，则引力 sdk 内部会自动采集设备 id 填入，采集优先级顺序为：oaid > android\_id > imei，如果所有id 都采集不到时，会生成随机的 16 位 id 保存到本地缓存中以保持相对稳定）**
>
> **如果产品为小游戏且没有自建后端，无法自行获取 openid 时，可参考[快捷获取 openid](/docs/client-sdk/unity/advanced/quick-get-openid)。**
>
> **针对 nickname 参数，您需要特殊注意**
>
> 1. **如果产品为 Android：如果传空，则引力 sdk 内部会自动根据 client\_id 计算 md5 生成**
**iOS**
```csharp
public class InitializeCallbackImpl : IInitializeCallback
{
// 初始化失败之后回调，errorMsg为报错信息
public void onFailed(string errorMsg)
{
Debug.Log("initialize failed with message " + errorMsg);
}
// 初始化成功之后回调
public void onSuccess()
{
Debug.Log("initialize success");
Debug.Log("initialize call end");
// 建议在此执行一次Flush
GravityEngineAPI.Flush();
}
}
///
/// 在引力引擎注册，后续其他方法均需在本方法回调成功之后才可正常使用（iOS专用）
///
/// 是否开启 ASA 广告采集，建议传 YES 以开启归因采集能力，后续可由引力后台的归因配置开关控制是否开启ASA归因。
/// 用户在引力系统中的唯一标识，如果传空字符串，则引力 sdk 内部会采集一个稳定的 idfv 作为用户唯一标识（推荐传空字符串）
/// 当前用户中广协 ID, 类型为json字符串，数组里面是字典，字典里有version和caid字段(可以为空字符串)
/// 是否开启同步获取归因信息，具体请参考同步归因：/docs/attribution/synchronous-attribution
/// 网络回调，其他方法均需在回调成功之后才可正常使用
///
GravityEngineAPI.InitializeIOS(true, clientId,CAID_STR, false, new InitializeCallbackImpl());
```
> **注意**
> * **`openId`**：微信和抖音、快手小游戏此参数为必填项，是买量归因必须的参数，请注意一定传入！
> * **首次调用后，需要等** `IInitializeCallback` **的** `onSuccess` **回调之后才能继续调用其他事件上报的方法，否则会上报失败！**
> * **用户整个生命周期内，初始化接口只需要调用一次，调用成功之后，后续冷启动可以不再调用，只需要保证 SDK 正确执行初始化逻辑即可**（多次调用也不会有问题，引力做了兼容）。
## 4. 事件上报 [#4-事件上报]
### 4.1 业务注册事件上报 [#41-业务注册事件上报]
> **注意**
> **如果您的应用不需要追踪用户注册行为，可以跳过此事件接入。此功能仅适用于需要统计业务注册转化数据的场景。**
> **注意**
> 该方法可多次调用，每次调用都会上报一个用户注册事件（计算指标时会去重）
当用户完成应用内业务注册后，您可以调用 `trackRegisterEvent` 方法来上报用户注册事件(APP:`$AppRegister`/小游戏：`$MPRegister`)给引力，引力会使用该事件统计后台计算指标：标准\_注册数
#### 调用示例 [#调用示例]
**Android/iOS**
```csharp
GravityEngineAPI.TrackAppRegister();
```
**小游戏/快游戏**
```csharp
GravityEngineAPI.TrackMPRegister();
```
### 4.2 付费事件上报 [#42-付费事件上报]
> **注意**
> **付费事件上报用于收入统计和分析，如您的应用不涉及内购或付费服务，则无需接入此事件。**
> **注意**
> 如果您需要通过后端 API 方式上报付费事件，请参考 [混合上报模式](/docs/client-sdk/hybrid-reporting) 来接入事件上报接口报送付费事件。
当用户发生付费行为时，需要调用 `trackPayEvent` 方法记录用户付费事件，此事件非常重要，会影响买量和 ROI 统计，请务必重点测试！
#### 方法示例 [#方法示例]
```csharp
public static string TrackPayEvent(int payAmount, string payType, string orderId, string payReason, string payMethod)
```
#### 参数说明 [#参数说明]
| **参数名称** | **参数含义** | **参数类型** | **是否必传** |
| --------- | ----------------------------------------------------------------------------------------------------------------- | -------- | -------- |
| payAmount | 付费金额 单位为分。请务必注意，传错单位可能会导致买量受到影响！ | int | 是 |
| payType | 货币类型 按照国际标准组织ISO 4217中规范的3位字母，例如CNY人民币、USD美金等，具体请参考：[国际标准组织 ISO 4217 代码表](https://en.wikipedia.org/wiki/ISO_4217) | string | 是 |
| orderId | 订单号。引力引擎会通过订单号去重，避免重复上报，请务必准确传入！ | string | 是 |
| payReason | 付费原因 例如：购买钻石、办理月卡 | string | 是 |
| payMethod | 付费方式 例如：支付宝、微信、银联等 | string | 是 |
#### 返回值 [#返回值]
返回值为当前事件生成的事件 trace\_id
#### 调用示例 [#调用示例-1]
```csharp
GravityEngineAPI.TrackPayEvent(300, "CNY", "your_order_id", "月卡", "支付宝");
```
### 4.3 广告观看事件上报 [#43-广告观看事件上报]
> **注意**
> **广告观看上报适用于广告变现类应用，若您的应用未集成广告模块，则无需接入此事件。**
> **注意**
> **微信小游戏产品需要参照** **[微信广告变现实时统计](/docs/server-integration/mini-game-tokens/wechat-monetization-stats)** **一文，检查是否正确配置微信** **`access_token`** **，配置错误将无法正确获取微信小游戏广告变现数据！**
> **注意**
> **抖音小游戏、快手小游戏、B 站小游戏无需接入，会由引力后端自动拉取，具体配置，请参考**[这里](https://gravityengine.feishu.cn/wiki/SBsxwmeb5iNrPKkUtzCcmisXnzd#OwM8doB35oKDTrxsHKkcvr9Bnqe)
若您的产品内有广告变现，则需要在用户点击广告观看的同时上报用户广告观看事件给引力，具体参考如下：
#### 方法示例 [#方法示例-1]
**Android/iOS**
```csharp
public static void TrackNativeAppAdShowEvent(string adUnionType, string adPlacementId, string adSourceId, string adType, string adnType, float ecpm)
```
为生成准确的广告收益分析报表，请尽量遵循规范填写下方的广告平台参数。正确的字段是生成有价值报表的基础。
我们为您准备了详细的指引： 👉 [广告聚合平台字段配置说明](/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，分别对应为穿山甲、优量汇、快手联盟、Mintegral、百度联盟） | string | 否 |
| ecpm | 预估ECPM价格（千次展示收入（单位元）） | float | 建议填写 |
**小游戏/快游戏**
```csharp
public static void TrackMiniGameAdShowEvent(string adType, string adUnitId, Dictionary otherProperties = null)
```
为生成准确的广告收益分析报表，请尽量遵循规范填写下方的广告平台参数。正确的字段是生成有价值报表的基础。
我们为您准备了详细的指引： 👉 [广告聚合平台字段配置说明](/docs/appendix/ad-mediation-fields)
| **参数名称** | **参数含义** | **参数类型** | **是否必传** |
| --------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------- | -------- |
| adType | 广告类型 （取值为：reward、banner、native、interstitial、video\_feed、video\_begin，分别对应激励视频广告、Banner广告、原生模板广告、插屏广告、视频广告、视频贴片广告） | string | 是 |
| adUnitId | 广告位ID（一般以adunit开头，注意不要填错，会导致广告收入统计不准！） | string | 是 |
| otherProperties | 自定义参数。其他需要携带的自定义参数，需要提前在引力后台[元数据管理](https://web.gravity-engine.com/#/manage/metadata/eventProperty)中针对广告观看($AdShow) 事件配置好相关属性，比如快游戏上报广告 ecpm，可以使用引力预置好的属性字段：$ecpm，具体见下方代码示例。 | Dictionary\ | 否 |
#### 调用示例 [#调用示例-2]
**Android/iOS**
```csharp
GravityEngineAPI.TrackNativeAppAdShowEvent("topon", "placement_id", "ad_source_id", "reward", "csj", 1);
```
**小游戏/快游戏**
```csharp
var otherProperties = new Dictionary()
{
{"$ecpm", 10000}, // 本次广告曝光的 ECPM
{"other_key", "other_value"} // 其他想携带的属性信息
};
GravityEngineAPI.TrackMiniGameAdShowEvent("reward", "your_ad_unit_id", otherProperties);
```
## 5. 接入验证 [#5-接入验证]
> **注意**
> **正式上线之前，请完成本节的校验，否则可能会导致买量上报异常！**
### 5.1 关键事件验证 [#51-关键事件验证]
在引力后台[事件流](https://web.gravity-engine.com/#/manage/metadata/eventFlow) 界面开启**加载实时数据**，并在产品中触发以下几个事件。事件验收与排错：[接入验收与排错](/docs/getting-started/integration-checklist)
| 事件名 | 事件英文名 | 触发时机 | 采集方式 | 默认映射到媒体事件 | 备注 |
| ---- | ----------------------------------------- | ---------- | ---------------------- | --------- | ----------------------- |
| 用户注册 | APP:`$AppRegister`
小游戏:`$MPRegister` | 用户完成业务注册之后 | 调用SDK的**上报业务注册事件**方法采集 | 暂无 | 接入了**业务注册上报事件**的产品均需要校验 |
| 付费 | `$PayEvent` | 用户付费之后 | 调用SDK的**上报用户付费事件**方法采集 | 付费 | 接入了**付费事件上报事件**的产品均需要校验 |
| 广告展示 | `$AdShow` | 用户观看广告之后 | 调用SDK的**上报广告展示事件**方法采集 | 暂无 | 接入了**广告事件上报事件**的产品均需要校验 |
| 用户提现 | `$UserWithdraw` | 用户提现之后 | 调用SDK的**上报用户提现事件**方法采集 | 暂无 | 接入了**用户提现上报事件**的产品均需要校验 |
触发操作后，请在[事件流](https://web.gravity-engine.com/#/manage/metadata/eventFlow) 界面中筛选测试用户的 Client ID，观察对应事件是否出现在实时入库页面。若事件数据正常显示，则说明接入成功；如出现于错误数据页面请根据页面错误提示进行排查；如未显示对应数据，请及时联系引力运营支持团队获取协助。
### 5.2 避免重复上报 [#52-避免重复上报]
如果您之前单独接了媒体的回传(SDK 或者 API)，则上线之前需要去掉，否则可能会导致重复上报数据！
> **注意**
> 至此验证无误之后，您可以正常上线了。
## 6. 媒体平台SDK集成说明 [#6-媒体平台sdk集成说明]
**🎯 集成策略说明：**
Unity SDK **仅针对【微信小游戏】平台** 集成了腾讯广告小游戏SDK。对于Unity项目发布至其他平台（如抖音小游戏、Android App、iOS App等），**我们未集成任何媒体的SDK**。
### 6.1 微信小游戏平台 [#61-微信小游戏平台]
* **状态**：已集成腾讯广告小游戏SDK
* **上报方式**：需**手动调用**我们提供的方法进行事件上报
* **版本**：自 `4.8.34`开始支持
> **重要说明**
> 按照《腾讯广告小游戏 SDK 集成》的步骤完成集成后，引力SDK会**自动上报**以下两个基础事件给腾讯：
>
> * REGISTER（用户注册）
> * RE\_ACTIVE（沉默唤起）
>
> 此外，**START\_APP**（小游戏启动）事件由腾讯SDK**自动采集**（引力SDK初始化腾讯SDK时默认开启该功能）。
>
> 除以上事件外，其他所有事件（如付费、自定义行为等）均需**客户端手动调用**我们提供的方法进行上报。
>
> 点击查看详细集成文档：[腾讯广告小游戏 SDK 集成](/docs/client-sdk/unity/advanced/tencent-ads-integration)
### 6.2 其他平台 [#62-其他平台]
*(包括但不限于：抖音小游戏、OPPO小游戏、vivo小游戏、Android App、iOS App等)*
* **状态**：**未集成**任何媒体SDK（腾讯、巨量等均未集成）
* **上报方式**：如需向媒体平台上报事件，请**自行接入**该平台的官方SDK
# Unity SDK升级方案
> 来源：https://help.gravity-engine.com/docs/client-sdk/unity/sdk-upgrade
> 说明 Unity SDK 导入方式的变更、旧文件清理与新版升级步骤，避免升级后出现文件冲突。
## 1. Unity SDK 导入方式变更说明 [#1-unity-sdk-导入方式变更说明]
> **注意**
> **🚨 重要提示：从老版本迁移到新版本的必须操作**
**迁移前必须执行的步骤**
**移除老版本 SDK 文件（\<=5.0.24）**
**在导入新版本 UnityPackage 之前，必须先手动删除以下老版本文件：**
> **注意**
> **⚠️ 注意：** 必须在导入新版本 UnityPackage 之前完成删除操作，否则会导致编译冲突！
**📱 Android SDK 文件移除：**
```
Assets/Plugins/Android/GravityEngineSDK-*.aar # 所有以 GravityEngineSDK- 开头的 aar 文件
```
**📱 iOS SDK 文件移除：**
```
Assets/Plugins/iOS/GravityEngineSDK/ # 整个 GravityEngineSDK 文件夹
```
***
## 2. 新版本接入方式（版本 ≥ 5.0.25） [#2-新版本接入方式版本--5025]
### 方式一：插件引入（推荐） [#方式一插件引入推荐]
**EDM4U 插件使用说明**
* **引入方式**：使用 EDM4U 插件动态引用底层 SDK
* **Android**：通过 Maven 库方式引用
* **iOS**：通过 CocoaPods 方式引用
* **详细操作请参考**：《[EDM4U 插件使用说明](/docs-assets/attachments/Cy9ZDPCW/EDM4U%E8%87%AA%E5%8A%A8%E9%9B%86%E6%88%90%E4%BD%BF%E7%94%A8%E4%BA%8B%E9%A1%B9.zip)》文档
### 方式二：非插件引入 [#方式二非插件引入]
如果不使用自动导入 SDK 插件，在导入 unitypackage 时，**无需**勾选以下两个文件夹：
* `Assets/ExternalDependencyManager`
* `Assets/GravityNet`
此时需要将 Android 和 iOS 的 SDK 手动导入到 Unity 项目，可参考下述的导入方式。
***
## 📱 Android SDK 导入 [#-android-sdk-导入]
### 方法 1：Maven 方式（推荐） [#方法-1maven-方式推荐]
**1. 配置仓库地址**：在 `/Assets/Plugins/Android/settingsTemplate.gradle` 文件中添加以下仓库地址：
```groovy
maven { url 'https://nexus.gravity-engine.com/repository/maven-releases/' }
maven { url 'https://nexus.gravity-engine.com/repository/maven-snapshots/' }
maven { url 'https://developer.huawei.com/repo' }
maven { url 'https://developer.hihonor.com/repo' }
```
**2. 添加依赖**
**国内：** 在 `/Assets/Plugins/Android/mainTemplate.gradle` 文件中添加以下依赖：
```groovy
implementation ("cn.gravity.android:GravityEngineSDK:+")
implementation "com.huawei.hms:ads-identifier:3.4.62.300" // 华为 SDK
implementation 'com.hihonor.mcs:ads-identifier:1.0.3.300' // 荣耀 SDK
```
**海外：** 在 `/Assets/Plugins/Android/mainTemplate.gradle` 文件中添加以下依赖：
```groovy
implementation ("oversea.gravity.android:GravityEngineSDK:+")
implementation "com.huawei.hms:ads-identifier:3.4.62.300" // 华为 SDK
implementation 'com.hihonor.mcs:ads-identifier:1.0.3.300' // 荣耀 SDK
implementation "com.android.installreferrer:installreferrer:+" // Google
```
### 方法 2：手动导入 AAR 方式（不推荐） [#方法-2手动导入-aar-方式不推荐]
1. 下载 Android 最新 SDK 的 AAR 文件（[下载地址](/docs/client-sdk/sdk-overview)）
2. 将 AAR 文件放入 `Assets/Plugins/Android/` 目录下
3. 华为 SDK 和荣耀 SDK 仍需通过上述 Maven 方式引入
### 方法 3：在已有的 Android 项目中接入 [#方法-3在已有的-android-项目中接入]
除上述方式外，也可在已有的 Android 项目中接入，详细操作请参考 [Android 接入文档](/docs/client-sdk/android/quickstart)。
***
## 📱 iOS SDK 导入 [#-ios-sdk-导入]
### 方法 1：CocoaPods 导入（推荐） [#方法-1cocoapods-导入推荐]
**国内：** 在原有的 Podfile 文件中，添加引力 SDK 的引用：
```ruby
pod 'GravityEngineSDK'
```
**海外：** 在原有的 Podfile 文件中，添加引力 SDK 的引用：
```ruby
pod 'GravityEngineOverseaSDK'
```
### 方法 2：手动导入 Framework 方式（不推荐） [#方法-2手动导入-framework-方式不推荐]
1. 下载 iOS 最新 SDK 的 Framework 文件（[下载地址](/docs/client-sdk/sdk-overview)）
2. 将 Framework 文件放入 `Assets/Plugins/iOS/` 目录下
3. 需要对 iOS 项目进行相应设置，详细操作请参考 [iOS 接入文档](/docs/client-sdk/ios/quickstart)
### 方法 3：在已有的 iOS 项目中接入 [#方法-3在已有的-ios-项目中接入]
除上述方式外，也可在已有的 iOS 项目中接入，详细操作请参考 [iOS 接入文档](/docs/client-sdk/ios/quickstart)。
> **注意**
> **注意：** 如果 Unity 版本是区分 UnityFramework 方式，需要将 GravityEngineSDK 引入到名字为 UnityFramework 的 Target 中
# 行为事件上报
> 来源：https://help.gravity-engine.com/docs/client-sdk/unity/track-events
> 说明如何使用 Gravity Engine Unity SDK 上报业务事件，并管理事件公共属性。
本文档详细介绍了 SDK 提供的事件上报功能，帮助开发者全面采集用户行为事件数据，为业务分析和运营决策提供数据支持。
通过上报应用内用户行为事件，您可以：
* **完整记录用户行为**：追踪用户在应用内的关键操作路径
* **支持多维度分析**：通过事件属性丰富分析维度
* **构建数据闭环**：为产品优化和精准运营提供数据基础
通过 `GravityEngineAPI.Track()` 可以上报事件及其属性。一般情况下，您可能需要上传十几到上百个不同的事件，如果您是第一次使用引力引擎事件采集系统，我们推荐您先上传几个关键事件。
我们也支持了若干自动采集事件，包括游戏启动、关闭、异常、小游戏添加收藏、Unity 场景加载或者卸载等事件，您可以根据业务需求选择是否开启自动采集事件。
## 1. 自定义事件上报 [#1-自定义事件上报]
> **注意**
> **如需上报自定义事件，您必须先在[元事件](https://web.gravity-engine.com/#/manage/metadata/metaEvent)中添加，否则会上报失败！**
您必须先在[元事件](https://web.gravity-engine.com/#/manage/metadata/metaEvent)中添加自定义事件，然后在游戏中指定位置埋点调用 `Track` 方法上报自定义事件。
```csharp
Dictionary properties = new Dictionary();
properties["channel"] = "base"; // 字符串，长度不超过 2048
properties["age"] = 1; // 数字
properties["isVip"] = true; // 布尔
properties["birthday"] = DateTime.Now; // 时间
properties["movies"] = new List() { "Interstellar", "The Negro Motorist Green Book" }; // 字符串元素的数组，最大元素个数为 500
GravityEngineAPI.Track("TEST_EVENT_NAME", properties);
```
* 事件名称是 `string` 类型，只能以字母开头，可包含数字、字母和下划线（\_），长度最大为 50 个字符。
* 事件属性是 `Dictionary` 类型，其中每个元素代表一个属性。
* 事件属性 `Key` 为属性名称，为 `string` 类型，规定只能以字母开头，包含数字、字母和下划线（\_），长度最大为 50 个字符。
* 属性 `Value` 支持 `string`、`int`、`float`、`bool`、`DateTime`、`List`。
当您调用 `Track()` 时，SDK 会取系统当前时间作为事件发生的时刻，如果您需要指定事件时间，可以传入 `DateTime` 类型的参数来设置事件触发时间。
SDK 提供了时间校准接口，允许使用服务器时间对 SDK 时间进行校准，具体请参考 Demo 中对 `CalibrateTime` 和 `CalibrateTimeWithNtp` 方法的使用。
> **注意**
> **尽管事件可以设置触发时间，但是接收端会做如下的限制：只接收相对服务器时间在前 10 天至后 1 小时的数据，超过时限的数据将会被视为异常数据，整条数据无法入库！**
## 2. 公共属性 [#2-公共属性]
公共事件属性指的就是每个事件都会带有的属性，对于一些重要的属性，譬如玩家的区服和渠道等，这些属性需要设置在每个事件中，此时您可以将这些属性设置为公共事件属性。
> **注意**
> **公共属性需要先在[事件属性](https://web.gravity-engine.com/#/manage/metadata/eventProperty)中添加，否则会上报失败！**
### 设置公共属性 [#设置公共属性]
您可以调用 `SetSuperProperties` 来设置公共事件属性，我们推荐您在发送事件前，先设置公共事件属性。
```csharp
Dictionary superProperties = new Dictionary()
{
{"SERVER", 0},
{"CHANNEL", "A3"}
};
GravityEngineAPI.SetSuperProperties(superProperties);
```
公共事件属性将会被保存到缓存中，无需每次启动 APP 时调用。如果调用 `SetSuperProperties` 上传了先前已设置过的公共事件属性，则会覆盖之前的属性。如果公共事件属性和 `Track()` 上传的某个属性的 Key 重复，则该事件的属性会覆盖公共事件属性。
### 删除公共属性 [#删除公共属性]
如果您需要删除某个公共事件属性，可以调用 `UnsetSuperProperty` 清除其中一个公共事件属性。
```csharp
// 清除属性名为 CHANNEL 的公共属性
GravityEngineAPI.UnsetSuperProperty("CHANNEL");
```
### 清空公共属性 [#清空公共属性]
如果您想要清空所有公共事件属性，则可以调用 `ClearSuperProperties`。
```csharp
// 清空所有公共属性
GravityEngineAPI.ClearSuperProperties();
```
### 获取公共属性 [#获取公共属性]
如果您想要获取所有公共事件属性，可以调用 `GetSuperProperties`。
```csharp
// 获取所有公共属性
GravityEngineAPI.GetSuperProperties();
```
## 3. 记录事件时长 [#3-记录事件时长]
如果您需要记录某个事件持续时长，您可以调用 `TimeEvent()` 来开始计时，配置您想要计时的事件名称，当您上传该事件时，将会自动在您的事件属性中加入 `$event_duration` 这一属性来表示记录的时长，单位为秒。
```csharp
// 调用 TimeEvent 开启对 TIME_EVENT 事件的计时
GravityEngineAPI.TimeEvent("TIME_EVENT");
// do some thing...
// 通过 Track 上传 TIME_EVENT 事件时，会在属性中添加 $event_duration 属性
GravityEngineAPI.Track("TIME_EVENT");
```
## 4. 立即上报事件 [#4-立即上报事件]
如果需要立即上报缓存的事件，可以调用 `Flush()` 来上报所有缓存的事件。
```csharp
// 调用 Flush() 上报缓存事件
GravityEngineAPI.Flush();
```
# 用户属性上报
> 来源：https://help.gravity-engine.com/docs/client-sdk/unity/user-properties
> 说明如何使用 Gravity Engine Unity SDK 设置、追加、累加和删除用户属性，并提供参数要求与调用示例。
本文档详细介绍了 SDK 提供的用户属性上报功能，帮助开发者高效地收集、更新和维护用户画像数据。
通过本功能，您可以：
* **全面记录用户特征**：存储用户基础信息（如昵称、性别）、行为偏好等关键数据
* **灵活更新用户画像**：支持覆盖、追加、数值计算等多种更新方式
* **构建精准用户模型**：通过属性组合分析，实现用户分群和个性化服务
> **注意**
> **如需上报自定义的用户属性，您必须先在[元数据](https://web.gravity-engine.com/#/manage/metadata/userProperty)中添加对应的用户属性，否则会上报失败！**
## 1. 设置用户属性 [#1-设置用户属性]
对于一般的用户属性，您可以调用 `UserSet` 来进行设置，使用该接口上传的属性将会覆盖原有的属性值。
```csharp
GravityEngineAPI.UserSet(new Dictionary()
{
{"USER_PROP_NUM", 0},
{"USER_PROP_STRING", "A3"}
});
```
## 2. 初始化用户属性 [#2-初始化用户属性]
如果您要上传的用户属性只要设置一次，则可以调用 `UserSetOnce` 来进行设置，当该属性之前已经有值的时候，将会忽略这条信息：
```csharp
GravityEngineAPI.UserSetOnce(new Dictionary()
{
{"USER_PROP_NUM", -50},
{"USER_PROP_STRING", "A3"}
});
```
## 3. 累加用户属性 [#3-累加用户属性]
当您要上传数值型的属性时，您可以调用 `UserAdd` 来对该属性进行累加操作，可传入负值，等同于相减操作。
```csharp
GravityEngineAPI.UserAdd(new Dictionary()
{
{"USER_PROP_NUM", -100.9},
{"USER_PROP_NUM2", 10.0}
});
```
> **注意**
> 设置的属性 key 为字符串，Value 只允许为数值。
## 4. 重置用户属性 [#4-重置用户属性]
如果您需要重置用户的某个属性，可以调用 `UserUnset` 将该用户指定用户属性的值重置，此接口支持传入字符串、列表、布尔类型的参数。
```csharp
// 删除单个用户属性
GravityEngineAPI.UserUnset("userPropertyName");
// 删除多个用户属性
GravityEngineAPI.UserUnset(new List() {"age", "$name", "$first_visit_time", "movies"});
```
> **注意**
> `UserUnset` 的传入值为被重置属性的 Key 值。
## 5. 清空用户属性 [#5-清空用户属性]
如果您要删除某个用户，可以调用 `UserDelete` 将这名用户删除，您将无法再查询该名用户的用户属性，但该用户产生的事件仍然可以被查询到。
```csharp
GravityEngineAPI.UserDelete();
```
## 6. 用户属性追加（Array） [#6-用户属性追加array]
可以调用 `UserAppend` 为 List 类型的用户属性追加元素。
```csharp
List propList = new List();
propList.Add("Interstellar");
propList.Add("The Negro Motorist Green Book");
// 为属性名为 movies 的用户属性追加 2 个元素
GravityEngineAPI.UserAppend(new Dictionary()
{
{"movies", propList}
});
```
## 7. 用户属性去重追加（Array） [#7-用户属性去重追加array]
可以调用 `UserUniqAppend` 为 List 类型的用户属性进行去重追加元素。
```csharp
List propList = new List();
propList.Add("Interstellar");
propList.Add("The Shawshank Redemption");
// 为属性名为 movies 的用户属性去重追加 2 个元素
GravityEngineAPI.UserUniqAppend(new Dictionary()
{
{"movies", propList}
});
```
## 8. 用户属性取最大值 [#8-用户属性取最大值]
对于数值型的用户属性，可以使用 `UserNumberMax` 用来比较数值大小，保存较大的。
```csharp
GravityEngineAPI.UserNumberMax("age", 10);
```
## 9. 用户属性取最小值 [#9-用户属性取最小值]
对于数值型的用户属性，可以使用 `UserNumberMin` 用来比较数值大小，保存较小的。
```csharp
GravityEngineAPI.UserNumberMin("age", 10);
```
# 发版记录
> 来源：https://help.gravity-engine.com/docs/client-sdk/web/changelog
> 记录 Gravity Engine Web SDK 各版本的发布日期、功能变更和升级备注，便于核对版本能力。
| 版本 | 日期 | 备注 |
| ----- | ---------- | ------------- |
| 5.0.6 | 2026-09-18 | 数据上报优化 |
| 5.0.5 | 2026-09-10 | 支持海外 |
| 5.0.4 | 2026-02-11 | 支持Native打通 |
| 5.0.1 | 2025-04-23 | 性能优化 |
| 2.1.5 | 2024-06-28 | 优化提示 |
| 2.1.3 | 2023-12-28 | 支持绑定三方平台 |
| 2.1.2 | 2023-12-12 | 优化接入流程 |
| 1.0.6 | 2023-11-09 | 支持 vivo 投放 |
| 1.0.5 | 2023-11-09 | 支持 uc 投放 |
| 1.0.4 | 2023-11-09 | 支持历史用户注册、同步归因 |
# Web
> 来源：https://help.gravity-engine.com/docs/client-sdk/web
> Web SDK索引，汇总快速集成、行为事件上报等主题，便于按功能进入对应的配置、接入或参考说明。
{/* Generated by scripts/generate-docs-routes.mjs. Do not edit. */}
## 目录 [#目录]
* [快速集成](/docs/client-sdk/web/quickstart)
* [行为事件上报](/docs/client-sdk/web/track-events)
* [用户属性上报](/docs/client-sdk/web/user-properties)
* [进阶功能](/docs/client-sdk/web/advanced) — 子目录
* [发版记录](/docs/client-sdk/web/changelog)
# 快速集成
> 来源：https://help.gravity-engine.com/docs/client-sdk/web/quickstart
> 介绍 Gravity Engine Web SDK 的安装、初始化、用户注册与事件上报流程，并提供参数说明和调用示例。
本文档为 **JavaScript** 接入[引力引擎](https://gravity-engine.com/)的技术接入方案，`JavaScript SDK` 运行环境需为浏览器，暂不兼容 IE 8 及以下版本。
建议您先阅读[接入前准备](/docs/getting-started/overview)以了解接入必备的基础概念。
## 1. SDK 基础配置 [#1-sdk-基础配置]
### 1.1 SDK 引入 [#11-sdk-引入]
下载最新的[SDK](/docs/client-sdk/sdk-overview)文件，并导入到您的项目中，推荐使用 gravityEngine.umd.min.js。
如果您想使用其他类型，使用参考如下：
* 当您想使用 commonjs require 引入时，可使用 gravityEngine.cjs.min.js；
* 当您想使用 es6 import 引入时，可使用 gravityEngine.esm.min.js；
```html
```
### 1.2 配置并启动 SDK [#12-配置并启动-sdk]
请直接复制以下代码到您项目中需要进行引力引擎初始化的地方，一般建议在能够获取到用户唯一 ID 时调用。
```js
const config = {
autoTrack: {
pageShow: true,
pageHide: true,
},
isChina: true, // 是否使用国内域名，默认为 true
showLog: true,
useAppTrack: false, // 普通网页使用 false；仅在 App WebView 打通场景按对应文档开启
accessToken: "your_access_token", // 项目通行证，在：网站后台 --> 设置 --> 应用列表中找到 Access Token 列 复制（首次使用可能需要先新增应用）
// clientId: "your_client_id", // 用户唯一标识，如果不传，就用 SDK 生成的 uuid 代替
// useAppTrack: true, // 设置 Native 打通
};
window.ge = gravityEngine;
ge.setupAndStart(config);
```
## 2. 初始化 [#2-初始化]
在用户可以获取到用户唯一性信息时调用 `ge.initialize` 方法，推荐首次安装启动时调用，后续其他方法均需在本方法回调成功之后才可正常使用。
> **注意**
> 首次调用后，需要在 `initialize` 的 `then` 中**才能继续调用其他事件上报的方法**。
>
> 初始化方法调用成功之后，后续冷启动可以不再调用，只需要正常启动 SDK 即可（多次调用也不会有问题，引力做了兼容）。
### 方法示例 [#方法示例]
```js
ge.initialize({
name: "your_name",
version: 123,
enable_sync_attribution: false,
channel: "your_channel",
})
.then((res) => {
console.log("initialize success " + res);
})
.catch((err) => {
console.log("initialize failed, error is " + err);
});
```
### 参数说明 [#参数说明]
| 参数名称 | 参数含义 | 参数类型 | 是否必传 |
| ------------------------- | ------------------------------------------------------------------- | ------- | ---- |
| name | 用户名或用户唯一 ID（可理解为业务中的昵称） | string | 是 |
| version | 用户初始化的程序发布更新的版本号 | number | 是 |
| enable\_sync\_attribution | 是否开启同步获取归因信息（参考[同步归因](/docs/attribution/synchronous-attribution)文档） | boolean | 是 |
| channel | 当前用户来源渠道，对应用户细查中的：客户端渠道（默认值：base\_channel） | string | 否 |
## 3. 事件上报 [#3-事件上报]
### 3.1 付费事件上报 [#31-付费事件上报]
> **注意**
> **付费事件上报用于收入统计和分析，如您的应用不涉及内购或付费服务，则无需接入此事件。**
> **注意**
> 如果您需要通过后端 API 方式上报付费事件，请参考[混合上报模式](/docs/client-sdk/hybrid-reporting)来接入事件上报接口报送付费事件。
当用户发生付费行为时，需要调用 `ge.payEvent()` 方法记录用户付费事件，此事件非常重要，会影响买量和 ROI 统计，请务必重点测试。
#### 方法示例 [#方法示例-1]
```js
ge.payEvent(300, "CNY", "your_order_id", "月卡", "支付宝", true);
```
#### 参数说明 [#参数说明-1]
| 参数名称 | 参数含义 | 参数类型 | 是否必传 |
| ---------- | ------------------------------------------------------------------------------------------------------------------------ | ------- | ---- |
| payAmount | 付费金额，单位为分。请务必注意，传错单位可能会导致买量受到影响！ | number | 是 |
| payType | 货币类型，按照国际标准组织 ISO 4217 中规范的 3 位字母，例如 CNY 人民币、USD 美金等，具体请参考：[国际标准组织 ISO 4217 代码表](https://en.wikipedia.org/wiki/ISO_4217) | string | 是 |
| orderId | 订单号。引力引擎会通过订单号去重，避免重复上报，请务必准确传入！ | string | 是 |
| payReason | 付费原因，例如：购买钻石、办理月卡 | string | 是 |
| payMethod | 付费方式，例如：支付宝、微信、银联等 | string | 是 |
| isFirstPay | 是否首次付费，对应示例的第六个参数 | boolean | 否 |
## 4. 接入验证 [#4-接入验证]
> **注意**
> **正式上线之前，请完成本节的校验，否则可能会导致买量上报异常！**
### 4.1 关键事件验证 [#41-关键事件验证]
在引力后台[事件流](https://web.gravity-engine.com/#/manage/metadata/eventFlow) 界面开启**加载实时数据**，并在产品中触发以下几个事件。事件验收与排错：[接入验收与排错](/docs/getting-started/integration-checklist)
| 事件名 | 事件英文名 | 触发时机 | 采集方式 | 默认映射到媒体事件 | 备注 |
| --- | ----------- | ------ | ------------------------ | --------- | ----------------------- |
| 付费 | `$PayEvent` | 用户付费之后 | 调用 SDK 的**上报用户付费事件**方法采集 | 付费 | 接入了**付费事件上报事件**的产品均需要校验 |
触发操作后，请在[事件流](https://web.gravity-engine.com/#/manage/metadata/eventFlow) 界面中筛选测试用户的 Client ID，观察对应事件是否出现在实时入库页面。若事件数据正常显示，则说明接入成功；如出现于错误数据页面请根据页面错误提示进行排查；如未显示对应数据，请及时联系引力运营支持团队获取协助。
### 4.2 避免重复上报 [#42-避免重复上报]
上线前，请按媒体和事件核对回传来源（引力回传、媒体 SDK 自动采集、客户端手动上报、自有服务端 API），确认同一转化不会通过多条链路重复回传。需要切换到引力回传的事件，应在验证新链路正常后停用原有重复链路；媒体 SDK 的其他功能是否保留，请按对应集成文档确认。
> **注意**
> 至此验证无误之后，您可以正常上线了。
# 行为事件上报
> 来源：https://help.gravity-engine.com/docs/client-sdk/web/track-events
> 说明如何使用 Gravity Engine Web SDK 上报业务事件，并管理事件公共属性。
本文档详细介绍了 SDK 提供的事件上报功能，帮助开发者全面采集用户行为事件数据，为业务分析和运营决策提供数据支持。
通过上报应用内用户行为事件，您可以：
* **完整记录用户行为**：追踪用户在应用内的关键操作路径
* **支持多维度分析**：通过事件属性丰富分析维度
* **构建数据闭环**：为产品优化和精准运营提供数据基础
通过 `ge.track` 方法可以上报事件及其属性。一般情况下，您可能需要上传十几到上百个不同的事件，如果您是第一次使用引力引擎事件采集系统，我们推荐您先上传几个关键事件。
我们也支持了页面显示和页面隐藏 2 个自动采集事件，您可以根据业务需求选择是否开启自动采集事件。
## 1. 自定义事件上报 [#1-自定义事件上报]
> **注意**
> **如需上报自定义事件，您必须先在[元事件](https://web.gravity-engine.com/#/manage/metadata/metaEvent)中添加，否则会上报失败！**
建议您先在[元事件](https://web.gravity-engine.com/#/manage/metadata/metaEvent)中添加自定义事件，然后在页面中指定位置埋点调用 `track` 方法上报自定义事件。
```js
ge.track("test", {
$pay_type: "rmb",
});
```
* 事件名称是 `string` 类型，只能以字母开头，可包含数字、字母和下划线（\_），长度最大为 50 个字符。
* 事件属性是 `Record` 类型，其中每个元素代表一个属性。
* 事件属性 `Key` 为属性名称，为 `string` 类型，规定只能以字母开头，包含数字、字母和下划线（\_），长度最大为 50 个字符。
* 属性 `Value` 支持 `string`、`number`、`boolean`、`Date`、`Array`。
当您调用 `ge.track()` 时，SDK 会取系统当前时间作为事件发生的时刻，如果您需要指定事件时间，可以传入 `Date` 类型的参数来设置事件触发时间。
> **注意**
> **尽管事件可以设置触发时间，但是接收端会做如下的限制：只接收相对服务器时间在前 10 天至后 1 小时的数据，超过时限的数据将会被视为异常数据，整条数据无法入库！**
## 2. 公共属性 [#2-公共属性]
> **注意**
> **公共属性需要先在[事件属性](https://web.gravity-engine.com/#/manage/metadata/eventProperty)中添加，否则会上报失败！**
公共事件属性指的就是每个事件都会带有的属性，对于一些重要的属性，譬如玩家的区服和渠道等，这些属性需要设置在每个事件中，此时您可以将这些属性设置为公共事件属性。
### 设置公共属性 [#设置公共属性]
您可以调用 `setSuperProperties` 来设置公共事件属性，我们推荐您在发送事件前，先设置公共事件属性。
```js
// 设置公共事件属性
ge.setSuperProperties({ channel: "your channel" });
```
公共事件属性将会被保存到缓存中，无需每次启动时调用。如果调用 `setSuperProperties` 上传了先前已设置过的公共事件属性，则会覆盖之前的属性。如果公共事件属性和 `ge.track()` 上传的某个属性的 Key 重复，则该事件的属性会覆盖公共事件属性。
### 删除公共属性 [#删除公共属性]
如果您需要删除某个公共事件属性，可以调用 `unsetSuperProperty` 清除其中一个公共事件属性：
```js
// 清除属性名为 CHANNEL 的公共属性
ge.unsetSuperProperty("CHANNEL");
```
### 清空公共属性 [#清空公共属性]
如果您想要清空所有公共事件属性，则可以调用 `clearSuperProperties`：
```js
// 清空所有公共属性
ge.clearSuperProperties();
```
### 获取公共属性 [#获取公共属性]
如果您想要获取所有公共事件属性，可以调用 `getSuperProperties`：
```js
// 获取所有公共属性
ge.getSuperProperties();
```
## 3. 记录事件时长 [#3-记录事件时长]
如果您需要记录某个事件持续时长，您可以调用 `timeEvent()` 来开始计时，配置您想要计时的事件名称，当您上传该事件时，将会自动在您的事件属性中加入 `$event_duration` 这一属性来表示记录的时长，单位为秒。
```js
// 调用 timeEvent 开启对 Enter_Shop 事件的计时
ge.timeEvent("Enter_Shop");
// do some thing...
// 通过 track 上传 Enter_Shop 事件时，会在属性中添加 $event_duration 属性
ge.track("Enter_Shop", { product_id: "A1354" });
```
## 4. 立即上报事件 [#4-立即上报事件]
如果需要立即上报缓存的事件，可以调用 `flush()` 来上报所有缓存的事件。
```js
// 调用 flush() 上报缓存事件
ge.flush();
```
# 用户属性上报
> 来源：https://help.gravity-engine.com/docs/client-sdk/web/user-properties
> 说明如何使用 Gravity Engine Web SDK 设置、追加、累加和删除用户属性，并提供参数要求与调用示例。
本文档详细介绍了 SDK 提供的用户属性上报功能，帮助开发者高效地收集、更新和维护用户画像数据。
通过本功能，您可以：
* **全面记录用户特征**：存储用户基础信息（如昵称、性别）、行为偏好等关键数据
* **灵活更新用户画像**：支持覆盖、追加、数值计算等多种更新方式
* **构建精准用户模型**：通过属性组合分析，实现用户分群和个性化服务
> **注意**
> **如需上报自定义的用户属性，您必须先在[元数据](https://web.gravity-engine.com/#/manage/metadata/userProperty)中添加对应的用户属性，否则会上报失败！**
## 1. 设置用户属性 [#1-设置用户属性]
对于一般的用户属性，您可以调用 `userSet` 来进行设置，使用该接口上传的属性将会覆盖原有的属性值。
```js
// 设置用户属性，会员等级
ge.userSet({ vip_level: "钻石会员" });
```
> **注意**
> 属性格式要求与事件属性保持一致。
## 2. 初始化用户属性 [#2-初始化用户属性]
如果您要上传的用户属性只要设置一次，则可以调用 `userSetOnce` 来进行设置，当该属性之前已经有值的时候，将会忽略这条信息。
```js
// 以设置用户名为例，如果用户名已设置，则忽略本次设置
ge.userSetOnce({ user_name: "TestUser" });
```
> **注意**
> 属性格式要求与事件属性保持一致。
## 3. 累加用户属性 [#3-累加用户属性]
对于数值型的用户属性，可以调用 `userAdd` 进行累加操作。
```js
// 以付费为例，用户每次付费时调用此接口，则 total_revenue 字段每次会做累加付费金额的处理
ge.userAdd({ total_revenue: 50 });
```
> **注意**
> 设置的属性 key 为字符串，Value 只允许为数值。
## 4. 重置用户属性 [#4-重置用户属性]
当您要清空用户的某个用户属性值时，可以调用 `userUnset` 来对指定属性进行清空操作。
```js
// 清空指定 key 的用户属性值，即设置为 null
ge.userUnset("userPropertyKey");
```
> **注意**
> `userUnset` 的传入值为被清空属性的 Key 值。
## 5. 清空用户属性 [#5-清空用户属性]
如果您要删除某个用户，可以调用 `userDel` 将这名用户删除，您将无法再查询该名用户的用户属性，但该用户产生的事件仍然可以被查询到：
```js
ge.userDel();
```
## 6. 用户属性追加（Array） [#6-用户属性追加array]
您可以调用 `userAppend` 对 Array（List）类型的用户数据追加元素。
```js
ge.userAppend({ Movies: ["Interstellar", "The Negro Motorist Green Book"] });
```
## 7. 用户属性去重追加（Array） [#7-用户属性去重追加array]
`userUniqAppend` 用来对 Array（List）类型的用户数据**去重**追加元素。
```js
ge.userUniqAppend({
Movies: ["Interstellar", "The Negro Motorist Green Book"],
});
```
# C++ SDK
> 来源：https://help.gravity-engine.com/docs/server-integration/event-collection/cpp-sdk
> 介绍 Gravity Engine C++ SDK 的环境要求、安装初始化、事件追踪和用户属性管理，并提供参数说明与代码示例。
## 概述 [#概述]
Gravity Engine C++ SDK 是一个用于数据采集和上报的工具，帮助开发者轻松集成事件追踪和用户行为分析功能。在接入前，请先阅读 [接入前准备](/docs/getting-started)。服务端接入 C++ SDK，完成事件的服务端报送功能，您需要注意以下几点：
* 服务端 SDK 仅负责事件的收集上报，不负责用户的注册，用户注册需要调用客户端 SDK 的 `initialize` 方法完成；
* 客户端和服务端 SDK 使用的用户 `client id` 需要保持一致；
* 在客户端完成 `initialize` 方法调用之后，服务端 SDK 才能开始做事件采集上报，否则上报不成功；
* 服务端 SDK 接入事件上报时，请参考 [元事件页面](https://web.gravity-engine.com/#/manage/metadata/metaEvent) 下关于事件的详情属性；
* 请尽量上报事件的公共属性，引力不做强制要求，但是上报足够多属性，可以方便您后续在引力平台使用数据分析功能（`$city`、`$province`、`$country`、`$browser`、`$browser_version` 属性可以不上报，引力后端会自动采集）；
* 关于属性的更多信息，请您参考 [事件属性页面](https://web.gravity-engine.com/#/manage/metadata/eventProperty)。
### 1. 环境要求 [#1-环境要求]
构建工具、编译器标准和依赖要求请核对 [SDK 仓库说明](https://github.com/GravityInfinite/cpp-sdk)。请先按下载版本的说明编译示例，再集成到您的服务端工程。
### 2. 安装集成 [#2-安装集成]
* **资源下载**：[下载地址](https://github.com/GravityInfinite/cpp-sdk)
#### 自动集成 [#自动集成]
```cpp
#include "../include/GEAnalytics.h"
#include "../include/GEDebugConsumer.h"
#include "../include/GEBatchConsumer.h"
```
### 3. 初始化配置 [#3-初始化配置]
#### 基础配置 [#基础配置]
```cpp
#include "../include/GEAnalytics.h"
#include "../include/GEDebugConsumer.h"
#include "../include/GEBatchConsumer.h"
#include
#include
using namespace GEData;
// enable debug
#ifdef _DEBUG
#ifndef DBG_NEW
#define DBG_NEW new ( _NORMAL_BLOCK , __FILE__ , __LINE__ )
#define new DBG_NEW
#endif
#endif // _DEBUG
const static std::string SERVER_URL = "https://backend.gravity-engine.com/event_center/api/v1/event/collect/?access_token=___XXX___";
std::unique_ptr getBatchConsumer() {
// 批提交数据条数4，默认值20
std::unique_ptr ptr(new GEBatchConsumer(SERVER_URL,4));
return ptr;
}
std::unique_ptr getDebugConsumer() {
std::unique_ptr ptr(new GEDebugConsumer(SERVER_URL));
return ptr;
}
```
## 核心功能 [#核心功能]
### 1. 事件追踪 [#1-事件追踪]
> **注意**
> **如需上报自定义事件，您必须先在 [元事件](https://web.gravity-engine.com/#/manage/metadata/metaEvent) 中添加，否则会上报失败！**
您可以调用 `track` 方法，记录用户自定义事件。
您需要先在 [元事件](https://web.gravity-engine.com/#/manage/metadata/metaEvent) 中添加自定义事件，然后调用 `track` 方法上报自定义事件。
```cpp
std::string clientId = "_test_client_id_0";
std::string eventName = "$AdClick";
for (int i = 0; i <= 1; ++i) {
GEPropertiesNode properties;
properties.SetNumber("idx", i);
properties.SetString("name1", "2-新消息");
properties.SetString("name2", "logBugs");
properties.SetString("name3", "name3");
properties.SetNumber("test_number_int", 3);
properties.SetNumber("test_number_double", 3.14);
properties.SetBool("test_bool", true);
properties.SetString("test_stl_string1", "string1");
timeb t1 = {};
ftime(&t1);
properties.SetDateTime("time2", t1.time, t1.millitm);
std::vector list;
list.emplace_back("item11");
list.emplace_back("item21");
properties.SetList("test_list1", list);
ge.track(clientId, eventName, properties);
}
```
* 事件的名称是字符串类型。
* Key 为该属性的名称，为字符串类型。
* Value 为该属性的值，支持字符串、数字、布尔、时间、对象、对象组、数组。
### 2. 用户属性管理 [#2-用户属性管理]
#### 设置用户属性（覆盖） [#设置用户属性覆盖]
对于一般的用户属性，您可以调用 `user_set` 进行设置，使用该接口上传的属性将会覆盖原有的属性值。
```cpp
GEPropertiesNode user_set_properties;
user_set_properties.SetString("user_name", "xxx");
ge.user_set(clientId, user_set_properties);
```
#### 初始化用户属性（仅首次设置有效） [#初始化用户属性仅首次设置有效]
对于只在首次设置时有效的属性，我们可以使用 `user_set_once` 记录这些属性。与 `user_set` 方法不同的是，如果被设置的用户属性已存在，则这条记录会被忽略而不会覆盖已有数据。因此，`user_set_once` 适用于为用户设置首次激活时间、首次注册时间等属性。
```cpp
GEPropertiesNode user_set_once_properties;
user_set_once_properties.SetString("prop_set_once", "ABC");
ge.user_set_once(clientId, user_set_once_properties);
```
#### 累加用户属性 [#累加用户属性]
对于数值型的用户属性，可以使用 `user_increment` 对属性值进行累加。常用于记录用户付费次数、付费额度、积分等属性。
```cpp
GEPropertiesNode user_change_num_properties;
user_change_num_properties.SetNumber("TotalRevenue",100);
ge.user_increment(clientId, user_change_num_properties);
```
#### 用户属性取最大值 [#用户属性取最大值]
对于数值型的用户属性，可以使用 `user_max` 比较数值大小，保存较大的值。
```cpp
GEPropertiesNode user_change_num_properties;
user_change_num_properties.SetNumber("TotalRevenue", 1000);
ge.user_max(clientId, user_change_num_properties);
```
#### 用户属性取最小值 [#用户属性取最小值]
对于数值型的用户属性，可以使用 `user_min` 比较数值大小，保存较小的值。
```cpp
GEPropertiesNode user_change_num_properties;
user_change_num_properties.SetNumber("TotalRevenue",1);
ge.user_min(clientId, user_change_num_properties);
```
#### 用户属性追加 [#用户属性追加]
对用户喜爱的电影、用户点评过的餐厅等属性，可以调用 `user_append` 记录列表型属性。
```cpp
GEPropertiesNode userAppend_properties;
std::vector userAppendListValue;
userAppendListValue.emplace_back("11");
userAppendListValue.emplace_back("33");
userAppend_properties.SetList("prop_list_type", userAppendListValue);
ge.user_append(clientId, userAppend_properties);
```
#### 用户属性去重追加 [#用户属性去重追加]
调用 `user_uniq_append` 对 Array 类型的用户数据去重追加元素。
```cpp
GEPropertiesNode userUniqAppend_properties;
std::vector userUniqAppendListValue;
userUniqAppendListValue.emplace_back("55");
userUniqAppendListValue.emplace_back("22");
userUniqAppendListValue.emplace_back("33");
userUniqAppendListValue.emplace_back("66");
userUniqAppendListValue.emplace_back("55");
userUniqAppend_properties.SetList("prop_list_type", userUniqAppendListValue);
ge.user_uniq_append(clientId, userUniqAppend_properties);
```
#### 重置用户属性 [#重置用户属性]
如果需要重置已设置的某个用户属性，可以调用 `user_unset` 进行重置。
```cpp
GEPropertiesNode user_unset__properties;
user_unset__properties.SetNumber("TotalRevenue", 123);
ge.user_unset(clientId, user_unset__properties);
```
#### 清空用户属性 [#清空用户属性]
调用 `user_del` 方法，将把当前用户属性清空，您将无法再查询该名用户的用户属性，但该用户产生的事件仍然可以被查询到。
```cpp
ge.user_del(clientId);
```
### 3. 数据管理 [#3-数据管理]
#### 立即上报数据 [#立即上报数据]
```cpp
ge.flush();
```
> **注意**
> 频繁调用 `flush()` 会影响性能，建议在重要操作后调用。
#### 关闭 SDK [#关闭-sdk]
```cpp
ge.close();
```
> **注意**
> 在应用关闭前调用，确保缓存数据不会丢失。
## 完整示例 [#完整示例]
```cpp
#include "../include/GEAnalytics.h"
#include "../include/GEDebugConsumer.h"
#include "../include/GEBatchConsumer.h"
#include
#include
using namespace GEData;
// enable debug
#ifdef _DEBUG
#ifndef DBG_NEW
#define DBG_NEW new ( _NORMAL_BLOCK , __FILE__ , __LINE__ )
#define new DBG_NEW
#endif
#endif // _DEBUG
const static std::string SERVER_URL = "https://backend.gravity-engine.com/event_center/api/v1/event/collect/?access_token=YOUR_ACCESS_TOKEN";
std::unique_ptr getBatchConsumer() {
// 批提交数据条数4，默认值20
std::unique_ptr ptr(new GEBatchConsumer(SERVER_URL,4));
return ptr;
}
std::unique_ptr getDebugConsumer() {
std::unique_ptr ptr(new GEDebugConsumer(SERVER_URL));
return ptr;
}
int main(int argc, char *argv[]) {
GELog::enable = true;
std::unique_ptr consumer = getDebugConsumer();
// std::unique_ptr consumer = getBatchConsumer();
GEAnalytics ge(*consumer);
std::string clientId = "_test_client_id_0";
std::string eventName = "$AdClick";
for (int i = 0; i <= 100; ++i) {
GEPropertiesNode properties;
properties.SetNumber("idx", i);
properties.SetString("name1", "2-新消息");
properties.SetString("name2", "logBugs");
properties.SetString("name3", "name3");
properties.SetNumber("test_number_int", 3);
properties.SetNumber("test_number_double", 3.14);
properties.SetBool("test_bool", true);
properties.SetString("test_stl_string1", "string1");
timeb t1 = {};
ftime(&t1);
properties.SetDateTime("time2", t1.time, t1.millitm);
std::vector list;
list.emplace_back("item11");
list.emplace_back("item21");
properties.SetList("test_list1", list);
ge.track(clientId, eventName, properties);
}
GEPropertiesNode user_set_properties;
user_set_properties.SetString("user_name", "test1");
ge.user_set(clientId, user_set_properties);
GEPropertiesNode user_set_once_properties;
user_set_once_properties.SetString("prop_set_once", "ABC");
ge.user_set_once(clientId, user_set_once_properties);
GEPropertiesNode user_change_num_properties;
user_change_num_properties.SetNumber("TotalRevenue",100);
ge.user_increment(clientId, user_change_num_properties);
user_change_num_properties.Clear();
user_change_num_properties.SetNumber("TotalRevenue", 1000);
ge.user_max(clientId, user_change_num_properties);
user_change_num_properties.Clear();
user_change_num_properties.SetNumber("TotalRevenue",1);
ge.user_min(clientId, user_change_num_properties);
GEPropertiesNode userAppend_properties;
std::vector userAppendListValue;
userAppendListValue.emplace_back("11");
userAppendListValue.emplace_back("33");
userAppend_properties.SetList("prop_list_type", userAppendListValue);
ge.user_append(clientId, userAppend_properties);
GEPropertiesNode userUniqAppend_properties;
std::vector userUniqAppendListValue;
userUniqAppendListValue.emplace_back("55");
userUniqAppendListValue.emplace_back("22");
userUniqAppendListValue.emplace_back("33");
userUniqAppendListValue.emplace_back("66");
userUniqAppendListValue.emplace_back("55");
userUniqAppend_properties.SetList("prop_list_type", userUniqAppendListValue);
ge.user_uniq_append(clientId, userUniqAppend_properties);
GEPropertiesNode user_unset__properties;
user_unset__properties.SetNumber("TotalRevenue", 123);
ge.user_unset(clientId, user_unset__properties);
ge.user_del(clientId);
ge.flush();
ge.close();
return 0;
}
```
## 最佳实践 [#最佳实践]
1. **异常处理**：对所有 SDK 调用进行异常捕获。
2. **资源清理**：在应用关闭前调用 `close()` 方法。
3. **属性命名**：使用有意义的属性名称，保持一致性。
4. **数据类型**：确保属性值类型符合预期，避免类型错误。
## 故障排除 [#故障排除]
### 常见问题 [#常见问题]
1. **初始化问题**：检查 `ACCESS_TOKEN` 和服务器地址是否正确
2. **数据格式**：验证事件属性数据类型是否符合要求
3. **性能问题**：避免频繁调用 `flush()` 方法
# Csharp SDK
> 来源：https://help.gravity-engine.com/docs/server-integration/event-collection/csharp-sdk
> 介绍 Gravity Engine Csharp SDK 的环境要求、安装初始化、事件追踪和用户属性管理，并提供参数说明与代码示例。
## 概述 [#概述]
Gravity Engine Csharp SDK 是一个用于数据采集和上报的工具，帮助开发者轻松集成事件追踪和用户行为分析功能。在接入前，请先阅读 [接入前准备](/docs/getting-started)。服务端接入 Csharp SDK，完成事件的服务端报送功能，您需要注意以下几点：
* 服务端 SDK 仅负责事件的收集上报，不负责用户的注册，用户注册需要调用客户端 SDK 的 `initialize` 方法完成；
* 客户端和服务端 SDK 使用的用户 `client id` 需要保持一致；
* 在客户端完成 `initialize` 方法调用之后，服务端 SDK 才能开始做事件采集上报，否则上报不成功；
* 服务端 SDK 接入事件上报时，请参考 [元事件页面](https://web.gravity-engine.com/#/manage/metadata/metaEvent) 下关于事件的详情属性；
* 请尽量上报事件的公共属性，引力不做强制要求，但是上报足够多属性，可以方便您后续在引力平台使用数据分析功能（`$city`、`$province`、`$country`、`$browser`、`$browser_version` 属性可以不上报，引力后端会自动采集）；
* 关于属性的更多信息，请您参考 [事件属性页面](https://web.gravity-engine.com/#/manage/metadata/eventProperty)。
### 1. 环境要求 [#1-环境要求]
* .NET：10+
### 2. 安装集成 [#2-安装集成]
* **资源下载**：[下载地址](https://github.com/GravityInfinite/csharp-sdk)
#### 自动集成 [#自动集成]
```xml
Exe
net10.0
enable
enable
```
#### 手动集成 [#手动集成]
导入文件：
* [GravityEngineData.cs](https://github.com/GravityInfinite/csharp-sdk/blob/main/GravityEngineData.cs)
* [Consumer.cs](https://github.com/GravityInfinite/csharp-sdk/blob/main/Consumer.cs)
```csharp
using GEData.Analytics;
```
### 3. 初始化配置 [#3-初始化配置]
#### 基础配置 [#基础配置]
```csharp
using GEData.Analytics;
namespace DemoNamespace
{
class Program
{
static void Main(string[] args)
{
GELog.Enable = true;
String serverUrl = "https://backend.gravity-engine.com/event_center/api/v1/event/collect/?access_token=___XXX___";
// GEAnalytics ge = new(new GEBatchConsumer(serverUrl, 200, 2, true, false));
GEAnalytics ge = new(new GEDebugConsumer(serverUrl));
}
}
}
```
## 核心功能 [#核心功能]
### 1. 事件追踪 [#1-事件追踪]
> **注意**
> **如需上报自定义事件，您必须先在 [元事件](https://web.gravity-engine.com/#/manage/metadata/metaEvent) 中添加，否则会上报失败！**
您可以调用 `Track` 方法，记录用户自定义事件。
您需要先在 [元事件](https://web.gravity-engine.com/#/manage/metadata/metaEvent) 中添加自定义事件，然后调用 `Track` 方法上报自定义事件。
```csharp
for (int i = 0; i < 3; i = i + 1)
{
Dictionary dic2 = new Dictionary();
dic2.Add("idx", i);
dic2.Add("create_date", Convert.ToDateTime("2019-7-8 20:23:22"));
dic2.Add("group_no", "T22514");
dic2.Add("group_title", "title");
dic2.Add("group_purchase_id", 438);
dic2.Add("group_order_is_vip", 3);
dic2.Add("service_id", 0);
ge.Track(client_id, "$AdClick", dic2);
}
```
* 事件的名称是字符串类型。
* Key 为该属性的名称，为字符串类型。
* Value 为该属性的值，支持字符串、数字、布尔、时间、对象、对象组、数组。
### 2. 用户属性管理 [#2-用户属性管理]
#### 设置用户属性（覆盖） [#设置用户属性覆盖]
对于一般的用户属性，您可以调用 `UserSet` 进行设置，使用该接口上传的属性将会覆盖原有的属性值。
```csharp
Dictionary dic3 = new Dictionary();
dic3.Add("user_name", "xxx");
ge.UserSet(client_id, dic3);
```
#### 初始化用户属性（仅首次设置有效） [#初始化用户属性仅首次设置有效]
对于只在首次设置时有效的属性，我们可以使用 `UserSetOnce` 记录这些属性。与 `UserSet` 方法不同的是，如果被设置的用户属性已存在，则这条记录会被忽略而不会覆盖已有数据。因此，`UserSetOnce` 适用于为用户设置首次激活时间、首次注册时间等属性。
```csharp
Dictionary dic5 = new Dictionary();
dic5.Add("prop_set_once", "xxx");
ge.UserSetOnce(client_id, dic5);
```
#### 累加用户属性 [#累加用户属性]
对于数值型的用户属性，可以使用 `UserIncrement` 对属性值进行累加。常用于记录用户付费次数、付费额度、积分等属性。
```csharp
Dictionary dic4 = new Dictionary();
dic4.Add("TotalRevenue", 648);
ge.UserIncrement(client_id, dic4);
```
#### 用户属性取最大值 [#用户属性取最大值]
对于数值型的用户属性，可以使用 `UserMax` 比较数值大小，保存较大的值。
```csharp
Dictionary dic4_2 = new Dictionary();
dic4_2.Add("TotalRevenue", 1000);
ge.UserMax(client_id, dic4_2);
```
#### 用户属性取最小值 [#用户属性取最小值]
对于数值型的用户属性，可以使用 `UserMin` 比较数值大小，保存较小的值。
```csharp
Dictionary dic4_1 = new Dictionary();
dic4_1.Add("TotalRevenue", 1);
ge.UserMin(client_id, dic4_1);
```
#### 用户属性追加 [#用户属性追加]
对用户喜爱的电影、用户点评过的餐厅等属性，可以调用 `UserAppend` 记录列表型属性。
```csharp
Dictionary dictionary = new Dictionary();
List list6 = new List();
list6.Add("a");
list6.Add("b");
list6.Add("a");
dictionary.Add("prop_list_type", list6);
ge.UserAppend(client_id, dictionary);
```
#### 用户属性去重追加 [#用户属性去重追加]
调用 `UserUniqAppend` 对 Array 类型的用户数据去重追加元素。
```csharp
Dictionary dictionary = new Dictionary();
List list6 = new List();
list6.Add("a");
list6.Add("b");
list6.Add("a");
dictionary.Add("prop_list_type", list6);
ge.UserUniqAppend(client_id, dictionary);
```
#### 重置用户属性 [#重置用户属性]
如果需要重置已设置的某个用户属性，可以调用 `UserUnSet` 进行重置。
```csharp
List list = new List();
list.Add("user_name");
ge.UserUnSet(client_id, list);
```
#### 清空用户属性 [#清空用户属性]
调用 `UserDelete` 方法，将把当前用户属性清空，您将无法再查询该名用户的用户属性，但该用户产生的事件仍然可以被查询到。
```csharp
ge.UserDelete(client_id);
```
### 3. 数据管理 [#3-数据管理]
#### 立即上报数据 [#立即上报数据]
```csharp
ge.Flush();
```
> **注意**
> 频繁调用 `flush()` 会影响性能，建议在重要操作后调用。
#### 关闭 SDK [#关闭-sdk]
```csharp
ge.Close();
```
> **注意**
> 在应用关闭前调用，确保缓存数据不会丢失。
## 完整示例 [#完整示例]
```csharp
using GEData.Analytics;
namespace DemoNamespace
{
class Program
{
static void Main(string[] args)
{
GELog.Enable = true;
String serverUrl = "https://backend.gravity-engine.com/event_center/api/v1/event/collect/?access_token=___XXX___";
// GEAnalytics ge = new(new GEBatchConsumer(serverUrl, 200, 2, true, false));
GEAnalytics ge = new(new GEDebugConsumer(serverUrl));
String client_id = "_test_client_id_0";
for (int i = 0; i < 30; i = i + 1)
{
Dictionary dic2 = new Dictionary();
dic2.Add("idx", i);
dic2.Add("create_date", Convert.ToDateTime("2019-7-8 20:23:22"));
dic2.Add("group_no", "T22514");
dic2.Add("group_title", "title");
dic2.Add("group_purchase_id", 438);
dic2.Add("group_order_is_vip", 3);
dic2.Add("service_id", 0);
ge.Track(client_id, "$AdClick", dic2);
}
Dictionary dic3 = new Dictionary();
dic3.Add("user_name", "xxx");
ge.UserSet(client_id, dic3);
Dictionary dic4 = new Dictionary();
dic4.Add("TotalRevenue", 648);
ge.UserIncrement(client_id, dic4);
Dictionary dic4_1 = new Dictionary();
dic4_1.Add("TotalRevenue", 1);
ge.UserMin(client_id, dic4_1);
Dictionary dic4_2 = new Dictionary();
dic4_2.Add("TotalRevenue", 1000);
ge.UserMax(client_id, dic4_2);
Dictionary dic5 = new Dictionary();
dic5.Add("prop_set_once", "xxx");
ge.UserSetOnce(client_id, dic5);
List list2 = new List();
list2.Add("user_name");
ge.UserUnSet(client_id, list2);
Dictionary dictionary = new Dictionary();
List list6 = new List();
list6.Add("a");
list6.Add("b");
list6.Add("a");
dictionary.Add("prop_list_type", list6);
ge.UserAppend(client_id, dictionary);
ge.UserUniqAppend(client_id, dictionary);
ge.UserDelete(client_id);
ge.Flush();
ge.Close();
}
}
}
```
## 最佳实践 [#最佳实践]
1. **异常处理**：对所有 SDK 调用进行异常捕获。
2. **资源清理**：在应用关闭前调用 `close()` 方法。
3. **属性命名**：使用有意义的属性名称，保持一致性。
4. **数据类型**：确保属性值类型符合预期，避免类型错误。
## 故障排除 [#故障排除]
### 常见问题 [#常见问题]
1. **初始化问题**：检查 `ACCESS_TOKEN` 和服务器地址是否正确
2. **数据格式**：验证事件属性数据类型是否符合要求
3. **性能问题**：避免频繁调用 `flush()` 方法
# GO SDK
> 来源：https://help.gravity-engine.com/docs/server-integration/event-collection/go-sdk
> 介绍 Gravity Engine GO SDK 的环境要求、安装初始化、事件追踪和用户属性管理，并提供参数说明与代码示例。
## 概述 [#概述]
Gravity Engine Go SDK 是一个用于数据采集和上报的工具，帮助开发者轻松集成事件追踪和用户行为分析功能。本 SDK 兼容 Golang 1.25.5 及以上版本。在接入前，请先阅读 [接入前准备](/docs/getting-started)。服务端接入 Go SDK，完成事件的服务端报送功能，您需要注意以下几点：
* 服务端 SDK 仅负责事件的收集上报，不负责用户的注册，用户注册需要调用客户端 SDK 的 `initialize` 方法完成；
* 客户端和服务端 SDK 使用的用户 `client id` 需要保持一致；
* 在客户端完成 `initialize` 方法调用之后，服务端 SDK 才能开始做事件采集上报，否则上报不成功；
* 服务端 SDK 接入事件上报时，请参考 [元事件页面](https://web.gravity-engine.com/#/manage/metadata/metaEvent) 下关于事件的详情属性；
* 请尽量上报事件的公共属性，引力不做强制要求，但是上报足够多属性，可以方便您后续在引力平台使用数据分析功能（`$city`、`$province`、`$country`、`$browser`、`$browser_version` 属性可以不上报，引力后端会自动采集）；
* 关于属性的更多信息，请您参考 [事件属性页面](https://web.gravity-engine.com/#/manage/metadata/eventProperty)。
### 1. 环境要求 [#1-环境要求]
* Golang 1.25.5 及以上版本。
### 2. 安装集成 [#2-安装集成]
#### 自动集成 [#自动集成]
```go
import "github.com/GravityInfinite/go-sdk"
```
#### 手动下载 [#手动下载]
直接下载：[下载地址](https://github.com/GravityInfinite/go-sdk)
### 3. 初始化配置 [#3-初始化配置]
#### 基础配置 [#基础配置]
```go
const ServerUrl = "https://backend.gravity-engine.com/event_center/api/v1/event/collect/?access_token=XXXX"
func generateBatchConsumer() (gedata.GEConsumer, error) {
config := gedata.GEBatchConfig{
ServerUrl: ServerUrl,
AutoFlush: true,
BatchSize: 100,
Interval: 20,
Compress: true,
}
return gedata.NewBatchConsumerWithConfig(config)
}
func generateDebugConsumer() (gedata.GEConsumer, error) {
return gedata.NewDebugConsumer(ServerUrl)
}
// e.g. init consumer, you can choose different consumer
//consumer, err := generateDebugConsumer() // GEDebugConsumer
consumer, err := generateBatchConsumer() // GEBatchConsumer
if err != nil {
// consumer init error
}
ge := gedata.New(consumer)
```
## 核心功能 [#核心功能]
### 1. 事件追踪 [#1-事件追踪]
> **注意**
> **如需上报自定义事件，您必须先在 [元事件](https://web.gravity-engine.com/#/manage/metadata/metaEvent) 中添加，否则会上报失败！**
您可以调用 `track` 方法，记录用户自定义事件。
您需要先在 [元事件](https://web.gravity-engine.com/#/manage/metadata/metaEvent) 中添加自定义事件，然后调用 `track` 方法上报自定义事件。
```go
// 设置事件属性
properties := map[string]interface{}{
// 系统预置属性
"$city": "xx",
// 用户自定义属性, 字符串类型
"prop_string": "abcdefg",
// 用户自定义属性, 数值类型
"prop_num": 56.56,
// 用户自定义属性, bool 类型
"prop_bool": true,
// 用户自定义属性, time.Time 类型
"prop_date": time.Now(),
}
err := ge.Track(clientId, eventName, properties)
```
* 事件的名称是字符串类型。
* Key 为该属性的名称，为字符串类型。
* Value 为该属性的值，支持字符串、数字、布尔、时间、对象、对象组、数组。
### 2. 用户属性管理 [#2-用户属性管理]
#### 设置用户属性（覆盖） [#设置用户属性覆盖]
对于一般的用户属性，您可以调用 `UserSet` 进行设置，使用该接口上传的属性将会覆盖原有的属性值。
```go
properties := map[string]interface{}{"user_name": "xxx", "count": 1, "arr": []int{11, 22}}
err := ge.UserSet(clientId, properties)
```
#### 初始化用户属性（仅首次设置有效） [#初始化用户属性仅首次设置有效]
对于只在首次设置时有效的属性，我们可以使用 `UserSetOnce` 记录这些属性。与 `UserSet` 方法不同的是，如果被设置的用户属性已存在，则这条记录会被忽略而不会覆盖已有数据。因此，`UserSetOnce` 适用于为用户设置首次激活时间、首次注册时间等属性。
```go
properties := map[string]interface{}{"prop_once": "xxx"}
err := ge.UserSetOnce(clientId, properties)
```
#### 累加用户属性 [#累加用户属性]
对于数值型的用户属性，可以使用 `UserIncrement` 对属性值进行累加。常用于记录用户付费次数、付费额度、积分等属性。
```go
properties := map[string]interface{}{"prop_incr": 123}
err := ge.UserIncrement(clientId, properties)
```
#### 用户属性取最大值 [#用户属性取最大值]
对于数值型的用户属性，可以使用 `UserMax` 比较数值大小，保存较大的值。
```go
properties := map[string]interface{}{"prop_num": 100}
err := ge.UserMax(clientId, properties)
```
#### 用户属性取最小值 [#用户属性取最小值]
对于数值型的用户属性，可以使用 `UserMin` 比较数值大小，保存较小的值。
```go
properties := map[string]interface{}{"prop_num": 1}
err := ge.UserMin(clientId, properties)
```
#### 用户属性追加 [#用户属性追加]
对用户喜爱的电影、用户点评过的餐厅等属性，可以调用 `UserAppend` 记录列表型属性。
```go
properties := map[string]interface{}{"prop_list_type": []string{"a", "b", "c", "c"}}
err := ge.UserAppend(clientId, properties)
```
#### 用户属性去重追加 [#用户属性去重追加]
调用 `UserUniqAppend` 对 Array 类型的用户数据去重追加元素。
```go
properties := map[string]interface{}{"prop_list_type": []string{"a", "b", "c", "c"}}
err := ge.UserUniqAppend(clientId, properties)
```
#### 重置用户属性 [#重置用户属性]
如果需要重置已设置的某个用户属性，可以调用 `UserUnset` 进行重置。
```go
properties := map[string]interface{}{"prop_unset": "xxx"}
err := ge.UserUnset(clientId, properties)
```
#### 清空用户属性 [#清空用户属性]
调用 `UserDelete` 方法，将把当前用户属性清空，您将无法再查询该名用户的用户属性，但该用户产生的事件仍然可以被查询到。
```go
err := ge.UserDelete(clientId)
```
### 3. 数据管理 [#3-数据管理]
#### 立即上报数据 [#立即上报数据]
```go
err := ge.Flush()
if err != nil {
// handle error
}
```
> **注意**
> 频繁调用 `flush()` 会影响性能，建议在重要操作后调用。
#### 关闭 SDK [#关闭-sdk]
```go
err := ge.Close()
if err != nil {
// handle error
}
```
> **注意**
> 在应用关闭前调用，确保缓存数据不会丢失。
## 完整示例 [#完整示例]
```go
package main
import (
"fmt"
"time"
// "gedata/src/gedata"
"github.com/GravityInfinite/go-sdk/src/gedata"
)
const ServerUrl = "https://backend.gravity-engine.com/event_center/api/v1/event/collect/?access_token=___XXX___"
const clientId = "_test_client_id_0"
const eventName = "$AdClick"
var trackProperties = func() map[string]interface{} {
type B struct {
Trigger string
Time time.Time
}
type A struct {
Name string
Time time.Time
Event []B
}
customData := A{
eventName,
time.Now(),
[]B{
{Trigger: "Now We Support", Time: time.Now()},
{Trigger: "User Custom Struct Data", Time: time.Now()},
},
}
properties := map[string]interface{}{
"channel": "ge",
"age": 1,
"isSuccess": true,
"birthday": time.Now(),
"object": map[string]interface{}{
"key": "value",
},
"objectArr": []interface{}{
map[string]interface{}{
"key": "value",
},
},
"arr": []string{"test1", "test2", "test3"},
"my_data": customData,
"time_now": time.Now(),
"time_2": "2022-12-12T22:22:22.333444555Z",
}
return properties
}()
func mainDebug() {
// e.g. init consumer, you can choose different consumer
consumer, err := generateDebugConsumer() // GEDebugConsumer
//consumer, err := generateBatchConsumer() // GEBatchConsumer
if err != nil {
// consumer init error
panic(err)
}
ge := gedata.New(consumer)
defer func() {
err = ge.Flush()
if err != nil {
fmt.Printf("GE flush error: %v", err.Error())
}
err = ge.Close()
if err != nil {
fmt.Printf("GE close error: %v\n", err.Error())
}
}()
func() {
for i := 0; i < 6; i++ {
p := trackProperties
p["idx"] = i
err = ge.Track(clientId, eventName, p)
if err != nil {
fmt.Println(err)
}
}
}()
func() {
properties := map[string]interface{}{"user_name": "xxx", "count": 1, "arr": []int{11, 22}}
_ = properties
err = ge.UserSet(clientId, trackProperties)
if err != nil {
fmt.Println(err)
}
}()
func() {
properties := map[string]interface{}{"user_name": ""}
err = ge.UserUnset(clientId, properties)
if err != nil {
fmt.Println(err)
}
}()
func() {
properties := map[string]interface{}{"prop_set_once": "111"}
err = ge.UserSetOnce(clientId, properties)
if err != nil {
fmt.Println(err)
}
}()
func() {
properties := map[string]interface{}{"TotalRevenue": 100}
err = ge.UserIncrement(clientId, properties)
if err != nil {
fmt.Println(err)
}
}()
func() {
properties := map[string]interface{}{"TotalRevenue": 1}
err = ge.UserNumMin(clientId, properties)
if err != nil {
fmt.Println(err)
}
}()
func() {
properties := map[string]interface{}{"TotalRevenue": 1000}
err = ge.UserNumMax(clientId, properties)
if err != nil {
fmt.Println(err)
}
}()
func() {
properties := map[string]interface{}{"prop_list_type": []string{"a", "a"}}
err = ge.UserAppend(clientId, properties)
if err != nil {
fmt.Println(err)
}
}()
func() {
properties := map[string]interface{}{"prop_list_type": []string{"a", "b", "c", "c"}}
err = ge.UserUniqAppend(clientId, properties)
if err != nil {
fmt.Println(err)
}
}()
func() {
err = ge.UserDelete(clientId)
if err != nil {
fmt.Println(err)
}
}()
}
func mainBatch() {
// e.g. init consumer, you can choose different consumer
//consumer, err := generateDebugConsumer() // GEDebugConsumer
consumer, err := generateBatchConsumer() // GEBatchConsumer
if err != nil {
// consumer init error
panic(err)
}
ge := gedata.New(consumer)
defer func() {
err = ge.Flush()
if err != nil {
fmt.Printf("GE flush error: %v", err.Error())
}
err = ge.Close()
if err != nil {
fmt.Printf("GE close error: %v\n", err.Error())
}
}()
func() {
for i := 0; i < 1000; i++ {
p := trackProperties
p["idx"] = i
err = ge.Track(clientId, eventName, p)
if err != nil {
fmt.Println(err)
}
}
}()
func() {
properties := map[string]interface{}{"user_name": "xxx", "count": 1, "arr": []int{11, 22}}
err = ge.UserSet(clientId, properties)
if err != nil {
fmt.Println(err)
}
}()
func() {
properties := map[string]interface{}{"user_name": ""}
err = ge.UserUnset(clientId, properties)
if err != nil {
fmt.Println(err)
}
}()
func() {
properties := map[string]interface{}{"prop_set_once": "111"}
err = ge.UserSetOnce(clientId, properties)
if err != nil {
fmt.Println(err)
}
}()
func() {
properties := map[string]interface{}{"TotalRevenue": 100}
err = ge.UserIncrement(clientId, properties)
if err != nil {
fmt.Println(err)
}
}()
func() {
properties := map[string]interface{}{"prop_list_type": []string{"a", "a"}}
err = ge.UserAppend(clientId, properties)
if err != nil {
fmt.Println(err)
}
}()
func() {
properties := map[string]interface{}{"prop_list_type": []string{"a", "b", "c", "c"}}
err = ge.UserUniqAppend(clientId, properties)
if err != nil {
fmt.Println(err)
}
}()
func() {
err = ge.UserDelete(clientId)
if err != nil {
fmt.Println(err)
}
}()
}
func main() {
// enable console log
gedata.SetLogLevel(gedata.GELogLevelDebug)
func() {
mainDebug()
//mainBatch()
}()
fmt.Println("ok")
}
func generateBatchConsumer() (gedata.GEConsumer, error) {
config := gedata.GEBatchConfig{
ServerUrl: ServerUrl,
AutoFlush: true,
BatchSize: 100,
Interval: 20,
Compress: true,
}
return gedata.NewBatchConsumerWithConfig(config)
}
func generateDebugConsumer() (gedata.GEConsumer, error) {
return gedata.NewDebugConsumer(ServerUrl)
}
```
## 最佳实践 [#最佳实践]
1. **异常处理**：对所有 SDK 调用进行异常捕获。
2. **资源清理**：在应用关闭前调用 `close()` 方法。
3. **属性命名**：使用有意义的属性名称，保持一致性。
4. **数据类型**：确保属性值类型符合预期，避免类型错误。
## 故障排除 [#故障排除]
### 常见问题 [#常见问题]
1. **初始化问题**：检查 `ACCESS_TOKEN` 和服务器地址是否正确
2. **数据格式**: 验证事件属性数据类型是否符合要求
3. **性能问题**: 避免频繁调用 `flush()` 方法
# 事件采集
> 来源：https://help.gravity-engine.com/docs/server-integration/event-collection
> Gravity Engine 事件采集索引，汇总C++ SDK、Csharp SDK等主题，便于按功能进入对应的配置、接入或参考说明。
{/* Generated by scripts/generate-docs-routes.mjs. Do not edit. */}
## 目录 [#目录]
* [C++ SDK](/docs/server-integration/event-collection/cpp-sdk)
* [Csharp SDK](/docs/server-integration/event-collection/csharp-sdk)
* [GO SDK](/docs/server-integration/event-collection/go-sdk)
* [Java SDK](/docs/server-integration/event-collection/java-sdk)
* [Lua SDK](/docs/server-integration/event-collection/lua-sdk)
* [Node SDK](/docs/server-integration/event-collection/node-sdk)
* [PHP SDK](/docs/server-integration/event-collection/php-sdk)
* [Python SDK](/docs/server-integration/event-collection/python-sdk)
* [Restful API](/docs/server-integration/event-collection/restful-api)
# Java SDK
> 来源：https://help.gravity-engine.com/docs/server-integration/event-collection/java-sdk
> 介绍 Gravity Engine Java SDK 的环境要求、安装初始化、事件追踪和用户属性管理，并提供参数说明与代码示例。
## 概述 [#概述]
Gravity Engine Java SDK 是一个用于数据采集和上报的工具，帮助开发者轻松集成事件追踪和用户行为分析功能。本 SDK 兼容 JDK 8 及以上版本。在接入前，请先阅读 [接入前准备](/docs/getting-started)。服务端接入 Java SDK，完成事件的服务端报送功能，您需要注意以下几点：
* 服务端 SDK 仅负责事件的收集上报，不负责用户的注册，用户注册需要调用客户端 SDK 的 `initialize` 方法完成；
* 客户端和服务端 SDK 使用的用户 `client id` 需要保持一致；
* 在客户端完成 `initialize` 方法调用之后，服务端 SDK 才能开始做事件采集上报，否则上报不成功；
* 服务端 SDK 接入事件上报时，请参考 [元事件页面](https://web.gravity-engine.com/#/manage/metadata/metaEvent) 下关于事件的详情属性；
* 请尽量上报事件的公共属性，引力不做强制要求，但是上报足够多属性，可以方便您后续在引力平台使用数据分析功能（`$city`、`$province`、`$country`、`$browser`、`$browser_version` 属性可以不上报，引力后端会自动采集）；
* 关于属性的更多信息，请您参考 [事件属性页面](https://web.gravity-engine.com/#/manage/metadata/eventProperty)。
### 1. 环境要求 [#1-环境要求]
* JDK 8 或更高版本
* Maven 项目管理工具
### 2. 安装集成 [#2-安装集成]
#### Maven 集成 [#maven-集成]
* Maven 配置私有仓库：`https://nexus.gravity-engine.com/repository/maven-releases/`
```xml
nexus-profile
maven-nexus
https://nexus.gravity-engine.com/repository/maven-releases/
true
true
nexus-profile
```
* 在项目的 `pom.xml` 文件中添加以下依赖：
```xml
cn.gravity.java
gedata
3.0.9
```
#### 手动下载 [#手动下载]
下载 JAR 文件：[下载地址](https://nexus.gravity-engine.com/repository/maven-public/cn/gravity/java/gedata/3.0.8/gedata-3.0.8.jar)
### 3. 初始化配置 [#3-初始化配置]
#### 基础配置 [#基础配置]
```java
public final static String GE_SERVER_MAIN_URL = "https://backend.gravity-engine.com/event_center/api/v1/event/collect/";
public final static String GE_ACCESS_TOKEN = "你的ACCESS_TOKEN";
public static String getMainServerUri() {
return GE_SERVER_MAIN_URL + "?access_token=" + GE_ACCESS_TOKEN;
}
```
#### 选择数据上报模式 [#选择数据上报模式]
**批量上报模式（推荐）**
```java
public static IGEConsumer generateBatchConsumer() {
IGEConsumer consumer = null;
try {
GEBatchConsumer.Config config = new GEBatchConsumer.Config();
config.setBatchSize(20); // 批量大小
config.setMaxCacheSize(10); // 最大缓存数量
String url = getMainServerUri();
consumer = new GEBatchConsumer(url, config);
} catch (Exception ignored) {
}
return consumer;
}
// 初始化
IGEConsumer consumer = generateBatchConsumer();
GEAnalytics ge = new GEAnalytics(consumer, false);
```
## 核心功能 [#核心功能]
### 1. 事件追踪 [#1-事件追踪]
> **注意**
> **如需上报自定义事件，您必须先在 [元事件](https://web.gravity-engine.com/#/manage/metadata/metaEvent) 中添加，否则会上报失败！**
您可以调用 `track` 方法，记录用户自定义事件。
您需要先在 [元事件](https://web.gravity-engine.com/#/manage/metadata/metaEvent) 中添加自定义事件，然后调用 `track` 方法上报自定义事件。
```java
// 设置事件属性
HashMap properties = new HashMap<>();
// 支持的数据类型
properties.put("#ip", "192.168.1.1"); // 字符串
properties.put("channel", "ge"); // 字符串
properties.put("age", 1); // 数字
properties.put("isSuccess", true); // 布尔值
properties.put("birthday", new Date()); // 时间
// 对象类型
HashMap object = new HashMap<>();
object.put("key", "value");
properties.put("object", object);
// 对象数组
HashMap object1 = new HashMap<>();
object1.put("key", "value");
ArrayList