# JavaScript SDK 接入指南

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

# 1. SDK 基础配置

# 1.1 SDK 引入

下载最新的 GravityEngine.jsopen in new window sdk 文件，并导入到您的项目中.

# 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);

# 1.3 初始化

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

/**
 * @param {string} name                     用户名，可以理解成用户在业务中的昵称，如果没有，可以填用户唯一ID（必填）
 * @param {number} version                  用户初始化的程序发布更新的版本号（必填）
 * @param {boolean} enable_sync_attribution 是否开启同步归因
 */

ge.initialize({
  name: "your_name",
  version: 123,
  enable_sync_attribution: false,
})
  .then((res) => {
    console.log("initialize success " + res);
  })
  .catch((err) => {
    console.log("initialize failed, error is " + err);
  });

# 1.4 历史用户初始化（可选，不建议使用）

如果您的产品有较多的历史买量用户数据，为了避免引力重复归因，我们建议您配合使用 initializeWithHistoryUserInfo 方法来实现初始化。

您需要后端同学配合，查询自有用户数据库来获取用户归因媒体和注册时间，并进行判断：

• 如果是新用户，则调用 initialize 方法完成引力初始化
• 如果是历史用户，则调用 initializeWithHistoryUserInfo 方法完成初始化

/**
 * @param {string} name         用户名，可以理解成用户在业务中的昵称，如果没有，可以填用户唯一ID（必填）
 * @param {number} version      用户初始化的程序发布更新的版本号（必填）
 * @param {string} company      归因媒体，允许的枚举值请参考：https://doc.gravity-engine.com/turbo-integrated/others/enum.html
 * @param {string} create_time  历史用户注册时间，为毫秒级时间戳
 */

ge.initializeWithHistoryUserInfo(
  {
    name: "your_name",
    version: 123,
  },
  {
    company: "bytedance",
    create_time: 1697079715332,
  }
)
  .then((res) => {
    console.log("initialize success " + res);
  })
  .catch((err) => {
    console.log("initialize failed, error is " + err);
  });

# 2. 行为事件上报

通过 ge.track方法可以上报事件及其属性。一般情况下，您可能需要上传十几到上百个不同的事件，如果您是第一次使用引力引擎事件采集系统，我们推荐您先上传几个关键事件。

我们也支持了页面显示和页面隐藏 2 个自动采集事件，您可以根据业务需求选择是否开启自动采集事件。

# 2.1 自定义事件上报

建议您先在元事件open in new window中添加自定义事件，然后在页面中指定位置埋点调用 track 方法上报自定义事件。

ge.track("test", {
  $pay_type: "rmb",
});

• 事件名称是 string 类型，只能以字母开头，可包含数字，字母和下划线 “_”，长度最大为 50 个字符。
• 事件属性是 Record<string, object> 类型，其中每个元素代表一个属性；
  • 事件属性 Key 为属性名称，为 string 类型，规定只能以字母开头，包含数字，字母和下划线 “_”，长度最大为 50 个字符；
  • 属性 Value 支持string、number、boolean、Date、Array<string>；

当您调用 ge.track() 时，SDK 会取系统当前时间作为事件发生的时刻，如果您需要指定事件时间，可以传入 Date 类型的参数来设置事件触发时间。

# 2.2 付费事件上报

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

/**
 * 上报付费事件
 * @param payAmount     付费金额 单位为分
 * @param payType       货币类型 按照国际标准组织ISO 4217中规范的3位字母，例如CNY人民币、USD美金等
 * @param orderId       订单号
 * @param payReason     付费原因 例如：购买钻石、办理月卡
 * @param payMethod     付费方式 例如：支付宝、微信、银联等
 * @param isFirstPay    是否首次付费
 */
ge.payEvent(300, "CNY", "your_order_id", "月卡", "支付宝", true);

国际标准组织 ISO 4217 代码表open in new window

# 2.3 设置事件公共属性

对于一些重要的属性，譬如玩家的区服和渠道等，这些属性需要设置在每个事件中，此时您可以将这些属性设置为公共事件属性。公共事件属性指的就是每个事件都会带有的属性，您可以调用 setSuperProperties 来设置公共事件属性，我们推荐您在发送事件前，先设置公共事件属性。

//设置公共事件属性
ge.setSuperProperties({ channel: "your channel" });

公共事件属性将会被保存到缓存中，无需每次启动 APP 时调用。如果调用 setSuperProperties 上传了先前已设置过的公共事件属性，则会覆盖之前的属性。如果公共事件属性和 ge.track() 上传的某个属性的 Key 重复，则该事件的属性会覆盖公共事件属性。

• 如果您需要删除某个公共事件属性，可以调用 unsetSuperProperty 清除其中一个公共事件属性；
• 如果您想要清空所有公共事件属性，则可以调用 clearSuperProperties;
• 如果您想要获取所有公共事件属性，可以调用getSuperProperties;

// 清除属性名为 CHANNEL 的公共属性
ge.unsetSuperProperty("CHANNEL");

// 清空所有公共属性
ge.clearSuperProperties();

// 获取所有公共属性
ge.getSuperProperties();

# 2.4 记录事件时长

如果您需要记录某个事件持续时长，您可以调用 timeEvent() 来开始计时，配置您想要计时的事件名称，当您上传该事件时，将会自动在您的事件属性中加入 $event_duration 这一属性来表示记录的时长，单位为秒。

// 调用 TimeEvent 开启对 TIME_EVENT 事件的计时
ge.timeEvent("Enter_Shop");

// do some thing...

// 通过 Track 上传 TIME_EVENT 事件时，会在属性中添加 $event_duration 属性
ge.track("Enter_Shop", { product_id: "A1354" });

# 2.5 立即上报事件

如果需要立即上报缓存的事件，可以调用 flush() 来上报所有缓存的事件。

// 调用 flush() 上报缓存事件
ge.flush();

# 3. 用户属性上报

目前支持的用户属性设置接口为 userSet、userSetOnce、userAdd、userUnset、userDelete、userAppend.

# 3.1 设置用户属性

对于一般的用户属性，您可以调用 userSet 来进行设置，使用该接口上传的属性将会覆盖原有的属性值，如果之前不存在该用户属性，则会新建该用户属性。

//设置用户属性，会员等级
ge.userSet({ vip_level: "钻石会员" });

# 3.2 初始化用户属性

如果您要上传的用户属性只要设置一次，则可以调用 userSetOnce 来进行设置，当该属性之前已经有值的时候，将会忽略这条信息：

//以设置用户名为例，如果用户名已设置，则忽略本次设置，如果不存在，则设置为传入值
ge.userSetOnce({ user_name: "TestUser" });

# 3.3 累加用户属性

当您要上传数值型的属性时，您可以调用 userAdd 来对该属性进行累加操作，如果该属性还未被设置，则会赋值 0 后再进行计算，可传入负值，等同于相减操作。

//以付费为例，用户每次付费时调用此接口，则'total_revenue'字段每次会做累加付费金额的处理
ge.userAdd({ total_revenue: 50 });

设置的属性 key 为字符串，Value 只允许为数值。

# 3.4 重置用户属性

如果您需要重置用户的某个属性，可以调用 userUnset 将该用户指定用户属性的值重置，此接口支持传入字符串、列表、布尔类型的参数:

//清空属性名为userPropertyKey的用户属性值该用户，即设置成NULL
ge.userUnset("userPropertyKey");

UserUnset: 的传入值为被重置属性的 Key 值。

# 3.5 清空用户属性

如果您要删除某个用户，可以调用 userDelete 将这名用户删除，您将无法再查询该名用户的用户属性，但该用户产生的事件仍然可以被查询到。

ge.userDel();

# 3.6 Array 属性追加

您可以调用 userAppend 对 Array (List) 类型的用户数据追加元素。

ge.userAppend({ Movies: ["Interstellar", "The Negro Motorist Green Book"] });

# 3.7 Array 属性 去重追加

userUniqAppend 用来对 Array (List) 类型的用户数据去重追加元素。

ge.userUniqAppend({
  Movies: ["Interstellar", "The Negro Motorist Green Book"],
});

# 4. 其他功能

# 4.1 自动采集事件

引力引擎 SDK 支持自动采集一些基础事件以降低您的接入成本，您可以参考自动采集一文来快速开启。

# 4.2 开启 Debug 模式

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

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

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

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

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

# 4.3 绑定三方平台

引力支持与其他三方的数据分析平台打通，具体调用如下：

# 4.3.1 数数

ge.bindTAThirdPlatform(CURRENT_USER_TA_ACCOUNT_ID, CURRENT_USER_TA_DISTINCT_ID);

参数说明：

• CURRENT_USER_TA_ACCOUNT_ID：当前用户的数数账户 ID (#account_id)
• CURRENT_USER_TA_DISTINCT_ID：当前用户的数数访客 ID (#distinct_id)

# 5. 发版记录