Web SDK 快速集成

介绍 Gravity Engine Web SDK 的安装、初始化、用户注册与事件上报流程，并提供参数说明和调用示例。

本文档为 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,
  },
  isChina: true, // 是否使用国内域名，默认为 true
  showLog: true,
  useAppTrack: true,
  accessToken: "Yf2HrgFlP6dmNMz5wfytbaorqzJv9i7x", // 项目通行证，在：网站后台 --> 设置 --> 应用列表中找到 Access Token 列 复制（首次使用可能需要先新增应用）
  // clientId: "your_client_id", // 用户唯一标识，如果不传，就用 SDK 生成的 uuid 代替
  // useAppTrack: true, // 设置 Native 打通
};

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 关键事件验证

在引力后台事件流界面开启加载实时数据，并在产品中触发以下几个事件。事件流使用说明：事件流 - 飞书云文档

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

触发操作后，请在事件流界面中筛选测试用户的 Client ID，观察对应事件是否出现在实时入库页面。若事件数据正常显示，则说明接入成功；如出现于错误数据页面请根据页面错误提示进行排查；如未显示对应数据，请及时联系引力运营支持团队获取协助。

4.2 避免重复上报

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

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

快速集成

本页内容