購入者の状態
メールアドレスから、お客様に付いている機能フラグを照会する。
購入者の状態は、お客様が今どの機能フラグを持っているかを、1回の照会で返すものです。アプリのサーバーで、限定機能を開くかどうかと、上限などの設定値を決めるために使います。
購入者の状態の API にメールアドレスを渡すと、そのお客様に付いている機能フラグと設定値が返ります。機能フラグの商品を使うアプリで、機能の API ごとに権利を確かめるときに使います。
状態に含まれるもの
状態に含まれる権利は、今は機能フラグだけです。応答の形は次のとおりです。
{
"customer_id": "…",
"feature_flags": [
{
"product_id": "…",
"benefit_id": "…",
"granted_at": "…",
"metadata": { "daily_messages": 500 }
}
]
}
| 項目 | 内容 |
|---|---|
customer_id |
このクリエイターのお客様としての ID です。機能フラグが1つ以上あるときだけ入り、無ければ null です。 |
feature_flags |
付与されている(剥奪されていない)機能フラグの一覧です。商品ごとに1件で、付与された日時の古い順に並びます。購入者限定ページの権利は含みません。 |
feature_flags[].product_id |
商品の ID です。 |
feature_flags[].benefit_id |
商品の種類の設定の ID です。 |
feature_flags[].granted_at |
いま有効な権利のうち、いちばん古い付与の日時です。外れた権利は数えないため、全額返金のあとに同じ商品を買い直すと、買い直したときの日時になります。初回の購入日時としては使わないでください。 |
feature_flags[].metadata |
商品に設定した設定値です。 |
benefit_id は商品の種類の設定(API では benefit)の ID です。1つの商品に1つあります。詳しくは 商品の種類の概要 を参照してください。
機能フラグが無いときも、成功の応答になります。customer_id は null、feature_flags は空の配列です。この照会は機能フラグの権利だけを返します。購入の有無をこの API で判定することはできません。
設定値(metadata)には次の決まりがあります。
- 50件までです。キーは1〜40字の英数字、
_、-です。 - 値は文字列(1〜500字)、数値、真偽値のいずれかです。
- 管理画面と API の応答にそのまま表示されます。URL や API キーなどの秘密の値は入れないでください。
SDK の関数では、項目の名前が camelCase になります(customerId、featureFlags、productId、benefitId、grantedAt、metadata)。
照会する
POST /customers/state を自分のサーバーから呼びます。スコープは customers:read です。メールアドレスは URL ではなく本文で送ります。
{
"email": "buyer@example.com"
}
SDK では次の関数で呼びます。Next.js では @nulogic/cozeni-sdk/next から読み込みます。
getCustomerState({ email }):付いている機能フラグをすべて返します。hasFeatureFlag({ email, productId }):特定の商品の機能フラグだけを確かめます。無ければ{ granted: false, metadata: {} }を返します。
応答の形は 状態に含まれるもの を見てください。API のリファレンスは 購入者の状態を取得 を見てください。
キャッシュと再照会
- 照会の結果は最大60秒までキャッシュしてかまいません。キャッシュは自分のサーバーのメモリに置きます。
- 付与されている(
granted: true)結果だけをキャッシュします。付与されていない結果をキャッシュすると、お客様が購入した直後の60秒間、購入済みなのに未購入と判定されます。 - 機能フラグが剥奪された場合は、キャッシュの期限である60秒以内に反映されます。
- 購入直後は、権利ができるまで数秒かかることがあります。見つからないときは、2秒おきに最大3回など、回数を限って照会し直します。
メールアドレスをログや外部の保存先、分析の仕組みに出さないでください。
前提
機能を使えるかどうかを自分のサーバーで判定してください。画面で隠すだけでは、機能の API を直接呼ばれると使えてしまいます。
レート制限
照会の API の呼び出し回数は管理の API とは別の枠で数えます。キーごとに600回/分が上限です。超えると、429 の rate_limited が返り、Retry-After で待つ秒数が分かります。SDK は自動で再送しません。詳しくは レート制限 を見てください。