@thinkingai/ae-cli 1.0.30 → 6.0.16

package/wiki/te-docs/raw//345/256/242/346/210/267/347/253/257-sdk//346/270/270/346/210/217/345/274/225/346/223/216/layaair//350/277/233/351/230/266/346/214/207/345/215/227.md

@@ -0,0 +1,597 @@
+---
+code: laya_sdk_advanced
+name: "进阶指南"
+wikiToken: UGaFwQQPEi69XukGdVocvRTSnjh
+parentWikiToken: DwgQwnSQpibhLEkcrR8cQbaHnKg
+updateTime: 1776262596000
+sourceUrl: https://docs-v2.thinkingdata.cn/?version=v6.0&lan=zh-CN&code=laya_sdk_advanced
+---
+
+## 一、设置用户ID
+SDK 实例默认会使用随机数作为每个用户的默认访客 ID，该 ID 将会作为用户在未登录状态下身份识别 ID。需要注意的是，访客 ID 在用户清理缓存以及更换设备时将会变更。
+### 1.1 设置访客 ID
+::: tip 提示
+ 一般情况下，您不需要自定义访客 ID. 请确保已经理解[<text color="purple" underline="true">用户识别规则</text>](https://thinkingdata.feishu.cn/wiki/AUyiw6XZsiF9EMk2fBScKjzunjd)，再进行访客 ID 的设置。
+ :::
+如果您的 App 对每个用户有自己的访客 ID 管理体系，则您可以调用 `setDistinctId` 来设置访客 ID：
+```java
+// 将访客ID设置为Thinker
+TDAnalytics.setDistinctId("Thinker");
+```
+
+如果需要获得当前访客 ID，可以调用 `getDistinctId` 获取：
+```java
+TDAnalytics.getDistinctIdAsync((distinctId)=>{
+//返回访客ID
+});
+```
+
+<quote-container>
+如果需要进行设置，必须在初始化之前调用本接口
+</quote-container>
+
+### 1.2 设置账号 ID
+在用户进行登录时，可调用 `login` 来设置用户的账号 ID， AE 平台将会以账号 ID 作为身份识别 ID，并且设置的账号 ID 将会在调用 `logout` 之前一直保留。多次调用 `login` 将覆盖先前的账号 ID 。
+```javascript
+//用户的登录唯一标识，此数据对应上报数据里的#account_id，此时#account_id的值为TA
+TDAnalytics.login("TA");
+```
+
+<quote-container>
+**该方法不会上传登录事件**
+</quote-container>
+
+### 1.3 清除账号ID
+在用户产生登出行为之后，可调用 `logout` 来清除账号 ID，在下次调用 `login` 之前，将会以访客 ID 作为身份识别 ID。
+```javascript
+// 去除上报数据里的 "#account_id"，之后的数据将不带有 "#account_id"
+TDAnalytics.logout();
+```
+
+我们推荐您在显性的登出事件时调用 `logout`，比如用户产生了注销账号这一行为时才调用，而不需要在关闭 App 时调用。
+<quote-container>
+**该方法不会上传登出事件**
+</quote-container>
+
+## 二 、发送事件
+在 SDK 初始化完成之后，您就可以进行数据埋点，收集用户的的行为信息。一般情况下普通事件即可满足业务场景需求，您也可以根据自己的实际业务场景使用首次、可更新等事件。
+### 2.1 普通事件
+您可以调用 `track` 来上传事件，建议您根据先前梳理的文档来设置事件的属性以及发送事件的条件，此处以用户购买某商品作为范例
+```javascript
+TDAnalytics.track({
+    eventName: "product_buy", // 事件名称
+    properties: {
+        product_name: "商品名"
+    } //事件属性
+});
+```
+
+### 2.2 首次事件
+首次事件是指针对某个设备或者其他维度的 ID，只会记录一次的事件。例如在一些场景下，您可能希望记录在某个设备上的激活事件，则可以用首次事件来上报数据。
+```javascript
+TDAnalytics.trackFirst({
+    eventName: "device_activation",
+    properties: { key: "value" }
+});
+```
+
+如果您希望以设备以外的其他维度来判断是否首次，则可以为首次事件自定义first_check_id:
+```javascript
+// 将用户ID设置为首次事件的first_check_id，实现用户首次激活事件的采集
+TDAnalytics.trackFirst({
+  eventName: "account_activation",
+  firstCheckId: "TA",
+  properties: { key: "value" }
+});
+```
+
+<quote-container>
+注意：由于在服务端完成对是否首次的校验，首次事件默认会延时 1 小时入库。
+</quote-container>
+
+### 2.3 可更新事件
+您可以通过可更新事件实现特定场景下需要修改事件数据的需求。可更新事件需要指定标识该事件的 ID，并在创建可更新事件对象时传入。AE 后台将根据事件名和事件 ID 来确定需要更新的数据。
+```javascript
+// 示例： 上报可被更新的事件，假设事件名为 UPDATABLE_EVENT
+// 上报后事件属性 status 为 3, price 为 100
+TDAnalytics.trackUpdate({
+  eventName: "UPDATABLE_EVENT",
+  properties: { status: 3, price: 100 },
+  eventId: "test_event_id"
+});
+
+// 上报后事件属性 status 被更新为 5, price 不变
+TDAnalytics.trackUpdate({
+  eventName: "UPDATABLE_EVENT",
+  properties: { status: 5 },
+  eventId: "test_event_id"
+});
+```
+
+### 2.4 可重写事件
+可重写事件与可更新事件类似，区别在于可重写事件会用最新的数据完全覆盖历史数据，从效果上看相当于删除前一条数据，并入库最新的数据。AE 后台将根据事件名和事件 ID 来确定需要更新的数据。
+```javascript
+// 示例： 上报可被重写的事件，假设事件名为 OVERWRITE_EVENT
+// 上报后事件属性 status 为 3, price 为 100
+TDAnalytics.trackOverwrite({
+  eventName: "OVERWRITE_EVENT",
+  properties: { status: 3, price: 100 },
+  eventId: "test_event_id"
+});
+
+// 上报后事件属性 status 被更新为 5, price 属性被删除
+TDAnalytics.trackOverwrite({
+  eventName: "OVERWRITE_EVENT",
+  properties: { status: 5 },
+  eventId: "test_event_id"
+});
+```
+
+### 2.5 公共事件属性
+对于一些重要的属性，譬如用户的设备 ID、来源渠道、用户状态等，这些属性需要设置在每个事件中，此时您可以将这些属性设置为公共属性，即每个事件中都带有的属性。我们推荐您在发送事件前，先设置公共属性。
+公共属性包含两种，事件公共属性和动态公共属性。在事件上报时，公共属性将会被插入到数据的 properties 中。如果此时公共属性与事件中设置的自定义属性有相同 key 值，则属性会根据下述优先级判断该取什么值：`自定义属性>动态公共事件属性>静态公共事件属性>预置属性`
+#### 2.5.1 静态公共事件属性
+对于一些重要的属性，譬如用户的渠道、昵称、ID 等，这些属性需要设置在每个事件中，您可以调用`setSuperProperties` 来设置静态公共事件属性，静态公共事件属性会对全局生效。当开启缓存时（默认打开），静态公共属性会缓存在 `localStorage` 或 `cookie` 中。
+ 静态公共属性的参数是一个 JSON 对象，其格式要求与事件属性保持一致。
+```javascript
+// 设置公共事件属性，所有数据事件中都会带有这些属性
+TDAnalytics.setSuperProperties({ channel: "渠道名", user_name: "用户名" });
+```
+
+ 除了属性设置，我们也提供其他API来操作静态公共事件属性，满足日常的业务需求。
+```javascript
+// 获取静态公共事件属性
+var superProperties = TDAnalytics.getSuperProperties();
+// 清除一条静态公共事件属性，比如将之前设置 'channel' 属性清除，之后的数据将不会该属性
+TDAnalytics.unsetSuperProperty("channel");
+// 清除所有静态公共事件属性
+TDAnalytics.clearSuperProperties();
+```
+
+#### 2.5.2 动态公共事件属性
+通过 `setDynamicSuperProperties` 设置动态公共属性的回调函数，SDK 将会在事件上报时触发回调函数，并把返回 JSON 对象加入到事件属性中。`setDynamicSuperProperties` 的参数是一个函数，函数需要返回一个 JSON 对象。
+```javascript
+// 设置动态公共属性，在事件上报时触发回调函数，并把返回的JSON对象加入到事件属性中
+TDAnalytics.setDynamicSuperProperties(function() {
+  var d = new Date();
+  d.setHours(10);
+  return { date: d };
+});
+```
+
+### 2.6 记录事件时长
+如果您需要记录某个事件的持续时长，可以调用 `timeEvent` 来开始计时。配置您想要计时的事件名称，当您上传该事件时，将会自动在您的事件属性中加入 `#duration` 这一属性来表示记录的时长，单位为秒。需要注意的是，同一个事件名只能有一个在计时的任务。
+```javascript
+//以下示例，完成用户在某个商品页面停留时长的统计
+TDAnalytics.timeEvent({
+    eventName: "stay_shop"
+});
+/**do someting
+    .......
+**/
+//用户离开商品页面，计时结束，"stay_shop" 这一事件中将会带有表示事件时长的属性#duration
+TDAnalytics.track({
+    eventName: "stay_shop",
+    properties: {
+        product_name: "商品名"
+    }
+});
+```
+
+## 三、用户属性
+AE 平台支持的用户属性设置API有: `userSet`、`userSetOnce`、`userAdd`、`userUnset`、`userDelete`、`userAppend`、`userUniqAppend`。
+### 3.1 userSet
+ 对于一般的用户属性，您可以调用 `userSet` 来进行设置。使用该接口上传的属性将会覆盖原有的属性值，如果之前不存在该用户属性，则会新建该用户属性，类型与传入属性的类型一致，此处以设置用户名为例：
+```javascript
+// username为TA
+TDAnalytics.userSet({
+    properties: {
+        username: "TA" 
+    }
+});
+//username为AE
+TDAnalytics.userSet({
+    properties: {
+        username: "TE" 
+    }
+});
+```
+
+### 3.2 userSetOnce
+如果您要上传的用户属性只要设置一次，则可以调用 `userSetOnce` 来进行设置，当该属性之前已经有值的时候，将会忽略这条信息，以设置首次付费时间来为例：
+```javascript
+//first_payment_time为2018-01-01 01:23:45.678
+TDAnalytics.userSetOnce({
+    properties: {
+        first_payment_time: "2018-01-01 01:23:45.678" 
+    }
+});
+//first_payment_time仍然为2018-01-01 01:23:45.678
+TDAnalytics.userSetOnce({
+    properties: {
+        first_payment_time: "2018-12-31 01:23:45.678" 
+    }
+});
+```
+
+### 3.3 userAdd
+当您要上传数值型的属性时，您可以调用 `userAdd` 来对该属性进行累加操作，如果该属性还未被设置，则会赋值 0 后再进行计算。如果传入负值，等同于减法操作。
+```javascript
+//此时total_revenue为30
+TDAnalytics.userAdd({
+    properties: {
+        total_revenue: 30
+    }
+});
+//此时total_revenue为678
+TDAnalytics.userAdd({
+    properties: {
+        total_revenue: 648
+    }
+});
+```
+
+### 3.4 userUnset
+当您要清空用户的用户属性值时，您可以调用 `userUnset` 来对指定属性进行清空操作，如果该属性还未在集群中被创建，则 `userUnset` **不会**创建该属性
+```javascript
+// 清空该用户属性名为 userPropertykey 的用户属性值，即设置成 NULL
+TDAnalytics.userUnset({
+    property: "userPropertykey"
+});
+```
+
+### 3.5 userDelete
+如果您要删除某个用户，可以调用 `userDelete` 将这名用户删除，您将无法再查询该名用户的用户属性，但该用户产生的事件仍然可以被查询到。
+```javascript
+TDAnalytics.userDelete();
+```
+
+### 3.6 userAppend
+您可以调用 `userAppend` 对数组类型的用户数据追加元素。
+```javascript
+TDAnalytics.userAppend({
+    properties: {
+        user_list: ["apple", "ball"]
+    }
+});
+```
+
+### 3.7 userUniqAppend
+自 v1.6.0 开始，您可以调用 `userUniqAppend` 对 Array (List) 类型的用户数据追加唯一元素。调用 `userUniqAppend` 接口会对追加的用户属性进行去重， `userAppend` 接口不做去重，用户属性可存在重复。
+```javascript
+//此时user_list的属性值为["apple"，"ball"]
+TDAnalytics.userAppend({
+    properties: {
+        user_list: ["apple", "ball"]
+    }
+});
+//此时user_list的属性值为["apple","apple","ball","cube"]
+TDAnalytics.userAppend({
+    properties: {
+        user_list: ["apple", "cube"]
+    }
+});
+//此时user_list的属性值为["apple"，"ball","cube"]
+TDAnalytics.userUniqAppend({
+    properties: {
+        user_list: ["apple", "cube"]
+    }
+});
+```
+
+## 四、加密功能
+从 v2.1.0 版本开始，SDK 支持加密功能，客户端支持 AES + RSA 对数据进行加密，再由服务端对数据进行解密，加解密能力需要客户端和服务端配合完成，具体请咨询客户成功人员。
+设置` enableEncrypt` 属性为true，并设置默认版本号和公钥。
+```javascript
+var config = {
+  appId: "YOUR_APP_ID", // 项目 APP ID
+  serverUrl: "YOUR_SERVER_URL", // 上报地址
+  enableEncrypt: true, // 开启数据传输加密
+  secretKey: {
+    publicKey:'YOUR_PUBLIC_KEY', // 加密公钥
+    version:0 // 密钥版本号
+   }
+};
+// 初始化
+TDAnalytics.init(config);
+```
+
+## 五、其他功能
+### 5.1 获取设备ID
+您可以调用 `getDeviceId()` 获取设备 ID。
+```javascript
+var deviceId = TDAnalytics.getDeviceId();
+```
+
+<quote-container>
+**设备 ID 会保存在缓存中，用户清理缓存，设备ID会被重置。**
+</quote-container>
+
+### 5.2 onCompelete 回调函数
+对于 `track, userSet, userSetOnce, userAdd, userDel` 等接口，支持传入 onComplete 回调。 可以直接在原参数列表后传入 onComplete， 也可以使用参数对象的方式。如果使用参数对象，参数对象中必须包含 onComplete，否则会出现参数错误。以上传事件为例：
+```javascript
+TDAnalytics.track({
+  eventName: "test", // 必填
+  properties: { testkey: 123 }, // 可选
+  time: new Date(),
+  onComplete: res => {
+    console.log(res);
+  }
+});
+```
+
+onComplete 的参数 res 为 object 类型，有两个属性 code 和 msg.
+res.code 为 int 类型，定义如下:
+- 0: 成功
+- -1: 数据格式不正确
+- -2: APP ID 无效
+- -3: 网络或服务端异常
+Debug 模式定义如下:
+- 0: 成功
+- -1: 参数或者权限校验的问题
+- 1: 表示字段基本的错误, 会给出详细的错误字段和原由
+- 2: 表示整条错误
+- -3: 网络或服务端异常
+res.msg 是对 res.code 的文字说明。
+### 5.3 设置事件缓存上报
+自 v2.2.0 开始，您可以在初始化的时候配置开启事件缓存上报。
+```javascript
+// TE SDK 配置对象
+var config = {
+  appId: "YOU-APP-ID", // 项目的 APP ID
+  serverUrl: "https://youserverurl.com", // 数据上报地址
+  enableBatch: true, // 是否开启事件缓存批量上报，true=开启，false=关闭
+  batchConfig: {
+    size: 5, // 事件缓存上报条数
+    interval: 5000 // 事件缓存上报间隔（毫秒）
+  }
+};
+// 初始化
+TDAnalytics.init(config); 
+```
+
+## 六、渠道SDK兼容
+### 6.1 腾讯广告
+#### 6.1.1 方案简述
+在集成了TDAnalytics SDK之后，您无需额外集成腾讯广告SDK。一旦您完成了TDAnalytics的初始化方法，系统会自动触发腾讯广告SDK的初始化。当您上报注册、付费等关键事件时，系统会根据您的配置自动将这些事件信息报送给腾讯广告。
+#### 6.1.2 接入流程
+1. [下载腾讯广告SDK](https%3A%2F%2Fdownload.thinkingdata.cn%2Fclient%2Fmini_game%2Fdn-sdk-minigame.zip)，目前使用的是1.5.4版本，如果换成其他版本的也可以。
+将dn-sdk-minigame.cjs.js跟TDAnalytics SDK放到同一目录下。
+1. 初始化
+<callout emoji="camping" background-color="light-orange" border-color="light-orange">
+TDAnalytics SDK的版本需 >= 3.0.4
+</callout>
+
+```javascript
+TDAnalytics.init({
+    appId: 'AppId',
+    serverUrl: 'ServerUrl',
+    tgaInitParams: {
+        user_action_set_id: 100001,// 数据源ID，数字，必填
+        secret_key: '5e853xxxxxxd57a690xxxxxxxxxx',// 加密key，必填
+        appid: 'wx123xyz123xyz123x',//微信小游戏APPID，wx开头，必填
+    },
+    reportingToTencentSdk: 2,//1 只上报给腾讯 2 同时上报给腾讯和TA 3 只上报给TA
+    debugMode: 'debug'// 如果是debug模式，会打印腾讯广告SDK本地调试日志
+})
+```
+
+1. 设置用户ID
+- setOpenId
+openid一般是调用后端接口异步获取的([<text color="purple" underline="true">获取openid方法</text>](https%3A%2F%2Fdevelopers.weixin.qq.com%2Fminigame%2Fdev%2Fapi-backend%2Fopen-api%2Flogin%2Fauth.code2Session.html))，请在获取到 openid 后调用* sdk.setOpenId() *方法设置。openid 和 unionid 只能设置一个，优先设置openid。
+```javascript
+wx.request({
+    url: '后端获取openid以及判断是否注册用户的接口url', 
+    success: function(res){
+        if(res.openid){ 
+          // 设置opneid，必须先设置openid再上报注册行为。setOpenId为同步方法，设置完可立即上报注册行为。            
+          TDAnalytics.login(res.openid);
+          
+          //上报注册行为，后台接口判断是否为注册用户
+          if(res.isRegisterUser){
+           TDAnalytics.track({
+                eventName: "REGISTER"
+            });
+          }
+        }
+    }
+});
+```
+
+- setUnionId
+unionid 一般是调用后端接口异步获取的([<text color="purple" underline="true">获取unionid方法</text>](https%3A%2F%2Fdevelopers.weixin.qq.com%2Fminigame%2Fdev%2Fapi-backend%2Fopen-api%2Flogin%2Fauth.code2Session.html))，请在获取到 unionid 后调用* sdk.setUnionId() *方法设置。没有openid才需使用此方法设置unionid。
+```javascript
+wx.request({
+    url: '后端获取openid以及判断是否注册用户的接口url', 
+    success: function(res){
+        if(res.unionid){ 
+          // 设置unionid ，请优先使用openid，没有openid 或者后台统一使用 unionid 才设置。           
+          TDAnalytics.setDistinctId(res.unionid);
+          
+          //上报注册行为，后台接口判断是否为注册用户
+          if(res.isRegisterUser){
+           TDAnalytics.track({
+                eventName: "REGISTER"
+            });
+          }
+        }
+    }
+});
+```
+
+1. 上报行为
+```javascript
+TDAnalytics.track({
+    eventName: "product_buy", // 事件名称
+    properties: {
+        product_name: "商品名"
+    } //事件属性
+});
+```
+
+如果是以下特定事件，需要上报指定的事件名称
+
+<lark-table rows="12" cols="3" column-widths="202,309,309">
+
+  <lark-tr>
+    <lark-td>
+      事件
+    </lark-td>
+    <lark-td>
+      事件名
+    </lark-td>
+    <lark-td>
+      事件属性（需要包含其中的key）
+    </lark-td>
+  </lark-tr>
+  <lark-tr>
+    <lark-td>
+      #### 小游戏启动
+    </lark-td>
+    <lark-td>
+      #### START_APP
+    </lark-td>
+    <lark-td>
+      无
+    </lark-td>
+  </lark-tr>
+  <lark-tr>
+    <lark-td>
+      #### 付费
+    </lark-td>
+    <lark-td>
+      #### PURCHASE
+    </lark-td>
+    <lark-td>
+      {
+              value: 600
+      }
+    </lark-td>
+  </lark-tr>
+  <lark-tr>
+    <lark-td>
+      #### 注册
+    </lark-td>
+    <lark-td>
+      #### REGISTER
+    </lark-td>
+    <lark-td>
+    </lark-td>
+  </lark-tr>
+  <lark-tr>
+    <lark-td>
+      #### 沉默唤起
+    </lark-td>
+    <lark-td>
+      #### RE_ACTIVE
+    </lark-td>
+    <lark-td>
+      {
+              backFlowDay: 30
+      }
+    </lark-td>
+  </lark-tr>
+  <lark-tr>
+    <lark-td>
+      #### 收藏小游戏
+    </lark-td>
+    <lark-td>
+      #### ADD_TO_WISHLIST
+    </lark-td>
+    <lark-td>
+      {
+              type: 'default',
+      }
+    </lark-td>
+  </lark-tr>
+  <lark-tr>
+    <lark-td>
+      #### 分享小游戏
+    </lark-td>
+    <lark-td>
+      #### SHARE
+    </lark-td>
+    <lark-td>
+      {
+              target: 'APP_MESSAGE'
+      }
+    </lark-td>
+  </lark-tr>
+  <lark-tr>
+    <lark-td>
+      #### 创建角色
+    </lark-td>
+    <lark-td>
+      #### CREATE_ROL
+    </lark-td>
+    <lark-td>
+      {
+              name: 'SuperMan'
+      }
+    </lark-td>
+  </lark-tr>
+  <lark-tr>
+    <lark-td>
+      #### 完成新手指引
+    </lark-td>
+    <lark-td>
+      #### TUTORIAL_FINISH
+    </lark-td>
+    <lark-td>
+      无
+    </lark-td>
+  </lark-tr>
+  <lark-tr>
+    <lark-td>
+      #### 游戏等级提升
+    </lark-td>
+    <lark-td>
+      #### UPDATE_LEVEL
+    </lark-td>
+    <lark-td>
+      {
+              level: 2,
+              power: 85,
+      }
+    </lark-td>
+  </lark-tr>
+  <lark-tr>
+    <lark-td>
+      #### 浏览商城页面
+    </lark-td>
+    <lark-td>
+      #### VIEW_CONTENT
+    </lark-td>
+    <lark-td>
+      {
+      <text color="gray">// 关键场景访问：商城</text>
+              item: 'Mall',
+      }
+    </lark-td>
+  </lark-tr>
+  <lark-tr>
+    <lark-td>
+      #### 浏览游戏活动
+    </lark-td>
+    <lark-td>
+      #### VIEW_CONTENT
+    </lark-td>
+    <lark-td>
+      <text color="gray">{</text>
+        <text color="gray">// 关键场景访问：活动</text>
+        item<text color="orange">:</text> <text color="green">'Activity'</text><text color="gray">,</text>
+      <text color="gray">}</text>
+    </lark-td>
+  </lark-tr>
+</lark-table>
+
+比如上报游戏等级提升事件
+```javascript
+TDAnalytics.track({
+    eventName: "UPDATE_LEVEL", 
+    properties: {
+        level: 2,
+        power: 85,
+    }
+});
+```