revenuecat-audiences

オーディエンスフィルターとダッシュボードリンク

Audiences を使用すると、ユーザーの顧客をフィルタリングし、その対象に絞ったダッシュボードリンクを共有できます。フィルターでセグメントを選択し、preview-audience の sort_by ／ sort_direction で返されるサンプルを並べ替えます。

オーディエンス用の専用 CLI コマンドはありません。RevenueCat では顧客をフィルタリングまたはセグメント化できない、とユーザーに伝えてはいけません。

顧客の特定、フィルタリング、ランキング

オーディエンスでは、以下のフィールドでフィルタリングできます。

• 商品と期間 — latestProduct、allPurchasedProductIds、latestPurchasedOffering、エンタイトルメント、オファー
• 支出と更新 — totalSpent（フィルターおよび sort_by: total_spent）、totalRenewals（フィルターのみ。更新による並べ替えはできません）
• サブスクリプションの状態 — status、トライアル、自動更新の意向、所有権
• ストア、プラットフォーム、国 — platform、latestStore、country、storefront
• 日付 — 初回確認、購入、更新、有効期限、トライアル、解約
• アトリビューションと実験 — メディアソース、キャンペーン、広告グループ、キーワード、価格実験
• ID とカスタム属性 — アプリユーザー 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（total_customers、active_subscriptions、active_trials、currency での 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. ダッシュボードリンクを共有します。body.rules を使った preview-audience の結果には、「Dashboard URL for this result」で始まる行が含まれます。その URL をそのままリンクします。ツールの結果に URL がない場合に限り、自分でリンクを作成します。

リンクの構築

ツールの結果に「この結果のダッシュボード URL」の行が含まれていない場合にのみ使用します。形式は 2 種類あります。アドホックな探索に使うフィルター付きの all-customers リンクと、create-audience の後に使う保存済みオーディエンスへのリンクです。

1. list-projects からプロジェクト ID を取得します。ダッシュボード URL では、proj プレフィックスを取り除いてください。
2. フィールドの表からフィールドと演算子を選びます。フィールド名や演算子名を創作してはいけません。
3. プロジェクト固有のフィールドについては、先に get-audience-filter-options で有効な値を取得します。
4. ルール JSONを組み立てます。OR 分岐ごとにグループを 1 つ作り、各グループ内に AND 条件を指定し、値の形式に従って値をエンコードします。
5. 短いスクリプトでルールをシリアライズして URL エンコードします（ルールのエンコードを参照してください）。手作業でエンコードしてはいけません。
6. https://app.revenuecat.com/projects/{project_id}/customer-lists/all-customers の filters クエリパラメーターとして追加します。

URL 形式

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

• {project_id} — proj を取り除いた、list-projects の短い 16 進数 ID です。
• フィルターは all-customers リストでのみ機能します。フィルターのない Audiences ホームは /projects/{project_id}/customer-lists です。

保存済みオーディエンスへのリンク

create-audience と get-audience の結果には「この結果のダッシュボード URL」の行が含まれます。その URL をそのままリンクします。list-audiences の出力しかない場合は、id とともに返されるフィールド customer_list_id を使ってリンクします。

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

オーディエンスの id（aud…）と customer_list_id（list…）は異なる識別子です。 ダッシュボードのルートで解決できるのは customer_list_id のみです。その位置に aud… ID を指定すると、「オーディエンスが見つかりません」と表示されます。

正しい例：

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

誤った例（customer_list_id ではなく、オーディエンスの id を指定しています）：

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

保存済みオーディエンスへのリンクに filters パラメーターを追加してはいけません。オーディエンス自体にルールが含まれているためです。レスポンスに customer_list_id がない場合は、ID を推測せず、/customer-lists にリンクしてオーディエンス名を伝えてください。

フィルター済みビューの保存を提案する

フィルター付きの all-customers リンクはアドホックなもので、保存されている情報はありません。リンクを共有するときは、そのことを短い一文で伝え、保存を提案してください。「このビューは保存されていません。後で見つけられるように、オーディエンスとして保存しますか？」

提案は会話ごとに 1 回だけ行います。相手が承諾した場合は、リンク用に作成したものと同じルールで 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 のプレビューテーブルに表示されるのは、Customer、Subscription Status、Auto-Renewal Status、Spent、Latest Purchase のみです。その他の属性は、Export all から出力される 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 — from と to のみを含むJSON文字列： "value": "{\"from\":\"2026-01-01\",\"to\":\"2026-01-31\"}"（from ≤ to）。
• within — direction、value、unit のみを含むJSON文字列： "value": "{\"direction\":\"last\",\"value\":30,\"unit\":\"days\"}"。direction は last または next、unit は minutes、hours、days、value は0以上の整数です。 before / beforeOrOn / after / afterOrOn もこの相対形式を受け付けます（on は除く）。

プロジェクト固有の値の取得

プロジェクト固有とされるフィールド（mediaSource、campaign、adGroup、ad、keyword、creative、 priceExperimentId、latestProduct）およびカスタム属性は、プロジェクトのデータに存在する値とのみ一致します。get-audience-filter-options で取得してください：

• project_id（必須）
• fields（必須、少なくとも1つ） — 上記8つのフィールドのいずれか、1つのカスタム属性を指定する customAttribute:{key}、またはすべてのカスタム属性キーとその値を一覧表示する customAttribute。

カスタム属性の項目には cardinality_exceeded: true が返される場合があります。ユーザーがその値を明示した場合、一覧に含まれていなくても有効な値である可能性があります。

固定値フィールド（country、platform、status、…）はこのツールでは提供されません。上記の表を使用してください。プロジェクト固有の値を推測してはいけません。存在しない値でフィルタリングすると、一致する顧客がゼロ件でも警告なく処理されます。

例：リンクの作成

ユーザーの要望：「Instagram経由で獲得したAndroidの顧客」。プロジェクトは proj56965ae1 です。

ルール（両方の条件を1つのグループに指定 — 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\"}"
        }
      ]
    }
  ]
}