游戏 SDK 预置事件和预置属性
|
收藏
App 平台
说明
指游戏 SDK，被客户集成后，最终打包成 App 在 Android & iOS 平台运行的场景
预置事件
| 事件英文变量名 | 事件显示名 | 属性英文变量名 | 事件属性显示名 | 属性值类型 | 属性值示例或说明 | 触发时机 |
|---|---|---|---|---|---|---|
| $AppStart | App 启动 | $is_first_time | 是否首次 | 布尔值 | 表示是否是首次启动 App，可参考文档新增用户及首日首次标记 | 启动 App 或从后台切换进入 App 时触发 |
| $resume_from_background | 是否从后台唤醒 | 布尔值 | ||||
| $AppEnd | App 退出 | $event_duration | 事件时长 | 数值 | 特指本次 App 启动到 App退出的时长，单位为 秒 | 退出 App 或 App 进入后台时触发 |
| $AppInstall | App 激活 / App 安装后首次启动 | $browser | 浏览器名 | 字符串 | 通过 UA 解析出来的值 | 需要调用 trackAppInstall 接口采集采集该事件，且 App 安装后首次调用才会触发，第二次调用不会再触发。 |
| $utm_source | 广告系列来源 | 字符串 | 需要使用神策 App 渠道追踪方法，渠道匹配成功之后，AppInstall 事件才会有 $utm 相关的属性，具体可参考神策的 App 渠道追踪。 | |||
| $utm_medium | 广告系列媒介 | 字符串 | ||||
| $utm_term | 广告系列字词 | 字符串 | ||||
| $utm_content | 广告系列内容 | 字符串 | ||||
| $utm_campaign | 广告系列名称 | 字符串 | ||||
| $ios_install_source | / | 字符串 | 记录 App 精准匹配时的匹配字段，比如 IMEI、Android ID、Mac 地址、IDFA。在 App 端采集数据时，会上传此字段，但是在 extractor 模块会将该字段去掉不入库。因此该属性不会入库。 | |||
| $utm_matching_type | 渠道追踪匹配模式 | 字符串 | 在 App 端采集事件时默认没有该属性，而是在 extractor 模块添加，是App 渠道追踪匹配成功时，记录渠道匹配成功的模式，比如设备指纹模糊匹配，设备标识精准匹配，如果没有匹配成功，该属性值在事件分析页面展示为「未知」。 | |||
| $matched_key | 渠道匹配关键字 | 字符串 | 在 App 端采集事件时默认没有该属性，而是在 extractor 模块添加，是App 渠道追踪匹配成功时，记录匹配关键字段，比如是用 IMEI 匹配成功的，则记录 md5 后的IMEI，如果是用 IP_UA 的方式匹配成功的，则记录为 IP_UA。如果没有匹配成功，该属性值在事件分析页面展示为「未知」。 | |||
| $matching_key_list | 渠道匹配关键字列表 | 字符串 | SA 1.14 版本后支持；在 App 端采集事件时默认没有该属性，而是在 extractor 模块添加，是记录该激活事件所有可匹配的关键字，比如 md5 后的 IMEI，Android ID，oaid ，IP_UA 等。在匹配的时候，会按照这些关键字的优先级，和点击广告时记录的关键字进行匹配。 | |||
| $channel_active_period_day | 有效激活窗口期（天） | 数值 | 记录窗口期配置的信息，因窗口期变化造成的激活变化也可进行溯源。 | |||
| $channel_attribute_period_hour | 激活归因窗口期（小时） | 数值 | ||||
| $AppRemoteConfigChanged | 远程控制配置变化 | $app_remote_config | 远程控制配置信息 | 字符串 | 获取远程配置，SDK 加载配置生效后，采集该事件，并采集对应的控制信息，用于问题排查 | SDK 获取到远程配置 |
所有事件都有的预置属性
| 属性名 | 属性类型 | 默认显示名 | 说明 | 备注 |
|---|---|---|---|---|
| $app_id | 字符串 | 应用唯一标识 | App 的唯一标识 | |
| $app_name | 字符串 | 应用名称 | 应用的名称 | |
| $app_version | 字符串 | 应用版本 | APP 的应用版本 | |
| $lib | 字符串 | SDK类型 | SDK 类型，比如 Android/iOS | |
| $lib_version | 字符串 | SDK版本 | SDK 版本 | |
| $manufacturer | 字符串 | 设备制造商 | 设备制造商 | |
| $brand | 字符串 | 设备品牌 | 设备品牌 | 只有 Android 端采集 |
| $model | 字符串 | 设备型号 | 设备型号 | |
| $os | 字符串 | 操作系统 | 操作系统 | |
| $os_version | 字符串 | 操作系统版本 | 操作系统版本 | |
| $screen_height | 数值 | 屏幕高度 | 屏幕高度（iOS 端是逻辑分辨率，开发中的点像素；Android 采集的是物理像素点，例如 Android 手机分辨率是 1920 x 1080，采集到的就是这个值。） | |
| $screen_width | 数值 | 屏幕宽度 | 屏幕宽度（iOS 端是逻辑分辨率，开发中的点像素；Android 采集的是物理像素点，例如 Android 手机分辨率是 1920 x 1080，采集到的就是这个值。） | |
| $wifi | 布尔值 | 是否 WiFi | 事件触发时是否为 WiFi | |
| $carrier | 字符串 | 运营商名称 | 事件触发时设备 SIM 卡的运营商名称，如果 Android 没有获取 READ_PHONE_STATE 权限，或者未插卡，则无法获取运营商名称；如果 iOS 未插卡，则无法获取运营商名称 | |
| $network_type | 字符串 | 网络类型 | 事件触发时的网络类型，如果 SDK 没有获取网络类型的权限，或者手机为飞行模式、未插卡且没有连接 WiFi等情况，则无法获取网络类型。 | |
| $timezone_offset | 数值 | 时区偏移量 | App 或系统的时区 | |
| $is_first_day | 布尔值 | 是否首日访问 | 表示是否是首日触发事件，此属性可用于筛选新老用户，具体取值逻辑可参考文档 新增用户及首日首次标记 | |
| $is_login_id | 布尔值 | 是否登录 ID | 数据入库时判断添加 | |
| $ip | 字符串 | IP | 后端通过解析 HTTP 请求而得到 | |
| $country | 字符串 | 国家 | 由 IP 解析得到 | |
| $province | 字符串 | 省份 | ||
| $city | 字符串 | 城市 | ||
| $device_id | 字符串 | 设备 ID | Android 端主要取 Android ID ，iOS 端先尝试获取 IDFA，如果获取不到，则取 IDFV，具体取值逻辑可参考文档 如何准确的标识用户 |
预置用户属性
| 属性名 | 属性类型 | 默认显示名 | 说明 | 备注 |
|---|---|---|---|---|
| $first_visit_time | Datetime（时间） | 首次访问时间 | 调用 trackAppInstall 接口后，新用户首次启动App， 会给此属性赋值 | 该属性是在调用 trackAppInstall 接口时设置的， 一般标记在匿名 ID （Android ID/IDFA）的用户身上，如果登录 ID 和匿名 ID 没有关联成功，则登录 ID 用户的该属性值没值。 |
| $utm_source | 字符串 | 首次广告系列来源 | 这些属性是依赖于调用 trackAppInstall 接口，且使用 APP 渠道追踪，在匹配成功后，渠道链接中包含的对应渠道信息（ utm_ 参数）会被写入用户表，渠道追踪匹配模式和渠道匹配关键字则记录匹配的渠道方式，以及通过哪个关键字匹配上的 | |
| $utm_medium | 字符串 | 首次广告系列媒介 | ||
| $utm_term | 字符串 | 首次广告系列字词 | ||
| $utm_content | 字符串 | 首次广告系列内容 | ||
| $utm_campaign | 字符串 | 首次广告系列名称 | ||
| $utm_matching_type | 字符串 | 渠道追踪匹配模式 | ||
$matched_key | 字符串 | 渠道匹配关键字 | ||
| $matching_key_list | 字符串 | 渠道匹配关键字列表 | 渠道匹配关键字列表，包含所有可能用于渠道匹配的 key | 同上，且 SA 1.14+ 版本支持，渠道匹配关键字列表，包含所有可能用于渠道匹配的 关键字 |
其他
| 属性名 | 属性类型 | 默认显示名 | 说明 | 备注 |
|---|---|---|---|---|
| $lib_plugin_version | List | SDK 插件版本号 | 该属性是用于记录神策分析各插件的版本号，例如： Android 插件；采集示例：$lib_plugin_version:["android_plugin:4.2"] | 一般是三方框架插件形式集成 SDK 才会采集 |
PC 平台
说明
- 指游戏 SDK，被客户集成后，最终 PC 平台（包括 Windows & macOS）运行的场景
- 目前仅 Unity SDK 和 Unreal Engine SDK 支持 PC 平台
预置事件
| 事件英文变量名 | 事件显示名 | 属性英文变量名 | 事件属性显示名 | 属性值类型 | 属性值示例或说明 | 触发时机 | 备注 |
|---|---|---|---|---|---|---|---|
| $AppStart | App 启动 | $is_first_time | 是否首次 | 布尔值 | 表示是否是首次启动 App，可参考文档新增用户及首日首次标记 | 启动 App 或从后台切换进入 App 时触发 | Unreal Engine SDK 暂不支持 |
| $AppEnd | App 退出 | $event_duration | 事件时长 | 数值 | 特指本次 App 启动到 App退出的时长，单位为 秒 | 退出 App 或 App 进入后台时触发 | Unreal Engine SDK 暂不支持 |
| $AppInstall | App 激活 / App 安装后首次启动 | $browser | 浏览器名 | 字符串 | 通过 UA 解析出来的值 | 需要调用 trackAppInstall 接口采集采集该事件，且 App 安装后首次调用才会触发，第二次调用不会再触发。 | Unreal Engine SDK v0.0.3 及之后的版本支持 |
| $channel_active_period_day | 有效激活窗口期（天） | 数值 | 记录窗口期配置的信息，因窗口期变化造成的激活变化也可进行溯源。 | ||||
| $channel_attribute_period_hour | 激活归因窗口期（小时） | 数值 |
所有事件都有的预置属性
| 属性名 | 属性类型 | 默认显示名 | 说明 | 备注 |
|---|---|---|---|---|
| $app_id | 字符串 | 应用唯一标识 | App 的唯一标识 | Unreal Engine SDK 暂不支持 |
| $app_name | 字符串 | 应用名称 | 应用的名称 | Unreal Engine SDK 暂不支持 |
| $app_version | 字符串 | 应用版本 | APP 的应用版本 | |
| $lib | 字符串 | SDK类型 | SDK 类型，比如 Android/iOS | |
| $lib_version | 字符串 | SDK版本 | SDK 版本 | |
| $manufacturer | 字符串 | 设备制造商 | 设备制造商，Windows 采集结果为显卡制造商 | Unreal Engine SDK 暂不支持 |
| $model | 字符串 | 设备型号 | 设备型号 | Unreal Engine SDK 暂不支持 |
| $os | 字符串 | 操作系统 | 操作系统 | |
| $os_version | 字符串 | 操作系统版本 | 操作系统版本 | |
| $screen_height | 数值 | 屏幕高度 | 屏幕高度 | |
| $screen_width | 数值 | 屏幕宽度 | 屏幕宽度 | |
| $timezone_offset | 数值 | 时区偏移量 | App 或系统的时区 | |
| $is_first_day | 布尔值 | 是否首日访问 | 表示是否是首日触发事件，此属性可用于筛选新老用户，具体取值逻辑可参考文档 新增用户及首日首次标记 | |
| $is_login_id | 布尔值 | 是否登录 ID | 数据入库时判断添加 | |
| $ip | 字符串 | IP | 后端通过解析 HTTP 请求而得到 | |
| $country | 字符串 | 国家 | 由 IP 解析得到 | |
| $province | 字符串 | 省份 | ||
| $city | 字符串 | 城市 | ||
| $device_id | 字符串 | 设备 ID |
预置用户属性
说明
Unreal Engine SDK v0.0.3 及之后的版本支持
| 属性名 | 属性类型 | 默认显示名 | 说明 | 备注 |
|---|---|---|---|---|
| $first_visit_time | Datetime（时间） | 首次访问时间 | 调用 trackAppInstall 接口后，新用户首次启动App， 会给此属性赋值 | 该属性是在调用 trackAppInstall 接口时设置的， 一般标记在匿名 ID 的用户身上，如果登录 ID 和匿名 ID 没有关联成功，则登录 ID 用户的该属性值没值。 |
| $matching_key_list | 字符串 | 渠道匹配关键字列表 | 渠道匹配关键字列表，包含所有可能用于渠道匹配的 key | 同上，且 SA 1.14+ 版本支持，渠道匹配关键字列表，包含所有可能用于渠道匹配的关键字 |
小游戏平台
说明
小游戏平台主要包括：
- 非 H5 小游戏：微信小游戏、QQ小游戏、字节小游戏 等
- H5 小游戏： H5 小游戏
预置事件
| 事件英文变量名 | 事件显示名 | 触发时机 | 对应的生命周期 | 非 H5 小游戏 | H5 小游戏 |
|---|---|---|---|---|---|
| $MPShow | 小程序显示 | 小游戏热启动或者从后台进入前台时触发 | 触发小游戏的 onShow 生命周期函数时触发 | 支持 | 不支持 |
| $MPHide | 小程序进入后台 | 小游戏进入后台时触发 | 触发小游戏的 onHide 生命周期函数时触发 | 支持 | 不支持 |
所有事件都有的预置属性
| 字段名称 | 类型 | 说明 | 非 H5 小游戏 | H5 小游戏 |
|---|---|---|---|---|
| $lib | 字符串 | SDK 类型 | 支持 | 支持 |
| $lib_version | 字符串 | SDK 版本 | 支持 | 支持 |
| $app_id | 字符串 | 小程序的 App ID | 支持 | 不支持 |
| $brand | 字符串 | 品牌 | 支持 | 不支持 |
| $screen_height | 数值 | 屏幕高度 | 支持 | 支持 |
| $screen_width | 数值 | 屏幕宽度 | 支持 | 支持 |
| $model | 字符串 | 设备型号 | 支持 | 支持 |
| $manufacturer | 字符串 | 设备制造商 | 支持 | 支持 |
| $mp_client_app_version | 字符串 | 客户端应用版本号 | 支持 | 不支持 |
| $mp_client_basic_library_version | 字符串 | 基础库版本 | 支持 | 不支持 |
| $os | 字符串 | 操作系统 | 支持 | 支持 |
| $os_version | 字符串 | 操作系统版本 | 支持 | 支持 |
| $is_first_day | 布尔值 | 是否首日访问（从新用户第一次访问到当天的二十三点五十九分五十九秒之间的值都为真，之后都为假，判断标识存在微信 storage 中） | 支持 | 支持 |
| $is_login_id | 布尔值 | 是否是登录 ID（数据入库后添加） | 支持 | 支持 |
| $ip | 字符串 | SDK 发送数据请求携带的属性 | 支持 | 支持 |
| $timezone_offset | 数值 | 时区偏移量 | 支持 | 支持 |
| $country | 字符串 | 由 IP 解析得到 | 支持 | 支持 |
| $province | 字符串 | 由 IP 解析得到 | 支持 | 支持 |
| $city | 字符串 | 由 IP 解析得到 | 支持 | 支持 |
| $network_type | 字符串 | 网络类型 | 支持 | 支持 |
| $browser | 字符串 | 浏览器类型，由 UA 解析得到 | 支持 | 支持 |
| $browser_version | 字符串 | 浏览器版本，由 UA 解析得到 | 支持 | 支持 |
注：本文档内容为神策产品使用和技术细节说明文档，不包含适销类条款；具体企业采购产品和技术服务内容，以商业采购合同为准。
