ae-tracking 0.1.0

package/wiki/te-docs/raw//346/216/245/345/205/245/346/214/207/345/215/227//345/256/242/346/210/267/347/253/257-sdk/javascript.md

@@ -0,0 +1,257 @@
+---
+code: javascript_sdk_installation
+name: "JavaScript"
+wikiToken: Ian8wU157i7or8kW1ORccuT8nWe
+parentWikiToken: FTcTwinIOi3OiRkK4MPc2Ex7neg
+updateTime: 1767751459000
+sourceUrl: https://docs-v2.thinkingdata.cn/?version=v5.0&lan=zh-CN&code=javascript_sdk_installation
+---
+# JavaScript
+
+::: tip 提示
+
+ 在接入前, 请先阅读接入前准备。
+
+JavaScript SDK 运行环境需为浏览器，暂不兼容 IE 8 及以下版本.
+
+JavaScript SDK体积大小约为 58 KB
+
+ :::
+
+**最新版本: ** v2.3.1 下载
+
+**更新时间: ** 2026-01-07
+
+**资源下载:**** **源代码
+
+::: warning 注意
+
+当前文档适用于 v2.0.0 及以后的版本，历史版本请参考 JS 接入指南（V1），SDK下载（V1）
+
+::: 
+
+### 一、集成SDK
+
+SDK支持范围：
+
+客户端框架：Vue2、Vue3、React、Angular
+
+桌面框架：Electron
+
+#### 1.1 自动集成
+
+```
+npm install thinkingdata-browser --save
+
+"dependencies": {
+    "thinkingdata-browser": "2.3.1",
+},
+```
+
+接下来开始初始化SDK，具体配置参数请参考第二步。
+
+```
+import ta from "thinkingdata-browser";
+var config = {
+    appId: "APP_ID",
+    serverUrl: "https://YOUR_SERVER_URL",
+    autoTrack: {
+     pageShow: true, //开启页面展示事件，事件名ta_page_show
+     pageHide: true, //开启页面隐藏事件，事件名ta_page_hide
+    }
+};
+ta.init(config);
+```
+
+#### 1.2 手动集成
+
+步骤一：下载** **JavaScript SDK
+
+压缩包中提供了两种规范的脚本，您可以根据需要选择所需的脚本。下文描述的异步载入，需要使用 `thinkingdata.min.js` 文件；同步载入需要使用 `thinkingdata.umd.min.js`.
+
+步骤2：载入 JavaScript SDK
+
+您可以选择异步载入或者同步载入的方式使用 SDK. 两种方式在实际使用中区别不大，可以任选其一。
+
+在初始化 SDK 的时候需要传入一些配置参数:
+
+- `appId`: 您的项目的 APP_ID，需要进行配置，在您申请项目时会给出，请在此处填入
+- `serverUrl`: 上传数据的 URL，需要进行配置
+<!-- unsupported block: 34 -->
+
+如果您使用的是云服务，请输入以下 URL: https://global-receiver-ta.thinkingdata.cn
+
+如果您使用的是私有化部署的版本，请输入以下 URL: https://数据采集地址
+
+:::: el-tabs
+
+::: el-tab-pane label=异步载入
+
+对于异步载入，请使用 `thinkingdata.min.js`, 将以下代码置入 html 的 `<``script``>`中，并配置对应参数：
+
+```
+<!--Thinking Analytics SDK BEGIN-->
+<script>
+    !function (e) { if (!window.ThinkingDataAnalyticalTool) { var n = e.sdkUrl, t = e.name, r = window, a = document, i = "script", l = null, s = null; r.ThinkingDataAnalyticalTool = t; var o = ["track", "quick", "login", "identify", "logout", "trackLink", "userSet", "userSetOnce", "userAdd", "userDel", "setPageProperty", "setSuperProperties", "setDynamicSuperProperties", "clearSuperProperties", "timeEvent", "unsetSuperProperties", "initInstance", "trackFirstEvent", "trackUpdate", "trackOverwrite"]; r[t] = function (e) { return function () { if (this.name) (r[t]._q = r[t]._q || []).push([e, arguments, this.name]); else if ("initInstance" === e) { var n = arguments[0]; r[t][n] = { name: n }; for (var a = 0; a < o.length; a++)r[t][n][o[a]] = r[t].call(r[t][n], o[a]); (r[t]._q1 = r[t]._q1 || []).push([e, arguments]) } else (r[t]._q = r[t]._q || []).push([e, arguments]) } }; for (var u = 0; u < o.length; u++)r[t][o[u]] = r[t].call(null, o[u]); r[t].param = e, r[t].__SV = 1.1, l = a.createElement(i), s = a.getElementsByTagName(i)[0], l.async = 1, l.src = n, s.parentNode.insertBefore(l, s) } }(
+    {
+        appId:'APP_ID', //系统分配的APPID
+        name: 'ta', //全局的调用变量名，可以任意设置，后续的调用使用该名称即可
+        sdkUrl:'./thinkingdata.min.js', //统计脚本URL
+        serverUrl:'https://YOUR_SERVER_URL', //数据上传的URL
+        autoTrack: {
+           pageShow: true, //开启页面展示事件，事件名ta_page_show
+           pageHide: true, //开启页面隐藏事件，事件名ta_page_hide
+        },
+        loaded: function(ta) {
+           // var currentId = ta.getDistinctId();
+           // ta.identify(currentId);
+           // ta.quick('autoTrack');
+        }
+    });
+</script>
+<!--Thinking Analytics SDK END-->
+```
+
+异步载入特有的参数说明:
+
+- `name` 为全局的调用变量名
+- `sdkUrl` 为 sdk 的 URL，需要进行配置
+- `loaded`，初始化回调函数，使用代码片段载入为异步载入，因此有返回值的方法可能调用不成功，或者在 SDK 加载完成前触发的 track 将会出现异常。我们在参数中提供了 loaded 属性，loaded 中的回调函数将会在初始化完成后、开始上报数据前被调用，比如在此设置用户 ID，则 SDK 载入前产生的数据，将会被设置上述用户 ID.
+:::
+
+::: el-tab-pane label=同步载入
+
+对于同步载入，请使用 `thinkingdata.umd.min.js`, 将以下代码置入初始化代码中，并配置对应参数：
+
+```
+<!--Thinking Analytics SDK BEGIN-->
+<script src="./thinkingdata.umd.min.js"></script>
+<script>
+// 创建 SDK 配置对象
+var config = {
+    appId: 'APP_ID',
+    serverUrl: 'https://YOUR_SERVER_URL',
+    autoTrack: {
+     pageShow: true, //开启页面展示事件，事件名ta_page_show
+     pageHide: true, //开启页面隐藏事件，事件名ta_page_hide
+    }
+};
+// 将 SDK 实例赋给全局变量 ta，或者其他您指定的变量
+window.ta = thinkingdata;
+// 用配置对象初始化 SDK
+ta.init(config);
+</script>
+<!--Thinking Analytics SDK END-->
+```
+
+:::
+
+::::
+
+### 二、常用功能
+
+在使用常用功能之前，建议你先了解用户识别规则。SDK默认会使用随机数作为访客ID，并持久化存储访客ID在本地，用户未登录之前，会以访客ID作为身份识别ID。注意:访客 ID 在本地缓存清理时会改变。
+
+#### 2.1 设置账号 ID
+
+在用户产生登录行为时，可调用 `login` 来设置用户的账号 ID. AE 平台优先以账号 ID 作为身份标识，设置后的账号 ID 将会被保存，多次调用 `login` 将会覆盖先前的账号 ID：
+
+```
+// 用户的登录唯一标识，此数据对应上报数据里的 #account_id，此时#account_id的值为TA
+ta.login("TA");
+```
+
+<!-- unsupported block: 34 -->
+
+该方法不会上传登录事件
+
+#### 2.2 设置公共事件属性
+
+公共事件属性指的就是每个事件都会带有的属性，您可以调用 `setSuperProperties` 来设置公共事件属性，我们推荐您在发送事件前，先设置公共事件属性。对于一些重要的属性，譬如用户的会员等级、来源渠道等，这些属性需要设置在每个事件中，此时您可以将这些属性设置为公共事件属性。
+
+```
+var superProperties = {};
+superProperties["channel"] = "ta";//字符串
+superProperties["age"] = 1;//数字
+superProperties["isSuccess"] = true;//布尔
+superProperties["birthday"] = new Date();//时间
+superProperties["object"] = {key:"value"};//对象
+superProperties["object_arr"] = [{key:"value"}];//对象组
+superProperties["arr"] = ["value"];//数组
+ta.setSuperProperties(superProperties);//设置公共事件属性
+```
+
+公共事件属性将会被保存到缓存中，无需每次打开网页时调用。如果调用 `setSuperProperties` 上传了先前已设置过的公共事件属性，则会覆盖之前的属性。
+
+- Key 为该属性的名称，为字符串类型，规定只能以字母开头，包含数字，字母和下划线 "_"，长度最大为 50 个字符，对字母大小写不敏感，AE 会统一转化为小写字母
+- Value 为该属性的值，支持字符串、数字、布尔、时间、对象、对象组、数组
+<!-- unsupported block: 34 -->
+
+事件属性、用户属性的要求与公共事件属性保持一致
+
+#### 2.3 发送事件
+
+您可以直接调用 `track` 上传自定义事件，建议您根据先前梳理的埋点文档来设置事件的属性以及发送事件的条件，此处以用户购买某商品作为范例：
+
+```
+ta.track("product_buy",{product_name:"商品名"});
+```
+
+事件的名称是字符串类型，只能以字母开头，可包含数字，字母和下划线 "_"，长度最大为 50 个字符。
+
+<!-- unsupported block: 34 -->
+
+ Array 类型在 v1.3.0 之后版本支持，需要配合 AE 平台 2.5 及以上版本.
+
+Object类型需要配合 AE 平台3.5及以上版本
+
+#### 2.4 设置用户属性
+
+对于一般的用户属性，您可以调用 `userSet` 来进行设置，使用该接口上传的属性将会覆盖原有的属性值，如果之前不存在该用户属性，则会新建该用户属性，类型与传入属性的类型一致，此处以设置用户名为例：
+
+```
+// username为TA
+ta.userSet({ username: "TA" });
+//username为TE
+ta.userSet({ username: "TE" });
+```
+
+### 三、最佳实践
+
+以下示例代码包含以上所有操作，我们推荐按照如下步骤使用:
+
+```
+import ta from "thinkingdata-browser";
+var config = {
+    appId: "APP_ID",
+    serverUrl: "https://YOUR_SERVER_URL/sync_js",
+    autoTrack: {
+     pageShow: true, //开启页面展示事件，事件名ta_page_show
+     pageHide: true, //开启页面隐藏事件，事件名ta_page_hide
+    }
+};
+//初始化SDK
+ta.init(config);
+
+//如果用户已登录，可以设置用户的账号ID作为身份唯一 标识
+ta.login("TA");
+
+//设置公共事件属性
+var superProperties = {};
+superProperties["channel"] = "ta";//字符串
+superProperties["age"] = 1;//数字
+superProperties["isSuccess"] = true;//布尔
+superProperties["birthday"] = new Date();//时间
+superProperties["object"] = {key:"value"};//对象
+superProperties["object_arr"] = [{key:"value"}];//对象组
+superProperties["arr"] = ["value"];//数组
+ta.setSuperProperties(superProperties);//设置公共事件属性
+
+//发送事件
+ta.track("product_buy", //事件名称
+ //事件属性
+ {product_name:"商品名"});
+ 
+//设置用户属性
+ta.userSet({username: "TA" });
+```

package/wiki/te-docs/raw//346/216/245/345/205/245/346/214/207/345/215/227//345/256/242/346/210/267/347/253/257-sdk/macos//350/277/233/351/230/266/346/214/207/345/215/227//345/256/236/346/227/266/350/260/203/350/257/225.md

@@ -0,0 +1,77 @@
+---
+code: macos_sdk_debug
+name: "实时调试"
+wikiToken: F0vNwpfkHiN0CZk4rL0cCr7Tn3f
+parentWikiToken: Zd3uwFeYfiYBPdkrRoAcOIIanFh
+updateTime: 1745310914000
+sourceUrl: https://docs-v2.thinkingdata.cn/?version=v5.0&lan=zh-CN&code=macos_sdk_debug
+---
+# 实时调试
+
+在SDK接入过程中，您可以通过查看 SDK 在 IDE 控制台中的日志或者使用 AE 的 Debug 功能，进行实时调试。
+
+### 一、 打印SDK日志
+
+:::: el-tabs
+
+::: el-tab-pane label=Objective-C
+
+```
+[TDAnalytics enableLog:YES];
+```
+
+:::
+
+::: el-tab-pane label=Swift
+
+```
+TDAnalytics.enableLog(true)
+```
+
+:::
+
+::::
+
+<!-- unsupported block: 34 -->
+
+打开日志后，可以在IDE中过滤 ThinkingData 相关的日志来观察 SDK 的数据上报。
+
+### 二、 开启 Debug 模式
+
+开启Debug模式需要如下两步操作:
+
+1. 客户端开启Debug模式
+以下是客户端开启Debug模式的示例代码:
+
+```
+[TDAnalytics enableLog:YES];
+NSString *appid = @"AppId";
+NSString *url = @"ServerUrl";
+
+// SDK needs to be initialized on the main thread
+
+// the second way
+TDConfig *config = [[TDConfig alloc] init];
+config.appid = appid;
+config.serverURL = url;
+/*
+设置运行模式为 Debug 模式
+Normal模式:数据会存入缓存，并依据一定的缓存策略上报,默认为normal模式；建议在线上环境使用
+Debug模式:数据逐条上报。当出现问题时会以日志和异常的方式提示用户；不建议在线上环境使用
+DebugOnly模式:只对数据做校验，不会入库；不建议在线上环境使用
+ */
+config.mode = TDModeDebug;
+[TDAnalytics startAnalyticsWithConfig:config];
+```
+
+1. TE后台添加Debug设备
+为了避免 Debug 模式在生产环境上线，规定只有指定的设备才能开启 Debug 模式。只有在客户端开启了 Debug 模式，并且设备 ID 在 AE 后台的"埋点管理"页的"Debug 数据"板块中配置了的设备才能开启 Debug 模式。
+
+设备 ID 可以通过以下三种方式获取：
+
+- AE 平台中事件数据中的 #device_id 属性
+- 客户端日志：SDK 初始化完成后会打印设备 DeviceId
+- 通过实例接口调用：获取设备ID
+<!-- unsupported block: 34 -->
+
+Debug 模式可能会影响数据采集质量和 App 的稳定性，只用于集成阶段数据验证，不要在线上环境使用。

package/wiki/te-docs/raw//346/216/245/345/205/245/346/214/207/345/215/227//345/256/242/346/210/267/347/253/257-sdk/macos//350/277/233/351/230/266/346/214/207/345/215/227//351/242/204/347/275/256/345/261/236/346/200/247.md

@@ -0,0 +1,249 @@
+---
+code: macos_sdk_preset_properties
+name: "预置属性"
+wikiToken: A9QBwbAe0iBHJZk0eWRcLnf8nzh
+parentWikiToken: Zd3uwFeYfiYBPdkrRoAcOIIanFh
+updateTime: 1745309845000
+sourceUrl: https://docs-v2.thinkingdata.cn/?version=v5.0&lan=zh-CN&code=macos_sdk_preset_properties
+---
+# 预置属性
+
+#### 一、 所有事件带有的预置属性
+
+以下预置属性，是 SDK 中所有事件都会带有的预置属性
+
+**属性名**
+
+**中文名**
+
+属性类型
+
+**说明**
+
+#ip
+
+IP 地址
+
+文本
+
+用户的 IP 地址，AE 将以此获取用户的地理位置信息
+
+#country
+
+国家
+
+文本
+
+用户所在国家，根据 IP 地址生成
+
+#country_code
+
+国家代码
+
+文本
+
+用户所在国家的国家代码(ISO 3166-1 alpha-2，即两位大写英文字母)，根据 IP 地址生成
+
+#province
+
+省份
+
+文本
+
+用户所在省份，根据 IP 地址生成
+
+#city
+
+城市
+
+文本
+
+用户所在城市，根据 IP 地址生成
+
+#os_version
+
+操作系统版本
+
+文本
+
+iOS 11.2.2、Android 8.0.0 等
+
+#manufacturer
+
+设备制造商
+
+文本
+
+用户设备的制造商，如 Apple，vivo 等
+
+#os
+
+操作系统
+
+文本
+
+如 Android、iOS 等
+
+#device_id
+
+设备 ID
+
+文本
+
+用户的设备 ID，iOS 取用户的 IDFV 或 UUID，Android 取 androidID
+
+#app_version
+
+APP 版本
+
+文本
+
+您的 APP 的版本
+
+#bundle_id
+
+应用唯一标识
+
+文本
+
+应用包名或进程名
+
+#lib
+
+SDK 类型
+
+文本
+
+您接入 SDK 的类型，如 Android，iOS 等
+
+#lib_version
+
+SDK 版本
+
+文本
+
+您接入 SDK 的版本
+
+#network_type
+
+网络状态
+
+文本
+
+上传事件时的网络状态，如 WIFI、3G、4G 等
+
+#zone_offset
+
+时区偏移
+
+数值
+
+数据时间相对 UTC 时间的偏移小时数
+
+#install_time
+
+程序安装时间
+
+时间
+
+用户安装应用的时间，值来源于系统
+
+#system_language
+
+系统语言
+
+文本
+
+用户设备的系统语言(ISO 639-1，即两位小写英文字母)，如 zh, en 等
+
+#### 二、 其他预置属性
+
+除了上述提到预置属性，还有部分预置属性需要调用对应接口才会被记录：
+
+**属性名**
+
+**中文名**
+
+属性类型
+
+**说明**
+
+#duration
+
+事件时长
+
+数值
+
+需要调用计时功能接口`timeEvent:`，记录事件发生时长，单位是秒
+
+#background_duration
+
+后台停留时长
+
+数值
+
+需要调用计时功能接口`timeEvent`，记录事件发生区间内，应用在后台的停留时长，单位是秒
+
+#### 三、 获取预置属性
+
+可以调用 `getPresetProperties` 方法获取预置属性。
+
+服务端埋点需要 App 端的一些预置属性时，可以通过此方法获取 App 端的预置属性，再传给服务端。
+
+:::: el-tabs
+
+::: el-tab-pane label=Objective-C
+
+```
+//获取属性对象
+TDPresetProperties *presetProperties = [TDAnalytics getPresetProperties];
+
+//生成事件预置属性
+NSDictionary *properties = [presetProperties toEventPresetProperties];
+/*
+   {
+        "#os": "iOS",
+        "#device_id": "A8B1C00B-A6AC-4856-8538-0FBC642C1BAD",
+        "#bundle_id": "com.sw.thinkingdatademo",
+        "#manufacturer": "Apple",
+        "#system_language": "zh",
+        "#os_version": "10",
+        "#network_type": "WIFI",
+        "#zone_offset": 8,
+        "#app_version":"1.0.0"
+    }
+*/
+
+//获取某个预置属性
+NSString *bundle_id = presetProperties.bundle_id;//包名
+NSString *os = presetProperties.os;//os类型，如iOS
+NSString *system_language = presetProperties.system_language;//手机系统语言类型
+NSString *os_version = presetProperties.os_version;//系统版本号
+NSNumber *zone_offset = presetProperties.zone_offset;//时区偏移
+```
+
+:::
+
+::: el-tab-pane label=Swift
+
+```
+let presetProperties = TDAnalytics.getPresetProperties();
+
+//生成事件预置属性
+let properties = presetProperties.toEventPresetProperties();
+
+//获取某个预置属性
+let bundle_id = presetProperties.bundle_id;//包名
+let os = presetProperties.os;//os类型，如iOS
+let system_language = presetProperties.system_language;//手机系统语言类型
+let os_version = presetProperties.os_version;//系统版本号
+let zone_offset = presetProperties.zone_offset;//时区偏移值
+```
+
+:::
+
+::::
+
+<!-- unsupported block: 34 -->
+
+IP，国家城市信息由服务端解析生成，客户端不提供接口获取这些属性