コンテンツにスキップ
Docs
Esc
↑↓移動↵開く⌘Jプレビュー
このページの内容

購入者の状態

メールアドレスから、お客様に付いている機能フラグを照会する。

購入者の状態は、お客様が今どの機能フラグを持っているかを、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 は自動で再送しません。詳しくは レート制限 を見てください。

次に読むページ

このページは役に立ちましたか?