revenuecat-charts

访问 RevenueCat 图表

查询 RevenueCat 图表时，请遵循以下工作流：

1. 使用 get-chart-options-schema 查看图表可用的选项。
2. 使用 get-chart-data 和正确的选项获取图表数据。
3. 分析数据；涉及非简单运算时，请使用脚本。

通过 rc CLI（参见 revenuecat-cli 技能）：使用 rc charts list 列出图表，使用 rc charts options <chart> 查看架构，使用 rc charts show <chart> 获取数据。

通常，为避免占满上下文，请从已定义的时间范围和较大的时间粒度开始，然后逐步缩小范围。

1. 使用 get-chart-options-schema 查看图表选项

• 调用 get-chart-data 前，请将 get-chart-options-schema 视为每个图表的权威信息来源。它会返回图表支持的 resolutions、filters、segments 和 user_selectors。调用此工具时，始终使用 "realtime": true。后续调用 get-chart-data 时，必须使用此处原样返回的字符串 ID。
• filters 是之后可以在 get-chart-data 中添加限制条件的维度。
  • 每个筛选器都包含：
    • 一个之后可用作筛选器 name 的 id。
    • 一个用于说明如何选择有效值的 value_mode：
      • inline_enum 表示必须使用返回的某个 options 的 id。先使用匹配的列表工具（例如 list-products、list-offerings、list-apps 等）解析用户提供的名称。
      • inferred_standard 表示使用 value_source 中的标准代码，例如 ISO 国家代码。
      • dynamic 表示值来自观测到的项目数据，必须完全匹配。
  • 除非架构明确说明它们是有效值，否则不要传入显示名称、商店产品标识符、Bundle ID 或猜测的值。
• segments 是之后可以在 get-chart-data 中通过 segment 分组的维度。
  • 每个 segment 条目会直接提供要使用的维度 id。它不会列出 segment 值，因为图表会按该维度分组，并在输出中显示所有值。
  • 每个图表的筛选器和 segment 是分开的列表，因此不要假设可筛选的维度也可用于分组。例如，conversion_to_paying 可能支持将 product_id 和 offering_identifier 用作筛选器，但不支持用作 segment。
• user_selectors 是特定于图表的开关，用于更改图表返回的指标或时间窗口。每个选择器都以其 ID 为键，该 ID 需传入 get-chart-data 的 selectors JSON 对象中，通常还包含允许使用的选项 ID 和默认值。例如，revenue 图表可能使用 revenue_type（revenue、revenue_net_of_taxes、proceeds），而转化图表可能使用 conversion_timeframe，默认值为 7_days。呈现结果时，请说明非默认的选择器选项。
• resolutions 列出支持的时间粒度及其在 get-chart-data 中使用的字符串 ID。之后调用 get-chart-data 时，必须始终传入其中一个时间粒度 ID（例如，日对应的 "0" 或月对应的 "2"）。

2. 使用 get-chart-data 获取图表数据

选择日期和分辨率

• 以周、月或季度表述的相对日期范围（“过去 2 周”“上个月”）含义模糊。假设今天是 2026-07-31，星期五，“过去 2 周”可能指 7 月 18 日至 31 日（过去 14 天）、7 月 12 日至 25 日（最近两个完整周），也可能指 7 月 19 日至 31 日（上一个完整周加上当前周）。询问用户指的是哪种含义，并给出每种解释对应的具体日期。只有在日期已明确时，才跳过提问：例如，用户给出明确日期、以天为单位的范围、明确指明完整日历周期（“上一个日历月”），或此前已有澄清。
• 日期范围包含首尾日期（start_date 和 end_date 均包含在范围内）。“过去 N 天”是一个向后滚动的时间窗口：结束日期为今天，开始日期为今天之前 N-1 天。
• 每个周期都以其所属日历周期的第一天作为标签（周、月或季度的起始日），与 start_date 无关。周从项目配置的每周起始日开始（例如星期日或星期一），因此每个项目的周标签可能不同。从周期中途开始或结束的范围会返回不完整的时间桶，其标签与请求的日期不一致。对于向后滚动的时间窗口，优先使用日级分辨率；如果只需要总计，可搭配 aggregate，以确保数据准确覆盖所请求的日期。
• 呈现结果时，说明查询的开始和结束日期，绝不要使用首个或末个时间桶标签。例如，以周日为起始日，按周查询 7 月 18 日至 31 日会返回标签为 7 月 12 日、19 日和 26 日的时间桶——应写“7 月 18 日至 7 月 31 日”，而不是“7 月 12 日至 7 月 26 日”。

调用 get-chart-data

• 始终设置 "realtime": true，并指定开始日期、结束日期和分辨率 ID。
• 始终遵循此前获取的该图表 get-chart-options-schema 指南。
• 对于涉及多个项目的问题，每个项目调用一次 get-chart-data，并按每批约 10–20 个并行发起。批次过大可能触发 API 速率限制；检查每批调用是否受到速率限制，并仅重新发起受限的调用。不要退而求其次，逐个调用。
• 使用可用的 filters 限定输出。它是一个 JSON 编码的数组，格式为 {"name": "<filter id>", "values": ["<value id>", ...]}。
  • 同一项中的值按 OR 处理；不同项之间按 AND 处理。示例：美国或英国的 App Store 收入： "[{\"name\": \"store\", \"values\": [\"app_store\"]}, {\"name\": \"country\", \"values\": [\"US\", \"GB\"]}]"。
  • 每个筛选器名称最多使用一项：重复的名称会静默替换较早的项（不会与之合并）。筛选器值不得包含逗号。
• 使用可用的 selectors 配置图表。它是一个 JSON 编码的对象，将选择器 ID 映射到选项 ID，例如 "{\"revenue_type\": \"proceeds\"}"。省略的选择器将使用默认值；响应会在 user_selectors 中回显已应用的值。
• 使用 segment 按部分可分段维度 ID 对输出分组：
  • 请注意，分段会增加输出大小。可以使用更粗粒度的分辨率、更短的日期范围、limit_num_segments（保留按值排序的前 N 项，并将其余项合并到“其他”），或在只需要各分段总计时使用 aggregate，以缩小响应。
• 对于仅需摘要的问题（例如总额或平均值，如“Q1 总收入”），使用 aggregate。相比获取原始数据点后自行计算，应优先采用此方式。与 segment 结合时，它会返回精简的分段摘要（例如各国家/地区的平均值）。在输出中，values 将为空，summary 仅包含这些运算结果。
• 传入 currency，将输出转换为某种货币单位（参见响应中的 yaxis_currency）。

阅读 get-chart-data 输出

• measures 列出图表返回的指标（显示名称、单位、描述）。大多数图表会返回多个指标，例如 revenue 可能返回收入、交易次数和广告展示次数。
• values 是一个由数据点 {cohort, measure, value, incomplete} 组成的扁平数组；分段时还会包含 segment。cohort 是周期起始时间的 Unix 时间戳；measure 和 segment 是指向 measures 和 segments 数组的索引。第一个分段通常是 "is_total": true，切勿将其与其他分段相加。
• summary 按指标显示名称列出 total 和 average；分段时会按分段嵌套。
• incomplete: true 的数据点涵盖不完整周期：当前周期，以及 start_date 落在周期中途时的第一个周期（因为 expand_periods 默认为 false）。进行趋势或对比分析时请排除这些数据点，并在呈现结果时指出它们。时点图表（MRR、活跃用户、试用）会忽略 expand_periods：其值是周期边界时的快照，永远不会是不完整周期。
• annotations 列出用户在其仪表板上添加的带日期备注（例如发布、上线或实验）。解释数据变动时请查看这些备注。
• 无效的筛选条件、分段或选择器值会导致 400 parameter_error 错误，其消息会列出受支持的 ID。遇到此类错误时，请重新读取选项架构，而不是盲目重试。

3. 分析数据

• 分段响应包含 Total 分段；limit_num_segments 上限会将排名前 N 以外的分段合并到 Other 分段。请以 Total 为基准；不要自行汇总分段。
• 使用脚本（例如 jq 或简短的 Python 脚本）对图表输出进行复杂运算（增长率、分段占比、合并多次调用中的数字），不要直接推算。
• 最近一个周期可能会被标记为不完整。未说明这一点时，不要将它与完整周期进行比较。
• 推测指标变动原因之前，请先检查可用的用户备注。
• Cohort 图表衡量的是从首次出现起、在累积时间窗口内的数据；该窗口由选择器指定（转化图表使用 conversion_timeframe，实际 LTV 图表使用 customer_lifetime），每次调用只能使用一个窗口。呈现结果时请说明窗口，并在比较 Cohort 时保持窗口不变。

解读指标

订阅应用受四种力量驱动：

• 获客——有多少新客户来到应用
• 转化——这些客户中有多少转化为试用或付费方案
• 留存——这些客户会留存多久
• 重新激活——如何让老用户回归

应用收入的净变化取决于这几种力量的共同作用。提供建议时，务必使用基准数据，确保没有错误诊断问题。

一般准则：

• 在告知用户 RevenueCat 没有他们提到的指标数据源之前，先选择可能相关的图表，调用 get-chart-options-schema 获取选项，再调用 get-chart-data 并检查其 periods / measures——不熟悉的名称往往是图表中的某个周期或度量（仅凭 schema 无法列出这些内容）。get-benchmarks 中没有该指标，意味着没有同类产品的百分位区间，并不意味着无法计算该值。
• 检查后，如果工具中没有匹配项，或者不同解读会导致结果存在实质差异，请询问用户如何定义该指标。不要擅自编造定义。
• 面对复杂问题，要有选择地展开查询：先查看高层级图表，然后提出澄清问题（例如是哪款产品、哪个商店或哪个国家？），而不是拉取所有可能的细分数据。
• 使用数据工具时，日期范围包含起止日期（start_date 和 end_date 都包含在范围内）。当用户要求查看“过去 N 天”的数据时，请注意这一点（将今天作为结束日期，开始日期为今天往前推 (N-1) 天）。
• 在有帮助时，提供 RevenueCat 图表链接（参见下方的 Dashboard URL Format 部分）。提供包含筛选条件、细分项、日期范围等信息的具体链接。例如，如果用户询问过去 3 个月的净收入，请链接到设置为过去 3 个月自定义日期范围且 revenue_type 选择器设为 proceeds 的收入图表，而不是普通收入图表。
• 对于预测、预估或运行率，在拉取图表之前加载 revenuecat-forecasting 技能。

收入

• 用户未明确指定时，询问一般收入数据默认使用总收入（即包含税费和商店佣金的收入），并明确说明这一点。

获客

• 使用“新客户”图表了解应用带来了多少漏斗顶部用户。
• 按国家或 Apple Ads 维度细分新客户，有助于了解获客情况。
  • RevenueCat 的 Apple Ads 集成会设置归因维度信息，例如 campaign、ad group、keyword。
  • 开发者也可以使用保留的客户属性，在每位客户层级手动设置这些归因维度。
• 不要把明确归因筛选得出的零结果，当作更广泛渠道没有用户或活动的证据。例如，attribution_source = Organic 只表示明确标记为该值的用户；它不包括未标记用户，也不代表所有自然流量或非付费用户。
• 如果归因数据稀疏或缺失，请明确说明。使用“未归因”或“未明确标记”，不要假定这些用户来自某个特定渠道。

转化

转化的定义可能因应用使用的模型而异。应用可能先让用户开始试用，之后再转为订阅；也可能直接引导用户订阅。

• 使用“初始转化”图表，查看所选转化时间范围内开始订阅或试用的新客户占比。
• 使用“转化为付费”图表，查看所选转化时间范围内完成付款的新客户占比。
• “初始转化”（开始试用或订阅）和“转化为付费”（完成付款）衡量的是不同事件。切勿将其中一个用作另一个的替代指标，也不要将两者的数值进行比较。
• 随后，你可以查看“新试用”图表，进一步了解他们是否在使用免费试用。
• “试用转化率”图表有助于了解试用转化本身的表现。
• 筛选后的图表仍以所有新客户为分母。例如，按特定的 product_id 筛选“转化为付费”图表，得出的是所有新客户中转化为该产品的占比，而不是该产品自身的转化率。展示筛选结果时，请说明这一点。

留存

• “流失”图表会显示每个周期流失的活跃订阅者占比。由于它混合了不同周期的数据，因此可能难以解读或用作基准。
• 若要了解不同产品的长期留存情况，请查看“订阅留存”图表，或在“队列探索器”中使用 retained_subscriptions 指标，该指标会返回一段时间内仍处于活跃状态（即未过期）的订阅数量。
• 若要了解订阅在其生命周期的哪个阶段被取消（即关闭自动续订），请在“队列探索器”中使用 subscriptions_set_to_renew 指标。
• “订阅留存”图表会按周期报告每个队列的续订情况，包括数量和预先计算的比率（“Month N” / “Month N rate”列）。单个周期可回答“有多少比例续订过一次”之类的问题：首次续订所在周期与套餐时长相对应（月度套餐为第 1 个月，年度套餐为第 1 年）。按 product_duration 筛选，以便每次只查看一种套餐时长；按 subscription_type（new）筛选，以排除产品变更和重新订阅。对于队列尚未有完整机会达到的周期，报告会标记为未完成——不要将其视为零。

重新激活

• 了解重新激活的唯一可靠方式，是查看 MRR 变动图表和重新订阅 MRR 图表

调查指标变化

当需要解释指标变化时——收入下降、试用量减少、转化率飙升——请按以下顺序操作，然后再作答：

1. 量化变化。 获取图表数据，确认变化幅度和时间。
2. 检查配置。 方案、套餐、产品、付费墙和实验在指标中不可见，因此绝不能根据图表推断。如果答案中要提及其中任何一项，都必须在本次运行中查证。使用「可能」「值得确认」等措辞，或询问「要我检查吗？」都不能让猜测变得可接受。以下检查均为必做项，并非任选其一：
   • 使用 list-experiments，分别设置 status="stopped" 和 status="running"。如果某个实验在变化前后停止，请自行调用 get-experiment-results 查看哪个变体胜出——不要让用户去检查。
   • 使用 list-offerings，设置 limit: 100 且不传 expand（默认仅返回 20 项的页面通常不足以涵盖实际项目；绝不能根据不完整页面断定当前没有方案），然后对 is_current 对应的 id 调用 get-offering，并设置 expand: ["package.product"]——在 get-offering 中，值为 package 和 package.product，不带 list-offerings 使用的 items. 前缀。paywall_id: null 的方案没有 RevenueCat 付费墙——提供付费墙建议前，先加载 revenuecat-paywall-design。
   • 在称某个产品已下架、不可用或不再销售前，调用 get-product-store-state。用通俗语言报告商店状态，绝不要直接使用原始字段名。
   • 如果实验和方案无法解释变化，请调用 list-paywalls 检查付费墙变化。
3. 检查注释。 查看图表响应中的 annotations 字段。
4. 最后再提出假设。 将其表述为假设，而非已证实的结论。对配置未经核实的猜测，说明你漏掉了工具调用，绝不能把它当作首要结论。

不要跳过第 2 步。如果你准备写「已从方案中移除」或「已推出某项实验」，但本次运行中尚未调用 list-experiments 或 list-offerings，请停下来先调用相应工具。完成调用后，如果结果仍无法解释变化——例如时间范围早于当前配置，或期间没有任何变化——请明确说明，不要编造原因。「数据表明发生了 X，但根据现有配置无法确定原因」是有效的回答。日期范围较早可能导致无法得出结论，但绝不能成为跳过这些调用的理由。

人群与分母

比率仅描述其分母所代表的人群。在报告比率前，请先确认该人群就是问题所关注的人群。

• 当某个细分人群在分母中占主导时，汇总比率描述的是该细分人群，而不是整个应用。请针对问题关注的人群重新查询并添加筛选条件，优先报告该数值，同时列出汇总比率。
• 绝不要一边将分母称为膨胀或缺乏代表性，一边把比率作为证据。 请改用筛选条件重新查询，而不是附加保留意见。
• 请自行报告筛选后的数值，不要建议用户去查看筛选后的图表。

分析对比

• 比较同类数据。任何两个相互比较的数字都必须来自同一张图表和同一项指标，且转换时间窗口和群组定义相同。日期范围也应相同，除非是有意进行周期同比或环比。
• 如果对比的一方有某项指标，另一方没有，请先用相同的图表和设置查询缺失的一方，再进行比较。不要用其他图表中的数值代替。如果无法获取匹配的数值，请分别列出每个数字，并注明其图表和指标，不要声称存在差距或比例关系。
• 对于“{segment} 用户表现如何？”这类开放式问题，不要只看细分群组指标。请提取用户要求的细分群组数据，以及关键转化或收入质量指标的整体／未筛选基线，然后根据该基线评估表现。若不与基线比较，不要将某个细分群组评为“健康”“表现不佳”等。
• 不要将经过筛选的新客群组的收入或转化，与所有群组及续订的应用总收入进行比较。如果无法获取匹配的基线，请说明这一点，并避免作出表现方向的判断。
• 如果用户不理解为什么两项指标出现分歧，请先说明每项指标分别统计什么，再解释差距。只有当一项指标是另一项指标的子集时，两项指标才会同步变化。

错误示例 — 将不同图表的数据合并到同一列标题下：

国家	转化为付费用户（14 天）
US	26.3%（这是初始转化率）
PL	2.1%（这是转化为付费用户的转化率）

正确示例 — 每项指标单独一列，每列中的所有数值均来自同一张图表、同一项指标和相同设置：

国家	初始转化率（14 天）	转化为付费用户的转化率（14 天）
US	26.3%	9.6%
PL	4.3%	2.1%

图表仪表盘链接

生成 RevenueCat 仪表盘图表的可分享链接。

构建链接

图表链接必须遵循特定的仪表盘 URL 格式，并且必须根据已验证的、先前成功的 get-chart-data 调用构建。

0. 如果此前没有针对该图表成功调用 get-chart-data，请先按照上方的 RevenueCat 图表查询工作流操作。
1. 构建链接，以以下基本路径开头： https://app.revenuecat.com/projects/{project_id}/charts/{chart_name}。
2. 添加包含日期范围的 range 参数。此参数为必填项。
3. 添加包含分辨率的 resolution 参数。不要依赖默认值。
4. 通过 filter 参数添加筛选条件。
5. 如果按细分群组筛选，则添加 segment 参数。
6. 根据需要添加图表专用选择器。
7. 对所有值进行 URL 编码（空格 → +，冒号 → %3A 等）。

仪表盘 URL 格式

重要：必须使用以下确切结构：

https://app.revenuecat.com/projects/{project_id}/charts/{chart_name}?range={range_value}

• {project_id} — 短十六进制 ID（例如 56965ae1），而非完整的 proj56965ae1
• {chart_name} — 与 get-chart-data 调用中使用的图表名称相同（revenue、churn、mrr、conversion_to_paying 等）
• 项目 ID 应放在路径中，而不是查询参数中

正确示例：

https://app.revenuecat.com/projects/56965ae1/charts/revenue?range=Custom%3A2025-11-16%3A2026-02-13

错误 — 请勿使用：

https://app.revenuecat.com/charts/revenue?project=proj56965ae1&chart_start=...&chart_end=...

查询参数

range 参数 — 必填

range 参数用于控制日期范围。格式：{preset}:{start_date}:{end_date}，其中 start_date 和 end_date 使用 YYYY-MM-DD 格式。将 Custom 用作预设值。

始终使用此格式——不要使用 start_date、end_date、chart_start 或 chart_end 参数。注意：各部分之间的 : 必须进行 URL 编码，写作 %3A。

示例：range=Custom%3A2025-01-01%3A2025-12-31

resolution 参数

值	含义
0	按日粒度
1	按周粒度
2	按月粒度
3	按季度粒度
4	按年粒度

segment 参数

用于细分数据的维度。使用你在 get-chart-data 请求中使用的确切维度 ID。

• country — 按国家/地区
• store — 按应用商店（App Store、Play Store 等）
• product_id — 按产品标识符
• platform — 按平台（iOS、Android 等）
• offering_identifier — 按套餐

不同图表支持的细分维度各不相同 — 只能关联你在该图表的 get-chart-data 调用中成功使用过的细分维度。

filter 参数

筛选条件以独立的查询 filter 参数传递，内容为 {dimension}%3A%3D%3A{value}。使用你在 get-chart-data 请求中使用的维度名称。

维度	示例
country	filter=country%3A%3D%3AUS
store	filter=store%3A%3D%3Aapp_store
product_id	filter=product_id%3A%3D%3Aprodbb68905d98
platform	filter=platform%3A%3D%3AiOS

要使用多个筛选条件，无论它们属于同一维度还是多个维度，都需要包含多个 filter 查询参数。为同一维度传递多个筛选条件会执行 OR 操作；为不同维度传递筛选条件会执行 AND 操作。

特定图表的选择器

选择器以独立的查询参数传递，名称和值与 get-chart-data 的 selectors 参数中使用的相同。参考示例（以 get-chart-data 为准）：

• revenue_type（收入图表）— revenue、revenue_net_of_taxes 或 proceeds
• conversion_timeframe（转化图表）— 0_days、3_days、7_days、14_days、30_days 或 unbounded
• customer_lifetime（实际 LTV 图表）— 7_days、14_days、30_days、3_months 至 24_months，或 unbounded

API 参数与仪表板参数的映射

将 API 参数转换为仪表板 URL 时：

API 参数	仪表板参数
start_date + end_date	range=Custom%3A{start}%3A{end}（使用 Custom 预设）
segment	segment
filters（JSON 数组）	独立的 filter 查询参数
selectors（JSON 对象）	独立的查询参数

示例：构建链接

用户需求：“过去 90 天按国家/地区细分，并筛选美国和德国的收入图表”

计算日期：如果今天是 2026-02-13，那么 90 天前是 2025-11-16。

https://app.revenuecat.com/projects/56965ae1/charts/revenue?range=Custom%3A2025-11-16%3A2026-02-13&segment=country&filter=country%3A%3D%3AUS&filter=country%3A%3D%3ADE

用户需求：“从 2025 年 8 月至今的流失率图表”

https://app.revenuecat.com/projects/56965ae1/charts/churn?range=Custom%3A2025-08-01%3A2026-02-13

获取项目 ID

可以通过 list-projects 工具查找项目 ID，该工具会列出所有项目及其 ID。

• 工具返回的 ID 以 proj 开头，例如 proj56965ae1
• 对于仪表板 URL，请去掉 proj 前缀 — 在路径中只使用 56965ae1