×
01
创建项目
登录后进入「我的项目」，点击右上角＋ 新建项目 。选择项目类型（网页 / H5 或微信小程序），填写项目名称，网页类型需填站点域名、小程序类型需填 AppID，行业为必选。创建成功后会自动进入项目看板。
一个账号可创建多个项目，数据互相隔离；每个项目对应一套独立的 app_id 与接入代码。
02
接入 SDK
创建项目后进入「项目设置 → SDK 接入」，复制接入代码放到你的页面或小程序里即可开始采集。网页在 <head> 引入脚本并初始化；小程序把 iris-sdk-wx.js 放入项目并引入。
接入代码里替换了你的 app_id 与采集端点，直接粘贴使用。详细见「02 SDK 接入」章节。
接入后无需重启服务，刷新页面即开始上报；数据通常在 1 分钟内进入看板。Web / H5 若暂未看到数据，可在“项目设置 → SDK 接入”生成调试代码排查。
03
查看数据
接入后回到项目看板，默认展示最近 7 天数据。顶部可切换 7 / 14 / 30 天 ，或点项目设置上方自定义日期。概览页汇总 PV / UV / 新访客 / 平均停留 / 跳出率，下方有访问趋势与热门页面。
看板共 12 个分析页：概览 / 趋势 / 事件 / 页面 / 来源 / 用户 / 留存 / 漏斗 / 分群 / 路径 / 热力 / 回放 ，逐个点击了解每个页面的用法（见「03 分析看板」）。
04
Web / H5 接入
在页面 <head> 中引入 SDK 脚本并初始化。接入代码以项目设置为准，核心如下：
<script src="/sdk/iris-sdk.js"></script>
<script>
iris('init', 'app_xxxxxxxx', {
endpoint: 'https://iris.teown.com/api/collect'
});
// 上报自定义事件（第三参 label/desc 可选，自动进事件字典）
iris('track', 'signup', { plan: 'pro' }, { label: '注册', desc: '用户完成账号注册' });
</script>接入后自动采集 PV / 点击 / 页面离开 / 心跳停留 （见「自动采集」），无需额外代码。
需要验证接入时，可临时在初始化参数中加入 debug: true ，或在“项目设置 → SDK 接入”开启“在示例代码中开启调试”后重新复制代码。调试日志只显示在待验证页面的浏览器 Console，不会上传到 Iris，也不会改变实际上报数据。
调试默认关闭。确认事件名、脱敏属性预览和 HTTP 状态正常后，请移除 debug: true ；Beacon 的 accepted 只表示浏览器已接收发送任务，不代表事件已经入库。
05
小程序接入
下载 iris-sdk-wx.js 放入小程序 utils/ 目录，在 app.js 顶部引入并初始化：
const iris = require('./utils/iris-sdk-wx.js');
iris.init({ app_id: 'app_xxxxxxxx',
endpoint: 'https://iris.teown.com/api/collect' });
// 上报自定义事件
iris.track('signup', { plan: 'pro' },
{ label: '注册', desc: '用户完成账号注册' });需在微信公众平台「开发 → 开发管理 → 服务器域名」中配置 request 合法域名 为采集端点域名。
06
上报事件 track
用 track 上报任意业务事件。第一个参数是事件名（字母数字下划线），第二个是事件属性对象，第三个可选：友好名称与描述。事件属性支持字符串 / 数字 / 布尔。
// Web
iris('track', 'purchase', { product: 'p001', price: 199, vip: true });
// 小程序
iris.track('purchase', { product: 'p001', price: 199, vip: true });事件名建议统一命名规范（如 action_object ），事件页会按名称聚合展示 PV / UV，并支持搜索过滤。
新建项目后可在「项目设置 → SDK 接入」重新打开接入引导，直接复制注册、表单、支付、分享等常用事件模板。模板仅供示例，请按业务替换属性值。
07
自动采集
SDK 接入后自动采集 4 类系统事件，无需手动上报：
事件 含义
$pageview 页面浏览（PV），带 URL 与来源 $click 点击（文档坐标，用于热力） $pageleave 离开页面，带停留时长 $heartbeat 前台心跳，用于停留时长统计
这些事件在事件页归入「自动采集事件」，参与趋势 / 页面 / 热力等分析。
08
事件属性
事件属性用于记录事件的业务信息，如商品、价格、渠道。在事件页点击某个事件行，可查看该事件所有属性的取值分布（Top 10）。
iris('track', 'view_item', {
sku_id: '8842',
category: '跑鞋',
price: 599,
in_stock: true
});属性名建议统一规范，值支持字符串 / 数字 / 布尔；单条事件属性最多 20 个键。Owner / Admin 可在「事件 → 管理事件」为属性补充中文名、类型、是否必填与说明；字典只保存定义，不保存属性值。
09
用户标识 identify
默认每个浏览器 / 设备生成独立访客标识（distinct_id）。登录后可用 identify 把匿名访客绑定到业务账号，注册前后的漏斗行为会归并到同一用户。
// Web
iris('identify', 'user_10086');
// 退出登录时重置为新的匿名访客
iris('reset');
// 小程序
iris.identify('user_10086');
iris.reset();identify 会自动建立匿名 ID 到账号 ID 的项目级映射；重复调用相同 ID 不会重复绑定。退出账号必须调用 reset，避免同一设备上的下一个账号继承前一个身份。当前身份归并用于漏斗分析；其他指标仍按原始 distinct_id 口径统计。
10
事件名称与描述
埋点时可在 track 第三参传入友好名称与描述（均可选）。上报后系统自动填充「事件字典」，事件页 / 漏斗 / 路径 / 分群里都显示友好名称；管理员手动在事件字典配置的名称优先于 SDK 上报。
iris('track', 'click_banner',
{ position: 'home_top' },
{ label: '点击横幅', desc: '首页顶部横幅点击' });不带第三参不影响上报；若不想在代码里维护名称，也可由管理员在「事件字典」中统一配置。
11
服务端事件接入
订单、支付、注册等必须由后端确认的事件，应从「项目设置 → 服务端接入」上报。Owner / Admin 可以创建和吊销项目级 Ingest Key；Member 可查看说明与示例；Viewer 不显示该入口。
新 Key 只显示一次 。请立即保存到服务器密钥管理系统，并通过环境变量 IRIS_EVENT_KEY 注入；不要写进源码、前端代码、聊天或日志。页面示例始终读取环境变量，不会嵌入真实 Key。
export IRIS_EVENT_KEY='从密钥管理系统读取'
export IRIS_ENDPOINT='https://iris.teown.com/api/server/collect'
# 仓库中的完整可运行示例
bash examples/server-ingest/curl.sh
php examples/server-ingest/php.php
node examples/server-ingest/node.mjs
python3 examples/server-ingest/python.py每个事件都要提供稳定且唯一的 event_id 。网络失败、429 或 5xx 最多重试 3 次，并在重试中复用原 event_id；400 / 401 / 403 等错误应先修正请求或 Key，不要盲目重试。
HTTP 202 仅表示请求已校验并进入异步队列，通常 1 分钟内可在事件和回放中查询。事件名为 1～50 位字母、数字或下划线且以字母开头，禁止使用 $ 开头的系统事件名。
不要上传密码、访问令牌、银行卡、邮箱、手机号或可直接识别个人身份的数据。Key 泄露或服务下线时立即吊销；吊销不可恢复，使用该 Key 的服务会立即停止上报。
12
概览
项目核心指标一屏概览：PV 浏览量 / UV 访客数 / 新访客 / 平均停留 / 跳出率 五个指标卡 + 访问趋势折线 + 热门页面 Top 10。适合每日巡检业务大盘。
点指标名旁的 i 可查看即时口径说明：PV 是页面浏览次数；UV 为窗口内近似去重访客；新访客为窗口内首次出现访客；跳出率为仅一次页面浏览的会话占比。
13
趋势
访问量随时间变化：每日 PV / UV 折线。7 天范围内可切换按小时 粒度，观察日内流量波峰；14 / 30 天为按天粒度。
14
事件
全部事件按「自定义 / 自动采集」分组，展示每个事件的 PV / UV。顶部搜索框可按事件名即时过滤。点击事件行查看该事件的趋势折线 与属性分布 （点属性键看取值 Top 10）。管理员可见「管理事件」按钮维护事件字典。
看板顶部的用户范围 可切换“全部用户”或已保存分群；事件列表、趋势、属性和归因会使用同一成员范围。
日期右侧的全部来源 可筛选某个渠道。事件详情默认按渠道展示触发次数、去重用户与次数占比；也可切换入口页或上一页。其余渠道合并 Top 50 之外的已知来源，未归因单独展示，二者不是一回事。
15
页面
热门页面 Top 50，含 PV / UV / 平均停留。搜索框支持按 URL 关键词搜索全量页面。同一页展示来源 / 渠道分布，供交叉参考。可用顶部用户范围 只查看某个已保存分群访问过的页面。
16
来源
流量来源 / 渠道构成（环形图 + 明细）。渠道识别优先级：utm_source → utm_medium → referrer 域名 → 直接访问 。投放链接建议带标准 UTM 参数（如 ?utm_source=wechat ）以便区分各渠道进人。顶部用户范围 可比较特定分群来自哪些渠道。
按来源查看所有分析： 点击日期旁的“全部来源”，搜索并单选渠道，点击“应用来源”。取消或 Esc 不生效；切换模块、日期或分群会保留来源，切换项目则重置。某天没有该来源的数据时保留筛选、显示空结果，不会自动改成全部来源。
来源筛选按同一项目、同一会话最早可用的页面入口判断，可关联日期之前或跨月的入口；优先读取入口的 utm_source，其次 utm_medium，再取外部引荐域名。可靠的网页入口没有渠道和 referrer 才记为直接访问；缺少入口、内部引荐或无效来源不能猜成直接访问。有明确 UTM 的事件可单独兜底，其余记为未归因 。
筛选只包含匹配来源的事件，不会把同一用户从其他来源产生的行为全部带入。wechat 与 wechat_share、大小写不同的来源保持原值，不自动合并。来源和用户范围是两个条件：前者选渠道，后者选已保存分群；分群定义与成员规则不因来源选择而改变。独立实时大屏与采集状态仍显示项目整体数据。
17
用户
「用户」分为趋势、地域和设备三个视图。趋势展示每日 UV（去重访客）与新访客 （窗口期内首次出现的用户），以及总访客和新访客占比，用于观察新老客结构与拉新效果。
地域视图根据访问时的 IP 离线近似解析国家 / 地区、省份和城市；设备视图根据 User-Agent 解析设备类型、操作系统和浏览器。两者都展示 PV、UV、UV 占比、已识别数、未知数和识别率，并支持随当前日期范围查询和 CSV / PPT 导出。地域和设备视图还可用顶部用户范围 查看已保存分群的人群构成；用户趋势暂不支持该筛选，因此不会显示无效入口。
口径与误差： IP 定位不代表常住地，也不提供街道或经纬度。同一访客在不同地域或设备访问时，会在各分类中分别计入，因此明细 UV 相加可能大于总访客。旧数据、内网 IP、无法定位的 IP 或无法识别的客户端会归入“未知”，不会阻断原始事件采集。
18
留存
留存矩阵：队列 = 首次访问日的新增用户，Dn = n 天后仍活跃（当日有任意事件）的用户比例。横滑查看完整 D0~Dn 列。判断产品粘性：D1 高代表首访体验好，D7 高代表长期价值。
选择来源后，按用户在本项目首次页面访问的来源 筛选新增队列；后续回访不限制来源。已有用户换渠道进入不会因此变成新用户。
19
漏斗
定义有序事件步骤 （2~8 步，每步选事件 + 可选 URL 条件 + 转化窗口），分析每一步的完成人数与转化率，定位流失环节。适合转化路径分析（如 首页 → 详情 → 加入购物车 → 支付）。顶部用户范围 可将漏斗限定为某个已保存分群。
选择来源后，只限定漏斗第一步的来源 ；后续步骤仍按原有顺序和转化窗口计算，允许跨会话、跨来源完成。筛选不会修改已保存的漏斗模型。
20
分群
用纳入条件 与排除条件 圈定目标用户。纳入条件可选择“全部满足”或“任一满足”，每条规则都能设置事件和最少发生次数；命中任一排除条件的用户不会入群。
事件下方可继续添加属性条件 ：文本支持等于 / 不等于，数字支持等于 / 大于 / 小于，布尔支持是 / 否；同一条事件规则内的属性条件需同时满足，最多添加 2 个。属性必须先由 Owner/Admin 在事件字典中登记明确类型。
分群成员按当前分析结束日期向前计算 7 / 30 / 90 / 180 天。详情页提供成员数、成员占比、近期活跃、行为趋势、常用事件、常访问页面及分群留存，适合识别待转化、高活跃或流失风险人群。
保存后可在事件、页面、来源、用户地域与设备、漏斗页面顶部的用户范围 中复用。筛选提示会显示成员人数和精确计算日期；切换分析结束日期时，成员会按新结束日期重新计算。
21
路径
选一个起点事件，展示用户后续依次发生的节点分布（页面按 URL 路径、事件按名称），3 / 5 / 8 步深度。看清用户进入产品后的真实行为流向。
22
热力
页面点击热力图：选择有点击数据的页面，查看点击坐标密度分布（红色越深点击越集中）。用于优化页面布局与按钮位置。数据来自自动采集的 $click 。
23
回放
在「用户分析 → 访客列表」或「回放」选择访客，查看顶部所选日期范围内的事件时间轴。列表支持用户标识搜索、分页、复制标识和直接查看回放；返回列表保留搜索与页码。也可展开「已知标识？直接查询」手动输入 distinct_id。
用户标识由接入应用采集，不一定对应 Iris 注册账号。列表按最后活跃时间排序，使用全部访客口径，不应用分群筛选；日期选择与自定义起止日期保持有效。列表导出为当前页访客，回放详情导出为当前会话筛选下的事件。
回放支持会话筛选、上一步、下一步与播放。事件有中文名时优先展示中文名并保留原代码；这是行为时间轴，不是录屏。每次最多返回 200 条事件，可缩小日期范围查看。
24
实时大屏
投屏模式：今日 PV / UV / 事件数 / 在线用户 + 实时事件流滚动。活动期间投屏盯数据，观察实时涌入。页面在后台时自动暂停轮询以省资源。
25
基本信息
项目名称 / 所属行业 / LOGO / 描述。LOGO 用于看板与报告封面展示；行业会带入报告 AI 洞察，建议准确选择。
26
SDK 接入代码
项目的接入代码中心：Web / 小程序切换，复制即用。代码中已包含你的 app_id 与采集端点，粘贴到页面 / 小程序即可。改项目后这里同步最新接入代码。
Web / H5 接入可开启“在示例代码中开启调试”。开启后，上方示例会加入 debug: true ；需要重新复制并部署，系统不会远程修改你已经接入的网站。切换项目后会恢复为普通代码，小程序示例暂不提供此开关。
部署调试代码后，在待验证页面的浏览器开发者工具 Console 查看 [Iris debug] 日志，包括初始化、事件入队、发送、HTTP 成功、重试、最终失败与 Beacon 交接。属性预览会遮蔽密码、Token、邮箱、手机号和银行卡等敏感字段，调试日志不会上传到 Iris。
调试默认关闭，且不会改变上报内容。HTTP success 表示采集接口已接受请求；Beacon accepted 只表示浏览器已接收发送任务，不代表事件已经入库。最终是否进入分析数据，请结合事件页或概览的数据健康提示确认。验证完成后请关闭开关并重新复制普通代码。
27
成员管理
项目成员角色：owner （全部权限）/ admin （可管理成员与项目）/ member （可创建漏斗·分群等分析配置）/ viewer （仅查看）。
按邮箱邀请 ：搜索已注册用户邮箱添加（对方须已有账号），可移除成员、调整角色。
邀请链接 ：owner / admin 生成带角色权限的链接发给任何人——对方打开后登录或注册新账号，项目自动出现在其列表并按预设角色加入。链接可选单次 / 可复用 与有效天数 ，可复制、撤销；撤销后新用户无法通过该链接加入，已加入成员不受影响。
28
危险区
删除项目：删除后该项目 SDK 上报立即失效，数据不再采集且不可恢复。仅 owner 可见。删除前请确认已迁移 / 备份所需数据。
29
事件字典
在事件页点「管理事件」进入事件字典，为事件配置友好名称 与业务描述 ，事件页 / 漏斗 / 路径 / 分群下拉都会显示友好名称（原始事件名保留在括号内）。
名称与描述都留空即清除该事件配置；事件匹配仍按原始事件名，改名称不影响已采集数据。SDK 埋点时传入的 label / desc 会自动填充到这里（管理员手动配置优先）。
30
公告通知
平台运营会通过公告 推送产品更新与重要通知，采用站内信 + 邮件 双通道同步送达：登录后点顶部铃铛图标 进入公告列表查看站内信，同时绑定邮箱也会收到对应的公告邮件。
公告列表中未读 的公告带红点标记，点击展开正文即自动标记为已读，铃铛上的未读数字会随之减少；已读公告保留在列表里可随时回看。
公告由平台管理员（root）在「系统管理 → 公告管理」中统一发送，可选择发送给所有用户或指定邮箱；个人用户无法自行关闭，如不想再收到邮件可联系管理员反馈。
31
导出报告
报告沿用当前来源，并在数据范围说明中注明。CSV 同时包含项目、日期、来源和用户分群；选择分群时暂不支持整份 PPT，会明确禁用入口。筛选查询失败时不导出全量数据替代；单一来源报告不会把筛选导致的 100% 占比解释成渠道过度集中。
在看板工具栏点「导出报告」，选择日期范围、报告语言和主题，即可生成一份可直接用于汇报的 PPT。报告语言支持中文与 English，默认中文；语言选择会同时应用于 AI 洞察、系统文案、表头和文件名。报告固定包含经营摘要、AI 执行摘要 、AI 优化建议 和数据范围说明；流量、行为、转化、画像等业务页按可用数据追加，正常报告不少于 9 页。
AI 摘要与建议均为独立页面，建议逐项显示数据证据、优先级与下一步动作。AI 服务暂不可用时会明确标注「规则生成建议」，并基于跳出率、停留、渠道集中度、留存和漏斗规则生成内容。
导出前可选择报告语言与主题。语言支持中文和 English，默认中文；英文版会同步使用英文生成 AI 执行摘要、优化建议、各页标题和说明。默认主题「瞳见玫瑰」使用 Iris 洋红与石墨灰；另有深海航标、松风叙事、琥珀经纬、紫雾远见、夜航鎏金和月光石。主题仅改变 PPT 视觉，不改变统计口径或 AI 结论。
导出报告当前不消耗次数，所有用户均可使用。
为防止脚本批量导出，点「生成报告」前需完成一次人机验证 （阿里云无痕验证，风控判定有风险时自动升级滑块），通过后即开始生成。
两次导出之间需间隔 60 秒 （平台后台可调），防止频繁生成占用资源。
导出前的人机验证跟随平台全局风控开关；如遇验证码组件异常，可刷新重试或点「联系我们」反馈。
32
MCP 接入与权限
历史分析工具支持可选 source_filter={"kind":"channel","value":"zhihu"}，不传表示全部来源；get_source_options 可按日期搜索、分页列出来源。直接访问用 {"kind":"direct"}，未归因用 {"kind":"unattributed"}。漏斗限定首步来源，留存限定首次访问来源；访客引用保留来源供回放沿用。筛选不扩大任何项目权限，也不改变分群定义。旧版 npm 客户端需等待包含这些参数的新版发布，远程 MCP 则随服务端更新。
Iris 支持通过 MCP 把项目的聚合分析数据 带进 Codex、Claude 等 AI 客户端。可读取页面、事件、归因、留存、路径、热力、实时与分群；不会返回邮箱、IP、手机号、原始用户标识、项目 Secret 或完整 Token。
推荐使用浏览器授权： 把远程 MCP 地址设为 https://iris.teown.com/mcp。客户端会打开 Iris 登录与授权页，无需复制 Token；首次只申请读取权限，需要维护项目配置或导出时再增量授权。
{
"mcpServers": {
"iris": { "url": "https://iris.teown.com/mcp" }
}
}需要从连接、权限到自动埋点和漏斗配置完整走一遍，可阅读MCP 数据分析实战指南 ，或直接观看45 秒开源 Skill 真实演示 。
OAuth 能力范围与项目角色会同时生效：Viewer 与 Member 只读；Owner / Admin 获得 workspace:write 后，AI 才能维护项目、漏斗、分群、事件字典和邀请记录。报告导出另需 report:export；脱敏事件明细导出另需 Owner / Admin 与 analytics:raw-export。所有权限均在每次调用时重新校验。
导出通过后台任务生成。AI 发起后应轮询任务状态，完成后获得一个 24 小时有效的下载链接；原始明细会去除完整 URL 参数、IP、完整 UA 和敏感属性。删除、撤销、密钥、支付和平台管理操作不向公开 OAuth MCP 提供。
兼容旧客户端： 也可以在「我的项目 → 账户设置 → MCP 访问」创建个人 Token，再使用 npm stdio 连接器。Token 仅展示一次，请立即复制并保存在客户端环境变量中。
{
"mcpServers": {
"iris": {
"command": "npx",
"args": ["-y", "@teown/iris-mcp"],
"env": { "IRIS_MCP_TOKEN": "sk-mcp-…" }
}
}
}写入与导出操作会修改真实配置或消耗资源。每次预期的新操作都要使用新的 UUID request_id；仅在重试同一次操作时复用原 UUID。删除项目、成员、事件、漏斗或任何凭据必须在网页端由人工完成。
33
微信登录与账户资料
在登录页先勾选用户协议与隐私政策，再点「微信扫码登录」。使用微信扫描二维码；已关注「缔昂」公众号的用户扫码确认即可继续，未关注用户关注后也会自动完成确认。
微信已绑定 Iris 账号时会直接登录并进入项目列表。首次使用微信且尚未绑定账号时，可选择「注册新账号」，或选择「绑定现有账号」并用邮箱、密码完成身份确认。进入邮箱登录页后，微信按钮显示「已绑定（可解绑）」；若所登录账号已经绑定其他微信，系统会要求另选账号登录，不会覆盖原绑定。
注册页也提供「绑定微信（可选）」按钮。可以先扫码再注册，按钮会切换为「已绑定（可解绑）」；不绑定微信也能正常完成邮箱注册，微信绑定不是必填项。
登录后点击页面右上角头像进入「我与账户」。个人资料可更换头像和昵称：头像需先完成 1:1 裁切，再保存最终预览；注册邮箱仅展示。手机号为必填资料，可随时修改，不发送短信验证码。
在「登录与安全」中可以修改密码、绑定或解绑微信。已绑定时按钮显示「已绑定（可解绑）」；解绑必须输入当前密码，解绑后邮箱密码登录不受影响。一个 Iris 账号只能绑定一个微信，同一微信也不能覆盖绑定到其他 Iris 账号。
修改密码后其他设备上的旧登录态会失效。解绑微信与注销账号都需要当前密码再次确认；注销前还必须先转移或删除自己拥有的项目。解绑、注销与删除操作不提供给 MCP。
