菜单

快速集成

本文档为JavaScript接入 引力引擎的技术接入方案，JavaScript SDK 运行环境需为浏览器，暂不兼容 IE 8 及以下版本。

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

1. SDK 基础配置

1.1 SDK 引入

下载最新的SDK 文件，并导入到您的项目中，推荐使用 gravityEngine.umd.min.js。

如果您想使用其他类型，使用参考如下：

  • 当您想使用 commonjs require 引入时，可使用 gravityEngine.cjs.min.js；
  • 当您想使用 es6 import 引入时，可使用 gravityEngine.esm.min.js；
<script src="./gravityengine.umd.min.js"></script>

1.2 配置并启动 SDK

请直接复制以下代码到您项目中需要进行引力引擎初始化的地方，一般建议在能够获取到用户唯一 ID 时调用。

const config = {
  autoTrack: {
    pageShow: true,
    pageHide: true,
  },
  mode: "none",
  showLog: true,
  accessToken: "Yf2HrgFlP6dmNMz5wfytbaorqzJv9i7x", // 项目通行证，在：网站后台-->设置-->应用列表中找到Access Token列 复制（首次使用可能需要先新增应用）
  // clientId: "your_client_id", // 用户唯一标识，如果不传，就用sdk生成的uuid代替
};

window.ge = gravityEngine;
ge.setupAndStart(config);

2.初始化

在用户可以获取到用户唯一性信息时调用 ge.initialize 方法，推荐首次安装启动时调用，后续其他方法均需在本方法回调成功之后才可正常使用。

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

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

方法示例

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 是否开启同步获取归因信息（参考同步归因文档） boolean 是
channel 当前用户来源渠道，对应用户细查中的：客户端渠道（默认值：base_channel） string 否

3.事件上报

3.1 付费事件上报

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

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

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

方法示例

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

参数说明

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

4.接入验证

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

4.1 开启 Debug 模式

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

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

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

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

var config = {
  mode: "debug",
};
// 调用init的时候，传入此config

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

4.2 关键事件验证

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

事件名 事件英文名 触发时机 采集方式 默认映射到媒体事件 备注
付费 $PayEvent 用户付费之后 调用 SDK 的 上报用户付费事件 方法采集 付费 接入了付费事件上报事件的的产品均需要校验

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

4.3 避免重复上报

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

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

 

 

 

上一个
Web
下一个
行为事件上报
最近修改: 2025-09-10Powered by