456数据SDK文档看什么？先查端支持与接入边界

目录索引

• 先立个误区：SDK 文档不是安装说明
• 456数据SDK文档第一层：端支持全景
• 第二层：接入边界与前置条件
• 第三层：指标口径章节
• 把文档用成团队契约
• 常见问题
• 参考资料

团队常把 SDK 文档当成安装说明书，看完第一步就收工。456数据SDK文档其实是接入契约：端支持清单、前置条件、指标口径写在里面，别把争议留到上线后。

本文要点

• SDK 文档不是安装说明书，而是接入契约与边界说明书，先查它支持哪几端。
• 端支持看全景：覆盖网站、App、小程序三端，提供6种接入方式，先对号再入座。
• 接入位置与前置条件逐端核对：Web 内联、iOS 必须 Keychain Sharing、HarmonyOS 需要网络权限。
• 指标口径单独成章：UV 按 Cookie 去重、PV 逐页累计、App 按设备去重，小程序未定义的不替补。
• 把文档当唯一契约：团队里关于接入的争议，回到文档原文对齐。

示例数字仅用于说明口径。

　　你有没有见过这种场面：前端说代码按示例贴好了，客户端说原生 SDK 也接了，上线一周后报表对不上，三方各执一词，最后发现谁都只看了文档的前两屏。一份 SDK 文档到底该看什么？换个前提想：你查的不是某端的安装说明，而是一份管着网站、App、小程序三端的一体化数据分析契约，流量统计、用户行为分析与前端性能监控的口径都写在里面；下面按技术架构师的读法，把这份文档拆成三层来查。

▌ 先立个误区：SDK 文档不是安装说明

　　先把常见的误读摆出来：很多新人打开文档，找的是「第一步贴哪段代码」，复制粘贴完就认为接入结束了。这个读法漏掉的恰恰是文档里最值钱的部分。

把文档当说明书的后果

　　后果通常在上线后才暴露：网页端看着正常，App 端开了新会话就被算成新访客；HarmonyOS 包装上了，数据一个都没落库。回头翻文档才发现，这些前置条件早就写在注意事项里，只是没人看第二屏。

换个读法：文档是接入契约

　　换个角度，SDK 文档其实是一份接入契约：它声明了支持哪些端、每种端要满足什么前置条件、指标按什么口径计算。团队评审接入方案时，争议应该回到这份契约里找答案，而不是凭经验争论。

　　契约思维和说明书思维的差别在于：说明书告诉你怎么操作，契约告诉你双方各自承担什么。开发负责把代码放对位置并满足前置条件，平台负责按声明的口径采集与计算；任何一方跳过契约，偏差都会在报表数字里兑现。

目录结构先扫一遍，六个入口各对应一端，别只点开第一个就动手。

▌ 456数据SDK文档第一层：端支持全景

　　读文档的第一层，是先看全景：这套 SDK 到底覆盖哪些端，你要接的端在不在清单里。这一步决定后面用哪一份文档。

三端与6种接入方式

　　整体覆盖网站、App、小程序三端，提供6种接入方式：Web JS、微信小程序、Android、iOS、uni-app、HarmonyOS。注意这不是按操作系统数出来的六个独立体系，而是三端之下的六种具体接入路径，选型时先问自己的业务落在哪一端。

Web JS 与微信小程序的位置

　　Web JS 对应网站端，以一段内联代码的形式贴进页面；微信小程序对应小程序生态，在小程序工程内初始化，不混用网站脚本。两者验证路径不同，网站端到实时访客确认，小程序端走专属页面查看。

Android、iOS、uni-app、HarmonyOS 怎么归位

　　Android 与 iOS 是 App 端的两条原生线；uni-app 以原生插件形式接入，文档里没有提供下载链接，需要按说明自行集成；HarmonyOS 走原生 .har 包。归位错了，比如拿 uni-app 的说明去接原生工程，前置条件自然对不上。

▌ 第二层：接入边界与前置条件

　　全景对完号，第二层逐端读边界：每种接入方式放在哪、开工前必须满足什么条件。这一层最容易被跳过，也最容易出线上事故。建议把每个端的注意事项单独抄进评审清单，和代码仓库里的配置项一一对应，免得到时候文档归文档、配置归配置。

Web：内联代码贴在哪里

　　网站端直接复制统计代码中的内联片段，贴在页面模板里即可。边界是：所有要统计的页面都得加载这段脚本，单页应用还要确认路由切换时的浏览事件能被正确记录。

iOS：Keychain Sharing 为什么必须开

　　iOS 接入文档明确要求开启 Keychain Sharing，因为它关系到跨会话的标识一致性。不开的直接后果是：同一台设备每次重启应用都被当作新访客，UV 虚高，留存类判断全部失真。这一条不是可选项，是前置条件。

HarmonyOS：.har 包与网络权限

　　HarmonyOS 以原生 .har 包接入，权限清单里 INTERNET 与 GET_NETWORK_INFO 是必须项，GET_WIFI_INFO 为可选。少配一个必须项，表现就是装上之后数据静默为零，控制台不报错、日志里看不出来。

三端各有前置条件，iOS 与 HarmonyOS 的硬性要求是接入评审的必过项。

▌ 第三层：指标口径章节

　　前两层解决「怎么接」，第三层解决「数字怎么算」。指标口径单独成章，是验收报表数字时的共同标尺。

UV、PV、设备去重的官方词条

　　按指标词典的口径：UV 按 Cookie 去重，同一访客当天多次访问只记一次；PV 逐页累计，打开一个页面记一次；App 端按设备去重。跨端数字不能直接相加，因为去重基数根本不同；报表汇报时若需要总量，应注明是分端数字的合计，而不是一个去重后的整体访客数。

小程序端未定义指标不替补

　　小程序端部分指标在文档中尚未给出定义，这种情况下不要拿网站口径换算，也不要自行命名一个指标填进报表。口径留白比填错安全，等文档更新再补。

对应能力的档位边界

　　这份文档服务于的能力里，456数据用户行为分析以基础版为基础能力，专业版及企业版完整支持；做接入方案时顺手核对一下当前档位与目标能力是否匹配，避免接完才发现某层分析用不了。

App 与 H5 之间怎么打通

　　App 内嵌 H5 页面时，两端的标识默认是分开的，事件会裂成两路。文档给出的打通方式是在 H5 里调用 getUserCookie()，把 App 侧的标识带进来，两边才能算同一访客。这一步属于接入边界里容易漏掉的细节，评审时应单独列出来确认。

同一份文档，读法差两屏，覆盖的边界项差一整列。

▌ 把文档用成团队契约

　　读完三层，最后一步是把文档从「个人参考」变成「团队契约」，让它在评审和验收时真正起作用。契约立住了，后续每一次发版复核都会省掉大量争论。

接入评审时逐条对照

　　评审会上准备一份对照表：端支持、接入位置、前置条件、指标口径，逐条从文档原文里摘依据。有争议的句子直接引用文档原文，谁也不凭记忆发言，争论时间立刻变短。

最小验证动作

　　接完不要立刻铺全端，先做最小验证：自己访问一次，到实时访客里看到自己；自定义事件手动触发一次，确认请求发出。这两步过了，再接下一端。把文档当作唯一契约，接入这件事就从反复试错变成照单验收，后续版本升级也只要对照同一套清单复核，不必每次重新争论。

　　评审用的对照表可以落成下面这张文档审查清单：八项逐条核对，每项写清要核对什么、不核对的风险。SDK 的具体依赖版本号不在本文展开，可在对应端接入文档中核对。

　　这张表的输入是八项审查项，核对动作是步骤，失败分支是右列风险；输出是一份可签字的接入评审记录：八项全过才进入最小验证，任一项存疑就回到对应端接入文档补依据。

▌ 常见问题

SDK 文档只看安装步骤够不够？

　　不够。安装步骤只解决代码放哪里，前置条件与指标口径分别藏在各端注意事项和名词解释里。只看前两屏，iOS 的 Keychain Sharing 与 HarmonyOS 的权限清单这类坑，会留到上线后才暴露。

iOS 端为什么必须开 Keychain Sharing？

　　它关系到跨会话的标识一致性，不开会导致同一台设备被重复计作新访客。这一条写在 iOS 接入文档的前置条件里，接入评审时应作为必过项核对，而不是上线后再补开。

文档里没有的指标能自己定义吗？

　　不建议。小程序端部分指标尚未给出定义，这种情况下不要拿网站口径换算或自行命名。口径留白比填错更安全，等文档更新后再补，能避免报表数字长期误导团队。

▌ 参考资料

1. 微信小程序接入文档，说明小程序端的初始化方式与验证路径。
2. iOS 接入文档，列明 Keychain Sharing 等前置条件与集成步骤。
3. HarmonyOS 接入文档，说明原生 .har 包与网络权限要求。
4. 指标名词解释，给出 UV、PV 与设备去重的官方口径。