ae-tracking 0.1.0

package/wiki/te-docs/raw//346/216/245/345/205/245/346/214/207/345/215/227//346/234/215/345/212/241/347/253/257-sdk/ruby//350/277/233/351/230/266/346/214/207/345/215/227.md

@@ -0,0 +1,226 @@
+---
+code: ruby_sdk_advanced
+name: "进阶指南"
+wikiToken: P5StwizCriCXBEkP5Vkczd14nVh
+parentWikiToken: JQwMwwgRviGugBklAUJcBSSjnng
+updateTime: 1745309888000
+sourceUrl: https://docs-v2.thinkingdata.cn/?version=v5.0&lan=zh-CN&code=ruby_sdk_advanced
+---
+# 进阶指南
+
+### 一、发送事件
+
+在 SDK 初始化完成之后，您就可以进行数据埋点，收集用户的的行为信息。一般情况下普通事件即可满足业务场景需求，您也可以根据自己的实际业务场景使用首次、可更新等事件。
+
+#### 1.1 普通事件
+
+您可以调用 `track` 来上传事件，建议您根据先前梳理的文档来设置事件的属性以及发送事件的条件，此处以用户购买某商品作为范例：
+
+```
+*DEMO_ACCOUNT_ID *= '123'
+*DEMO_DISTINCT_ID *= 'aaa'
+
+*properties *= {
+  array: ["str1", "11", Time.now, "2020-02-11 17:02:52.415"],
+  prop_date: Time.now,
+  prop_double: 134.1,
+  prop_string: 'hello world',
+  prop_bool: true,
+}
+
+*ta*.track(event_name: 'test_event', distinct_id: DEMO_DISTINCT_ID, account_id: DEMO_ACCOUNT_ID, properties: *properties*)
+```
+
+#### 1.2 首次事件
+
+首次事件是指针对某个设备或者其他维度的 ID，只会记录一次的事件。例如在一些场景下，您可能希望记录在某个设备上的激活事件，则可以用首次事件来上报数据。
+
+```
+*DEMO_ACCOUNT_ID *= '123'
+*DEMO_DISTINCT_ID *= 'aaa'
+
+*properties *= {
+  array: ["str1", "11", Time.now, "2020-02-11 17:02:52.415"],
+  prop_date: Time.now,
+  prop_double: 134.1,
+  prop_string: 'hello world',
+  prop_bool: true,
+}
+*ta*.track(event_name: 'test_event', distinct_id: DEMO_DISTINCT_ID, account_id: DEMO_ACCOUNT_ID, first_check_id:'first_id', properties: *properties*)
+```
+
+<!-- unsupported block: 34 -->
+
+注意：由于在服务端完成对是否首次的校验，首次事件默认会延时 1 小时入库。
+
+#### 1.3 可更新事件
+
+您可以通过可更新事件实现特定场景下需要修改事件数据的需求。可更新事件需要指定标识该事件的 ID，并在创建可更新事件对象时传入。AE 后台将根据事件名和事件 ID 来确定需要更新的数据。
+
+```
+*DEMO_ACCOUNT_ID *= '123'
+*DEMO_DISTINCT_ID *= 'aaa'
+
+*properties *= {
+  array: ["str1", "11", Time.now, "2020-02-11 17:02:52.415"],
+  prop_date: Time.now,
+  prop_double: 134.1,
+  prop_string: 'hello world',
+  prop_bool: true,
+}
+*ta*.track_update(event_name: 'update', event_id: 'id123', distinct_id: DEMO_DISTINCT_ID, account_id: DEMO_ACCOUNT_ID, properties:*properties*)
+```
+
+#### 1.4 可重写事件
+
+可重写事件与可更新事件类似，区别在于可重写事件会用最新的数据完全覆盖历史数据，从效果上看相当于删除前一条数据，并入库最新的数据。AE 后台将根据事件名和事件 ID 来确定需要更新的数据。
+
+```
+*DEMO_ACCOUNT_ID *= '123'
+*DEMO_DISTINCT_ID *= 'aaa'
+
+*properties *= {
+  array: ["str1", "11", Time.now, "2020-02-11 17:02:52.415"],
+  prop_date: Time.now,
+  prop_double: 134.1,
+  prop_string: 'hello world',
+  prop_bool: true,
+}
+*ta*.track_overwrite(event_name: 'update', event_id: 'id123', distinct_id: DEMO_DISTINCT_ID, account_id: DEMO_ACCOUNT_ID, properties:*properties*)
+```
+
+### 二、用户属性
+
+AE 平台支持的用户属性设置API有: `user_set`、`user_set_once`、`user_add`、
+
+`user_unset`、`user_del`、`user_append`、`user_uniq_append`。
+
+#### 2.1 user_set
+
+对于一般的用户属性，您可以调用 `user_set` 来进行设置。使用该接口上传的属性将会覆盖原有的属性值，如果之前不存在该用户属性，则会新建该用户属性，类型与传入属性的类型一致，此处以设置用户名为例：
+
+```
+*DEMO_ACCOUNT_ID = '123'*
+*DEMO_DISTINCT_ID = 'aaa'*
+
+*user_data = {*
+*  array: ["str1", 11, 22.22],*
+*  prop_double: 134.12,*
+*  prop_string: 'hello',*
+*  prop_int: 666,*
+*}*
+*ta.user_set(distinct_id: DEMO_DISTINCT_ID, account_id: DEMO_ACCOUNT_ID, properties: user_data)*
+```
+
+#### 2.2 user_set_once
+
+如果您要上传的用户属性只要设置一次，则可以调用`user_set_once`来进行设置，当该属性之前已经有值的时候，将会忽略这条信息，再以设置用户名为例：
+
+```
+*user_set_once_data *= {
+  prop_int_new: 888,
+}
+*ta*.user_set_once(distinct_id: DEMO_DISTINCT_ID, account_id: DEMO_ACCOUNT_ID, properties: *user_set_once_data*)
+```
+
+#### 2.3 user_add
+
+当您要上传数值型的属性时，您可以调用`user_add`来对该属性进行累加操作，如果该属性还未被设置，则会赋值 0 后再进行计算，可传入负值，等同于相减操作。此处以累计付费金额为例：
+
+```
+# 对数值类型的属性进行累加操作
+*ta*.user_add(distinct_id: DEMO_DISTINCT_ID, properties: {prop_int: 10, prop_double: 15.88})
+```
+
+<!-- unsupported block: 34 -->
+
+设置的属性key为字符串，Value 只允许为数值。
+
+#### 2.4 user_append
+
+您可以调用 `user_append` 对数组类型的用户属性进行追加操作。
+
+```
+*user_append_data *= {
+  array: %w[33 44]
+}
+*ta*.user_append(distinct_id: DEMO_DISTINCT_ID, account_id: DEMO_ACCOUNT_ID, properties: *user_append_data*)
+
+*user_append_data_new *= {
+  array: %w[44 55]
+}
+*ta*.user_append(distinct_id: DEMO_DISTINCT_ID, account_id: DEMO_ACCOUNT_ID, properties: *user_append_data_new*)
+```
+
+#### 2.5 user_uniq_append
+
+您可以调用`user_uniq_append`对数组类型的用户属性进行追加操作。调用`user_uniq_append`接口会对追加的用户属性进行去重，`user_append`接口不做去重，用户属性可存在重复。
+
+```
+*user_append_data *= {
+  array: %w[33 44]
+}
+*ta*.user_append(distinct_id: DEMO_DISTINCT_ID, account_id: DEMO_ACCOUNT_ID, properties: *user_append_data*)
+
+*user_uniq_append_data *= {
+  array: %w[44 55]
+}
+*ta*.user_uniq_append(distinct_id: DEMO_DISTINCT_ID, account_id: DEMO_ACCOUNT_ID, properties: *user_uniq_append_data*)
+```
+
+#### 2.6 user_unset
+
+当您要清空用户的用户属性值时，您可以调用`user_unset`来对指定属性进行清空操作，如果该属性还未在集群中被创建，则`user_unset`不会创建该属性
+
+```
+*ta*.user_unset(distinct_id: DEMO_DISTINCT_ID, property: [:prop_string, :prop_int])
+```
+
+<!-- unsupported block: 34 -->
+
+user_unset: 的传入值为被清空属性的 Key 值。
+
+#### 2.7 user_del
+
+如果您要删除某个用户，可以调用`user_del`将这名用户删除，您将无法再查询该名用户的用户属性，但该用户产生的事件仍然可以被查询到，该操作可能产生不可逆的后果，请慎用
+
+```
+*ta*.user_del(distinct_id: DEMO_DISTINCT_ID)
+```
+
+### 三、其他功能
+
+#### 3.1 TDBatchConsumer
+
+::: warning 注意
+
+当数据量过大或者网络异常时，有数据丢失的风险，不建议在正式环境中使用
+
+:::
+
+批量实时地向 AE 服务器传输数据，不需要搭配传输工具。
+
+```
+*consumer *= ThinkingData::TDBatchConsumer.new('SERVER_URL', 'APPID', 30)
+ta = ThinkingData::TDAnalytics.new(consumer)
+
+*DEMO_ACCOUNT_ID *= '123'
+*DEMO_DISTINCT_ID *= 'aaa'
+
+*properties *= {
+  array: ["str1", "11", Time.now, "2020-02-11 17:02:52.415"],
+  prop_date: Time.now,
+  prop_double: 134.1,
+  prop_string: 'hello world',
+  prop_bool: true,
+}
+
+*ta*.track(event_name: 'test_event', distinct_id: DEMO_DISTINCT_ID, account_id: DEMO_ACCOUNT_ID, properties: *properties*)
+```
+
+参数说明:
+
+- `APPID`: 您的项目的 APP ID，可通过在 AE 后台项目管理页面获取
+- `SERVER_URL`: 数据上传的 URL
+- 如果您对接的是云服务，填入: https://global-receiver-ta.thinkingdata.cn 
+- 如果您使用私有化部署版本，请为数据采集地址绑定域名，并配置 HTTPS 证书：https://数据采集地址绑定域名

package/wiki/te-docs/raw//346/216/245/345/205/245/346/214/207/345/215/227//346/234/215/345/212/241/347/253/257-sdk/ruby.md

@@ -0,0 +1,165 @@
+---
+code: ruby_sdk_installation
+name: "Ruby"
+wikiToken: JQwMwwgRviGugBklAUJcBSSjnng
+parentWikiToken: O3YxwgHGiiEnvYkHCcIcX51inkf
+updateTime: 1745310924000
+sourceUrl: https://docs-v2.thinkingdata.cn/?version=v5.0&lan=zh-CN&code=ruby_sdk_installation
+---
+# Ruby
+
+本指南将会为您介绍如何使用 Ruby SDK 接入您的项目。
+
+**最新版本为**：v2.0.0
+
+**更新时间为**：2023-10-08
+
+**资源下载****：**源代码
+
+::: warning 注意
+
+当前文档适用于 v2.0.0 及以后的版本，历史版本请参考 Ruby SDK 接入指南（V1）
+
+::: 
+
+### 一、集成SDK
+
+1. 请使用`gem`命令集成 SDK 包
+```
+# 获取 SDK
+gem install thinkingdata-ruby
+```
+
+1.  安装Logbus
+我们推荐使用SDK+LogBus的形式，完成服务端数据的采集上报.您可以参考以下文档完成Logbus的安装:LogBus使用指南
+
+### 二、初始化
+
+以下是SDK初始化的示例代码:
+
+```
+require 'thinkingdata-ruby'
+
+*consumer *= ThinkingData::TDLoggerConsumer.new("LOG_DIRECTORY")
+*ta *= ThinkingData::TDAnalytics.new(*consumer*)
+```
+
+`LOG_DIRECTORY`为写入本地的文件夹地址。您只需将 LogBus 的监听文件夹地址设置为此处的地址，即可使用 LogBus 进行数据的监听上传。
+
+### 三、常用功能
+
+为了保证访客 ID 与账号 ID 能够顺利进行绑定，如果您的游戏中会用到访客 ID 与账号 ID，我们极力建议您同时上传这两个 ID，否则将会出现账号无法匹配的情况，导致用户重复计算，具体的 ID 绑定规则可参考用户识别规则一章。
+
+#### 3.1 发送事件
+
+您可以调用`track`来上传事件，建议您根据先前梳理的文档来设置事件的属性以及发送信息的条件，以下是发送事件的示例代码:
+
+```
+*DEMO_ACCOUNT_ID *= '123'
+*DEMO_DISTINCT_ID *= 'aaa'
+
+*properties *= {
+  array: ["str1", "11", Time.now, "2020-02-11 17:02:52.415"],
+  prop_date: Time.now,
+  prop_double: 134.1,
+  prop_string: 'hello world',
+  prop_bool: true,
+}
+
+*ta*.track(event_name: 'test_event', distinct_id: DEMO_DISTINCT_ID, account_id: DEMO_ACCOUNT_ID, properties: *properties*)
+```
+
+- 事件的名称是字符串类型，只能以字母开头，可包含数字，字母和下划线 "_"，长度最大为 50 个字符。
+- Key 为该属性的名称，为字符串类型，规定只能以字母开头，包含数字，字母和下划线 "_"，长度最大为 50 个字符，对字母大小写不敏感,TE会统一转化为小写字母
+- Value 为该属性的值，支持字符串、数字、布尔、时间、对象、对象组、数组
+<!-- unsupported block: 34 -->
+
+**用户属性的要求与事件属性保持一致**
+
+#### 3.2 设置用户属性
+
+对于一般的用户属性，您可以调用 `user_set` 来进行设置，使用该接口上传的属性将会覆盖原有的属性值，如果之前不存在该用户属性，则会新建该用户属性，类型与传入属性的类型一致，此处以设置用户名为例：
+
+```
+*DEMO_ACCOUNT_ID *= '123'
+*DEMO_DISTINCT_ID *= 'aaa'
+
+*user_data *= {
+  array: ["str1", 11, 22.22],
+  prop_date: Time.now,
+  prop_double: 134.12,
+  prop_string: 'hello',
+  prop_int: 666,
+}
+*ta*.user_set(distinct_id: DEMO_DISTINCT_ID, account_id: DEMO_ACCOUNT_ID, properties: *user_data*)
+```
+
+#### 3.3 数据上报
+
+使用 TDLoggerConsumer 时，SDK 会实时的将采集到的数据写入磁盘，无需调用`flush()`方法。
+
+#### 3.4 关闭SDK
+
+```
+# 关闭并退出 SDK
+ta.close
+```
+
+<!-- unsupported block: 34 -->
+
+关闭并退出 SDK，请在关闭服务器前调用本接口，以避免缓存内的数据丢失
+
+### 四、最佳实践
+
+以下示例代码包含以上所有操作，我们推荐按照如下步骤使用:
+
+```
+ThinkingData::set_stringent(false)
+ThinkingData::set_enable_log(false)
+
+*consumer *= ThinkingData::TDLoggerConsumer.new( 'LOG_DIRECTORY', 'hourly')
+*ta *= ThinkingData::TDAnalytics.new(*consumer*, *my_error_handler*, uuid: true)
+
+*DEMO_ACCOUNT_ID *= '123'
+*DEMO_DISTINCT_ID *= 'aaa'
+
+*properties *= {
+  array: ["str1", "11", Time.now, "2020-02-11 17:02:52.415"],
+  prop_date: Time.now,
+  prop_double: 134.1,
+  prop_string: 'hello world',
+  prop_bool: true,
+}
+
+*ta*.track(event_name: 'test_event', distinct_id: DEMO_DISTINCT_ID, account_id: DEMO_ACCOUNT_ID, properties: *properties*)
+
+*user_data *= {
+  array: ["str1", 11, 22.22],
+  prop_date: Time.now,
+  prop_double: 134.12,
+  prop_string: 'hello',
+  prop_int: 666,
+}
+*ta*.user_set(distinct_id: DEMO_DISTINCT_ID, account_id: DEMO_ACCOUNT_ID, properties: *user_data*)
+
+*user_append_data *= {
+  array: %w[33 44]
+}
+*ta*.user_append(distinct_id: DEMO_DISTINCT_ID, account_id: DEMO_ACCOUNT_ID, properties: *user_append_data*)
+
+*user_uniq_append_data *= {
+  array: %w[44 55]
+}
+*ta*.user_uniq_append(distinct_id: DEMO_DISTINCT_ID, account_id: DEMO_ACCOUNT_ID, properties: *user_uniq_append_data*)
+
+*user_set_once_data *= {
+  prop_int_new: 888,
+}
+*ta*.user_set_once(distinct_id: DEMO_DISTINCT_ID, account_id: DEMO_ACCOUNT_ID, properties: *user_set_once_data*)
+
+*ta*.user_add(distinct_id: DEMO_DISTINCT_ID, properties: {prop_int: 10, prop_double: 15.88})
+
+*ta*.user_unset(distinct_id: DEMO_DISTINCT_ID, property: [:prop_string, :prop_int])
+
+*ta*.user_del(distinct_id: DEMO_DISTINCT_ID)
+```

package/wiki/te-docs/raw//346/216/245/345/205/245/346/214/207/345/215/227//346/234/215/345/212/241/347/253/257-sdk.md

@@ -0,0 +1,23 @@
+---
+code: server_sdk_menu
+name: "服务端 SDK"
+wikiToken: O3YxwgHGiiEnvYkHCcIcX51inkf
+parentWikiToken: GkqjwwBediy6Jzk35GAcAVNpncg
+updateTime: 1745310916000
+sourceUrl: https://docs-v2.thinkingdata.cn/?version=v5.0&lan=zh-CN&code=server_sdk_menu
+---
+# 服务端 SDK
+
+服务端 SDK：
+
+- Java
+- Golang
+- C
+- C#
+- Erlang
+- Ruby
+- Lua
+- Node.js
+- PHP
+- Python
+- C++

package/wiki/te-docs/raw//346/216/245/345/205/245/346/214/207/345/215/227.md

@@ -0,0 +1,64 @@
+---
+code: installation_menu
+name: "接入指南"
+wikiToken: GkqjwwBediy6Jzk35GAcAVNpncg
+parentWikiToken: Iufpwws70iX4tUk5qOOcwG5fnFb
+updateTime: 1745310857000
+sourceUrl: https://docs-v2.thinkingdata.cn/?version=v5.0&lan=zh-CN&code=installation_menu
+---
+# 接入指南
+
+本节将会介绍数据接入的方式，现在主要支持 SDK 接入，以及数据传输工具 LogBus，您也可以直接使用 POST 方法直接传入数据
+
+可以访问我们的Github 主页，查看各接入方式的源代码
+
+以下为现有接入方式的使用指南：
+
+客户端 SDK：
+
+- Android
+- iOS
+- OpenHarmony
+- JavaScript
+- 游戏引擎
+- Unity
+- Unreal
+- Cocos2d-x
+- Cocos2d-Lua
+- Cocos Creator
+- LayaAir
+- Egret
+- Corona
+- 小程序\小游戏
+- 跨平台框架
+- React Native
+- Flutter
+- uni-app
+- C++
+- C#
+- MacOS
+- H5 与 APP SDK 打通
+- 客户端 SDK 常见问题
+服务端 SDK：
+
+- Java
+- Golang
+- C
+- C#
+- Erlang
+- Ruby
+- Lua
+- Node.js
+- PHP
+- Python
+- C++
+传输工具：
+
+- LogBus 2 使用指南
+- LogBus 使用指南
+- LogBus Windows 版本使用指南
+- Filebeat + Logstash 使用指南
+- ta-datax-writer 插件使用指南
+其他方式
+
+- Restful API 使用指南

package/wiki/te-docs/raw//350/277/233/351/230/266/346/225/260/346/215/256/347/261/273/345/236/213//345/217/257/346/233/264/346/226/260/344/272/213/344/273/266.md

@@ -0,0 +1,109 @@
+---
+code: track_update_and_track_overwrite
+name: "可更新事件"
+wikiToken: P5ryw0zcmi9CJBk5S0LclWSEnlh
+parentWikiToken: Ljs3w406DiyDLnktFuAcHogInvg
+updateTime: 1745309946000
+sourceUrl: https://docs-v2.thinkingdata.cn/?version=v5.0&lan=zh-CN&code=track_update_and_track_overwrite
+---
+# 可更新事件
+
+本章节将介绍 AE 系统的特殊数据结构——可更新事件的使用方法。可更新事件是一种**特殊的事件数据**，可以对数据中的事件属性值进行更新，适合记录包含可变状态值或者可变累计值的事件数据，例如成本事件，可随时间推移对属性`成本金额`进行更新。
+
+::: warning
+
+ 可更新事件的存储以及处理的性能开销很大，为了保证数据处理效率以及查询性能，只适用于事件量较少、且在特殊业务场景下有较强的更新需求的事件，强烈建议在 AE 工作人员的协助下进行使用
+
+ :::
+
+### 一、数据结构
+
+<!-- unsupported block: 34 -->
+
+使用 AE 客户端 SDK 或服务端 SDK，可查看对应 SDK 的接入指南，指南中“可更新事件”及“可重写事件”章节将会提供详细的接口调用方法
+
+使用”可更新事件“特性，需要在数据中进行两个调整：
+
+1. 将标识数据类型的字段`#type`设置为`track_update`或`track_overwrite`，这两种数据类型分别表示两种事件的更新方式：更新部分属性与重写所有属性
+1. 增加字段`#event_id`，该字段是事件的唯一标识；在更新属性时，会根据`#event_name`与`#event_id`查找对应的事件数据，并对该条数据进行更新；不同事件的`#event_id`互相独立，因此每个可更新事件拥有一套单独的唯一标识体系
+以下是一条数据样例，可以关注`#event_id`的所在位置：
+
+```
+{
+  "#account_id": "ABCDEFG-123-abc",
+  "#distinct_id": "F53A58ED-E5DA-4F18-B082-7E1228746E88",
+  "#type": "track_update",
+  "#event_id": "F53A58ED-E5DA-4F18-B082-7E1228746E88",
+  "#time": "2020-08-18 14:37:28.527",
+  "#event_name": "test_event",
+  "properties": {
+    "argString": "abc"
+  }
+}
+```
+
+### 二、数据处理逻辑
+
+可更新事件在处理逻辑上和普通的事件数据有很大的差异：**请注意，如果一条事件数据的**`#type`**为**`track`**，则该条数据无法在之后被更新**；如果一条事件数据的`#type`为`track_update`或`track_overwrite`，就会被视为可更新事件，则之后可以使用两类数据中的任意一类对属性进行更新。
+
+AE 系统收到`track_update`或`track_overwrite`时会有不一样的处理方式，本节将会详细描述这两类数据的处理逻辑。
+
+#### 2.1 track_update 的处理逻辑
+
+数据中的`#type`为`track_update`时，数据的处理逻辑为事件属性更新。当系统收到该类型数据时，会根据`#event_id`字段查找对应事件数据在是否存在，如果存在，则会更新对应的字段，具体的处理逻辑如下：
+
+1. 若该事件下不存在`#event_id`对应的数据，该数据视为新增数据，将会直接入库
+1. 若`#event_id`存在，则新传入数据中的事件属性将会更新先前值，如果有新属性，也会将新属性加入进来，新传入数据中不包含的属性将不会被更新，因此只需要传入要被更新的属性即可
+1. 此外`#time`即事件时间也会被新数据更新，因此需根据实际业务场景，对新传入数据中的时间进行合理设置
+#### 2.2 track_overwrite 的处理逻辑
+
+数据中的`#type`为`track_overwrite`时，数据的处理逻辑为事件重写。当系统收到该类型数据时，会根据`#event_id`字段查找对应事件数据在是否存在，如果存在，则会删除该条数据，并且将新的事件数据写入到系统内（相当于替换了被删除的那条数据），具体的处理逻辑如下：
+
+1. 若该事件下不存在`#event_id`对应的数据，该数据视为新增数据，将会直接入库
+1. 若`#event_id`存在，则该条事件数据的所有内容都会重写，如需更新部分属性，可使用`track_update`
+1. 此外`#time`即事件时间也会被新数据更新，因此需根据实际业务场景，对新传入数据中的时间进行合理设置
+### 三、最佳实践
+
+#### 广告成本
+
+在广告成效分析时，往往需要计算广告位或素材的 ROI 投入产出比，也就是用户价值与用户成本的比值。用户的价值，即直接付费与其它方式产生价值的总和，是容易记录的；而成本数据，则会依赖于广告投放端的数据规则，一般成本金额会持续更新，不适合用一般的事件数据进行记录。
+
+由于成本数据会持续变化，广告成本数据很适合通过可更新数据的方式来进行记录，首次记录广告成本数据时，可以上传如下数据：
+
+```
+{
+  "#account_id": "admin",
+  "#distinct_id": "F53A58ED-E5DA-4F18-B082-7E1228746E88",
+  "#type": "track_update",
+  "#event_id": "2020-09-01_google_7-Tier1-0527_adset1_adname1",
+  "#time": "2020-09-01 00:00:00.000",
+  "#event_name": "ad_cost",
+  "properties": {
+    "channel": "google",
+    "campaignid": "7-Tier1-0527",
+    "adset": "adset1",
+    "adname": "adname1",
+    "cost": 100
+  }
+}
+```
+
+以上数据将会新增一条成本的可更新事件，其中`#event_id`由日期、渠道、活动名、广告组、广告名的拼接而成，作为成本的唯一 ID，从数据逻辑上而言，这也是成本事件可更新的最细粒度；`cost`字段记录此时广告的成本 100 元。
+
+随着时间推移，广告投放渠道的推送了新的成本数据，新的广告成本为 200，则可以发送如下数据，其中`#event_id`需要和之前的数据保持一致，代表更新先前的那条数据；更新的是`cost`字段，传入新成本值 200；由于`#time`也会被新数据更新，此处需要和之前保持一致，传入的是成本的日期（转化为时间类型）。其它字段如渠道、活动、广告位，由于没有不需要更新，所以数据中可以不填写。
+
+```
+{
+  "#account_id": "admin",
+  "#distinct_id": "F53A58ED-E5DA-4F18-B082-7E1228746E88",
+  "#type": "track_update",
+  "#event_id": "2020-09-01_google_7-Tier1-0527_adset1_adname1",
+  "#time": "2020-09-01 00:00:00.000",
+  "#event_name": "ad_cost",
+  "properties": {
+    "cost": 200
+  }
+}
+```
+
+当系统收到该条事件时，会查询该`#event_id`是否已经存在，发现存在后，会将原始数据（也就是第一条样例数据）中的`#time`以及`cost`字段进行更新，即完成了成本事件成本金额的更新操作。

package/wiki/te-docs/raw//350/277/233/351/230/266/346/225/260/346/215/256/347/261/273/345/236/213//351/246/226/346/254/241/344/272/213/344/273/266/346/240/241/351/252/214.md

@@ -0,0 +1,88 @@
+---
+code: first_check_id
+name: "首次事件校验"
+wikiToken: VcMswVyheiYNqek35fKcFYiEnTg
+parentWikiToken: Ljs3w406DiyDLnktFuAcHogInvg
+updateTime: 1745309948000
+sourceUrl: https://docs-v2.thinkingdata.cn/?version=v5.0&lan=zh-CN&code=first_check_id
+---
+# 首次事件校验
+
+本章节将介绍 AE 系统的特殊数据结构——首次事件校验的使用方法。首次事件校验是一种数据过滤特性，在事件数据中加入唯一标识 ID，系统收到数据时会比对该 ID 之前是否出现，ID 已出现的数据将无法入库，未出现的数据可以入库，并记录该 ID，以此保证该 ID 首次出现的事件才会入库。
+
+::: warning
+
+ 首次事件校验的性能开销较大，不建议在所有事件加入该校验，并且建议在 AE 工作人员的协助下进行使用
+
+ :::
+
+### 一、数据结构
+
+使用”首次事件校验“特性，需要在数据中进行一个调整：
+
+- 增加 ID 字段`#first_check_id`，类型必须是字符串，该字段是校验首次事件的标识 ID，该 ID 首条出现的数据将入库，之后出现的都无法入库。不同事件的`#first_check_id`互相独立，因此每个事件的首次校验互不干扰
+以下是一条数据样例，可以关注`#first_check_id`的所在位置：
+
+```
+{
+  "#account_id": "ABCDEFG-123-abc",
+  "#distinct_id": "F53A58ED-E5DA-4F18-B082-7E1228746E88",
+  "#type": "track",
+  "#ip": "192.168.171.111",
+  "#uuid": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
+  "#time": "2017-12-18 14:37:28.527",
+  "#first_check_id": "123456",
+  "#event_name": "test",
+  "properties": {
+    "argString": "abc",
+    "argNum": 123,
+    "argBool": true
+  }
+}
+```
+
+上述数据中的`#first_check_id`为"123456"，如果事件"test"之前已经入库了`#first_check_id`为"123456"的另一条数据，则该条数据无法入库，如果之前没有入库过，则该条数据可以入库
+
+### 二、数据处理逻辑
+
+AE 系统会为每一个事件维护一张 ID 表，不同事件之间 ID 表互相独立。
+
+当系统收到带有`#first_check_id`的事件数据时，会在相应事件的 ID 表中查找该数据的`#first_check_id`，根据查询结果，会进行不同处理：
+
+1. 如果 ID 表中不存在该`#first_check_id`，则该条数据通过校验，将会直接入库，并且 ID 表中将记录该`#first_check_id`
+1. 如果 ID 表中存在该`#first_check_id`，则该条数据将被直接抛弃
+如果同一个事件，既上传了带有`#first_check_id`的数据，也上传了不带有该字段的数据，那么不带有该字段的数据不会经过首次事件校验的处理，和通常的数据一致
+
+::: tip
+
+ 除以上的关键逻辑外，此处还有两个注意点：
+
+1.为了保证性能，系统采用定时批处理的方式进行判断，默认间隔为 1 小时，因此使用首次事件校验的事件数据会有默认 1 个小时的查询延迟
+
+2."#first_check_id"在处理后不会记录在数据库中，如果需要记录，请使用一个事件属性记录
+
+ :::
+
+### 三、最佳实践
+
+#### 设备新增
+
+设备新增数据非常适合使用首次事件校验，可以在每次应用启动时，上报一条以设备 ID 作为`#first_check_id`的”设备新增“事件，根据首次事件校验的逻辑，只有设备 ID 首次出现的”设备新增“事件会被记录下来，之后出现的数据都会被抛弃。因此入库事件就是每个设备 ID 首次出现的事件，符合设备新增的逻辑。
+
+以下是使用首次事件校验的”设备新增“事件的样例：
+
+```
+{
+  "#distinct_id": "F53A58ED-E5DA-4F18-B082-7E1228746E88",
+  "#type": "track",
+  "#ip": "192.168.171.111",
+  "#time": "2017-12-18 14:37:28.527",
+  "#first_check_id": "device_id_123456",
+  "#event_name": "new_device",
+  "properties": {
+    "device_id": "device_id_123456"
+  }
+}
+```
+
+该事件可以在每次应用启动时上报，并以设备 ID 作为`#first_check_id`；除此之外，也可以加入其它属性，比如”设备型号“，”来源渠道“等等，增加分析时的维度。 AE 客户端 SDK 或服务端 SDK，可查看对应 SDK 的接入指南，指南中“可更新事件”及“可重写事件”章节将会提供详细的接口调用方法