@guru-ai-product/ai-product-kit 0.2.251117213210 → 0.2.251118120602

package/mcp/.doc_cache/88e1d483f18abd02_/345/237/213/347/202/271/350/247/204/350/214/203/346/226/207/346/241/243.md

@@ -1,372 +0,0 @@
-# AI 应用类APP通用埋点规范文档
-
-本文档定义了 AI 应用类APP的埋点事件和参数的标准规范，确保埋点方案的一致性和可复用性。在编写埋点需求时，**必须优先参考和复用已有的事件名和参数名**，避免重复定义。
-
-## 1. 概念说明
-
-### 埋点目的
-
-埋点，也称打点。当用户在前端产生一些行为时，借助埋点来采集数据，对用户行为进行精准分析，是产品运营的基础数据支撑。
-
-### 平台说明
-
-- **Firebase**：Firebase 是Google 的移动开发平台，可帮助用户快速构建和发展应用，同时也是一个免费的数据采集平台，是Guru进行数据采集的主要平台之一。
-- **Guru自打点平台**：Guru 自研的事件上报平台
-- **事件**：用来记录用户的操作行为
-- **参数**：用来记录用户操作行为的信息
-- **用户属性**：用来记录用户当下的状态，需要注意，虽然事件和属性是相辅相成，它们有各自独立记录体系。
-
-## 2. 埋点规定
-
-### 2.1 命名规范
-
-- **所有的事件名称、参数名称、用户属性都必须为小写**。如果涉及到连接符，一律使用下划线"_"。全部大写，驼峰命名格式等等均不符合要求。
-- **BI中台建议项目方自定义事件的参数名称，尽量使用item_category、item_name、item_id**。这些参数名称用尽后再使用其他自定义参数
-- **"value"字样作为事件参数时，尽量被定义为货币价值**，而不是用来记录时间或者其他数值
-
-### 2.2 埋点注意事项
-
-- Firebase 对上报事件的个数和参数名称以及参数个数有数量限制（详见官方文档）
-- 用户属性类型，全部统一为string
-- 用户属性的b_level 和b_play初始值是0，level_start和level_end的初始值为1
-- 一个level_start对应一个level_end，两个事件意义对应。游戏重玩需要结束上一个level_start的对应的level_end，再开始 level_start。
-- Facebook的purchase上报广告的累计收入0.01和0.2，只能上报一个策略，不可以同时上报。
-- iap_purchase 的参数名是platform，tch_ad_rev_roas_001的参数名是ad_platform
-- tch_ad_rev_roas_001记录广告收入是条件参数可以不用传，只有记录商店购买时条件参数为必传
-- level_end_success_{num}的num是用户成功完成的局数
-- IAP商品的product_id如果存在 offer 的话：product id = sku:basePlan:offerId；如果不存在 offer 的话：product id = sku
-- 给adjust上报事件时，需要Adjust回调firebaseID和设备ID参数：user_pseudo_id、device_id。这两个值和firebase上报的用户属性值一致
-
-### 2.3 参数选项说明
-
-- **必选**：必须上报
-- **可选**：根据业务需求决定是否上报
-- **有则必选**：如果功能存在，则必须上报
-- **ios必选**：iOS平台必须上报
-- **条件必选**：满足特定条件时必选
-- **android必选**：Android平台必须上报
-
-## 3. 已定义事件库
-
-### 3.1 IAP相关事件
-
-| 事件名 | 描述 | 触发条件 | Firebase | Guru | Adjust | Facebook |
-|--------|------|----------|----------|------|--------|----------|
-| iap_purchase | 购买一次性商品 | 用户购买一次性商品时触发 | Required | Required | Required | Unnecessary |
-| sub_purchase | 购买订阅商品 | 用户购买订阅商品时触发 | Required | Required | Required | Unnecessary |
-| iap_imp | 展示iap商品页面 | 展示iap商店商品页时触发 | Required | Required | Unnecessary | Unnecessary |
-| iap_close | 关闭iap商品页面 | 关闭iap商店商品展示页时触发 | Required | Required | Unnecessary | Unnecessary |
-| iap_clk | 点击iap商品 | 点击iap商店商品展示页时触发 | Required | Required | Unnecessary | Unnecessary |
-| iap_ret_true | iap付费成功 | app 内付费或试用成功打点 | Required | Required | Required | Unnecessary |
-| iap_ret_false | iap付费失败 | app 内付费或试用失败打点 | Required | Required | Unnecessary | Unnecessary |
-
-### 3.2 广告相关事件
-
-#### 广告收入相关
-
-| 事件名 | 描述 | 触发条件 | Firebase | Guru | Adjust | Facebook |
-|--------|------|----------|----------|------|--------|----------|
-| tch_ad_rev_roas_001 | 用户收入累计0.01美金 | 用户的广告收入累计达到0.01美金时触发，或用户购买一笔商店商品时触发 | Required | Required | Unnecessary | Required |
-| tch_ad_rev_roas_02 | 用户收入累计0.2美金 | 用户的广告收入累计达到0.2美金时触发，或用户购买一笔商店商品时触发 | Optional | Optional | Unnecessary | Optional |
-| ad_impression | 每一条广告展示 | 每产生一笔广告收入，触发该事件 | Required | Required | Unnecessary | Unnecessary |
-
-#### Banner广告 (bads)
-
-| 事件名 | 描述 | Firebase | Guru | Adjust | Facebook |
-|--------|------|----------|------|--------|----------|
-| bads_load | Banner广告加载 | Required | Required | Unnecessary | Unnecessary |
-| bads_loaded | Banner广告加载完成 | Required | Required | Unnecessary | Unnecessary |
-| bads_failed | Banner广告加载失败 | Required | Required | Unnecessary | Unnecessary |
-| bads_imp | Banner广告展示 | Required | Required | Unnecessary | Unnecessary |
-| bads_clk | Banner广告点击 | Required | Required | Unnecessary | Unnecessary |
-
-#### 插屏广告 (iads)
-
-| 事件名 | 描述 | Firebase | Guru | Adjust | Facebook |
-|--------|------|----------|------|--------|----------|
-| iads_load | 插屏广告加载 | Required | Required | Unnecessary | Unnecessary |
-| iads_loaded | 插屏广告加载完成 | Required | Required | Unnecessary | Unnecessary |
-| iads_failed | 插屏广告加载失败 | Required | Required | Unnecessary | Unnecessary |
-| iads_imp | 插屏广告展示 | Required | Required | Unnecessary | Unnecessary |
-| iads_clk | 插屏广告点击 | Required | Required | Unnecessary | Unnecessary |
-| iads_close | 插屏广告关闭 | Required | Required | Unnecessary | Unnecessary |
-
-#### 激励广告 (rads)
-
-| 事件名 | 描述 | Firebase | Guru | Adjust | Facebook |
-|--------|------|----------|------|--------|----------|
-| rads_load | 激励广告加载 | Required | Required | Unnecessary | Unnecessary |
-| rads_loaded | 激励广告加载完成 | Required | Required | Unnecessary | Unnecessary |
-| rads_failed | 激励广告加载失败 | Required | Required | Unnecessary | Unnecessary |
-| rads_imp | 激励广告展示 | Required | Required | Unnecessary | Unnecessary |
-| rads_clk | 激励广告点击 | Required | Required | Unnecessary | Unnecessary |
-| rads_rewarded | 激励广告获得奖励 | Required | Required | Unnecessary | Unnecessary |
-| first_rads_rewarded | 首次激励广告获得奖励 | Required | Required | Unnecessary | Unnecessary |
-| rads_close | 激励广告关闭 | Required | Required | Unnecessary | Unnecessary |
-
-#### 开屏广告 (oads)
-
-| 事件名 | 描述 | Firebase | Guru | Adjust | Facebook |
-|--------|------|----------|------|--------|----------|
-| oads_load | 开屏广告加载 | Required | Required | Unnecessary | Unnecessary |
-| oads_loaded | 开屏广告加载完成 | Required | Required | Unnecessary | Unnecessary |
-| oads_failed | 开屏广告加载失败 | Required | Required | Unnecessary | Unnecessary |
-| oads_imp | 开屏广告展示 | Required | Required | Unnecessary | Unnecessary |
-| oads_close | 开屏广告关闭 | Required | Required | Unnecessary | Unnecessary |
-
-#### 原生广告 (nads)
-
-| 事件名 | 描述 | Firebase | Guru | Adjust | Facebook |
-|--------|------|----------|------|--------|----------|
-| nads_load | 原生广告加载 | Required | Required | Unnecessary | Unnecessary |
-| nads_loaded | 原生广告加载完成 | Required | Required | Unnecessary | Unnecessary |
-| nads_failed | 原生广告加载失败 | Required | Required | Unnecessary | Unnecessary |
-| nads_imp | 原生广告展示 | Required | Required | Unnecessary | Unnecessary |
-| nads_close | 原生广告关闭 | Required | Required | Unnecessary | Unnecessary |
-
-### 3.3 iOS弹窗相关事件
-
-| 事件名 | 描述 | Firebase | Guru | Adjust | Facebook |
-|--------|------|----------|------|--------|----------|
-| att_result | ATT授权结果 | Required | Required | Unnecessary | Unnecessary |
-
-### 3.4 Android推送相关事件
-
-| 事件名 | 描述 | Firebase | Guru | Adjust | Facebook |
-|--------|------|----------|------|--------|----------|
-| noti_perm_imp | 通知权限弹窗展示 | Required | Required | Unnecessary | Unnecessary |
-| noti_perm_result | 通知权限结果 | Required | Required | Unnecessary | Unnecessary |
-| noti_perm_rationale_imp | 通知权限说明弹窗展示 | Required | Required | Unnecessary | Unnecessary |
-| noti_perm_rationale_result | 通知权限说明弹窗结果 | Required | Required | Unnecessary | Unnecessary |
-
-### 3.5 Google DMA相关事件
-
-| 事件名 | 描述 | Firebase | Guru | Adjust | Facebook |
-|--------|------|----------|------|--------|----------|
-| dma_gg | Google DMA | Required | Required | Unnecessary | Unnecessary |
-
-### 3.6 项目方自定义事件（UserAction）
-
-#### 着陆相关
-
-| 事件名 | 描述 | 触发条件 | 必选性 |
-|--------|------|----------|--------|
-| app_landing_start | App着陆开始 | 当用户打开 App，开始处理 landing 过程时打点 | 有则必选 |
-| app_landing_complete | App着陆完成 | 当用户打开 App，完成landing过程后打点 | 有则必选 |
-| app_landing_failed | App着陆失败 | Landing过程中出错，则处理错误后打点 | 有则必选 |
-
-#### 登录相关
-
-| 事件名 | 描述 | 触发条件 | 必选性 |
-|--------|------|----------|--------|
-| user_login | 用户登录 | 用户点击登录后打点 | 有则必选 |
-| user_login_succeed | 用户登录成功 | 用户登录成功后打点 | 有则必选 |
-| user_login_failed | 用户登录失败 | 用户登录失败后打点 | 有则必选 |
-| user_logout | 用户登出 | 用户点击登出后打点 | 有则必选 |
-| user_logout_succeed | 用户登出成功 | 用户登出成功后打点 | 有则必选 |
-| user_logout_failed | 用户登出失败 | 用户登出失败后打点 | 有则必选 |
-
-#### 权限获取相关
-
-| 事件名 | 描述 | 触发条件 | 必选性 |
-|--------|------|----------|--------|
-| photo_permission_dialog_show | 相册权限弹窗展示 | 相册权限弹窗展示时打点（请求） | 有则必选 |
-| photo_permission_result | 相册权限结果 | - | 有则必选 |
-| photo_permission_granted | 相册权限授权 | 相册权限弹窗用户选择 allow 时打点（==authorized） | 有则必选 |
-| photo_permission_denied | 相册权限拒绝 | 相册权限弹窗用户选择 don't allow 时打点（==denied） | 有则必选 |
-| tutorial_photo_permission_skip | 引导页相册权限跳过 | 在引导过程中因为获取了相册权限跳过了对应的引导页时打此点 | 有则必选 |
-
-#### 引导页IAP相关
-
-| 事件名 | 描述 | 触发条件 | 必选性 |
-|--------|------|----------|--------|
-| tutorial_iap_imp | 引导页IAP展示 | IAP付费引导开始且第一页曝光 | 有则必选 |
-| tutorial_iap_clk | 引导页IAP点击 | 点击IAP商品时打点 | 有则必选 |
-| tutorial_iap_ret_true | 引导页IAP付费成功 | IAP付费或试用成功打点 | 有则必选 |
-| tutorial_iap_ret_false | 引导页IAP付费失败 | IAP付费或试用失败打点 | 有则必选 |
-| tutorial_iap_close | 引导页IAP关闭 | 点击「X」按钮或「Skip」按钮时打点 | 有则必选 |
-
-#### IAP相关
-
-| 事件名 | 描述 | 触发条件 | 必选性 |
-|--------|------|----------|--------|
-| iap_pop_up_failed | IAP弹窗失败 | 当 iap 的付费半窗弹出失败时打点 | 有则必选 |
-
-#### Rating相关
-
-| 事件名 | 描述 | 触发条件 | 必选性 |
-|--------|------|----------|--------|
-| rating_show | 评分弹窗展示 | 当引导用户评分弹窗弹出时打点 | 必选 |
-| rating_positive_submit | 评分5星提交 | 当用户评分5星时打点 | 必选 |
-| rating_negative_submit | 评分低于5星提交 | 当用户评分低于5星时打点 | 必选 |
-| rating_close | 评分弹窗关闭 | 当用户没有评分，关闭弹窗时打点 | 必选 |
-
-#### 上传下载相关
-
-| 事件名 | 描述 | 触发条件 | 必选性 |
-|--------|------|----------|--------|
-| upload_task_start | 上传任务开始 | 开始上传 | 有则必选 |
-| upload_task_get_config | 获取上传Token | 开始获取 Token | 有则必选 |
-| upload_task_get_config_success | 获取Token成功 | 获取 Token 成功 | 有则必选 |
-| upload_task_get_config_failed | 获取Token失败 | 获取 Token 失败 | 有则必选 |
-| upload_task_failed | 上传失败 | 上传失败 | 有则必选 |
-| upload_task_finish | 上传完成 | 上传完成 | 有则必选 |
-| download_task_start | 下载任务开始 | 开始下载 | 有则必选 |
-| download_task_failed | 下载失败 | 下载失败 | 有则必选 |
-| download_task_finish | 下载完成 | 下载完成 | 有则必选 |
-
-## 4. 已定义参数库
-
-### 4.1 通用参数
-
-| 参数名 | 类型 | 描述 | 示例值 | 必选性 |
-|--------|------|------|--------|--------|
-| item_category | string | 界面跳转的来源/文件类型/场景分类 | 从某个场景跳转 | 必选/可选 |
-| item_name | string | 商品ID/产品ID | 商品id | 必选/可选 |
-| item_id | string | 具体的主题id/项目ID | 具体的主题 id | 可选 |
-| product_id | string | 商店购买商品ID | 商品id（如果存在 offer 的话：product id = sku:basePlan:offerId；如果不存在 offer 的话：product id = sku） | 必选/条件必选 |
-| value | double | 收入价值/商品价格/货币价值 | 实际累计值，如0.01345 | 必选 |
-| currency | string | 收入币种/付费币种 | USD/用户的付费币种 | 必选 |
-| platform | string | 商店平台 | GooglePlay：google_play / AppleStore：appstore | 必选 |
-| ad_platform | string | 收入平台/广告平台 | 使用MAX广告平台：MAX / 使用ADMOB广告平台：ADMOB / 商店购买：google_play/appstore/thirdparty | 必选 |
-| order_type | string | 商店购买订单类型 | IAP/SUB | 必选/条件必选 |
-| order_id | string | 商店购买订单ID | 系统返回orderid | 必选/条件必选 |
-| trans_ts | timestamp | 商店购买付费时间戳 | - | 必选/条件必选 |
-| type | string | 商品类型/评分时机/文件类型等 | 订阅商品：subscription / 一次性商品：product / 评分时机：first/notfirst | 必选/可选 |
-| isfree | string | 是否试用 | 试用：1 / 付费：0 | 必选 |
-| duration | int | 时间长度（毫秒） | 毫秒 | 可选 |
-| error_code | string | 报错的分类编码 | 默认：-1 / 网络问题：400 | 可选 |
-| err | string | 具体的报错信息（异常信息） | 具体的错误信息 | 可选 |
-| result | string | 结果 | permanentlyDenied/denied/granted/notDetermined | 可选 |
-
-### 4.2 参数值枚举
-
-#### platform 枚举值
-
-- `google_play` - GooglePlay商店
-- `appstore` - AppleStore商店
-- `thirdparty` - 第三方商店
-
-#### ad_platform 枚举值
-
-- `MAX` - MAX广告平台
-- `ADMOB` - ADMOB广告平台
-- `google_play` - GooglePlay商店购买
-- `appstore` - AppleStore商店购买
-- `thirdparty` - 第三方商店购买
-
-#### order_type 枚举值
-
-- `IAP` - 商店内购买一次性商品
-- `SUB` - 商店内购买订阅商品
-
-#### type 枚举值（商品类型）
-
-- `subscription` - 订阅商品
-- `product` - 一次性商品
-
-#### type 枚举值（评分时机）
-
-- `first` - 首次评分
-- `notfirst` - 非首次评分
-
-#### isfree 枚举值
-
-- `1` - 试用
-- `0` - 付费
-
-#### result 枚举值（权限）
-
-- `permanentlyDenied` - 完全禁止
-- `denied` - 禁止
-- `granted` - 授权
-- `notDetermined` - 未决定
-
-#### item_category 枚举值（文件类型）
-
-- `image` - 图片 (jpg\jpeg\png\gif\webp\bpm\tiff\tif\heic\heif\ico\svg\ai\eps\raw\psd)
-- `video` - 视频(mov\mp4\avi\wmv\mkv\flv\webm\mpeg\mpg\avchd\3gp\vob\ogv\asf\m4v\rmvb\ts\qt\divx\xvid\f4v\mxf\swf\dv)
-- `audio` - 音频(mp3\wav\flac\aac\ogg\wma\m4a\ape\alac\aiff\opus\pcm\ac3\dts\au\amr\midi\mid)
-- `file` - 文件(txt\doc\docx\pdf\rtf\odt\md\html\htm\xml\json\csv\tex\log\ini\cfg\conf\yaml\yml\sub\srt\pages\key\ppt\pptx\xls\xlsx\epub\mobi\azw\bat\sh\py\js\css\php\java\c\cpp\h\cs\rb\go\swift\kt\sql\ps1\vb\vbs)
-- `package` - 压缩包(zip\rar\7z\tar\gz\bz2\xz\tgz\jar\arj\cab\iso\dmg\lha\z\sitx\deb\rpm\apk)
-- `others` - 其他
-
-## 5. 已定义用户属性库
-
-### 5.1 Firebase/Guru通用用户属性
-
-| 属性名 | 类型 | 描述 | 示例值 | 必选性 |
-|--------|------|------|--------|--------|
-| user_id | string | 后端中台生成ID | 新用户第一次打开APP时记录 | 必选 |
-| device_id | string | 用户的设备ID | 用户的设备ID | 必选 |
-| first_open_time | string | 用户第一次first_open的时间戳，单位毫秒 | - | 必选 |
-| is_iap_user | string | 是否为付费用户 | true/false（付费成功后设置属性参数为true，如果没有发生付费缺省为false） | 必选 |
-| att_status | string | ATT授权状态 | authorized/denied/restricted/notDetermined/notApplicable | ios必选 |
-| noti_perm | string | 消息通知权限状态 | Android: granted/denied / iOS: granted/denied/provisional/not_determined | 可选 |
-
-### 5.2 Guru Info信息
-
-| 属性名 | 类型 | 描述 | 示例值 | 必选性 |
-|--------|------|------|--------|--------|
-| info.deviceId | string | 设备ID（用户的设备ID，iOS取用户的IDFV或UUID，Android取androidID） | - | 必选（必须达到100%） |
-| info.uid | string | 中台ID | - | 必选（必须达到95%以上，只在未获取到uid时可以为空） |
-| info.adjustId | string | adjust_id | - | 必选（必须达到95%以上，只在未获取到adjust时可以为空） |
-| info.adId | string | 广告 ID/广告标识符 (IDFA) | - | 必选（必须达到95%以上） |
-| info.firebaseId | string | 用户的pseudo_id | - | 必选（必须达到100%） |
-
-### 5.3 项目方自定义用户属性
-
-| 属性名 | 类型 | 描述 | 示例值 | 必选性 |
-|--------|------|------|--------|--------|
-| pro_user_type | string | 用户当前的会员状态 | pro：会员 / nonpro：非会员 / freetrial：免费试用中 / unkown：尚未获取或者正在获取 / failed：会员状态获取失败 / expired：会员失效且超过宽限期 / expired_grace：会员失效但在宽限期内 | 必选 |
-| pro_user_order_id | string | 用户的 order id（根 order） | 只记录当前生效的 order id，失效的不记。同一个订阅应该是同样的order id | 必选 |
-
-## 6. 使用指南
-
-### 6.1 复用已有事件和参数
-
-在编写埋点需求时，**必须优先检查上述事件库和参数库**：
-
-1. **优先复用已有事件**：检查上述事件库，如果已有事件符合需求，必须直接使用已有事件名，不要创建新的事件名
-2. **优先复用已有参数**：检查上述参数库，如果已有参数符合需求，必须直接使用已有参数名，不要创建新的参数名
-3. **新增事件或参数**：如果需要新增，必须严格遵循命名规范（全小写，使用下划线），并在输出中明确标注为新增项
-
-### 6.2 事件和参数的组合
-
-每个事件应包含：
-
-- **必需参数**：根据事件类型选择对应的必需参数
-- **可选参数**：根据业务需求选择对应的可选参数
-- **参数值**：使用上述枚举值中的标准值
-
-### 6.3 命名一致性检查
-
-在生成埋点方案后，检查：
-
-- 事件名是否符合全小写+下划线格式
-- 参数名是否符合全小写+下划线格式
-- 是否复用了已有的事件和参数名
-- 枚举值是否使用了标准值
-- 参数类型是否正确（string/double/int/timestamp）
-
-### 6.4 平台上报要求
-
-根据"不同平台打点checklist"表格，确定每个事件需要在哪些平台上报：
-
-- **Required**：必须上报
-- **Optional**：可选上报
-- **Unnecessary**：不需要上报
-
-## 7. 常见问题
-
-- **没有展示广告，打印了ad_impression**：确保只在有广告展示时才触发该事件
-- **重启app，用户属性的b_level，b_play，is_iap_user等参数值被重置了**：检查用户属性的持久化逻辑
-- **iap_purchase和sub_purchase的参数，同时存在platform和ad_platform，预期只有platform**：确保正确使用参数名，iap_purchase使用platform，tch_ad_rev_roas_001使用ad_platform
-
-## 8. 更新记录
-
-本文档应随埋点规范的更新而同步更新。新增事件或参数时，请及时更新本文档。
-
----
-
-**注意**：本文档是埋点规范的核心参考文档，所有埋点方案设计都应遵循本文档的规范。在生成埋点需求时，必须优先复用本文档中已定义的事件和参数。