快速接入

约 7468 字大约 25 分钟

小程序/小游戏/快应用 SDK 接入指南

GravityAnalytics MP Library 是为小程序、小游戏、快应用等平台实现的数据埋点+买量归因+批量投放的工具 SDK，我们通过打包时对部分代码的替换，实现多个平台的适配，目前 SDK 支持以下技术栈接入：

支持以下小程序、小游戏平台

  • 微信小程序/小游戏
  • 抖音小程序/小游戏
  • 支付宝小程序/小游戏
  • 快手小程序/小游戏
  • 百度小游戏
  • Bilibili 小游戏
  • QQ 小游戏
  • 快应用/快游戏

提示

在接入前, 请先阅读 接入前准备

注意

在正式上线之前，请参考 接入验证 完成接入校验。

一、配置并启动 SDK

开始接入工作之前，您需要先下载 SDKopen in new window，然后再根据您的技术栈选择不同的接入方式。

将 ge_mg_sdk_version.zip 中的 gravityengine.mg.wx.min.js导入工程，并初始化 SDK：

import GravityEngine from "./js/utils/gravityengine.mg.wx.min";
const config = {
  accessToken: "your_access_token", // 项目通行证，在：网站后台-->设置-->应用列表中找到Access Token列 复制（首次使用可能需要先新增应用）
  clientId: "your_client_id", // 用户唯一标识，如产品为小游戏，则必须填用户openid（注意，不是小游戏的APPID！！！）
  autoTrack: {
    appLaunch: true, // 自动采集 $MPLaunch
    appShow: true, // 自动采集 $MPShow
    appHide: true, // 自动采集 $MPHide
  },
  name: "ge", // 全局变量名称, 默认为 gravityengine
  debugMode: "debug", // 是否开启测试模式，开启测试模式后，可以在 网站后台--设置--元数据--事件流中查看实时数据上报结果。（测试时使用，上线之后一定要关掉，改成none或者删除）
};
const ge = new GravityEngine(config);
ge.setupAndStart();

其他可能会用到的配置有：

sendTimeout: 3000, // 网络请求超时时间，单位毫秒，默认值 3000 ms
maxRetries: 3, // 网络请求失败时的重试次数，1 表示不重试。默认值是 3
enablePersistence: true, // 是否使用本地缓存，主实例默认为 true，子实例默认为 false
asyncPersistence: false, // 是否使用异步存储，默认为 false

配置项目合法域名

如果您的项目为小游戏或者小程序，您需要将 https://backend.gravity-engine.com 配置到后台 request 合法域名列表中。

二、配置 SDK

2.1 初始化

在用户可以获取到用户唯一 ID 时调用此方法，推荐首次启动时调用。

/**
 * @param {string} name                           用户名，可以理解成用户在业务中的昵称，如果没有，可以填用户唯一ID（必填）
 * @param {number} version                        用户初始化的程序发布更新的版本号（必填）
 * @param {string} openid                         open id (小程序/小游戏必填)
 * @param {string} enable_sync_attribution        是否开启同步获取归因信息，具体请参考同步归因：https://doc.gravity-engine.com/turbo-integrated/sync_attribution.html
 */

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

注意

返回对象为 Promise 类型，请在调用时监听 success 和 fail 回调

  • 首次调用后，需要等 success 回调成功之后才能继续调用其他事件上报的方法
  • 用户整个生命周期内，只需要调用一次，调用成功之后，后续冷启动可以不再调用，只需要正常启动 SDK 即可

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

警告

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

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

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

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

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

2.3 公共属性

提示

公共事件属性是所有事件（包括自动采集事件）都会包含的属性，用户属性中不会包含。

本节会介绍如何设置公共事件属性和动态公共属性。如果公共属性与事件中设置的自定义属性有相同 key 值，则最终的属性会根据下述优先级取值：

用户自定义事件属性 > 动态公共属性 > 事件公共属性

您可以调用 setSuperProperties来设置公共事件属性，公共事件属性的格式要求与事件属性一致。在设置时只能传入常量，适合设置变化不频繁的属性。

提示

根据属性优先级，自定义属性优先级高于事件公共属性，因此事件公共属性也可以作为某个属性的缺省值，在需要修改的事件中设置同名 Key 覆盖缺省值。

//设置公共事件属性
ge.setSuperProperties({ step: "第三关" });

//使用track上传事件，此时事件中会带有公共事件属性
ge.track(
  "Purchase", //追踪事件的名称
  {
    Item: "商品A",
    ItemNum: 1,
    Cost: 100,
  } //需要上传的事件属性
);

/* 等价于在事件中加入这些公共属性
ge.track(
    'Purchase', //追踪事件的名称
    {
        Item:'商品A',
        ItemNum:1,
        Cost:100,
        channel:'渠道' //相当于在事件中加入这个属性
    } 
);
*/

如果多次调用 setSuperProperties 设置公共事件属性，则同名字段后面的调用会覆盖之前的，不同名字段。

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

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

//清除公共事件属性
ge.clearSuperProperties();

//获取静态公共事件属性
ge.getSuperProperties();

三、发送事件

您可以直接调用 track上传自定义事件，建议您根据准备阶段梳理的文档来设置事件的属性以及发送信息的条件，此处以购买商品为范例：

ge.track(
  "$purchase", //追踪事件的名称
  {
    Item: "商品A",
    ItemNum: 1,
    Cost: 100,
    Elements: ["apple", "ball", "cat"],
  } //需要上传的事件属性
);
  • track 接口共有两个参数，第一个参数为事件的名称，第二个参数为事件的属性
  • 事件的名称是字符串，只能以字母开头，可包含数字，字母和下划线“_”，长度最大为 50 个字符。
  • 事件的属性是 JS 对象，每个元素代表一个属性。
  • 元素的 name 对应属性的名称，规定只能以字母开头，包含数字，字母和下划线“_”，长度最大为 50 个字符。
  • 元素的 Value 为该属性的值，支持 String、Integer、Float、Boolean、Date、DateTime和 Array;Array中的内容可以为 String

注意

如需上报自定义事件，建议您先在元事件open in new window中添加，否则会上报失败！

引力引擎后台内置了一些预置事件，您可以通过以下方法分别上报：付费、广告观看事件。

3.1 业务注册事件上报（可选）

当用户完成应用内业务注册后，您可以调用 registerEvent 方法来上报用户注册事件($MPRegister)给引力，引力会使用该事件统计指标：标准_注册数。

ge.registerEvent();

相关信息

该方法可多次调用，每次调用都会上报一个用户注册事件（计算指标时会去重）。

3.2 付费事件上报

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

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

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

相关信息

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

警告

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

3.3 广告观看事件上报(仅微信、支付宝小游戏、小程序需要接入)

若您的产品内有广告变现，则需要在用户点击广告观看的同时上报用户广告观看事件给引力，具体参考如下：

/**
 * 上报广告展示事件 参数如下
 * @param adType                广告类型 （取值为：reward、banner、native、interstitial、video_feed、video_begin，分别对应激励视频广告、Banner广告、原生模板广告、插屏广告、视频广告、视频贴片广告）
 * @param adUnitId              广告位ID（一般以adunit开头，注意不要填错，会导致广告收入统计不准！）
 * @param otherProperties       其他需要携带的自定义参数
 */
ge.adShowEvent("reward", "your_ad_unit_id", { custom_param: "" });

警告

  • 需要参照 微信广告变现实时统计 一文，检查是否正确配置微信 access_token ，配置错误将无法正确获取广告变现数据！
  • 仅微信、支付宝小游戏、小程序需要接入，抖音小游戏不要接入！抖音小游戏会由引力后端自动拉取。

3.4 设置事件上报时间

事件触发的时间默认取本机时间，但在一些情况下，可能需要手动设置事件的时间，可以使用以下方法进行调用：

//第三个参数，可以输入Date类型的参数，替换事件触发时间
ge.track("event", { parakey: "paravalue" }, new Date());

//如果没有properties需要上传，请传入一个空对象
ge.track("event", {}, new Date());

提示

第三个参数为事件触发时间，必须是 Date 类型，将会替换事件触发的时间，如果不传该参数，则事件触发时间默认选取用户的本机时间

3.5 记录事件时长

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

//用户进入商品页面，开始计时，记录的事件为"Enter_Shop"
ge.timeEvent("Enter_Shop");

//...

//上传事件，计时结束，"Enter_Shop"这一事件中将会带有表示事件时长的属性$event_duration
ge.track("Enter_Shop", { product_id: "A1354" });

四、用户属性

4.1 设置用户属性

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

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

属性格式要求与事件属性保持一致。

4.2 初始化用户属性

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

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

属性格式要求与事件属性保持一致。

4.3 累加用户属性

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

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

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

4.4 重置用户属性

当您要清空用户的某个用户属性值时，您可以调用 userUnset来对指定属性进行清空操作，如果该属性还未在集群中被创建，则 userUnset不会创建该属性

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

userUnset: 的传入值为被清空属性的 Key 值。

4.5 清空用户属性

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

ge.userDel();

4.6 Array 属性 追加

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

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

4.7 Array 属性 去重追加

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

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

4.8 用户属性取最大值

userNumberMax 用来比较数值大小，保存较大的，如果没有这个 key，则新增 key，value 取本次的值

ge.userNumberMax({
  ad_ecpm_max: 300,
});

4.9 用户属性取最小值

userNumberMin 用来比较数值大小，保存较小的，如果没有这个 key，则新增 key，value 取本次的值

ge.userNumberMin({
  ad_ecpm_min: 17,
});

五、其他功能

5.1 自动采集事件

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

5.2 开启 Debug 模式

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

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

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

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

var config = {
  debugMode: "debug",
};
var ge = new GE(config);

5.3 onComplete 回调函数

对于 track, userSet, userSetOnce, userAdd, userDel, userAppend, userUniqAppend、userNumberMax、userNumberMin 等方法，支持传入 onComplete 回调. 可以直接在原参数列表后传入 onComplete,

也可以使用参数对象的方式. 如果使用参数对象，参数对象中必须包含 onComplete, 否则会出现参数错误.

以上传事件为例：

// 以参数列表的形式传入回调
ge.track("test", { testkey: 123 }, new Date(), (res) => {
  console.log(res);
});

// 以参数对象的形式传入回调
ge.track({
  eventName: "test", // 必填
  properties: { testkey: 123 }, // 可选
  time: new Date(), // 可选
  onComplete: (res) => {
    console.log(res);
  }, // 必填
});

onComplete 的参数 res 为 object 类型，有两个属性 code 和 msg.

  • res.code 为 int 类型，定义如下:

    • 0：成功
    • -3：网络或服务端异常
    • 2001：应用未授权或已过期
    • 2000：权限不足 该用户尚未初始化
    • 1004：参数错误 一般是参数类型错误，或者缺失参数
    • 1001：数据错误 json 解析错误

  • res.msg 是对 res.code 的文字说明。

5.4 绑定三方平台

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

5.4.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_id、distinct_id 给数数后台

Copyright © 2024 引力引擎 @ 粤ICP备20048596号