こんにちは、Customer Engineerのgamiです！最近は、「あすけん」で食べたものを記録すると減量できるかという実験をしています。

さて、KARTEを利用している企業の方からよく実現方法を相談される施策として、 「クーポン在庫の順次払い出し」 があります。外部のクーポンシステムからクーポンコードの在庫を予め出力しておき、クーポン取得条件を満たしたユーザーに対してWeb上で順番にクーポンコードを払い出していく、といった内容です。

この「クーポン在庫の順次払い出し」においてクリアすべき最も大きな課題は、 「同一クーポンコードを複数ユーザーに払い出さないようにする」 という点です。素朴に実装すると、同時にアクセスした複数のユーザーに対して同じクーポンコードを払い出してしまうリスクがあります。それを回避するための制御を実現するには、KARTEの基本機能だけでは足りず、KARTE Craftによる実装が必要になります。

今回は、先日リリースされた Craft Counter の特性をうまく利用して「クーポン在庫を順次払い出すAPI」を実装する方法について紹介します。

アウトプットイメージ

最終的なアウトプットイメージは、次の通りです。シンプルな例として、ポップアップのボタンをクリックしたユーザーにユニークなクーポンコードを払い出す、という接客サービスを実装します。

スクリーンショット2023-10-1620.03.57.png

接客サービスの裏側では、Craft Functions + Craft Counter + Craft kvsを駆使して「クーポン在庫を順次払い出すAPI」を実装します。構成図は次の通りです。

スクリーンショット2023-10-1620.08.54.png

API設計

今回は、Craft Functionsを使って接客サービスのJavaScriptから利用できる「クーポン在庫を順次払い出すAPI」を実装する形になります。リクエストとレスポンスの内容は、次のように設計しました。

リクエスト

パラメータ	サンプル値	説明
user_id	`"user001"`	配信先user_id。同一ユーザーによる不正取得防止に利用
coupon_group_id	`"shop001"`	クーポン群を区別するID。クーポン在庫を管理する単位毎に任意のIDを設定する

レスポンス

パラメータ	サンプル値	説明
coupon_code	`"dummycouponcode42"`	取得したクーポンコード
error	-	エラー発生時はエラー内容を返す

データ設計

今回の実装サンプルでは、Craft kvsとCraft Counterでそれぞれ次のようなデータを管理します。

Craft kvs

クーポンコード
- 実際にユーザーに表示するクーポンコード。事前に別Functionを通じて格納しておく
- key
  - ${COUPON_CODE_PREFIX}_${couponGroupId}_${couponIndex}
  - （※サンプルコードではhotspotを避けるためにhash値をprefixに付与）
- value（例）
  - {"key":"coupon-code_shop001_1", "coupon_code":"xxxxx"}
ユーザー毎のクーポンコード前回取得日時
- 簡易的な不正取得検知に利用（後述）
- key
  - ${COUPON_USER_STATUS_PREFIX}_${couponGroupId}_${hashedUserId}
  - （※サンプルコードではhotspotを避けるためにhash値をprefixに付与）
- value（例）
  - { coupon_acquisition_date: "2023-10-17T00:00:00Z" }

Craft Counter

現在払い出し済みの通し番号
- 現在何番目のクーポンコードまで払い出しているかを管理
- key
  - ${COUPON_INDEX_PREFIX}_${couponGroupId}

さて、クーポンコードを順次上から払い出すためには、事前にクーポンコードに通し番号を振っておき、整理券的にそれをユーザーに払い出していくことになります。この「リクエストに応じて1から順に数字を出力する」という用途は、まさにCraft Counterが得意とするところです。

先日のCraft Counterの紹介記事で説明した通り、Craft Counterには次の特徴があります。

特徴1: valueにはnumber 型の整数値しか格納できない
特徴2: 秒間数十回以上のカウントアップ・ダウンリクエストに対応可能
特徴3: increment処理がアトミックに行われる

今回のユースケースでは、まず特徴2によって同時に多数のクーポンコード取得リクエストが来た場合でも問題なく処理を捌くことができます。また、特徴3にある「increment処理がアトミックに行われる」という性質により、冒頭に書いた「同一クーポンコードを複数ユーザーに払い出さないようにする」という課題を簡単にクリアすることができます。詳細はCraft Counterの紹介記事をご覧ください。

手順

「クーポン在庫を順次払い出すAPI」を実装する手順は次の通りです。

Craft kvsにクーポンコード在庫を格納しておく
クーポン払い出し用のCraft Functionsを作成する
Craft Functionsのエンドポイントを作成する
クーポンコード取得用接客サービスを作成する

順番に説明します。

0. Craft kvsにクーポンコード在庫を格納しておく

すでに構成図で示したように、まずは準備としてクーポンコードの在庫をCraft kvsに格納しておく必要があります。

スクリーンショット2023-10-1620.08.54.png

一般的に、Craft kvsにまとまったデータを格納する方法は次の通りです。

格納したいデータをDatahubデータセットにアップロードする
Craft kvsに入稿したい形式に合わせて、対象データを抽出するためのDatahubクエリを作成する
Datahubジョブフローから呼び出してCraft kvsを更新するためのCraft Functionsを作成する
作成したDatahubクエリの結果をそのFunctionに連携するためのDatahubジョブフローを作成し、実行する

詳細の手順やCraft kvs更新用のFunction実装については、下記の記事をご覧ください。

Datahubクエリの結果をCraft kvsに格納してみた

なお今回想定されているデータ形式は次の通りです。

key	value
xxxx_coupon-code_shop001_1	`{"key":"coupon-code_shop001_1", "coupon_code":"xxxxx"}`
yyyy_coupon-code_shop001_2	`{"key":"coupon-code_shop001_2", "coupon_code":"yyyyy"}`
zzzz_coupon-code_shop001_3	`{"key":"coupon-code_shop001_3", "coupon_code":"zzzzz"}`

※xxxx,yyyy,zzzzはkvsのhotspotを避けるためにkeyに付与するhash値

検証のためのダミーデータが欲しい場合は、次のようなDatahubクエリを利用するのが便利です。

WITH dummy_array AS (
  SELECT GENERATE_ARRAY(1, 1000) AS arr
)
SELECT
  CONCAT('coupon-code_shop001_', coupon_index) AS key
  , CONCAT('dummycouponcode', coupon_index) AS coupon_code
FROM dummy_array, UNNEST(arr) AS coupon_index
ORDER BY coupon_index

なお、最終的にkvsに格納される際のkeyの形式については、前項の「データ設計」の「クーポンコード」で記載した形式に合わせる必要があります。特に今回はサンプルコードではmurmurhashを使ってkeyをhash化してprefixに付与することで、kvsのパフォーマンスが下がらないようにしています。「Datahubクエリの結果をCraft kvsに格納してみた」で提供されるテンプレートでkvsを更新する場合、Craft Functionsの APPEND_HASH_PREFIX という変数をtrueにして利用すると自動でhash prefixが付与されるようになります。

Datahubジョブフローを実行してCraft kvsにクーポンコード在庫を格納できたら、事前準備はOKです。

1. クーポン払い出し用のCraft Functionsを作成する

まずは接客サービスからのリクエストを受け付けるCraft FunctionsのFunctionを作成します。サンプルとなるソースコードは、GitHubで公開しています。

craft-codes/craft-functions/coupon-dispenser at main · plaidev/craft-codes

作成手順は次の通りです。

[Craft > ファンクション] からファンクションを新規作成
サンプルコードからコードやモジュールをコピー
Functionを有効化して保存

なお、最近リリースされたファンクション一覧画面の 「テンプレートから作成」 を選んで検索することで、管理画面上から上記と同じサンプルコードを簡単に利用することもできます。便利ですね！

サンプルコードでは次の機能が実装されています。

リクエストbodyから coupon_group_id や user_id を取り出す
変数で設定された時間間隔よりも短い頻度で対象のクーポンを取得しようとしている user_id の場合、不正取得としてエラーを返却する
対象のクーポンについて、Craft Counterで管理された「現在払い出し済みの通し番号」をincrementし、increment後の通し番号を取得する
取得した通し番号に対応するクーポンコードをCraft kvsから取得する
取得したクーポンコードをレスポンスする

ここで注意が必要なのは、クーポンコードの不正取得対策です。サンプルコードでは簡易的に「短い間隔で何度もクーポン取得しようとしているuser_idはエラーにする」という対策を実装しています。しかし、仮にCraft FunctionsのエンドポイントURLが悪意のあるユーザーに特定された場合にuser_idをランダムに生成してエンドポイントにリクエストを送ることでクーポンコードを複数取得できてしまうという問題があります。実際にこのサンプルコードを利用する場合は、サイト側で払い出される独自の認証用tokenを使ったユーザー認証の仕組みを追加で組み込むか、実際にクーポンコードを利用するアプリケーション側で不正利用対策がされているか、いずれかの対応を推奨しています。

2. Craft Functionsのエンドポイントを作成する

Craft Functionsが作成できたら、アンケート接客で実行出来るようにするためのエンドポイントを作成します。

作成したファンクションの編集画面で [設定] タブを開く
[エンドポイント] 欄の [作成] ボタンを押す

作成したエンドポイントのURLは接客サービス側の実装で利用するので手元に控えておきます。

3. クーポンコード取得用接客サービスを作成する

最後に、上記で作成した「クーポン在庫を順次払い出すAPI」を利用する側の実装を行います。今回はKARTEで配信した接客サービスのJavaScriptを介して、エンドユーザーのブラウザから直接リクエストを送信してみましょう。細かい接客サービスの設定方法は割愛して、アクションのJavaScriptのサンプル実装を掲載します。

スクリーンショット2023-10-1620.03.57.png

クーポンコード取得用アクションのJavaScript例

実装内容
- ユーザーがボタンを押したらCraftエンドポイントにリクエストを送信し、 isLoading を true にする
- レスポンスが返ってきたら、取得できたクーポンコードを動的変数に格納し、 isLoading を false にした上でステートを1から2に切り替える

var CRAFT_ENDPOINT_URL = 'https://t.karte.io/hook/xxxxxxxxxx/craft/xxxxxxxxxx';
var COUPON_GROUP_ID = 'shop001'; // クーポン在庫の管理単位を特定するためのID

widget.setVal('isLoading', false);

widget.method('getCoupon', function() {
    // リクエスト完了までローディング表示
    widget.setVal('isLoading', true);

    // クーポンコード取得リクエストを送信
    fetchData(function(item, error) {
        widget.setVal('coupon_code', item.coupon_code);
        if (error) widget.setVal('error', error.toString());
        widget.setVal('isLoading', false);
        widget.setState(2);
    });
});

widget.show();

function fetchData(cb) {
    var payload = {
        user_id: "#{user_id}",
        coupon_group_id: COUPON_GROUP_ID
    };
    fetch(
        CRAFT_ENDPOINT_URL,
        {
            method: 'POST',
            headers: {
              "Content-Type": "application/json",
            },
            body: JSON.stringify(payload),
        }
    )
    .then(function(response) {
        return response.json();
    })
    .then(function(item) {
        cb(item);
    })
    .catch(function(err) {
        cb(null, err);
    })
}

対応するHTML/CSS側では、次の実装が必要となります。実装内容は簡単なので、サンプルコードは割愛します。

isLoading が true の場合のみローディング時のUIが表示されるようにする
リクエスト完了後に表示されるステート2で coupon_code の値を表示する

実際に動かしてみる

実際に接客サービスを配信して動作を確認してみましょう。問題なく実装できていれば、次のようにボタン押下後に異なるクーポンコードが順番に表示されるはずです。

スクリーンショット2023-10-1620.03.57.png

おわりに

今回はCraft kvsとCraft Counterをうまく組み合わせて「クーポン在庫順次払い出し施策」を実装する方法について紹介しました。

ちなみに今回の施策をCraft Counterを使わずCraft kvsだけで実装することも可能です。しかし、前述したCraft Counterの特徴により、 クーポンコードの通し番号を順次漏れなくダブり無く払い出すという用途にはCraft Counterを利用した方がシンプルに実装できます。

施策内容としても、特定の行動を取ってくれたユーザーに対して直接的なリワードを提供できるというのは強力です。クーポンコードの不正取得には十分に対策をした上で、ぜひ活用してみてください！

プレイドでは、世の中にインパクトを与える新しいソリューションを一緒につくる仲間を募集しています！
ぜひ気軽にお問い合わせください。

↓ パートナー企業になりたい

CustomerData-Driven Solution を一緒に創りませんか？ | PLAID Ecosystem

↓ PLAIDで働きたい

クーポン在庫を順次払い出すAPIをKARTE Craftで実装してみた