vivo快游戏快速集成
介绍 Gravity Engine vivo 快游戏 SDK 的安装、初始化、用户注册与事件上报流程，并提供参数说明和调用示例。
本文档主要讲述 原生 vivo 快游戏 接入 引力引擎 的技术接入方案，在开始接入前，建议您先阅读 接入前准备 以了解接入必备的基础概念。
本接入方案仅适用于官方 原生 vivo 快游戏 开发的项目。如果您使用的是其他游戏引擎，请访问 引力引擎 SDK 总览页面 选择对应的框架接入文档。
1. 获取 AccessToken
您可以在设置-应用管理页面点击"查看参数"按钮获取当前应用的 AccessToken，请妥善保存避免泄露。
2. 配置并启动 SDK
开始接入工作之前，您需要先下载 SDK。
将 ge_mg_sdk_version.zip 中的 gravityengine.mg.vivo.min.js 导入工程，并初始化 SDK：
每次冷启动过程中，
GravityEngine的实例化方法new GravityEngine()与初始化方法setupAndStart()均只能被调用一次。clientId参数必须在这两个方法的其中一个传入。
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. 初始化
在用户可以获取到用户唯一 ID 时调用此方法，推荐首次启动时调用。
首次调用后，需要在
initialize的then中才能继续调用其他事件上报的方法初始化方法调用成功之后，后续冷启动可以不再调用，只需要正常启动 SDK 即可（多次调用也不会有问题，引力做了兼容）
方法示例
ge.initialize({
name: "your_name",
version: 123,
enable_sync_attribution: false,
})
.then((res) => {
console.log("initialize success", res);
})
.catch((err) => {
console.log("initialize failed", err);
});参数说明
| 参数名称 | 参数含义 | 参数类型 | 是否必传 |
|---|---|---|---|
| name | 用户名或用户唯一 ID（可理解为业务中的昵称），如果不需要昵称，可以填默认值，但是不可以传空字符串！ | string | 是 |
| version | 产品发布版本号，便于后续在引力后台过滤 | number | 是 |
| enable_sync_attribution | 是否开启同步获取归因信息（参考同步归因文档）。在媒体点击下发延迟的情况下会影响归因，请谨慎开启 | boolean | 是 |
| channel | 当前用户来源渠道，对应用户细查中的：客户端渠道 | string | 否 |
| adData | 预设归因信息 | object | 否 |
4. 事件上报
4.1 业务注册事件上报
此功能仅适用于需要统计业务注册转化数据的场景。如果您的应用不需要追踪用户注册行为，可以跳过此事件接入。
该方法可多次调用，每次调用都会上报一个用户注册事件（计算指标时会去重）
当用户完成应用内业务注册后，您可以调用 registerEvent 方法来上报用户注册事件（$MPRegister）给引力，引力会使用该事件统计指标：标准_注册数
调用示例
ge.registerEvent();4.2 付费事件上报
付费事件上报用于收入统计和分析，如您的应用不涉及内购或付费服务，则无需接入此事件。
如果您需要通过后端 API 方式上报付费事件，请参考 混合上报模式 来接入事件上报接口报送付费事件。
当用户发生付费行为时，需要调用 payEvent 方法记录用户付费事件，此事件非常重要，会影响买量和 ROI 统计，请务必重点测试！
方法示例
ge.payEvent(payAmount, payType, orderId, payReason, payMethod);参数说明
| 参数名称 | 参数含义 | 参数类型 | 是否必传 |
|---|---|---|---|
| payAmount | 付费金额，单位为分。请务必注意，传错单位可能会导致买量受到影响！ | number | 是 |
| payType | 货币类型，按照国际标准组织 ISO 4217 中规范的 3 位字母，例如 CNY 人民币、USD 美金等，具体请参考：国际标准组织 ISO 4217 代码表 | string | 是 |
| orderId | 订单号。引力引擎会通过订单号去重，避免重复上报，请务必准确传入！ | string | 是 |
| payReason | 付费原因，例如：购买钻石、办理月卡 | string | 是 |
| payMethod | 付费方式，例如：支付宝、微信、银联等 | string | 是 |
调用示例
ge.payEvent(300, "CNY", "your_order_id", "月卡", "支付宝");4.3 广告观看事件上报
广告观看上报适用于广告变现类应用，若您的应用未集成广告模块，则无需接入此事件。
若您的产品内有广告变现，则需要在用户点击广告观看的同时上报用户广告观看事件给引力，具体参考如下：
方法示例
ge.miniGameAdShowEvent(adType, adUnitId, otherProperties);参数说明
为生成准确的广告收益分析报表，请尽量遵循规范填写下方的广告平台参数。正确的字段是生成有价值报表的基础。
我们为您准备了详细的指引：广告聚合平台字段配置说明
| 参数名称 | 参数含义 | 参数类型 | 是否必传 |
|---|---|---|---|
| adType | 广告类型（取值为：reward(激励视频广告)、banner(横幅广告)、native(信息流广告)、interstitial(插屏广告)、splash(开屏广告)、video_feed(视频信息流)、video_begin(贴片广告)） | string | 是 |
| adUnitId | 广告位 ID。一般以 adunit 开头，注意不要填错 | string | 是 |
| otherProperties | 自定义参数。其他需要携带的自定义参数，需要提前在引力后台元数据管理中针对广告观看（$AdShow）事件配置好相关属性，比如快游戏上报广告 ecpm，可以使用引力预置好的属性字段：$ecpm，具体见下发代码示例。 | object | 是 |
调用示例
ge.miniGameAdShowEvent("reward", "your_ad_unit_id", { custom_param: "12345" });
// 如果需要上报当次广告曝光的 ECPM，代码示例如下
ge.miniGameAdShowEvent("reward", "your_ad_unit_id", { $ecpm: 1000 });5. 接入验证
正式上线之前，请完成本节的校验，否则可能会导致买量上报异常！
5.1 关键事件验证
在引力后台事件流界面开启加载实时数据，并在产品中触发以下几个事件。事件流使用说明：事件流 - 飞书云文档
| 事件名 | 事件英文名 | 触发时机 | 采集方式 | 默认映射到媒体事件 | 备注 |
|---|---|---|---|---|---|
| 用户注册 | $MPRegister | 用户完成业务注册之后 | 调用 SDK 的上报业务注册事件方法采集 | 暂无 | 接入了业务注册上报事件的产品均需要校验 |
| 付费 | $PayEvent | 用户付费之后 | 调用 SDK 的上报用户付费事件方法采集 | 付费 | 接入了付费事件上报事件的产品均需要校验 |
| 广告展示 | $AdShow | 用户观看广告之后 | 调用 SDK 的上报广告展示事件方法采集 | 暂无 | 接入了广告事件上报事件的产品均需要校验 |
触发操作后，请在事件流界面中筛选测试用户的 Client ID，观察对应事件是否出现在实时入库页面。若事件数据正常显示，则说明接入成功；如出现于错误数据页面请根据页面错误提示进行排查；如未显示对应数据，请及时联系引力运营支持团队获取协助。
5.2 避免重复上报
如果您之前单独接了媒体的回传（SDK 或者 API），则上线之前需要去掉，否则可能会导致重复上报数据！
至此验证无误之后，您可以正常上线了。
以上是 SDK 的基础接入指引。如需使用 行为事件上报、用户属性上报、进阶功能、自动采集 等功能，请参考以下文档：
注意：这些功能并非所有业务场景都需要，请按需查阅。