revenuecat-audiences

受众筛选器和仪表板链接

使用受众筛选用户的客户，并分享指向该客户群的仪表板链接。筛选条件用于选择细分群体；preview-audience 上的 sort_by / sort_direction 用于排列返回的样本。

受众没有专门的 CLI 命令。不要告诉用户 RevenueCat 无法筛选或细分客户。

识别、筛选或排名客户

受众可按以下字段筛选，包括：

• 产品和期限 — latestProduct、allPurchasedProductIds、latestPurchasedOffering、权益、优惠
• 支出和续订 — totalSpent（可用于筛选，也可用作 sort_by: total_spent）、totalRenewals（仅用于筛选；不支持按续订次数排序）
• 订阅状态 — status、试用、自动续订意向、所有权
• 商店、平台和国家/地区 — platform、latestStore、country、storefront
• 日期 — 首次出现、购买、续订、到期、试用、取消
• 归因和实验 — 媒体来源、广告系列、广告组、关键词、价格实验
• 身份和自定义属性 — App 用户 ID、电子邮件、区域设置、customAttribute:{key}

将问题对应到这些字段，设置筛选条件，然后查看样本。

1. 对于问题涉及的任何标记为项目专属的字段，使用 get-audience-filter-options 获取项目专属值（project_id、fields）。
2. 使用 project_id 和符合筛选规则格式的 body.rules 调用 preview-audience（对于 list-audiences 返回的已保存受众，则传入 body.audience_uuid）。此操作为只读，不会保存任何内容。不要仅为查看细分群体而调用 create-audience。
3. 若要排名或指出最高/最低项，请将 sort_by（status、latest_auto_renew_intent、first_seen_at、last_seen_at、total_spent）和 sort_direction（默认为 asc，也可以是 desc）作为顶层参数传入，而不要放在 body 中。使用 sort_by: total_spent 和 sort_direction: desc 会让支出最高的客户排在前面，因此第一行 customer_sample 就是支出最高的客户。样本数量有上限（通常为 50）：其中是匹配项中排名最高或最低的客户，并非全部客户。
4. 对于“有多少”这类问题，应根据 stats（currency 中的 total_customers、active_subscriptions、active_trials、total_revenue）作答，切勿使用样本数量。当 stats.is_approximate 为 true 时，应将客户数和收入表述为约数（例如“约 6,400 位客户”）。
5. 仅根据 customer_sample 返回的字段（app_user_id、email、status、total_spent、latest_product_name、首次/最后出现时间）指出客户。若未设置 sort_by，样本顺序不代表排名：应说明这是匹配项的样本，而非排名结果。
6. totalRenewals 仅用于筛选，不是 sort_by 的有效值，也不是样本列。使用较高的阈值进行筛选并报告匹配结果；不要编造续订次数，也不要声称存在唯一的最高值。
7. 分享仪表板链接。preview-audience 返回的 body.rules 结果中包含一行以“Dashboard URL for this result”开头的内容；请链接到该行中的确切 URL。只有当工具结果未提供 URL 时，才自行构建链接（构建链接）。

构造链接

仅在没有工具结果提供“Dashboard URL for this result”这一行时使用此方法。有两种形式：用于临时探索的筛选后 all-customers 链接，以及 create-audience 之后的已保存受众链接。

1. 从 list-projects 获取项目 ID。对于仪表板 URL，去掉 proj 前缀。
2. 从字段表中选择字段和运算符。不要自行编造字段或运算符名称。
3. 对于特定项目的字段，先使用 get-audience-filter-options 获取有效值。
4. 组装规则 JSON：每个 OR 分支一个组，组内的条件用于 AND，值按值格式编码。
5. 使用简短脚本序列化并对规则进行 URL 编码（见编码规则）——不要手动编码。
6. 将其作为 filters 查询参数附加到 https://app.revenuecat.com/projects/{project_id}/customer-lists/all-customers。

URL 格式

https://app.revenuecat.com/projects/{project_id}/customer-lists/all-customers?filters={encoded_rule}

• {project_id} — 从 list-projects 获取的短十六进制 ID，去掉 proj 前缀。
• 筛选条件仅适用于 all-customers 列表。未筛选的 Audiences 首页为 /projects/{project_id}/customer-lists。

链接到已保存的受众

create-audience 和 get-audience 的结果包含一行“Dashboard URL for this result”；请链接到该确切 URL。如果你只有 list-audiences 的输出，请使用 customer_list_id 进行链接，该字段与 id 一同返回：

https://app.revenuecat.com/projects/{project_id}/customer-lists/{customer_list_id}

受众的 id（aud…）和 customer_list_id（list…）是不同的标识符。 仪表板路由只会解析 customer_list_id；在该位置使用 aud… ID 会显示 “Audience not found”。

正确：

https://app.revenuecat.com/projects/56965ae1/customer-lists/list7c1f0a2b93

错误（使用受众的 id 而不是 customer_list_id）：

https://app.revenuecat.com/projects/56965ae1/customer-lists/audf0269cdf3df84dd2

不要在已保存的受众链接中添加 filters 参数——受众本身已包含规则。如果响应中没有 customer_list_id，请链接到 /customer-lists 并写明受众名称，不要猜测 ID。

提议保存筛选视图

筛选后的 all-customers 链接是临时的——它不会保存任何内容。分享此类链接时，用一句简短的话说明这一点，并提议保存：“此视图尚未保存——要我将其保存为受众，方便你以后查找吗？”

每次对话只提议一次。如果对方接受，请使用你为链接构建的相同规则调用 create-audience，然后链接到该受众。如果链接已经指向已保存的受众，则不要提议保存。

筛选规则

filters 的值是经过 URL 编码的 JSON，格式如下：

{
  "groups": [
    {
      "conditions": [{ "field": "platform", "operator": "is", "value": "android" }]
    }
  ]
}

• 一个组内的条件通过 AND 组合。
• 各组通过 OR 组合。
• value 始终是 JSON 字符串——布尔值写作 "true"/"false"，数字写作 "42"，列表写作逗号分隔的字符串，日期范围和相对日期写作字符串化 JSON（见值格式）。

正确（紧凑 JSON，整个值均经过 URL 编码）：

?filters=%7B%22groups%22%3A%5B%7B%22conditions%22%3A%5B%7B%22field%22%3A%22platform%22%2C%22operator%22%3A%22is%22%2C%22value%22%3A%22android%22%7D%5D%7D%5D%7D

错误（原始 JSON，含空格、未编码的引号和花括号）：

?filters={"groups": [{"conditions": [...]}]}

编码规则

import json
from urllib.parse import quote

rule = {
    "groups": [
        {"conditions": [{"field": "platform", "operator": "is", "value": "android"}]},
    ]
}

print(quote(json.dumps(rule, separators=(",", ":")), safe=""))

字段

Audiences 预览表仅显示客户、订阅状态、自动续订状态、消费金额和最近一次购买。其他属性可在导出全部生成的 CSV 中查看，或在客户个人资料中查看。

请使用这些确切的 field 字符串。参见 Audiences。

文本字段

运算符：is、isNot、contains、doesNotContain、isEmpty、isNotEmpty。

字段	含义
customerId	应用用户 ID
originalAppUserId	原始应用用户 ID
email	电子邮件
phoneNumber	电话号码
locale	区域设置
appVersion	应用版本
sdkVersion	SDK 版本
platformVersion	平台（OS）版本
projectId	项目 ID（例如 proj1ab2c3d4）
projectName	项目名称
appConfigId	应用 ID（例如 app1ab2c3d4）
appConfigName	应用名称
idfa	IDFA
idfv	IDFV
gpsAdId	GPS 广告 ID
latestPurchasedOffering	最近购买的权益包
latestOffer	最近的优惠标识符
latestEntitlements	最近的权益标识符
allPurchasedProductIds	所有已购买产品的标识符

枚举字段

运算符：is、isNot、isAnyOf、isNotAnyOf、isEmpty、isNotEmpty。

字段	值
platform	iOS、android、web、macOS、amazon、roku、tvOS、visionOS、watchOS
status	active、trialing、in_grace_period、in_billing_retry、paused、expired、incomplete、unknown
latestStore	app_store、play_store、promotional、mac_app_store、stripe、amazon、roku、rc_billing、paddle、external
anyActiveStore	任意活跃商店——与 latestStore 使用相同的商店标识符
latestOwnershipType	PURCHASED、FAMILY_SHARED
latestOfferType	no_offer、free_trial、introductory_offer、offer_code、promotional_offer、win_back_offer、unspecified_offer
priceExperimentVariant	a、b、c、d
country	最近记录的国家/地区——ISO 3166-1 alpha-2 代码（例如 US、DE）
latestStoreCountry	ISO 3166-1 alpha-2 国家/地区代码
storefront	商店所在国家/地区——ISO 3166-1 alpha-2 代码
mediaSource	项目特定——获取有效值
campaign	项目特定
adGroup	项目特定
ad	项目特定
keyword	项目特定
creative	项目特定
priceExperimentId	项目特定
latestProduct	项目的产品 ID——获取有效值

布尔字段

运算符：is、isNot。值只能是 "true" 或 "false"。

字段	含义
hasMadeSandboxPurchase	曾进行沙盒购买
hasMadeNonSubscriptionPurchase	曾进行非订阅购买
latestAutoRenewIntent	自动续订状态（true = 已设置为续订）
isCurrentlyTrialing	当前处于试用期
isRcPromo	曾通过 RC（促销）获授权益

数字字段

运算符：equal、notEqual、greaterThan、greaterThanOrEqual、lessThan、 lessThanOrEqual、isEmpty、isNotEmpty。值为数字字符串，例如 "50"。

字段	含义
totalSpent	总支出
totalRenewals	续订总次数

日期字段

运算符：before、beforeOrOn、on、after、afterOrOn、within、between、notBetween、 isEmpty、isNotEmpty。

字段	含义
firstSeenAt	首次出现时间
lastSeenAt	最近出现时间
firstPurchaseAt	首次购买时间
mostRecentPurchaseAt	最近购买时间
mostRecentRenewalAt	最近续订时间
latestExpirationAt	最近到期时间
trialStartAt	试用开始时间
trialEndAt	试用结束时间
subscriptionOptOutAt	最近取消订阅时间
trialOptOutAt	最近取消试用时间

自定义属性字段

使用 customAttribute:{key} 筛选（例如 customAttribute:favorite_team）。这些字段使用枚举运算符。使用 get-audience-filter-options 获取已知的键和值——切勿编造键。

值格式

• isEmpty / isNotEmpty — 设置 "value": ""（该值会被忽略）。
• isAnyOf / isNotAnyOf — 逗号分隔的字符串："value": "US,CA,MX"。
• before、beforeOrOn、on、after、afterOrOn — 日历日期 "value": "2026-01-31" （YYYY-MM-DD）。
• between / notBetween — 字符串化的 JSON，且必须且仅包含 from 和 to： "value": "{\"from\":\"2026-01-01\",\"to\":\"2026-01-31\"}"（from ≤ to）。
• within — 字符串化的 JSON，且必须且仅包含 direction、value、unit： "value": "{\"direction\":\"last\",\"value\":30,\"unit\":\"days\"}"。direction 为 last 或 next；unit 为 minutes、hours 或 days；value 为非负整数。 before / beforeOrOn / after / afterOrOn 也接受此相对格式（on 除外）。

获取项目特定值

标记为项目特定的字段（mediaSource、campaign、adGroup、ad、keyword、creative、 priceExperimentId 和 latestProduct）以及自定义属性，只会匹配项目数据中存在的值。使用 get-audience-filter-options 获取：

• project_id（必需）
• fields（必需，至少一个）——以上八个字段中的任意字段、一个自定义属性对应的 customAttribute:{key}，或用于列出所有自定义属性键及其值的 customAttribute。

自定义属性条目可能会返回 cardinality_exceeded: true——即使用户逐字指定的值不在列表中，该值仍可能有效。

固定值字段（country、platform、status，……）不会由此工具提供——请使用上表。切勿猜测项目特定值——筛选不存在的值会静默匹配零个客户。

示例：构建链接

用户需求：“通过 Instagram 获取的 Android 客户”，项目为 proj56965ae1。

规则（两个条件位于同一组中——AND）：

{
  "groups": [
    {
      "conditions": [
        { "field": "platform", "operator": "is", "value": "android" },
        { "field": "mediaSource", "operator": "is", "value": "Instagram" }
      ]
    }
  ]
}

链接：

https://app.revenuecat.com/projects/56965ae1/customer-lists/all-customers?filters=%7B%22groups%22%3A%5B%7B%22conditions%22%3A%5B%7B%22field%22%3A%22platform%22%2C%22operator%22%3A%22is%22%2C%22value%22%3A%22android%22%7D%2C%7B%22field%22%3A%22mediaSource%22%2C%22operator%22%3A%22is%22%2C%22value%22%3A%22Instagram%22%7D%5D%7D%5D%7D

用户需求：“使用 iOS 或 Android、当前正在试用，且在过去 30 天内首次出现的客户”。

{
  "groups": [
    {
      "conditions": [
        { "field": "platform", "operator": "isAnyOf", "value": "iOS,android" },
        { "field": "isCurrentlyTrialing", "operator": "is", "value": "true" },
        {
          "field": "firstSeenAt",
          "operator": "within",
          "value": "{\"direction\":\"last\",\"value\":30,\"unit\":\"days\"}"
        }
      ]
    }
  ]
}