快速接入

约 3189 字大约 11 分钟

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

注意

返回对象为 Promise 类型,请在调用时监听 successfail 回调

  • 首次调用后,需要等 success 回调成功之后才能继续调用其他事件上报的方法
  • 用户整个生命周期内,只需要调用一次,调用成功之后,后续冷启动可以不再调用,只需要保证 SDK 执行初始化逻辑即可(多次调用也不会有问题,引力做了兼容)

提示

关于同步归因的详细介绍,您可以参考同步归因

1.4 历史用户初始化(可选,不建议使用)

警告

  • 一般情况下,您不需要接入这个方法,具体请参考这个文档open in new window中的历史用户导入部分!
  • 该方案接入复杂度较高,不推荐使用,如果有历史用户需要导入,建议使用表格导入的方式,参考这个文档open in new window中的表格导入部分

如果您的产品有较多的历史买量用户数据,为了避免引力重复归因,我们建议您配合使用 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 支持stringnumberbooleanDateArray<string>

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

注意

尽管事件可以设置触发时间,但是接收端会做如下的限制:只接收相对服务器时间在前 10 天至后 1 小时的数据,超过时限的数据将会被视为异常数据,整条数据无法入库!

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

相关信息

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

警告

  • 参数 payAmount 单位为分,请务必注意,传错单位可能会导致买量受到影响!
  • 引力引擎会通过订单号 orderId 去重,避免重复上报,请务必传入!

2.3 设置事件公共属性

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

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

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

  • 如果您需要删除某个公共事件属性,可以调用 unsetSuperProperty 清除其中一个公共事件属性;
  • 如果您想要清空所有公共事件属性,则可以调用 clearSuperProperties;
  • 如果您想要获取所有公共事件属性,可以调用getSuperProperties;
// 清除属性名为 CHANNEL 的公共属性
ge.unsetSuperProperty("CHANNEL");

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

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

注意

公共属性需要先在事件属性open in new window中添加,否则会上报失败!

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. 用户属性上报

目前支持的用户属性设置接口为 userSetuserSetOnceuserAdduserUnsetuserDeleteuserAppend.

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)

提示

引力会自动将引力 client ID 和您传入的数数 account_id 以及 distinct_id 做关联,在回调数数接口时,通过这个关联传递对应的 account_iddistinct_id 给数数后台

5. 发版记录

版本日期备注
1.0.42023-11-09支持历史用户注册、同步归因
1.0.52023-11-09支持 uc 投放
1.0.62023-11-09支持 vivo 投放
2.1.22023-12-12优化接入流程
2.1.32023-12-28支持绑定三方平台
2.1.52024-06-28优化提示