Solution Blog

Yusuke Kobayashi

Masamichi Kanakubo

Shin Yamamoto

Yuichiro Kohata

Shiori Megumi

Kai Murakami

Shogo Michihata

Yuji Yoshida

Akihiro Nakano

Kasumi Shimamoto

Daikichi Sasamori

Yuusuke Hasegawa

Jumpei Ikegami

Manabu Yazawa

Yusuke Yajima

Kippei Wada

Ikumi Watanabe

Jumpei Koshio

<p>こんにちは、Customer Engineerのkobasukeです。<br>
今年上京したのですが、上京したての頃に毎日驚嘆していた東京の街並みと人の多さは今では見慣れてきて、「都会に染まってきているな」と感じる今日この頃です。</p>
<p>突然ですが、皆様はKARTE Datahubのジョブフローを利用していただいているでしょうか？利用してくださっている方、いつもありがとうございます！</p>
<p>さて、Datahubジョブフローを使用している中で、以下のようなニーズを持つ方もいるのではないでしょうか？</p>
<ul>
<li><strong>ジョブフローに登録できるジョブの上限数を超えて複数ジョブを逐次実行させたい</strong></li>
<li><strong>ジョブフローAの完了後にジョブフローB〜Eを並列実行させたい</strong></li>
</ul>
<p>現在のDatahubジョブフロー機能では、これらのニーズに残念ながらお応えできません。というのも現状のジョブフロー機能では以下のような制約があるためです。</p>
<ul>
<li><strong>ジョブフローに登録できるジョブ数には上限がある</strong></li>
<li><strong>複数のジョブフローで順番を指定して逐次実行させるといったことはできない</strong></li>
</ul>
<p>ですが、KARTE Craftとの連携によって、この制約を超えて皆様のニーズにお応えすることができます。<br>
そこで今回は、KARTE CraftとKARTE Datahubを連携させた <strong>「あるジョブフローが完了したら別のジョブフローを実行する」</strong> というソリューションを紹介していきます。</p>
<h1>目次</h1>
<ul>
<li><strong>実装イメージ</strong></li>
<li><strong>作成手順</strong></li>
<li><strong>実際に動かしてみる</strong></li>
</ul>
<h1>実装イメージ</h1>
<p>KARTE Craftを用いて、あるジョブフローが完了したら別のジョブフローを実行するシステムは下記のような構成で実装します。<br>
<img src="https://ik.imagekit.io/plaid/757b2f44-cf35-48e3-b8f7-923ba735d649/%E3%82%B7%E3%82%99%E3%83%A7%E3%83%95%E3%82%99%E3%83%95%E3%83%AD%E3%83%BC%E3%83%95%E3%83%AD%E3%83%BC%E3%83%81%E3%83%A3%E3%83%BC%E3%83%88.png" alt="ジョブフローフローチャート.png"><br>
システムの各登場人物を整理すると下記のようになります。</p>
<table>
<thead>
<tr>
<th>登場人物</th>
<th>詳細</th>
</tr>
</thead>
<tbody>
<tr>
<td>ユーザー</td>
<td>KARTE利用者</td>
</tr>
<tr>
<td>Trigger Jobflow</td>
<td>実行終了することで、Target Jobflowの実行条件となるジョブフロー</td>
</tr>
<tr>
<td>Target Jobflow</td>
<td>Trigger Jobflowの終了によって、実行されるジョブフロー</td>
</tr>
<tr>
<td>Hook v2</td>
<td>Functionを起動するトリガー</td>
</tr>
<tr>
<td>Craft Functions</td>
<td>KARTE Craftで作成する汎用プログラム</td>
</tr>
</tbody>
</table>
<p>システムの流れを説明すると下記のようになります。<br>
⓪ ユーザーがCraft Functionに実行させたいジョブフローを設定する<br>
① 最初のジョブフロー( Trigger Jobflow )が実行される<br>
② Trigger Jobflowの終了をHook v2で検知する<br>
③ Craft Functionsが起動される<br>
④ 次に実行するジョブフロー( Target Jobflow )の実行requestを行う<br>
⑤ Target Jobflowが実行される<br>
<strong>--Triger JobflowにTarget Jobflowを設定している場合--</strong><br>
②' Target Jobflowが終了<br>
③ Craft Functionが起動する<br>
以降繰り返す</p>
<h1>作成手順</h1>
<p>手順は次の通りです。</p>
<ol>
<li>連続して実行したい2つ以上のジョブフローを用意する</li>
<li>API v2でアプリを作成する</li>
<li>Craft Functionsを作成する</li>
<li>API v2でHook v2を設定する</li>
</ol>
<p>順番に説明します。</p>
<h2>1. 連続して実行したい2つ以上のジョブフローを用意する</h2>
<p>まず、連続して実行したい2つ以上のジョブフローを用意します。まだジョブフローを作成していない場合は以下を参考に作成してください。</p>
<p>作成手順は次の通りです。</p>
<ol>
<li>[Datahub &gt; ジョブフロー &gt; 作成 &gt; ジョブを追加]を選択</li>
<li>任意のジョブを設定</li>
<li>ジョブフロー名を入力し、保存</li>
<li>残りのジョブフローも同じように作成</li>
</ol>
<h2>2. API v2でアプリを作成する</h2>
<p>次に、Craft FunctionsからKARTE Datahubを操作するアプリを作成します。</p>
<p>作成手順は次の通りです。<br>
<strong>＜アプリの設定＞</strong></p>
<ol>
<li>[ストア &gt; API v2 &gt; 作成] を選択</li>
<li>アプリの種類を<code>token</code>に設定</li>
<li>アプリのScopeを<code>datahub.jobflow.get</code>, <code>datahub.jobflow.exec</code>に設定</li>
<li>任意の名前をつけて保存<br>
<img src="https://ik.imagekit.io/plaid/56f3299c-4057-43e8-83dc-e16dac4449e6/%E3%82%B9%E3%82%AF%E3%83%AA%E3%83%BC%E3%83%B3%E3%82%B7%E3%83%A7%E3%83%83%E3%83%882023-11-2413.50.30.png" alt="スクリーンショット2023-11-2413.50.30.png"></li>
</ol>
<p><strong>＜アクセストークンの保存＞</strong></p>
<ol>
<li>アクセストークンが発行されるため「トークンをCraft Secretに保存する」を選択する</li>
<li>任意の名前をつけ、Craft Secretに保存する<br>
<img src="https://ik.imagekit.io/plaid/39c627c5-617c-4248-b1a2-72532a88115e/%E3%82%B9%E3%82%AF%E3%83%AA%E3%83%BC%E3%83%B3%E3%82%B7%E3%83%A7%E3%83%83%E3%83%882023-11-2413.39.24.png" alt="スクリーンショット2023-11-2413.39.24.png"></li>
</ol>
<h2>3.Craft Functionsを作成する</h2>
<p>次に、終了したジョブフローを判別し次のジョブフローを実行するCraft FunctionsのFunctionを作成します。サンプルとなるソースコードは、Craft FunctionsのテンプレートとしてGitHubで公開しています。<br>
<a href="https://github.com/plaidev/craft-codes/tree/main/craft-functions/execute-multiple-jobflow">craft-codes/craft-functions/execute-multiple-jobflow at main · plaidev/craft-codes</a></p>
<p>作成手順は次の通りです。</p>
<ol>
<li>[Craft &gt; ファンクション &gt; 作成 &gt; テンプレートから作成] を選択</li>
<li><strong>あるジョブフローが完了したら別のジョブフローを実行する</strong> というテンプレートを検索し「取得」ボタンをクリック</li>
<li>「反映」ボタンをクリック</li>
<li>コード内で<code>TARGET_JOBFLOWS</code>を設定する</li>
<li>【変数】タブで変数を設定する</li>
<li>Functionを有効化して保存</li>
</ol>
<p><code>TARGET_JOBFLOWS</code>はジョブフローの実行方法に合わせて以下のように設定します。<br>
<strong>＜順次実行＞</strong><br>
ジョブフローA→B→C...の場合</p>
<pre><code>const TARGET_JOBFLOWS = [
    { trigger: 'jobflowAのID', target: 'jobflowBのID' }, // A -&gt; B
    { trigger: 'jobflowBのID', target: 'jobflowCのID' }, // B -&gt; C
    /*
    ....
    */
]
</code></pre>
<p><strong>＜並列実行＞</strong><br>
ジョブフローA→B,C,...の場合</p>
<pre><code>const TARGET_JOBFLOWS = [
    { trigger: 'jobflowAのID', target: 'jobflowBのID' }, // A -&gt; B
    { trigger: 'jobflowAのID', target: 'jobflowCのID' }, // A -&gt; C
    /*
    ....
    */
]
</code></pre>
<p>ジョブフローのIDの取得方法は以下です。</p>
<ol>
<li>[Datahub &gt; ジョブフロー]を選択</li>
<li>1.で準備したジョブフローを選択</li>
<li>画面左下の【詳細情報】のJobflow Idを取得<br>
<img src="https://ik.imagekit.io/plaid/d6861851-796c-4890-a9d5-b8eb00a18bc1/%E3%82%B9%E3%82%AF%E3%83%AA%E3%83%BC%E3%83%B3%E3%82%B7%E3%83%A7%E3%83%83%E3%83%882023-11-2414.46.27.png" alt="スクリーンショット2023-11-2414.46.27.png"></li>
</ol>
<p>変数は以下のように設定します。</p>
<table>
<thead>
<tr>
<th>変数名</th>
<th>詳細</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>KARTE_APP_TOKEN_SECRET</code></td>
<td>KARTE API v2アプリのtokenを登録したシークレット名</td>
</tr>
<tr>
<td><code>LOG_LEVEL</code></td>
<td><code>ERROR</code>/<code>WARN</code>/<code>INFO</code>/<code>DEBUG</code>から出力するログレベルを指定します</td>
</tr>
</tbody>
</table>
<p>サンプルコードの実装の特徴は次の通りです。</p>
<ol>
<li>triggerに設定したジョブフロー以外が終了した場合、ログにメッセージを出し、処理を強制終了させる</li>
<li>複数のジョブフローを並列実行した場合に、各々のジョブフローの実行レスポンスが返ってくる</li>
</ol>
<h2>4. API v2でHook v2を設定する</h2>
<p>最後にCraft Functionsを起動させるトリガーとなるHook v2を設定します。</p>
<p>設定手順は以下です。</p>
<ol>
<li>2で作成したアプリにアクセス</li>
<li>[上部メニュー&gt;hook設定&gt;編集]を選択する</li>
<li>トリガー設定に<code>KARTE Datahub: ジョブフローの終了時</code>を追加</li>
<li>[チャネル設定&gt;Craft]を設定</li>
<li>保存<br>
<img src="https://ik.imagekit.io/plaid/1966a9d9-9f1d-4df8-bc73-2d3f84fa881b/%E3%82%B9%E3%82%AF%E3%83%AA%E3%83%BC%E3%83%B3%E3%82%B7%E3%83%A7%E3%83%83%E3%83%882023-11-2413.44.11.png" alt="スクリーンショット2023-11-2413.44.11.png"></li>
</ol>
<p>Hook v2の設定内容は以下です。</p>
<table>
<thead>
<tr>
<th>項目</th>
<th>詳細</th>
</tr>
</thead>
<tbody>
<tr>
<td>トリガー設定</td>
<td>KARTE Datahub: ジョブフローの終了時</td>
</tr>
<tr>
<td>hook status</td>
<td>有効にする</td>
</tr>
<tr>
<td>ファンクション名</td>
<td>3で作成したFunction名</td>
</tr>
</tbody>
</table>
<p>以上で、Craft FunctionsからKARTE Datahubのジョブフローを操作するための準備は完了です。</p>
<h1>実際に動かしてみる</h1>
<p>実際にKARTE Datehubで最初のTrigger Jobflowを実行して動作を確認してみましょう。</p>
<p>実際にKARTE DatahubからTrigger Jobflowとしたジョブフローを実行してみます。すると、Triggerに設定したジョブフローの実行が終了すると、Targetに設定したジョブフローが実行されていることがログで確認できます。以下はログの一例です。</p>
<p><strong>＜順次実行の場合（A→B→C）＞</strong><br>
<img src="https://ik.imagekit.io/plaid/bac9b838-d52c-474f-9e60-23e001e8e8b0/%E3%82%B9%E3%82%AF%E3%83%AA%E3%83%BC%E3%83%B3%E3%82%B7%E3%83%A7%E3%83%83%E3%83%882023-11-2415.14.08.png" alt="スクリーンショット2023-11-2415.14.08.png"><br>
<strong>＜並列実行の場合（A→B, C）＞</strong><br>
<img src="https://ik.imagekit.io/plaid/aea4a6be-b07e-4262-a048-f3dd120e0ada/%E3%82%B9%E3%82%AF%E3%83%AA%E3%83%BC%E3%83%B3%E3%82%B7%E3%83%A7%E3%83%83%E3%83%882023-11-2415.14.28.png" alt="スクリーンショット2023-11-2415.14.28.png"><br>
<strong>＜Trigger Jobflow以外が終了した場合＞</strong><br>
<img src="https://ik.imagekit.io/plaid/5122ab6a-d345-4edf-83b5-b4d41d095b58/%E3%82%B9%E3%82%AF%E3%83%AA%E3%83%BC%E3%83%B3%E3%82%B7%E3%83%A7%E3%83%83%E3%83%882023-11-2415.02.02.png" alt="スクリーンショット2023-11-2415.02.02.png"></p>
<h1>おわりに</h1>
<p>今回は <strong>「あるジョブフローが完了したら別のジョブフローを実行する」</strong> というソリューションについて紹介しました。このソリューションを応用することで、複数のジョブフローの順次実行を並列に実行させたり、反対に複数の並列実行を順次実行させるなども実現することができます。<br>
皆さんもCraftを使用してDatahubジョブフローの機能拡張を行い、施策の幅を広げてみてください！</p>
<hr>
<p>プレイドでは、世の中にインパクトを与える新しいソリューションを一緒につくる仲間を募集しています！<br>
ぜひ気軽にお問い合わせください。</p>
<p>↓ パートナー企業になりたい</p>
<ul>
<li><a href="https://ecosystem.plaid.co.jp/">CustomerData-Driven Solution を一緒に創りませんか？ | PLAID Ecosystem</a></li>
</ul>
<p>↓ PLAIDで働きたい</p>
<ul>
<li><a href="https://recruit.plaid.co.jp/requisitions/ecosystem-engineer">Ecosystem Engineer | 募集ポジション | 株式会社プレイド</a></li>
<li><a href="https://recruit.plaid.co.jp/requisitions/general-customer-engineer">General Customer Engineer | 募集ポジション | 株式会社プレイド</a></li>
</ul>


KARTE Craftを使って「あるジョブフローが完了したら別のジョブフローを実行する」ソリューションを作成しました。

あるジョブフローが完了したら別のジョブフローを実行する

<p>こんにちは、Customer EngineerのMasamichiです！<br>
最近は本格的に寒くなり冬服に衣替えする頃ですが着痩せしないように背中と肩の筋トレを頑張っています。</p>
<p>さて、<a href="https://solution.plaid.co.jp/202310-craft-counter">Craft Counter</a>を使う上で「<strong>現在のカウント数を定期的に確認したい</strong>」と思ったことはありませんか？例えばクーポン在庫の払い出しをCraftで管理している場合、在庫がどのくらい消費されているか知らなければいつ在庫を補充すれば良いかわかりません。</p>
<p>実際に想定されるユースケースとして以下のようなものが挙げられます：</p>
<ul>
<li>クーポン発行数をCraft Counterで管理していて、現在の発行数を知るために定期的にSlackに通知して欲しい<br>
（参考：<a href="https://solution.plaid.co.jp/202310-coupon-dispenser">クーポン在庫を順次払い出すAPIをKARTE Craftで実装してみた</a>）</li>
</ul>
<p>今回は、KARTE Craftを使ってCraft Counterの値を定期的にSlackに通知する処理を実装します。</p>
<hr>
<h1>全体像</h1>
<h2>処理の流れ</h2>
<p>実現する処理の流れは下図のようになります：<br>
<img src="https://ik.imagekit.io/plaid/5a585c12-9a7c-4696-9366-3b81127a4784/craft_counter_notification_flow.jpg" alt="all_process_flow"><br>
Craft Counterに対して取得したいkeyをカンマ区切りの文字列で指定しておくと、Slackにそれらの現在の値が通知されます。</p>
<h2>アウトプットイメージ</h2>
<p>最終的なアウトプットイメージは、以下のように指定した複数keyに対応するvalueを一度で返します。例えばKARTEを用いてクーポンの発行を東京、大阪、名古屋でそれぞれ発行している場合、東京<code>coupon_count_tokyo</code>、大阪<code>coupon_count_osaka</code>、名古屋<code>coupon_count_nagoya</code>とすると下図のように通知されます。<br>
<img src="https://ik.imagekit.io/plaid/6d29d425-41bf-424f-94d7-e91198150b64/スクリーンショット2023-11-2715.09.29.png" alt="アウトプットイメージ"  /></p>
<hr>
<h1>実装手順</h1>
<p>実装の手順は次の通りです。</p>
<ol>
<li>Slackアプリを作成しワークスペースにインストールする</li>
<li>Craft Counterから欲しい値を取得しSlackに通知する</li>
<li>定期的に自動投稿するようにスケジューリングする</li>
</ol>
<p>順番に説明します。</p>
<h2>1. Slackアプリを作成しチャンネルに追加する</h2>
<h3>アプリの作成</h3>
<p>次の手順に沿ってアプリを作成して下さい：</p>
<ul>
<li>[<a href="https://api.slack.com/apps">Slack API &gt; Your Apps</a>]へいき<code>Create New App</code>をクリック</li>
<li>Create New Appの画面で<code>From scratch</code>を選択</li>
<li>App名と追加したいWorkspaceを指定</li>
</ul>
<h3>Scopeの設定</h3>
<p>アプリを作成したら設定画面の<strong>OAuth &amp; Permission</strong>へいきBotの<strong>スコープ</strong>を設定します。<br>
<img src="https://ik.imagekit.io/plaid/f5b7a25f-4cf3-4f5e-be67-af7a47549395/%E3%82%B9%E3%82%AF%E3%83%AA%E3%83%BC%E3%83%B3%E3%82%B7%E3%83%A7%E3%83%83%E3%83%882023-11-2717.34.48.png" alt="view_detail.png"></p>
<p>今回の処理ではBotに投稿させたいので<code>Bot Token Scopes</code>に<code>chat:write</code>の権限を選択して付与します。</p>
<h3>チャンネルにアプリを追加する</h3>
<p>完了したら次の手順に沿ってチャンネルに作成したアプリを追加して下さい：</p>
<ul>
<li><strong>OAuth Token for Your Workspace</strong>の<code>Install to Workspace</code>をクリックしてSlackに接続</li>
<li>ワークスペースにいき<code>App</code>から作成したアプリを追加</li>
<li>[#Your Channel Name &gt; インテグレーション]から<code>アプリを追加する</code>をクリックして作成したアプリを追加</li>
</ul>
<p><img src="https://ik.imagekit.io/plaid/6c830b6f-70db-4350-80c6-6979bafb56e0/%E3%82%B9%E3%82%AF%E3%83%AA%E3%83%BC%E3%83%B3%E3%82%B7%E3%83%A7%E3%83%83%E3%83%882023-11-2910.19.39.png" alt="スクリーンショット2023-11-2910.19.39.png"></p>
<p>これでSlackの設定は完了です</p>
<p>Slack APIを使用するにあたって以下の情報を必ず控えておいてください</p>
<ul>
<li><code>Bot User OAuth Token</code>: Botが通知するのに必要な権限</li>
<li><code>Slack Channel ID</code>: SlackのチャンネルID(「チャンネル詳細を表示」を押して最下を確認)</li>
</ul>
<h2>2. Craft Counterの値をSlackに通知するCraft Functionsを作成する</h2>
<h3>Functionを作成する</h3>
<p>それでは実際にCraft Couternの値をSlackに通知するCraft FunctionsのFunctionを作成します。サンプルとなるソースコードは、Githubで公開しています。<br>
<a href="">https://github.com/plaidev/craft-codes/tree/main/craft-functions/counter-notification-slack</a></p>
<p>作成手順は次の通りです。</p>
<ul>
<li>[Craft &gt; ファンクション &gt; 作成 &gt; テンプレートから作成]を選択</li>
<li><code>Craft Counterの中身を定期的にSlackに通知する</code>というテンプレートを検索し「取得」をクリック</li>
<li>「反映」をクリックしFunctionを有効化してから保存</li>
</ul>
<p>ここでサンプルコードで行われている実装について解説します。</p>
<h3>Craft Counterから値を取得する</h3>
<p>JavaScriptでのコード例：</p>
<pre><code class="language-js:">const COUNTER_KEYS = '&lt;% COUNTER_KEYS %&gt;';

const { counter } = MODULES;

const counterKeys = COUNTER_KEYS.split(',');

const counterValues = await counter.get({keys: counterKeys});
</code></pre>
<p><code>COUNTER_KEYS</code>はCraft変数の参照をしていてkeyをカンマ区切りの文字列で指定します。<br>
（keyの例：<code>&quot;coupon_count_tokyo, coupon_count_osaka, coupon_count_nagoya&quot;</code>）<br>
<code>counterValues</code>に指定したkeyに対応するvalueが配列で格納されます。</p>
<h3>取得した値をSlackへ通知する</h3>
<p>JavaScriptでのコード例：</p>
<pre><code class="language-js">import { WebClient } from '@slack/web-api';

const SLACK_CHANNEL_ID = '&lt;% SLACK_CHANNEL_ID %&gt;';
const SLACK_TOKEN_SECRET = '&lt;% SLACK_ TOKEN_SECRET %&gt;';

const { secret } = MODULES;
const secrets = await secret.get({keys: [SLACK_TOKEN_SECRET]});
const token = secrets[SLACK_TOKEN_SECRET];

const slackClient = new WebClient(token);

const message = counterKeys
 .map((key, i) =&gt; `現在の${key}のカウント数: ${counterValues[i]}`)
 .join('\n');

await slackClient.chat.postMessage({
  channel: SLACK_CHANNEL_ID,
  text: message
  });
</code></pre>
<ul>
<li><code>SLACK_CHANNEL_ID</code>：前述した<code>Slack Channel ID</code>を格納したCraft変数</li>
<li><code>SLACK_TOKEN_SECRET</code>：前述した<code>Slack Bot User OAuth Token</code>を登録したシークレットのCraft変数</li>
</ul>
<p>取得した入力key: <code>counterKeys</code>と対応するvalue: <code>counterValues</code>が紐づくように、メッセージを以下のようなフォーマットで作成しSlackに通知します。</p>
<pre><code>  現在のcounterKeys[0]のカウント数：counterValues[0]
  現在のcounterKeys[1]のカウント数：counterValues[1]
  現在のcounterKeys[2]のカウント数：counterValues[2]
                              ⋮
</code></pre>
<h2>3. 定期的に自動投稿するようにスケジューリングする</h2>
<p>最後にBotが定期的に通知してくれるようにスケジューリングの設定をします。</p>
<p>スケジュールはCraft functionsの設定画面から<code>cron</code>形式を用いて分単位で設定できます。スケジュールを<strong>有効</strong>にすることを忘れないでください！<br>
<img src="https://ik.imagekit.io/plaid/d89a864c-e64f-45f7-b720-313f7cf0fbf7/%E3%82%B9%E3%82%AF%E3%83%AA%E3%83%BC%E3%83%B3%E3%82%B7%E3%83%A7%E3%83%83%E3%83%882023-11-2812.13.33.png" alt="スクリーンショット2023-11-2812.13.33.png"><br>
（※スケジュール設定の詳細は<a href="https://developers.karte.io/docs/craft-scheduler">Craft Scheduler</a>を確認して下さい。）</p>
<h1>おわりに</h1>
<p>以上で実装は終了です、お疲れ様でした。</p>
<p>今回は「Craft Counterの中身を定期的にSlackに通知する」を紹介しました。これによりCraft Counterの最新の値を簡単に確認できるようになります。ぜひ皆さんも活用してみてください！</p>
<hr>
<p>プレイドでは、世の中にインパクトを与える新しいソリューションを一緒につくる仲間を募集しています！<br>
ぜひ気軽にお問い合わせください。</p>
<p>↓ パートナー企業になりたい</p>
<ul>
<li><a href="https://ecosystem.plaid.co.jp/">CustomerData-Driven Solution を一緒に創りませんか？ | PLAID Ecosystem</a></li>
</ul>
<p>↓ PLAIDで働きたい</p>
<ul>
<li><a href="https://recruit.plaid.co.jp/requisitions/ecosystem-engineer">Ecosystem Engineer | 募集ポジション | 株式会社プレイド</a></li>
<li><a href="https://recruit.plaid.co.jp/requisitions/general-customer-engineer">General Customer Engineer | 募集ポジション | 株式会社プレイド</a></li>
</ul>


KARTE Craftを使って「Craft Counterからvalueを定期的に取得してSlackに自動投稿する」を実装しました。

Craft Counterの中身を定期的にSlackに通知する

<p>こんにちは、Customer Engineerのgamiです！！最近、いまさら<a href="https://ja.wikipedia.org/wiki/%E5%AE%B9%E7%96%91%E8%80%85X%E3%81%AE%E7%8C%AE%E8%BA%AB">『容疑者Xの献身』</a>を読みました。とても良かったので、Netflixで映画まで見てしまいました。</p>
<p>さて、KARTEでは「いま何人がこの商品を見ています」のようにアイテム別の閲覧人数をWebサイト上に簡単に表示できる機能があります。具体的には、接客サービスのアクションで <a href="https://developers.karte.io/reference/static-variables">page_user_count</a> という特別な静的変数を使うことで配信先ページの閲覧人数を参照できます。</p>
<p><img src="https://ik.imagekit.io/plaid/b2cbf1cb-ed8b-4fe7-8b0c-dbd72b1ab3e0/page_user_count.png" alt="page_user_count.png"></p>
<p>一方で、この <code>page_user_count</code> 変数で取得できる値の計算ロジックはKARTE全体で固定であり、カスタマイズができません。たとえば次のような難点があります。</p>
<ul>
<li><strong>「直近何分間の閲覧を対象にするか？」を自由に設定できない</strong></li>
<li><strong>ページ閲覧しかカウントできず、たとえば「何人が購入しました」といったカウントはできない</strong></li>
<li><strong>WebとAppで閲覧人数を合算できない</strong></li>
</ul>
<p>KARTE Datahubとアクションテーブルを利用すればこうしたカスタマイズ要望にも対応できますが、今度はデータが最大でも毎時更新になるためリアルタイム性が損なわれてしまいます。</p>
<p>そこで今回は、KARTE Craftを使ってこの「いま何人がこの商品を見ています」のリアルタイム集計ロジックを独自実装する方法について紹介します。</p>
<h1>アウトプットイメージ</h1>
<p>最終的なアウトプットイメージは次の通りです。</p>
<p><img src="https://ik.imagekit.io/plaid/d1476bf8-a60f-4688-b27d-eb8f3581da3f/%E3%82%B9%E3%82%AF%E3%83%AA%E3%83%BC%E3%83%B3%E3%82%B7%E3%83%A7%E3%83%83%E3%83%882023-10-3116.30.49.png" alt="スクリーンショット2023-10-3116.30.49.png"></p>
<p>構成図は次の通り。Craft側のデータベースはCraft Counterを使います。<br>
<img src="https://ik.imagekit.io/plaid/336e90de-24b0-4c29-8da8-13a689cb0f10/%E3%82%B9%E3%82%AF%E3%83%AA%E3%83%BC%E3%83%B3%E3%82%B7%E3%83%A7%E3%83%83%E3%83%882023-10-3116.24.00.png" alt="スクリーンショット2023-10-3116.24.00.png"></p>
<h1>API設計</h1>
<p>今回は、Craft Functionsを使って接客サービスのJavaScriptからcallできる「閲覧人数取得API」を実装する形になります。1リクエストで閲覧人数のincrementとgetを実現します。</p>
<p>リクエストとレスポンスの内容は、次のように設計しました。</p>
<p><strong>リクエスト</strong></p>
<table>
<thead>
<tr>
<th>パラメータ</th>
<th>サンプル値</th>
<th>説明</th>
</tr>
</thead>
<tbody>
<tr>
<td>itemId</td>
<td><code>&quot;011&quot;</code></td>
<td>対象のアイテムID</td>
</tr>
<tr>
<td>skipIncrement</td>
<td><code>false</code></td>
<td>同一ユーザーが同一アイテムを複数回見たときなど、incrementをスキップする場合にtrueにする</td>
</tr>
<tr>
<td>skipGettingCount</td>
<td><code>false</code></td>
<td>incrementだけ実行したい場合にtrueにする。「購入UU数」を「閲覧ユーザー」に表示したい場合など、incrementとgetのタイミングが違う場合に利用（後述）</td>
</tr>
</tbody>
</table>
<p><strong>レスポンス</strong></p>
<table>
<thead>
<tr>
<th>パラメータ</th>
<th>サンプル値</th>
<th>説明</th>
</tr>
</thead>
<tbody>
<tr>
<td>count</td>
<td><code>42</code></td>
<td>取得した閲覧人数</td>
</tr>
<tr>
<td>error</td>
<td>-</td>
<td>エラー</td>
</tr>
</tbody>
</table>
<h1>手順</h1>
<p>設定手順は次の通りです。</p>
<ol>
<li>Craft Functionsを作成する</li>
<li>Craft Functionsのエンドポイントを作成する</li>
<li>Functionと連携する接客サービスを作成する</li>
</ol>
<p>順番に説明します。</p>
<h2>1. Craft Functionsを作成する</h2>
<p>まずは接客サービスからのリクエストを受け付けるCraft FunctionsのFunctionを作成します。サンプルとなるソースコードは、Craft FunctionsのテンプレートとしてGitHubで公開しています。</p>
<p><a href="https://github.com/plaidev/craft-codes/tree/main/craft-functions/uu-per-item-counter">craft-codes/craft-functions/uu-per-item-counter at main · plaidev/craft-codes</a></p>
<p>作成手順は次の通りです。</p>
<ul>
<li>[Craft &gt; ファンクション &gt; 作成 &gt; テンプレートから作成] を選択</li>
<li><code>「いま何人がこの商品を見ています」施策をKARTE Craftで独自実装する</code> というテンプレートを検索し「取得」ボタンをクリック</li>
<li>「反映」ボタンをクリック</li>
<li>Functionを有効化して保存</li>
</ul>
<p>サンプルコードの実装の特徴は次の通りです。</p>
<ul>
<li><code>HOW_MANY_MINUTES_AGO</code> という定数で「直近何分間の閲覧を対象にするか」を自由に設定できる</li>
<li>1分間のtimewindow毎に閲覧UU数をCraft Counter上でカウントし、対象期間のレコード群を取得して合計値を返す</li>
</ul>
<p>Craft Counter側の設計について補足します。まずCraft Counterのkeyは次のような形式になっています。</p>
<ul>
<li><code>${COUNTER_KEY_PREFIX}_${timewindow}_${itemId}</code></li>
</ul>
<table>
<thead>
<tr>
<th>項目</th>
<th>サンプル値</th>
<th>説明</th>
</tr>
</thead>
<tbody>
<tr>
<td>COUNTER_KEY_PREFIX</td>
<td><code>&quot;item-view-uu&quot;</code></td>
<td>定数で指定する固定のprefix</td>
</tr>
<tr>
<td>timewindow</td>
<td><code>&quot;202301011259&quot;</code></td>
<td>閲覧日時を <code>yyyyMMddHHmm</code> の形式でフォーマットしたもの</td>
</tr>
<tr>
<td>itemId</td>
<td><code>&quot;011&quot;</code></td>
<td>対象のアイテムID</td>
</tr>
</tbody>
</table>
<p>たとえば2023年1月1日12時59分には、Craft Counter側の関連レコードは次のようになっていたとします。</p>
<table>
<thead>
<tr>
<th>key</th>
<th>value</th>
</tr>
</thead>
<tbody>
<tr>
<td>item-view-uu_202301011256_011</td>
<td>7</td>
</tr>
<tr>
<td>item-view-uu_202301011257_011</td>
<td>14</td>
</tr>
<tr>
<td>item-view-uu_202301011258_011</td>
<td>17</td>
</tr>
<tr>
<td>item-view-uu_202301011259_011</td>
<td>11</td>
</tr>
</tbody>
</table>
<p>定数 <code>HOW_MANY_MINUTES_AGO</code> が仮に3だった場合、直近3分間の閲覧人数を取得するので、取得対象のtimewindowは 202301011257 〜 202301011259 になります。その合計は14 + 17 + 11で42です。これがレスポンスに含まれるcountの値になります。</p>
<p>定数 <code>HOW_MANY_MINUTES_AGO</code> の値を変更すると、それに応じて取得対象のレコード数が増える形になります。</p>
<h2>2. Craft Functionsのエンドポイントを作成する</h2>
<p>Craft Functionsが作成できたら、接客サービスから実行出来るようにするためのエンドポイントを作成します。</p>
<ul>
<li>作成したファンクションの編集画面で [設定] タブを開く</li>
<li>[エンドポイント] 欄の [作成] ボタンを押す</li>
</ul>
<p>作成したエンドポイントのURLは接客サービス側の実装で利用するので手元に控えておきます。</p>
<h2>3. Functionと連携する接客サービスを作成する</h2>
<p>最後に、Craftで実装した「閲覧人数取得API」を利用する接客サービスを実装し、アイテム詳細ページで配信します。</p>
<p>細かい接客サービスの設定方法は割愛して、アクションのJavaScriptについてサンプル実装を掲載します。</p>
<h3>接客アクションのJavaScript例</h3>
<ul>
<li>実装のポイント
<ul>
<li><strong>同一ユーザーが同じアイテムを複数回見た場合の重複カウントを防ぐため、localStorageで閲覧済みアイテムを管理し毎回チェックする</strong></li>
<li>配信直後にCraft側にリクエストを送信し、結果が取得できたら閲覧人数を表示</li>
</ul>
</li>
</ul>
<pre><code class="language-js">var CRAFT_ENDPOINT_URL = 'https://t.karte.io/hook/xxxxx/craft/xxxxx';
var LOCAL_STORAGE_KEY = 'viewedItemIds';
var LOCAL_STORAGE_EXPIRE_MINUTES = 3; // 閲覧済みアイテムの保持期間
var MIN_SHOW_UU = 1; // 何人以上だったら表示するか？

// 閲覧URLからアイテムIDを取得
var itemId = location.pathname.split('/')[2]; // TODO: サイトに応じて実装する
if (!itemId) return;

widget.setVal('count', null);

// 配信先ユーザーがすでに当該アイテムを閲覧済みかチェックする
var alreadyViewed = checkAlreadyViewedAndUpdateLocalStorage(itemId);
fetchCount(itemId, alreadyViewed);

function checkAlreadyViewedAndUpdateLocalStorage(itemId) {
    var alreadyViewed = false;

    // viewedItemIds（カンマ区切り文字列）をlocalStorageから取得
    var viewedItemIds = widget.storage.local.restore(LOCAL_STORAGE_KEY);
    if (!viewedItemIds) {
        viewedItemIds = '';
    }

    // 配列化して、itemIdが追加済みかチェック
    var arr = viewedItemIds ? viewedItemIds.split(',') : [];
    if (!arr.includes(itemId)) {
        arr.push(itemId);
    } else {
        alreadyViewed = true;
    }
    viewedItemIds = arr.join(',');

    // localStorageを更新
    widget.storage.local.store(LOCAL_STORAGE_KEY, viewedItemIds, {
      expire: 1000 * 60 * LOCAL_STORAGE_EXPIRE_MINUTES // N分後に削除
    });
    return alreadyViewed;
}

function fetchCount(itemId, alreadyViewed) {
    _post({
        itemId: itemId,
        skipIncrement: alreadyViewed, // すでに配信先ユーザーが閲覧済みの商品であればincrementをスキップ
    })
    .then(function(body) {
        console.log('body: ',body)
        var count = body.count;
        widget.setVal('count', count);
        if (count &gt;= MIN_SHOW_UU) {
            widget.show();
        }
    });
}

function _post(body) {
    return fetch(CRAFT_ENDPOINT_URL, {
        method: 'POST',
        headers: {'Content-Type': 'application/json'},
        body: JSON.stringify(body),
    }).then(function(res) {
        if (res.ok) {
            return res.json();
        } else {
            return;
        }
    });
}
</code></pre>
<h1>実際に動かしてみる</h1>
<p>実際に動作を確認してみましょう。</p>
<p>Craft側の動作に問題がなければ、接客サービスの表示確認をしてみましょう。次のように閲覧人数が表示されるはずです。</p>
<p><img src="https://ik.imagekit.io/plaid/d1476bf8-a60f-4688-b27d-eb8f3581da3f/%E3%82%B9%E3%82%AF%E3%83%AA%E3%83%BC%E3%83%B3%E3%82%B7%E3%83%A7%E3%83%83%E3%83%882023-10-3116.30.49.png" alt="スクリーンショット2023-10-3116.30.49.png"></p>
<p>ユーザーはブラウザ単位で区別されるので、同一ページを別々のブラウザやシークレットウィンドウで開いてみてください。開いた数に応じて人数が加算されて表示されれば成功です。</p>
<h1>おわりに</h1>
<p>今回はKARTE Craftで「いま何人がこの商品を見ています」施策を独自実装する方法について紹介しました。</p>
<p>サンプルコードでの実装は、KARTEの標準機能であるpage_user_count変数と次の点で自由度が高いものになっています。</p>
<ul>
<li>「直近何分間の閲覧を対象にするか」を自由に設定できる</li>
<li>itemIdをリクエストパラメータに直接渡して集計対象に指定できる</li>
</ul>
<p>応用として、たとえば次のようなシナリオの実現でも利用することができます。</p>
<ul>
<li>(例) <strong>アイテム詳細ページを閲覧中のユーザーに対して「直近1時間で何人が購入しました」のように表示する</strong>
<ul>
<li>設定方法
<ul>
<li>アイテム購入時に、毎回Craft Functionsにリクエストを送る。このときincrementだけしたいので、 <code>skipGettingCount</code> をtrueに設定する</li>
<li>アイテム閲覧時に、「直近1時間で何人が購入しました」を表示する接客サービスからCraft Functionsにリクエストを送る。このときincrementしたくないので <code>skipIncrement</code> をtrueに設定する</li>
</ul>
</li>
</ul>
</li>
</ul>
<p>また、 <strong>WebとAppの両方にアイテム詳細画面がある場合も、同じCraft Functionsエンドポイントを共有すればWeb/App横断で数値を合算して表示することができます。</strong></p>
<p>「いま何人が見ています」や「直近1時間で何人が購入しました」といった施策は、臨場感がありエンドユーザーにとっても強く訴求できるものです。ぜひCraftを使って自由度高く実現してみてはいかがでしょうか？</p>
<hr>
<p>プレイドでは、世の中にインパクトを与える新しいソリューションを一緒につくる仲間を募集しています！<br>
ぜひ気軽にお問い合わせください。</p>
<p>↓ パートナー企業になりたい</p>
<ul>
<li><a href="https://ecosystem.plaid.co.jp/">CustomerData-Driven Solution を一緒に創りませんか？ | PLAID Ecosystem</a></li>
</ul>
<p>↓ PLAIDで働きたい</p>
<ul>
<li><a href="https://recruit.plaid.co.jp/requisitions/ecosystem-engineer">Ecosystem Engineer | 募集ポジション | 株式会社プレイド</a></li>
<li><a href="https://recruit.plaid.co.jp/requisitions/general-customer-engineer">General Customer Engineer | 募集ポジション | 株式会社プレイド</a></li>
</ul>


KARTE Craftを使って「いま何人がこの商品を見ています」のようにアイテム別の閲覧人数のリアルタイム集計ロジックを独自実装する方法について紹介します。

「いま何人がこの商品を見ています」施策をKARTE Craftで独自実装する

KARTE Craftを使って「Account Engagement（旧 Pardot）から取得したプロスペクト情報を KARTE にイベント送信する」方法について紹介します。

Account Engagement（旧 Pardot）から取得したプロスペクト情報を KARTE にイベント送信する

<p>こんにちは、Customer EngineerのShinです！<br>
最近行った銀座のスープカレー屋さんが美味しすぎました。</p>
<p>さて、<a href="https://karte.io/package/message/">KARTE Message</a>はパーソナライズ配信を簡単にできるMAツールですが、<strong>ECサイト等でエンドユーザーの商品閲覧状況に合わせ、パーソナライズにしてメール施策を実施したいと思ったことはないでしょうか？？</strong></p>
<p>今回は、KARTE Messageを使って、商品詳細閲覧イベントデータをもとにユーザーが直近閲覧した商品をパーソナライズして配信する方法をご紹介いたします。</p>
<h3>想定するユースケース</h3>
<p>「カートに入れる前に、商品を閲覧してECサイトから離脱してしまったユーザーに対して購買を促す」ことを想定しています。<br>
ユーザーが興味を持った商品を訴求することで、購買につながる可能性が高くなると言えます。（参考：<a href="https://jglobal.jst.go.jp/detail?JGLOBAL_ID=202002214494558739">ECサイトにおける閲覧履歴を用いた購買に繋がる行動の変化検出</a>）</p>
<hr>
<h1>全体像</h1>
<h2>処理の流れ</h2>
<p>実現する処理の全体像は、以下の通りで、エンドユーザーの商品閲覧という行動に対して発火したイベントを元にして、データをDatahubで整形し、Messageで配信をするといった流れになっています。</p>
<p><img src="https://ik.imagekit.io/plaid/433b8b2f-96af-46f8-a3d8-23f038e0cba5/%E3%82%B9%E3%82%AF%E3%83%AA%E3%83%BC%E3%83%B3%E3%82%B7%E3%83%A7%E3%83%83%E3%83%880005-11-0811.20.27.png" alt="all_process_flow"></p>
<h2>アウトプットイメージ</h2>
<p>最終のアウトプットイメージは、以下のように、カラム形式で閲覧した商品の情報が表示されているものとなっています。<br>
<img src="https://ik.imagekit.io/plaid/30e85f07-8ec1-4d47-9641-96d74704c155/output.png" alt="アウトプットイメージ" width="400px" /></p>
<h3>利用するKARTEのツール・必要な知識</h3>
<ul>
<li>利用するKARTEのツール<br>
（ご利用のプランによって使えるツールが違うのでご確認ください）
<ul>
<li>「<a href="https://karte.io/feature/insight/">KARTE Insight</a>」</li>
<li>「<a href="https://karte.io/package/message/">KARTE Message</a>」</li>
<li>「<a href="https://karte.io/feature/integration/">KARTE Datahub</a>」</li>
</ul>
</li>
<li>必要な知識
<ul>
<li>SQL</li>
<li>「<a href="https://support.karte.io/post/5a3by6movo4cJfBC1Pa7I8">Hundlbars構文</a>」</li>
</ul>
</li>
</ul>
<hr>
<h1>実装手順</h1>
<p>実装の手順は次の通りです。</p>
<ol>
<li>「商品詳細ページ閲覧(view_item)」イベントを発火させる</li>
<li>クエリコレクションを使って元データを作成する</li>
<li>商品情報を含んだメール配信するリストを作成する</li>
<li>キャンペーンを作成する</li>
</ol>
<p>順番に説明します。</p>
<h2>1. 「商品詳細ページ閲覧(view_item)」イベントを発火させる</h2>
<p>商品閲覧情報を取得するため、Insightで「商品詳細ページ閲覧(view_item)」イベントを発火させる必要があります。（既に実装済みの方は読み飛ばして2へ進んでください）</p>
<p><strong>すべてのメニュー &gt; Insight &gt; イベント</strong>をクリックして、<strong>「Insight &gt; イベント &gt; ストアからインストール &gt; eコマース &gt; [商品詳細ページ閲覧]」</strong> をインストールします。<br>
<img src="https://ik.imagekit.io/plaid/dfa174fb-3a68-448e-89e8-1cd633517024/view_detail.png" alt="view_detail.png"></p>
<p>別途、このイベントを発火させる必要があります。詳しくは<a href="https://support.karte.io/post/3SObAcXAvjn5S6kSQ4wuBZ#3-3">サポートサイト &gt; 閲覧商品情報を計測する</a> をご覧ください。</p>
<p>以下のように、イベントが計測できていることを確認します。<br>
<img src="https://ik.imagekit.io/plaid/03fb2957-44fe-4ac2-801c-a1d310f25c12/result_event.png" alt="result_event.png"></p>
<h2>2. クエリコレクションを使って元データを作成する</h2>
<p>次に、1で設定したイベントをもとに商品情報を含んだユーザーのリストをDatahubを使って作成します。</p>
<p><strong>すべてのメニュー &gt; Datahub &gt; クエリ</strong>をクリックします。</p>
<p>今回、私が <strong>&quot;閲覧した商品をパーソナライズメールで通知&quot;</strong> という「クエリコレクション」 を作成しました。</p>
<p>以下のクエリでは、view_itemイベントの中で、任意の期間に該当するイベントを抽出、最近閲覧した順で、上から最大表示商品数分取得し、メール配信するコンテンツ内で、商品情報を展開する必要があるので、<a href="https://cloud.google.com/bigquery/docs/nested-repeated?hl=ja">RECORD型</a>に整形しています。</p>
<pre><code class="language-sql">WITH raw AS (
  SELECT
    sync_date
    , user_id
    , event_name
    , values
  FROM
    {% karte_event relative_period[0], relative_period[1] %}
  WHERE
    event_name = 'view_item'
), expansion_array AS (
  SELECT
    user_id
    , JSON_VALUE(values, '$.view_item.item_id') AS item_id
    , sync_date
    , JSON_VALUE(values, '$.view_item.brand') AS brand_name
    , JSON_VALUE(values, '$.view_item.brand_cd') AS brand_cd
    , JSON_VALUE(values, '$.view_item.name') AS name
    , JSON_VALUE(values, '$.view_item.price') AS price
    , JSON_VALUE(values, '$.view_item.item_url') AS item_url
    , JSON_VALUE(values, '$.view_item.item_image_url') AS item_image_url
    , JSON_VALUE(values, '$.view_item.l_category_name') AS l_category_name
    , JSON_VALUE(values, '$.view_item.s_category_name') AS s_category_name
    , JSON_VALUE(values, '$.view_item.l_category_cd') AS l_category_cd
    , JSON_VALUE(values, '$.view_item.s_category_cd') AS s_category_cd
    , JSON_VALUE(values, '$.view_item.favorite_num') AS favorite_num
    , JSON_VALUE(values, '$.view_item.review_num') AS review_num
    , ROW_NUMBER() OVER (PARTITION BY user_id, JSON_VALUE(values, '$.view_item.item_id') ORDER BY sync_date DESC) AS child_row_num
  FROM
    raw
), latest_item_data AS (
  SELECT 
    user_id
    , item_id
    , sync_date
    , brand_name
    , brand_cd
    , name
    , price
    , item_url
    , item_image_url
    , l_category_name
    , s_category_name
    , l_category_cd
    , s_category_cd
    , favorite_num
    , review_num
    , ROW_NUMBER() OVER (PARTITION BY user_id) AS new_row_num
  FROM expansion_array
  WHERE child_row_num = 1
), limit_data AS (
  SELECT * FROM latest_item_data
  WHERE
    new_row_num &lt;= {{max_show_items_number}}
), mail_row_data AS (
  SELECT
    user_id
    , item_id
    , sync_date
    , brand_name
    , brand_cd
    , name
    , price
    , item_url
    , item_image_url
    , l_category_name
    , s_category_name
    , l_category_cd
    , s_category_cd
    , favorite_num
    , review_num
    , CASE
        WHEN MOD(new_row_num, {{mail_column_number}}) = 1 THEN true
        ELSE false
      END AS is_row_start
    , CASE
        WHEN MOD(new_row_num, {{mail_column_number}}) = 0 THEN true
        ELSE false
      END AS is_row_end
  FROM limit_data
)

SELECT
  user_id,
  ARRAY_AGG(
    STRUCT(
      item_id
      , sync_date
      , brand_name
      , brand_cd
      , name
      , price
      , item_url
      , item_image_url
      , l_category_name
      , s_category_name
      , l_category_cd
      , s_category_cd
      , favorite_num
      , review_num
      , is_row_start
      , is_row_end
    )
  ) AS item_arr
FROM
  mail_row_data
GROUP BY
  user_id
</code></pre>
<p>また、実際に配信することを想定し、以下の2つをパラメータから指定できるようにしました。</p>
<ul>
<li>「最大表示商品数」でメールで表示する最大の商品数を任意指定</li>
<li>「カラム数」で配信するコンテンツの表示カラム数を任意指定<br>
（こちらができるようにis_row_startとis_row_endというフィールドを追加しました）</li>
</ul>
<pre><code class="language-yaml">relative_period:
  type: period
  label: 抽出期間
  default: past 30 days
  tooltip: 長くすると、クエリリソースを多く消費します
  value: past 30 days
max_show_items_number:
  type: number
  label: 最大表示商品数
  default: 3
  tooltip: 最大で何件の商品をメールに表示するかを設定できます
  value: 3
mail_column_number:
  type: number
  label: カラム数
  default: 3
  tooltip: メールで商品を表示するカラム数
  value: 3
</code></pre>
<p>下図は、カラム数が2・最大表示商品数が3のケースとなっています。<br>
<img src="https://ik.imagekit.io/plaid/22100b61-e12f-403d-b2a8-900465f4f5f1/column_image.png" alt="column_image.png" width="400px"/></p>
<hr>
<p><strong>「作成 &gt; コレクションから作成 &gt; 閲覧した商品をパーソナライズメールで通知」を選択し、「このクエリを利用」</strong> をクリックします。<br>
基本的に、パラメータ設定で確認できる値を任意で変更するだけで良いでしょう。<br>
クエリを実行して、実行結果が正しく返ってくることを確認します。</p>
<p><img src="https://ik.imagekit.io/plaid/1b493eda-7eda-4736-afad-2b8600184784/%E3%82%B9%E3%82%AF%E3%83%AA%E3%83%BC%E3%83%B3%E3%82%B7%E3%83%A7%E3%83%83%E3%83%880005-11-0815.36.12.png" alt="スクリーンショット0005-11-0815.36.12.png"></p>
<h2>3. 商品情報を含んだメール配信するリストを作成する</h2>
<p><strong>すべてのメニュー &gt; Message β &gt; リスト管理</strong>から、配信するリストを作成します。<br>
詳細は、<a href="https://support.karte.io/post/wxduChZhEu8Hw5RPUVfsf">サポートサイトの「リストとは」</a> をご参照ください。</p>
<img src="https://ik.imagekit.io/plaid/552cff5b-378f-43d2-8151-d5d6f7d92023/list_image.png" alt="list_image.png" width="80%" />
<h2>4. キャンペーンを作成する</h2>
<p><strong>すべてのメニュー &gt; Message β &gt; キャンペーン管理</strong>をクリックします。<br>
右上の「キャンペーンを作成」をクリックして、実際に配信するキャンペーンを作っていきます。</p>
<h3>コンテンツ</h3>
<p>「メール配信」を選択します</p>
<h3>対象ユーザー</h3>
<p>マスターリストは、user_id・mailが入っているリストを選択してください。<br>
<strong>「さらに絞り込む」&gt; 「リストを追加」</strong> で先ほど3で作成した、リストを追加します。</p>
<h3>アクション</h3>
<p>ここが少し難しいポイントになります。<br>
「アクションを追加」を押して、メールアクション編集ページを開きます。</p>
<ol>
<li>
<p>「構造」から1カラムのものを追加します<br>
<img src="https://ik.imagekit.io/plaid/ac892a6e-5de8-4f56-a9bb-f1d7584559d1/%E3%82%B9%E3%82%AF%E3%83%AA%E3%83%BC%E3%83%B3%E3%82%B7%E3%83%A7%E3%83%83%E3%83%880005-11-0815.45.46.png" alt="スクリーンショット0005-11-0815.45.46.png"></p>
</li>
<li>
<p>「コンテンツ」から「HTML」をドラッグアンドドロップします。「コンテンツのプロパティ」を開いて以下にあるHTMLを追加します。</p>
</li>
</ol>
<pre><code class="language-html">&lt;table&gt;
  &lt;tr&gt;
    {{#each view_items_area}}
      {{#if is_row_start}}
  &lt;tr&gt;
    {{/if}}
    &lt;td style=&quot;padding: 3px;&quot;&gt;
      &lt;a href=&quot;{{ITEM_URL}}&quot;&gt;
        &lt;img width=&quot;100&quot; src=&quot;https://agitated-lamport-d75515.demo-karte.io/{{ITEM_IMAGE_URL}}&quot; alt={{NAME}} /&gt;
      &lt;/a&gt;
      &lt;p style=&quot;overflow-wrap: break-word;&quot;&gt;{{NAME}}&lt;/p&gt;
      &lt;h3 style=&quot;overflow-wrap: break-word;&quot;&gt;¥{{PRICE}}&lt;/h3&gt;
    &lt;/td&gt;
    {{#if is_row_end}}
  &lt;/tr&gt;
  {{/if}}
  {{/each}}
&lt;/table&gt;
</code></pre>
<p>こちらのコードには、以下の2つの「<a href="https://support.karte.io/post/5a3by6movo4cJfBC1Pa7I8">Hundlbars構文</a>」を使っています。</p>
<ul>
<li>each：繰り返し構文</li>
<li>if/else：条件文<br>
eachを使ってRECORD型の商品情報を展開することと、if/elseを使ってカラムの数に応じて折り返し表現を実現しています。</li>
</ul>
<ol start="3">
<li>
<p>埋め込み変数の指定からRECORD型のフィールドを紐付けします<br>
<img src="https://ik.imagekit.io/plaid/12edf2b1-c88e-4942-a7e2-bf07c83474eb/field_action.png" alt="field_action.png"></p>
</li>
<li>
<p>プレビューで確認してみましょう<br>
「プレビュー」をクリックして、想定通りのものが確認できれば完了です。<br>
<img src="https://ik.imagekit.io/plaid/e34a43fb-8036-461a-a806-487cd2bc11bc/preview.png" alt="preview.png" width="400px" /></p>
</li>
</ol>
<h1>おわりに</h1>
<p>お疲れ様でした。</p>
<p>今回はKARTE Messageを使って、商品詳細閲覧イベントデータをもとにユーザーが直近閲覧した商品をパーソナライズして配信する方法を紹介しました。</p>
<p>ユーザーのweb上の行動からメールのコンテンツをユーザーごとに変更する、というような複雑な施策をKARTEを使えば簡単に作成することができます。</p>
<p>ぜひ皆さんも、クエリコレクションから使ってみてください！</p>
<p>今後も、ソリューションブログで、マーケティング施策の幅が広がり結果的にエンドユーザーのCXを向上させられるように頑張ります。</p>
<hr>
<p>プレイドでは、世の中にインパクトを与える新しいソリューションを一緒につくる仲間を募集しています！<br>
ぜひ気軽にお問い合わせください。</p>
<p>↓ パートナー企業になりたい</p>
<ul>
<li><a href="https://ecosystem.plaid.co.jp/">CustomerData-Driven Solution を一緒に創りませんか？ | PLAID Ecosystem</a></li>
</ul>
<p>↓ PLAIDで働きたい</p>
<ul>
<li><a href="https://recruit.plaid.co.jp/requisitions/ecosystem-engineer">Ecosystem Engineer | 募集ポジション | 株式会社プレイド</a></li>
<li><a href="https://recruit.plaid.co.jp/requisitions/general-customer-engineer">General Customer Engineer | 募集ポジション | 株式会社プレイド</a></li>
</ul>


KARTE Messageでユーザーが直近閲覧した商品をパーソナライズして配信する方法をご紹介いたします。ユーザーが興味を持った商品を訴求することで、購買につながる可能性が高くなる施策内容となっています。

ユーザーがwebで閲覧した商品情報をメールに含めてKARTE Messageで配信してみた

<p>こんにちは、Customer Engineerの村上です！<br>
最近自転車通勤をしようかとe-bikeを物色中なので、お勧めがあれば教えてほしいです！</p>
<p>さて、KARTE Datahubでは様々なデータを管理することが出来ますが、データ監視の目的で「一定の基準を満たした時に通知を飛ばしたい」と思ったことはないでしょうか？</p>
<p>例えば次のようなケースです。</p>
<ul>
<li>一定期間のKARTEイベント数に急激な変化があった場合、イベント設定を見直したいから通知を取得したい</li>
</ul>
<p>今回は、KARTE DatahubにあるKARTEのイベントデータを集計して、閾値に達した場合にSlackへ通知を送る方法について紹介します。</p>
<p>以下のようなメッセージが、閾値を超えるイベント数が計測された時にSlackに届くようになります。<br>
<img src="https://ik.imagekit.io/plaid/682fc76d-8830-448e-be38-19389603519e/%E3%82%B9%E3%82%AF%E3%83%AA%E3%83%BC%E3%83%B3%E3%82%B7%E3%83%A7%E3%83%83%E3%83%882023-10-2710.09.48.png" alt="スクリーンショット2023-10-2710.09.48.png"></p>
<h1>全体像</h1>
<p>実現する処理の全体像は、次の通りです。<br>
DatahubのJobflowからクエリを実行して、実行結果をCraft Functionに渡して、Slack APIにリクエストして通知を送るというシンプルなものです。<br>
<img src="https://ik.imagekit.io/plaid/6d488dae-17d4-4271-8770-780113774d1f/PLAIDSolution%E6%A7%8B%E6%88%90%E5%9B%B3-KARTE%E3%81%AE%E3%82%A4%E3%83%98%E3%82%99%E3%83%B3%E3%83%88%E6%95%B0%E3%81%AE%E5%A4%89%E5%8C%96%E3%81%AB%E5%BF%9C%E3%81%97%E3%82%99%E3%81%A6Slack%E3%81%AB%E9%80%9A%E7%9F%A5%E3%82%92%E9%80%81%E3%82%8B.jpg" alt="PLAIDSolution構成図-KARTEのイベント数の変化に応じてSlackに通知を送る.jpg"></p>
<h1>実装手順</h1>
<p>実装の手順は次の通りです。</p>
<ol>
<li>Slack アプリを作成する</li>
<li>Slack アプリをチャンネルに追加する</li>
<li>Slack アプリの OAuth トークンを Craft Secret Manager に登録する</li>
<li>Slack通知をしたいデータを取得できるSQLをDatahubクエリで書く</li>
<li>Slack通知を行うCraft Functionsを作成する</li>
<li>SQLの結果をCraft Functionsに渡すJobflowを作成する</li>
</ol>
<p>順番に説明します。</p>
<p>まず、手順1〜3は以前に投稿した記事、<br>
「<a href="https://solution.plaid.co.jp/202307-hookv2-slack-integration">KARTE CraftでKARTEの接客ステータス変更時にSlack通知をする</a>」<br>
の同見出しの手順と全く同じです。こちらを実施した前提で手順4から説明します。<br>
（今回は API v2 アプリを使用しないため、以前に投稿した記事にある「3. API v2 アプリを作成する」の手順は実施しなくて大丈夫です。）</p>
<h2>4. Slack通知をしたいデータを取得できるSQLをDatahubクエリで書く</h2>
<p><a href="https://developers.karte.io/docs/execute-datahub-query">Datahubクエリ</a>を作成し、Slackに通知したい情報を集計します。</p>
<p>今回は、karte_eventデータテーブルで集計されるevent_name毎のレコード数が、前々日と前日比で閾値を超えるデータを抽出するためのクエリを1つ作成します。<br>
このクエリの結果がSlack通知の元となります。</p>
<p>SQLエディタ：</p>
<pre><code>WITH event_data AS (
  SELECT 
    * 
    , FORMAT_TIMESTAMP('%Y-%m-%d', Sync_date) AS date
  FROM {% karte_event param_period[0], param_period[1] %}
), events_yesterday AS (
  SELECT 
    user_id
    , sync_date
    , event_name
    , JSON_EXTRACT(values, &quot;$.view.access.uri.path&quot;) AS path
    , session_id
    , date
  FROM event_data
  WHERE date = FORMAT_TIMESTAMP('%Y-%m-%d', DATE_ADD(CURRENT_TIMESTAMP(), INTERVAL - 1 DAY))
), events_yesterday_cnt AS (
  SELECT
    MAX(date) AS date
    , event_name
    , COUNT(event_name) AS cnt
  FROM events_yesterday
  GROUP BY event_name
), events_day_before_yesterday AS (
  SELECT 
    user_id
    , sync_date
    , event_name
    , JSON_EXTRACT(values, &quot;$.view.access.uri.path&quot;) AS path
    , session_id
    , date
  FROM event_data
  WHERE date = FORMAT_TIMESTAMP('%Y-%m-%d', DATE_ADD(CURRENT_TIMESTAMP(), INTERVAL - 2 DAY))
), events_day_before_yesterday_cnt AS (
  SELECT
    MAX(date) AS date
    , event_name
    , COUNT(event_name) AS cnt
  FROM events_day_before_yesterday
  GROUP BY event_name
), compare_events_cnt_log AS (
  SELECT
    eyc.event_name
    , edbyc.cnt AS base_cnt
    , eyc.cnt AS new_cnt
    , ROUND(eyc.cnt / NULLIF(edbyc.cnt,0) * 100,2)  AS rate_of_change
    , eyc.cnt - edbyc.cnt AS comparison_cnt
  FROM events_yesterday_cnt AS eyc
  LEFT JOIN events_day_before_yesterday_cnt AS edbyc ON eyc.event_name = edbyc.event_name
  WHERE eyc.cnt - edbyc.cnt &gt; {{param_num}} OR eyc.cnt - edbyc.cnt  &lt; -{{param_num}}
    AND ROUND(eyc.cnt / NULLIF(edbyc.cnt,0) * 100,2) IS NOT NULL
)
SELECT
  *
FROM compare_events_cnt_log
ORDER BY rate_of_change DESC
</code></pre>
<p>パラメータエディタ：</p>
<pre><code>param_period:
  type: period
  label: 期間型パラメータ
  default:
    - 20220101
    - 20221110
  value: past 3 days
param_num:
  type: number
  label: 数値パラメータ
  default: 10000
  value: 10000
</code></pre>
<p>今回のクエリでは前日分と前々日分のデータ比較なので中間テーブルを使いませんでしたが、複数の施策で使い回す場合やより長期のデータを参照したい場合は中間テーブルを作ることでクエリリソース消費量の節約になります。</p>
<h2>5. Slack通知を行うCraft Functionsを作成する</h2>
<p>次に、実行したクエリ結果をSlackに通知するCraft Functionsを作ります。次のコードを利用して、Craft Functionsを新規作成します。</p>
<p><a href="https://github.com/plaidev/craft-codes/tree/a50bfa9bc51bad26c844343302d225a69d369ebc/craft-functions/event-notification-to-slack">craft-functions/event-notification-to-slack</a></p>
<p>実際に利用する際にはCraft コード内で利用している以下3つの変数を環境に合わせて修正してください。</p>
<ul>
<li>「KARTE_PROJECT_ID」は、KARTE の管理画面URLの project= 以降の部分（https://admin.karte.io/craft/functions?project=<code>XXXXXXXXXXXXXXXX</code>）</li>
<li>「SLACK_CHANNEL_ID」は、「1. Slack アプリを作成する」で控えておいたチャンネルID</li>
<li>「SLACK_TOKEN_SECRET」は、「3. Slack アプリの OAuth トークンを Craft Secret Manager に登録する」で作成したシークレット名</li>
</ul>
<p>また、サンプルコードにあるSlackのメッセージ内容は以下で定義しているものです。クエリの出力内容と合わせて、適宜通知したいメッセージに修正いただくことが可能です。</p>
<pre><code>// chat.postMessageのパラメータを設定
        const splitData = value.split(',');
        const eventname = splitData[0];
        const event_cnt_daybefore = splitData[1];
        const event_cnt_yesterday = splitData[2];
        const event_cnt_rate_of_change = splitData[3];

        let msg = `イベント数の急激な変化をキャッチしました。\n`;
            msg += `イベント名：${eventname}\n`;
            msg += `一昨日のイベント数：${event_cnt_daybefore}\n`;
            msg += `昨日のイベント数：${event_cnt_yesterday}\n`;
            msg += `イベントの増減率：${event_cnt_rate_of_change}%\n`;
            msg += `イベントURL： https://admin.karte.io/p/${KARTE_PROJECT_ID}/event_settings/each/${eventname}`;
</code></pre>
<p>現在の設定だと、以下のようなSlackメッセージが届きます。</p>
<pre><code>イベント数の急激な変化をキャッチしました。
イベント名：view_item
一昨日のイベント数：177
昨日のイベント数：327
イベントの増減率：184.75%
イベントURL： https://admin.karte.io/p/[project_id]/event_settings/each/view_item
</code></pre>
<h2>6. SQLの結果をCraft Functionsに渡すJobflowを作成する</h2>
<p>最後に、作成したSQLとCraft Functionsを繋ぐJobflowを作成します。Jobflowを下記の内容で新規作成してください。</p>
<ul>
<li>エクスポート元：作成したクエリ</li>
<li>エクスポート先：外部サービス</li>
<li>接続先：Craft</li>
<li>function名：作成したCraft Functions</li>
<li>行ごとにqueue をpublishする：チェックを入れる<br>
<img src="https://ik.imagekit.io/plaid/92bdc7a5-55fc-4616-a1ad-e27fbf5b1fe3/%E3%82%B9%E3%82%AF%E3%83%AA%E3%83%BC%E3%83%B3%E3%82%B7%E3%83%A7%E3%83%83%E3%83%882023-10-2710.13.43.png" alt="スクリーンショット2023-10-2710.13.43.png"></li>
</ul>
<p>また、イベント数の変化があった時に通知を受けられるように、日次でジョブ実行されるようにスケジュールを設定することをお勧めします。<br>
<img src="https://ik.imagekit.io/plaid/ea869499-c888-470a-8aaf-131e302ccb5e/%E3%82%B9%E3%82%AF%E3%83%AA%E3%83%BC%E3%83%B3%E3%82%B7%E3%83%A7%E3%83%83%E3%83%882023-10-2710.14.15.png" alt="スクリーンショット2023-10-2710.14.15.png"></p>
<p>注意点として、「4. Slack通知をしたいデータを取得できるSQLをDatahubクエリで書く」で作成したクエリはUTCで時刻の判定が行われます。<br>
よって、ジョブフローの実行時間はJST 9時以降に設定することをお勧めします。その場合、UTCベースで前々日と前日分のイベント数を比較した結果に基づいて通知が届きます。</p>
<h1>実際に動かしてみる</h1>
<p>実際に動作を確認してみましょう。<br>
「6. SQLの結果をCraft Functionsに渡すJobflowを作成する」で作成したジョブフローを手動実行すると、Slackの指定したチャネルに以下のようなメッセージが届きます。<br>
<img src="https://ik.imagekit.io/plaid/682fc76d-8830-448e-be38-19389603519e/%E3%82%B9%E3%82%AF%E3%83%AA%E3%83%BC%E3%83%B3%E3%82%B7%E3%83%A7%E3%83%83%E3%83%882023-10-2710.09.48.png" alt="スクリーンショット2023-10-2710.09.48.png"></p>
<h1>おわりに</h1>
<p>今回は「KARTEのイベント数の変化に応じてSlackに通知を送る」方法を紹介しました。<br>
他にも、特定のイベント（<code>_error</code>など）が発生した時にSlackに通知を送るなど、Datahubの情報をもとに必要なタイミングでSlackに通知を飛ばす様々な応用が可能です。</p>
<p>ぜひ皆さんも、作成してみてください！</p>
<hr>
<p>プレイドでは、世の中にインパクトを与える新しいソリューションを一緒につくる仲間を募集しています！<br>
ぜひ気軽にお問い合わせください。</p>
<p>↓ パートナー企業になりたい</p>
<ul>
<li><a href="https://ecosystem.plaid.co.jp/">CustomerData-Driven Solution を一緒に創りませんか？ | PLAID Ecosystem</a></li>
</ul>
<p>↓ PLAIDで働きたい</p>
<ul>
<li><a href="https://recruit.plaid.co.jp/requisitions/ecosystem-engineer">Ecosystem Engineer | 募集ポジション | 株式会社プレイド</a></li>
<li><a href="https://recruit.plaid.co.jp/requisitions/general-customer-engineer">General Customer Engineer | 募集ポジション | 株式会社プレイド</a></li>
</ul>


KARTE DatahubクエリでKARTEのイベント数をウォッチし、既定値を超える変化があった場合にSlack通知を送る方法を紹介します！

KARTEのイベント数の変化に応じてSlackに通知を送る

<p>こんにちは。エンジニアの矢澤です。今回はKARTE Craftの新機能である <strong>ファンクションのIPを固定する</strong> 機能 (固定IP機能) を紹介します。</p>
<p>KARTE CraftはKARTEと外部サービスをリアルタイムに連携できますが、サービスによっては <strong>送信元IP制限</strong> でアクセス元を制限している場合があります。これまでCraft FunctionsのIPアドレスは固定ではありませんでしたが、今回のアップデートにより、KARTEプロジェクトごとに払い出した固定のIPアドレスで通信ができるようになります。</p>
<p>この記事では固定IPアドレス機能の設定方法を紹介し、実際にIPアドレスが固定されていることを検証します。</p>
<h1>「ファンクションのIPアドレスを固定する」機能とは</h1>
<p>機能を試す前に、簡単に固定IP機能の概要を説明します。</p>
<h2>IPアドレスとは</h2>
<p>ネットワークに接続されている多くの端末（コンピュータやスマートフォンなど）は<strong>IPアドレス</strong>を使って他の端末やサービスに接続します。特に、インターネットに接続する際には <strong>グローバルIPアドレス</strong> と呼ばれるIPアドレスが割り当てられます。Craft Functionsも例外ではなく、インターネット上のサービスへの接続時にはグローバルIPアドレスを使って通信を行います。</p>
<h2>送信元IP制限と固定IP機能</h2>
<p>インターネット上のサービスがアクセス元を制限する方法には、ID/パスワードやアクセス用のトークンを使った認証など様々な方式があります。その中の一つに、上で説明したIPアドレスを使ってアクセス許可・拒否を行う <strong>送信元IP制限</strong> という方法があります。</p>
<p>インターネット上のサービスにおける送信元IP制限では、アクセス元のグローバルIPアドレスを許可リスト (もしくは拒否リスト) として保持しておき、リストに当てはまる (当てはまらない) グローバルIPアドレスからの接続のみを許可します。このようなシステムに接続するクライアントは、<strong>固定のグローバルIPアドレス</strong> を使って当該サービスに接続する必要があります。</p>
<p>冒頭で話した通り、KARTE Craftはこれまで <strong>外部接続時のIPアドレスが固定であることを保証していません</strong> でしたが、今回のアップデートで固定のグローバルIPアドレスが利用できるようになりました。これによって送信元IP制限がかけられたシステムにも接続できるようになりました。</p>
<p><img src="https://ik.imagekit.io/plaid/a4f11edf-eea0-4e62-913e-19dfda15b344/%E3%82%B9%E3%82%AF%E3%83%AA%E3%83%BC%E3%83%B3%E3%82%B7%E3%83%A7%E3%83%83%E3%83%882023-10-2514.22.39.png" alt="スクリーンショット2023-10-2514.22.39.png"></p>
<h1>設定してみる</h1>
<p>ここからは実際に固定IP機能を有効化し、実際にIPアドレスが固定されていることを確かめていきます。</p>
<p>操作手順はドキュメント（<a href="https://developers.karte.io/docs/static-ip-option">ファンクションのIPアドレスを固定する</a>）にも書いてありますので、興味のある方は併せてご確認ください。</p>
<h2>固定IP機能の有効化</h2>
<p>固定IP機能はKARTE CraftのEnterpriseプランから利用できます。利用の際にはプレイドの営業もしくはカスタマーサクセス担当者までご連絡ください。</p>
<h2>固定IPを利用する</h2>
<p>固定IP機能が有効化されると、KARTEプロジェクトに1つのIPアドレスが払い出されます。管理画面の [Craft] &gt; [設定] からIPアドレスが確認できます。</p>
<p><img src="https://ik.imagekit.io/plaid/0d907a7a-25df-47f4-95da-ba27e1d7afcc/%E3%82%B9%E3%82%AF%E3%83%AA%E3%83%BC%E3%83%B3%E3%82%B7%E3%83%A7%E3%83%83%E3%83%882023-10-2513.31.14.png" alt="スクリーンショット2023-10-2513.31.14.png"></p>
<p>ファンクションがこのIPアドレスを使うためには、ファンクションの設定で「ファンクションの外部IPアドレスを固定する」にチェックを入れて保存する必要があります。。</p>
<p><img src="https://ik.imagekit.io/plaid/7bb8d51e-2408-48d0-9d9f-e2b77864dc62/%E3%82%B9%E3%82%AF%E3%83%AA%E3%83%BC%E3%83%B3%E3%82%B7%E3%83%A7%E3%83%83%E3%83%882023-10-2513.35.16.png" alt="スクリーンショット2023-10-2513.35.16.png"></p>
<h2>ファンクションをデプロイして動作を検証する</h2>
<p>今回は検証用に <a href="https://httpbin.org/#/">httpbin.org</a> を使って送信元IPを確認します。httpbin.org はシンプルなHTTP APIを提供しており、その一つに送信元のグローバルIPアドレスを返却する <code>/ip</code> というエンドポイントがあります。今回はファンクションから <code>https://httpbin.org/ip</code> にリクエストを行い、その値をログとして出力することで、ファンクションが利用するグローバルIPアドレスを確認します。</p>
<p>実際のコードは次のとおりです：</p>
<pre><code class="language-js">const LOG_LEVEL = 'DEBUG';

export default async function (data, { MODULES }) {
  const { initLogger } = MODULES;
  const logger = initLogger({logLevel: LOG_LEVEL});

  const res = await fetch('https://httpbin.org/ip');
  const origin = await res.json();
  logger.log(origin);
}
</code></pre>
<p>このコードをファンクションとして保存します。</p>
<ul>
<li>modulesは <code>{}</code> としておきます。</li>
<li>ファンクション画面右上の「有効化」にチェックを入れておきます。</li>
<li>保存時に設定タブで「ファンクションの外部IPアドレスを固定する」にチェックを入れます。</li>
</ul>
<p>ファンクションの保存に成功したら、Craft EndpointもしくはCraft Schedulerで起動します。</p>
<ul>
<li><a href="https://developers.karte.io/docs/craft-scheduler">Craft Scheduler</a></li>
<li><a href="https://developers.karte.io/docs/craft-endpoint">Craft Endpoint</a></li>
</ul>
<p>ファンクションが起動すると次のようにログが記録されます。</p>
<p><img src="https://ik.imagekit.io/plaid/eaea79ee-0deb-4579-a7f3-994a80b8fcc6/%E3%82%B9%E3%82%AF%E3%83%AA%E3%83%BC%E3%83%B3%E3%82%B7%E3%83%A7%E3%83%83%E3%83%882023-10-2513.17.26.png" alt="スクリーンショット2023-10-2513.17.26.png"></p>
<p>ログの <code>origin</code> の値がファンクションの送信元IPです。ここではマスクしていますが、ファンクションの固定IP設定が有効であれば、プロジェクトに払い出された固定IPアドレスが表示されます。このようにして、固定IP設定によってIPアドレスが固定されることが確認できました。</p>
<h1>おわりに</h1>
<p>今回は新機能である固定IP機能を紹介しました。企業の内部システムはトークンベースのアクセス制限に加えて送信元IPによる制御を行っていることがあります。このアップデートにより、KARTEと企業システムとの連携の可能性がより広がりましたので、是非とも有効活用していただきたいと思います！</p>
<p>改めてですが、固定IP機能はKARTE CraftのEnterpriseプランからの提供となります。利用に際してはプレイドの営業・サクセスにお問い合わせください。</p>
<hr>
<p>プレイドでは、世の中にインパクトを与える新しいソリューションを一緒につくる仲間を募集しています！<br>
ぜひ気軽にお問い合わせください。</p>
<p>↓ パートナー企業になりたい</p>
<ul>
<li><a href="https://ecosystem.plaid.co.jp/">CustomerData-Driven Solution を一緒に創りませんか？ | PLAID Ecosystem</a></li>
</ul>
<p>↓ PLAIDで働きたい</p>
<ul>
<li><a href="https://recruit.plaid.co.jp/requisitions/ecosystem-engineer">Ecosystem Engineer | 募集ポジション | 株式会社プレイド</a></li>
<li><a href="https://recruit.plaid.co.jp/requisitions/general-customer-engineer">General Customer Engineer | 募集ポジション | 株式会社プレイド</a></li>
</ul>


Craft Functionsの外部リクエスト用IPアドレスを固定する機能（固定IP機能）をリリースしました。この記事では実際に設定を行い、ファンクションのIPアドレスが固定されることを確認します。

「Craft FunctionsのIPアドレスを固定する」機能をリリースしました！

<p>こんにちは、Customer Engineerの島本です！<br>
こないだ同僚に誘われて7月にオープンしたHUBHUB御徒街に行ってきたのですが、貸し切りでフィンランドサウナを楽しみつつ、電車の音を聞きながら整う空間が面白かったです！<br>
<img src="https://ik.imagekit.io/plaid/d39818f2-235b-4807-beb4-50e88d068f1a/IMG_1546.jpg" alt="IMG_1546.jpg"></p>
<p>さて、KARTE では<a href="https://support.karte.io/post/37WjobkPgizqvwhIY97dpH">ユーザーに対して表示回数やクリック回数に応じた接客サービスの配信停止条件</a>を設定できますが、ユーザーに対してではなく、「<strong>接客サービスに対して配信数やクリック数に応じた配信停止条件を指定したい</strong>」と思ったことはありませんか？</p>
<p>例えば次のようなケースです。</p>
<ul>
<li>KARTE の接客サービスを広告枠として活用していて、配信数やクリック数が一定の閾値に達したら停止したい</li>
<li>KARTE のアンケート接客でアンケート回答数が一定の閾値に達したら停止したい</li>
</ul>
<p>KARTE とDatahub を駆使して実現することも出来ますが、Datahub の特性上データの更新がバッチになるため、接客を停止するのに最短でも1時間のラグが出てしまいます。</p>
<p>しかし、<a href="https://solution.plaid.co.jp/202310-craft-counter">Craft Counter</a> を使うことで<strong>リアルタイム</strong>に接客を停止することを実現できます！<br>
今回はCraft Counter を使用して「配信数やクリック数に応じた接客サービスの自動停止」を実装する手順を紹介します。</p>
<h1>アウトプットイメージ</h1>
<p>接客サービス側のアクション設定で配信制御をしたい項目（配信数やクリック数）と上限回数を設定できるように実装しました。<br>
<img src="https://ik.imagekit.io/plaid/6b9d1026-afdd-42b9-8321-1a56a6fbe32f/%E3%82%B9%E3%82%AF%E3%83%AA%E3%83%BC%E3%83%B3%E3%82%B7%E3%83%A7%E3%83%83%E3%83%882023-10-1717.16.41.png" alt="スクリーンショット2023-10-1717.16.41.png"></p>
<h1>処理の流れ</h1>
<p>全体の処理の流れは、次の通りです。<br>
<img src="https://ik.imagekit.io/plaid/f18a3e31-4618-408e-bdf0-54b6d63a865b/Untitled-2023-07-28-0049.png" alt="Untitled-2023-07-28-0049.png"></p>
<p>接客サービス機能とCraft Functionsの連携では、次の2つの機能を利用します。</p>
<ul>
<li><a href="https://developers.karte.io/docs/craft-endpoint">Craft Endpoint トリガー</a>
<ul>
<li>Craft Functionを実行するためのHTTPエンドポイント</li>
</ul>
</li>
<li><a href="https://developers.karte.io/reference/post_v2beta-action-campaign-toggleenabled">Toggle campaign's enabled status API</a>
<ul>
<li>接客サービスの公開・非公開を制御するAPI</li>
</ul>
</li>
</ul>
<h1>実装手順</h1>
<p>実装の手順は次の通りです。</p>
<ol>
<li>API v2 アプリを作成する</li>
<li>API v2 アプリの アクセストークンを Craft Secret Manager に登録する</li>
<li>Craft Functionsを作成する</li>
<li>Craft Functionsのエンドポイントを作成する</li>
<li>Functionと連携する接客を作成する</li>
</ol>
<p>順番に見てみましょう。</p>
<h2>1. API v2 アプリを作成する</h2>
<p>まず、Toggle campaign's enabled status API を利用するためのAPI v2アプリを作成します。<br>
<img src="https://ik.imagekit.io/plaid/bfe2f6a8-b78c-4c95-ad91-db59ecc03a9b/image(5).png" alt="image(5).png"></p>
<ul>
<li>[ストア &gt; API v2設定] からアプリを新規作成</li>
<li>[アプリタイプ] を <code>token</code> に設定</li>
<li>必要なscopeを追加
<ul>
<li><code>beta.action.campaign.toggleEnabled</code>: API に必要</li>
</ul>
</li>
<li>アプリを保存し、一度だけ表示されるアクセストークンを控えておく</li>
</ul>
<p>「アプリタイプ」は後から変更できないため、誤って作成した場合は、アプリを再度作成し直してください。</p>
<h2>2. API v2 アプリの アクセストークンを Craft Secret Manager に登録する</h2>
<p>API v2 アプリのアクセストークンを Craft Secret Manager のシークレットとして登録します。それにより、秘匿すべきアクセストークンをファンクション上に直接記述する必要が無くなります。<br>
<img src="https://ik.imagekit.io/plaid/116765b1-4d21-4d74-8d3e-e5a4e4431e5b/image(6).png" alt="image(6).png"></p>
<ul>
<li>[Craft &gt; シークレット] からシークレットを新規作成</li>
<li>控えておいたアクセストークンを貼り付けて、適当な名前を付けて保存</li>
</ul>
<p>作成したシークレットの名前は、最後に作成するCraft Functions のファンクション中に記載します。</p>
<h2>3. Craft Functionsを作成する</h2>
<p>次に、接客サービスからのリクエストを受け付けるCraft FunctionsのFunctionを作成します。サンプルとなるソースコードは、GitHubで公開しています。<br>
<a href="https://github.com/plaidev/craft-codes/tree/main/craft-functions/stop-campaign-by-imp-click">craft-codes/craft-functions/stop-campaign-by-imp-click at main · plaidev/craft-codes</a></p>
<p>作成手順は次の通りです。</p>
<ul>
<li>[Craft &gt; ファンクション] からファンクションを新規作成</li>
<li>サンプルコードからコードやモジュールをコピー</li>
<li>Functionを有効化して保存</li>
</ul>
<p>サンプルコードでは次の機能が実装されています。</p>
<ul>
<li>接客サービスID毎の配信数 or クリック数をCraft Counter 上でincrement する</li>
<li>Craft Counter 上でincrement する際に上限値と比較し、上限値を超えていた場合にToggle campaign's enabled status API にリクエストを送信する</li>
</ul>
<p>increment する項目（配信数 or クリック数）と上限値については接客サービス側で設定するため、後ほど説明します。また、上記処理には数秒程度の時間を要するため、この実装方法では上限値に達した際に接客を即座に停止できないことに留意してください。</p>
<h2>4. Craft Functionsのエンドポイントを作成する</h2>
<p>Craft Functionsが作成できたら、接客側から実行出来るようにするためのエンドポイントを作成します。</p>
<p><img src="https://ik.imagekit.io/plaid/a1c8021e-4690-40ad-8e91-2efb5cad5176/image(7).png" alt="image(7).png"></p>
<ul>
<li>作成したファンクションの編集画面で [設定] タブを開く</li>
<li>[エンドポイント] 欄の [作成] ボタンを押す</li>
</ul>
<p>作成したエンドポイントのURLは接客サービス側の実装で利用するので手元に控えておきます。</p>
<h2>5. Functionと連携する接客を作成する</h2>
<p>最後に、配信数やクリック数に応じて自動停止したい接客サービスを実装します。細かい接客サービスの設定方法は割愛して、アクションのHTML/JavaScriptのサンプル実装を掲載します。</p>
<h3>アクションのJavaScript例</h3>
<p><strong>実装のポイント</strong></p>
<ul>
<li>配信を停止したい条件に合わせてCraft 側に接客サービスIDと上限値のデータを含めてリクエストを送信</li>
<li>クリック数に応じた配信停止を行いたい場合は、クリックしたタイミングでリクエストを送信する必要があるため、widget.method を使ってHTML とバインドするイベントハンドラを定義</li>
</ul>
<pre><code>// POSTリクエストを送信するためのデータ
var postData = {
    campaignId: &quot;#{campaign_id}&quot;, 
    limitNumber: #{limitNumber}
};

// FunctionsのエンドポイントURL
var endpointUrl = &quot;#{craft_endpoint}&quot;; 

// 条件分岐(クリックの場合)
widget.method(&quot;clicked&quot;, function(e){
    if( #{click} ){
        craftPost();
    }
});

// ウィジェットを表示
widget.show();

// 条件分岐（表示回数の場合）
if( #{impression} ){
    craftPost();
}

// POSTリクエスト処理関数
function craftPost() {
    fetch(endpointUrl, {
        method: &quot;POST&quot;,
        mode: &quot;cors&quot;,
        headers: {
            &quot;Content-Type&quot;: &quot;application/json&quot;, 
        },
        body: JSON.stringify(postData), 
    })
    .then(function(result) {
        if (!result.ok) {
            throw new Error(result);
        }
    })
    .catch(function(error) {
        // エラーハンドリング
        console.error(&quot;エラー:&quot;, error);
    });
}

</code></pre>
<h3>アクションのHTML例</h3>
<p><strong>実装のポイント</strong></p>
<ul>
<li>クリック数に応じた配信停止を行いたい場合は、先程widget.method で定義したイベントハンドラをkrt-on に指定</li>
</ul>
<pre><code>&lt;div class=&quot;banner-wrapper&quot;&gt;
    &lt;a krt-on:click=&quot;clicked&quot; href=&quot;#{href}&quot;&gt;
        &lt;img src=&quot;#{img}&quot; class=&quot;banner-image&quot;&gt;
    &lt;/a&gt;
&lt;/div&gt;
</code></pre>
<h3>アクションの静的変数の設定例</h3>
<p>JavaScript やHTML 内で変数を呼び出しているため、以下の通りに<a href="https://support.karte.io/post/3TPVVSzxiA6U3MYNRj25JJ">静的変数</a>を設定します。</p>
<p><img src="https://ik.imagekit.io/plaid/cd419c60-6de2-4831-8a89-910952467c20/%E3%82%B9%E3%82%AF%E3%83%AA%E3%83%BC%E3%83%B3%E3%82%B7%E3%83%A7%E3%83%83%E3%83%882023-10-170.27.46.png" alt="スクリーンショット2023-10-170.27.46.png"></p>
<p>以上で設定は完了です！</p>
<h1>実際に動かしてみる</h1>
<p>では、実際に動かしてみましょう！！！！<br>
今回は160×600のバナーを表示回数 10回で自動停止するように設定してみました。<br>
<img src="https://ik.imagekit.io/plaid/1c79eb83-f4d2-47d1-9a29-4e0faf1b6de0/%E3%82%B9%E3%82%AF%E3%83%AA%E3%83%BC%E3%83%B3%E3%82%B7%E3%83%A7%E3%83%83%E3%83%882023-10-171.02.11.png" alt="スクリーンショット2023-10-171.02.11.png"></p>
<p>Craft Functions のLog Level を DEBUG にすると、接客が配信される度に該当の接客サービスIDとincrement した数と指定した上限値を確認することができます。<br>
そして、increment した数が上限値に達して接客サービスが停止した際に表示される&quot;Campaign has been successfully stopped.&quot;というログを確認することが出来ました！</p>
<p><img src="https://ik.imagekit.io/plaid/ff31e4da-65d2-4be8-b782-20a514da4cb3/%E3%82%B9%E3%82%AF%E3%83%AA%E3%83%BC%E3%83%B3%E3%82%B7%E3%83%A7%E3%83%83%E3%83%882023-10-171.10.51.png" alt="スクリーンショット2023-10-171.10.51.png"></p>
<p>接客サービス側も確認してみると、該当接客が停止していますね！！！<br>
<img src="https://ik.imagekit.io/plaid/5400f362-f2a0-4071-baca-358a7a446a8c/%E3%82%B9%E3%82%AF%E3%83%AA%E3%83%BC%E3%83%B3%E3%82%B7%E3%83%A7%E3%83%83%E3%83%882023-10-171.11.52.png" alt="スクリーンショット2023-10-171.11.52.png"></p>
<h1>おわりに</h1>
<p>今回は「配信数やクリック数に応じた接客サービスの自動停止」をCraft Counterで実装する方法について紹介しました。</p>
<p>これまでKARTE はWeb 接客として活用いただくことが多かったのですが、冒頭お伝えした通り、この仕組みを活用することでKARTE を新たな広告サービスとして提供することもできるようになります。</p>
<p>さらに、KARTE で収集している1st Party Customer Data を活用することで、精度の高いターゲティングが可能となり、広告の効果的な配信が実現できるため、昨今注目されているリテールメディアも簡単に構築できるのです。</p>
<p>今までKARTE で蓄積してきたデータを新たなビジネスチャンスとして活用できるなんて可能性が広がりますね！</p>
<hr>
<p>プレイドでは、世の中にインパクトを与える新しいソリューションを一緒につくる仲間を募集しています！<br>
ぜひ気軽にお問い合わせください。</p>
<p>↓ パートナー企業になりたい</p>
<ul>
<li><a href="https://ecosystem.plaid.co.jp/">CustomerData-Driven Solution を一緒に創りませんか？ | PLAID Ecosystem</a></li>
</ul>
<p>↓ PLAIDで働きたい</p>
<ul>
<li><a href="https://recruit.plaid.co.jp/requisitions/ecosystem-engineer">Ecosystem Engineer | 募集ポジション | 株式会社プレイド</a></li>
<li><a href="https://recruit.plaid.co.jp/requisitions/general-customer-engineer">General Customer Engineer | 募集ポジション | 株式会社プレイド</a></li>
</ul>


Craft Counter を使った「配信数やクリック数に応じた接客サービスの自動停止」の方法について紹介します。

「配信数やクリック数に応じた接客サービスの自動停止」をCraft Counterで実装する

<p>こんにちは、Customer Engineerのgamiです！最近は、「 <a href="https://www.asken.jp/">あすけん</a> 」で食べたものを記録すると減量できるかという実験をしています。</p>
<p>さて、KARTEを利用している企業の方からよく実現方法を相談される施策として、 <strong>「クーポン在庫の順次払い出し」</strong> があります。外部のクーポンシステムからクーポンコードの在庫を予め出力しておき、クーポン取得条件を満たしたユーザーに対してWeb上で順番にクーポンコードを払い出していく、といった内容です。</p>
<p>この「クーポン在庫の順次払い出し」においてクリアすべき最も大きな課題は、 <strong>「同一クーポンコードを複数ユーザーに払い出さないようにする」</strong> という点です。素朴に実装すると、同時にアクセスした複数のユーザーに対して同じクーポンコードを払い出してしまうリスクがあります。それを回避するための制御を実現するには、KARTEの基本機能だけでは足りず、KARTE Craftによる実装が必要になります。</p>
<p>今回は、先日リリースされた <a href="https://solution.plaid.co.jp/202310-craft-counter">Craft Counter</a> の特性をうまく利用して「クーポン在庫を順次払い出すAPI」を実装する方法について紹介します。</p>
<h1>アウトプットイメージ</h1>
<p>最終的なアウトプットイメージは、次の通りです。シンプルな例として、ポップアップのボタンをクリックしたユーザーにユニークなクーポンコードを払い出す、という接客サービスを実装します。</p>
<p><img src="https://ik.imagekit.io/plaid/d2e71351-c0ac-4716-8d03-81d92a207ad2/%E3%82%B9%E3%82%AF%E3%83%AA%E3%83%BC%E3%83%B3%E3%82%B7%E3%83%A7%E3%83%83%E3%83%882023-10-1620.03.57.png" alt="スクリーンショット2023-10-1620.03.57.png"></p>
<p>接客サービスの裏側では、Craft Functions + Craft Counter + Craft kvsを駆使して「クーポン在庫を順次払い出すAPI」を実装します。構成図は次の通りです。</p>
<p><img src="https://ik.imagekit.io/plaid/7ce93748-635c-4658-b35e-c926af7ef107/%E3%82%B9%E3%82%AF%E3%83%AA%E3%83%BC%E3%83%B3%E3%82%B7%E3%83%A7%E3%83%83%E3%83%882023-10-1620.08.54.png" alt="スクリーンショット2023-10-1620.08.54.png"></p>
<h1>API設計</h1>
<p>今回は、Craft Functionsを使って接客サービスのJavaScriptから利用できる「クーポン在庫を順次払い出すAPI」を実装する形になります。リクエストとレスポンスの内容は、次のように設計しました。</p>
<p><strong>リクエスト</strong></p>
<table>
<thead>
<tr>
<th>パラメータ</th>
<th>サンプル値</th>
<th>説明</th>
</tr>
</thead>
<tbody>
<tr>
<td>user_id</td>
<td><code>&quot;user001&quot;</code></td>
<td>配信先user_id。同一ユーザーによる不正取得防止に利用</td>
</tr>
<tr>
<td>coupon_group_id</td>
<td><code>&quot;shop001&quot;</code></td>
<td>クーポン群を区別するID。クーポン在庫を管理する単位毎に任意のIDを設定する</td>
</tr>
</tbody>
</table>
<p><strong>レスポンス</strong></p>
<table>
<thead>
<tr>
<th>パラメータ</th>
<th>サンプル値</th>
<th>説明</th>
</tr>
</thead>
<tbody>
<tr>
<td>coupon_code</td>
<td><code>&quot;dummycouponcode42&quot;</code></td>
<td>取得したクーポンコード</td>
</tr>
<tr>
<td>error</td>
<td>-</td>
<td>エラー発生時はエラー内容を返す</td>
</tr>
</tbody>
</table>
<h1>データ設計</h1>
<p>今回の実装サンプルでは、Craft kvsとCraft Counterでそれぞれ次のようなデータを管理します。</p>
<p><strong>Craft kvs</strong></p>
<ul>
<li><strong>クーポンコード</strong>
<ul>
<li>実際にユーザーに表示するクーポンコード。事前に別Functionを通じて格納しておく</li>
<li>key
<ul>
<li><code>${COUPON_CODE_PREFIX}_${couponGroupId}_${couponIndex}</code></li>
<li>（※サンプルコードではhotspotを避けるためにhash値をprefixに付与）</li>
</ul>
</li>
<li>value（例）
<ul>
<li><code>{&quot;key&quot;:&quot;coupon-code_shop001_1&quot;, &quot;coupon_code&quot;:&quot;xxxxx&quot;}</code></li>
</ul>
</li>
</ul>
</li>
<li><strong>ユーザー毎のクーポンコード前回取得日時</strong>
<ul>
<li>簡易的な不正取得検知に利用（後述）</li>
<li>key
<ul>
<li><code>${COUPON_USER_STATUS_PREFIX}_${couponGroupId}_${hashedUserId}</code></li>
<li>（※サンプルコードではhotspotを避けるためにhash値をprefixに付与）</li>
</ul>
</li>
<li>value（例）
<ul>
<li><code>{ coupon_acquisition_date: &quot;2023-10-17T00:00:00Z&quot; }</code></li>
</ul>
</li>
</ul>
</li>
</ul>
<p><strong>Craft Counter</strong></p>
<ul>
<li><strong>現在払い出し済みの通し番号</strong>
<ul>
<li>現在何番目のクーポンコードまで払い出しているかを管理</li>
<li>key
<ul>
<li><code>${COUPON_INDEX_PREFIX}_${couponGroupId}</code></li>
</ul>
</li>
</ul>
</li>
</ul>
<p>さて、クーポンコードを順次上から払い出すためには、事前にクーポンコードに通し番号を振っておき、整理券的にそれをユーザーに払い出していくことになります。この「リクエストに応じて1から順に数字を出力する」という用途は、まさにCraft Counterが得意とするところです。</p>
<p><a href="https://solution.plaid.co.jp/202310-craft-counter">先日のCraft Counterの紹介記事</a> で説明した通り、Craft Counterには次の特徴があります。</p>
<ul>
<li>特徴1: valueにはnumber 型の整数値しか格納できない</li>
<li>特徴2: 秒間数十回以上のカウントアップ・ダウンリクエストに対応可能</li>
<li>特徴3: increment処理がアトミックに行われる</li>
</ul>
<p>今回のユースケースでは、まず特徴2によって同時に多数のクーポンコード取得リクエストが来た場合でも問題なく処理を捌くことができます。また、特徴3にある「increment処理がアトミックに行われる」という性質により、冒頭に書いた「同一クーポンコードを複数ユーザーに払い出さないようにする」という課題を簡単にクリアすることができます。詳細はCraft Counterの紹介記事をご覧ください。</p>
<h1>手順</h1>
<p>「クーポン在庫を順次払い出すAPI」を実装する手順は次の通りです。</p>
<ol start="0">
<li>Craft kvsにクーポンコード在庫を格納しておく</li>
<li>クーポン払い出し用のCraft Functionsを作成する</li>
<li>Craft Functionsのエンドポイントを作成する</li>
<li>クーポンコード取得用接客サービスを作成する</li>
</ol>
<p>順番に説明します。</p>
<h2>0. Craft kvsにクーポンコード在庫を格納しておく</h2>
<p>すでに構成図で示したように、まずは準備としてクーポンコードの在庫をCraft kvsに格納しておく必要があります。</p>
<p><img src="https://ik.imagekit.io/plaid/7ce93748-635c-4658-b35e-c926af7ef107/%E3%82%B9%E3%82%AF%E3%83%AA%E3%83%BC%E3%83%B3%E3%82%B7%E3%83%A7%E3%83%83%E3%83%882023-10-1620.08.54.png" alt="スクリーンショット2023-10-1620.08.54.png"></p>
<p>一般的に、Craft kvsにまとまったデータを格納する方法は次の通りです。</p>
<ul>
<li>格納したいデータをDatahubデータセットにアップロードする</li>
<li>Craft kvsに入稿したい形式に合わせて、対象データを抽出するためのDatahubクエリを作成する</li>
<li>Datahubジョブフローから呼び出してCraft kvsを更新するためのCraft Functionsを作成する</li>
<li>作成したDatahubクエリの結果をそのFunctionに連携するためのDatahubジョブフローを作成し、実行する</li>
</ul>
<p>詳細の手順やCraft kvs更新用のFunction実装については、下記の記事をご覧ください。</p>
<p><a href="https://solution.plaid.co.jp/202310-datahub-to-kvs">Datahubクエリの結果をCraft kvsに格納してみた</a></p>
<p>なお今回想定されているデータ形式は次の通りです。</p>
<table>
<thead>
<tr>
<th>key</th>
<th>value</th>
</tr>
</thead>
<tbody>
<tr>
<td>xxxx_coupon-code_shop001_1</td>
<td><code>{&quot;key&quot;:&quot;coupon-code_shop001_1&quot;, &quot;coupon_code&quot;:&quot;xxxxx&quot;}</code></td>
</tr>
<tr>
<td>yyyy_coupon-code_shop001_2</td>
<td><code>{&quot;key&quot;:&quot;coupon-code_shop001_2&quot;, &quot;coupon_code&quot;:&quot;yyyyy&quot;}</code></td>
</tr>
<tr>
<td>zzzz_coupon-code_shop001_3</td>
<td><code>{&quot;key&quot;:&quot;coupon-code_shop001_3&quot;, &quot;coupon_code&quot;:&quot;zzzzz&quot;}</code></td>
</tr>
</tbody>
</table>
<p>※xxxx,yyyy,zzzzはkvsのhotspotを避けるためにkeyに付与するhash値</p>
<p>検証のためのダミーデータが欲しい場合は、次のようなDatahubクエリを利用するのが便利です。</p>
<pre><code class="language-sql">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
</code></pre>
<p>なお、最終的にkvsに格納される際のkeyの形式については、前項の「データ設計」の「クーポンコード」で記載した形式に合わせる必要があります。特に今回はサンプルコードではmurmurhashを使ってkeyをhash化してprefixに付与することで、kvsのパフォーマンスが下がらないようにしています。「Datahubクエリの結果をCraft kvsに格納してみた」で提供されるテンプレートでkvsを更新する場合、Craft Functionsの <code>APPEND_HASH_PREFIX</code> という変数をtrueにして利用すると自動でhash prefixが付与されるようになります。</p>
<p>Datahubジョブフローを実行してCraft kvsにクーポンコード在庫を格納できたら、事前準備はOKです。</p>
<h2>1. クーポン払い出し用のCraft Functionsを作成する</h2>
<p>まずは接客サービスからのリクエストを受け付けるCraft FunctionsのFunctionを作成します。サンプルとなるソースコードは、GitHubで公開しています。</p>
<p><a href="https://github.com/plaidev/craft-codes/tree/main/craft-functions/coupon-dispenser">craft-codes/craft-functions/coupon-dispenser at main · plaidev/craft-codes</a></p>
<p>作成手順は次の通りです。</p>
<ul>
<li>[Craft &gt; ファンクション] からファンクションを新規作成</li>
<li>サンプルコードからコードやモジュールをコピー</li>
<li>Functionを有効化して保存</li>
</ul>
<p>なお、最近リリースされたファンクション一覧画面の <strong>「テンプレートから作成」</strong> を選んで検索することで、管理画面上から上記と同じサンプルコードを簡単に利用することもできます。便利ですね！</p>
<p>サンプルコードでは次の機能が実装されています。</p>
<ul>
<li>リクエストbodyから <code>coupon_group_id</code> や <code>user_id</code> を取り出す</li>
<li>変数で設定された時間間隔よりも短い頻度で対象のクーポンを取得しようとしている <code>user_id</code> の場合、不正取得としてエラーを返却する</li>
<li>対象のクーポンについて、Craft Counterで管理された「現在払い出し済みの通し番号」をincrementし、increment後の通し番号を取得する</li>
<li>取得した通し番号に対応するクーポンコードをCraft kvsから取得する</li>
<li>取得したクーポンコードをレスポンスする</li>
</ul>
<p>ここで注意が必要なのは、クーポンコードの不正取得対策です。サンプルコードでは簡易的に「短い間隔で何度もクーポン取得しようとしているuser_idはエラーにする」という対策を実装しています。しかし、仮にCraft FunctionsのエンドポイントURLが悪意のあるユーザーに特定された場合にuser_idをランダムに生成してエンドポイントにリクエストを送ることでクーポンコードを複数取得できてしまうという問題があります。 <strong>実際にこのサンプルコードを利用する場合は、サイト側で払い出される独自の認証用tokenを使ったユーザー認証の仕組みを追加で組み込むか、実際にクーポンコードを利用するアプリケーション側で不正利用対策がされているか、いずれかの対応を推奨しています。</strong></p>
<h2>2. Craft Functionsのエンドポイントを作成する</h2>
<p>Craft Functionsが作成できたら、アンケート接客で実行出来るようにするためのエンドポイントを作成します。</p>
<ul>
<li>作成したファンクションの編集画面で [設定] タブを開く</li>
<li>[エンドポイント] 欄の [作成] ボタンを押す</li>
</ul>
<p>作成したエンドポイントのURLは接客サービス側の実装で利用するので手元に控えておきます。</p>
<h2>3. クーポンコード取得用接客サービスを作成する</h2>
<p>最後に、上記で作成した「クーポン在庫を順次払い出すAPI」を利用する側の実装を行います。今回はKARTEで配信した接客サービスのJavaScriptを介して、エンドユーザーのブラウザから直接リクエストを送信してみましょう。細かい接客サービスの設定方法は割愛して、アクションのJavaScriptのサンプル実装を掲載します。</p>
<p><img src="https://ik.imagekit.io/plaid/d2e71351-c0ac-4716-8d03-81d92a207ad2/%E3%82%B9%E3%82%AF%E3%83%AA%E3%83%BC%E3%83%B3%E3%82%B7%E3%83%A7%E3%83%83%E3%83%882023-10-1620.03.57.png" alt="スクリーンショット2023-10-1620.03.57.png"></p>
<h3>クーポンコード取得用アクションのJavaScript例</h3>
<ul>
<li>実装内容
<ul>
<li>ユーザーがボタンを押したらCraftエンドポイントにリクエストを送信し、 <code>isLoading</code> を <code>true</code> にする</li>
<li>レスポンスが返ってきたら、取得できたクーポンコードを動的変数に格納し、 <code>isLoading</code> を <code>false</code> にした上でステートを1から2に切り替える</li>
</ul>
</li>
</ul>
<pre><code class="language-js">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: &quot;#{user_id}&quot;,
        coupon_group_id: COUPON_GROUP_ID
    };
    fetch(
        CRAFT_ENDPOINT_URL,
        {
            method: 'POST',
            headers: {
              &quot;Content-Type&quot;: &quot;application/json&quot;,
            },
            body: JSON.stringify(payload),
        }
    )
    .then(function(response) {
        return response.json();
    })
    .then(function(item) {
        cb(item);
    })
    .catch(function(err) {
        cb(null, err);
    })
}
</code></pre>
<p>対応するHTML/CSS側では、次の実装が必要となります。実装内容は簡単なので、サンプルコードは割愛します。</p>
<ul>
<li><code>isLoading</code> が <code>true</code> の場合のみローディング時のUIが表示されるようにする</li>
<li>リクエスト完了後に表示されるステート2で <code>coupon_code</code> の値を表示する</li>
</ul>
<h1>実際に動かしてみる</h1>
<p>実際に接客サービスを配信して動作を確認してみましょう。問題なく実装できていれば、次のようにボタン押下後に異なるクーポンコードが順番に表示されるはずです。</p>
<p><img src="https://ik.imagekit.io/plaid/d2e71351-c0ac-4716-8d03-81d92a207ad2/%E3%82%B9%E3%82%AF%E3%83%AA%E3%83%BC%E3%83%B3%E3%82%B7%E3%83%A7%E3%83%83%E3%83%882023-10-1620.03.57.png" alt="スクリーンショット2023-10-1620.03.57.png"></p>
<h1>おわりに</h1>
<p>今回はCraft kvsとCraft Counterをうまく組み合わせて「クーポン在庫順次払い出し施策」を実装する方法について紹介しました。</p>
<p>ちなみに今回の施策をCraft Counterを使わずCraft kvsだけで実装することも可能です。しかし、前述したCraft Counterの特徴により、 <strong>クーポンコードの通し番号を順次漏れなくダブり無く払い出すという用途にはCraft Counterを利用した方がシンプルに実装できます。</strong></p>
<p>施策内容としても、特定の行動を取ってくれたユーザーに対して直接的なリワードを提供できるというのは強力です。クーポンコードの不正取得には十分に対策をした上で、ぜひ活用してみてください！</p>
<hr>
<p>プレイドでは、世の中にインパクトを与える新しいソリューションを一緒につくる仲間を募集しています！<br>
ぜひ気軽にお問い合わせください。</p>
<p>↓ パートナー企業になりたい</p>
<ul>
<li><a href="https://ecosystem.plaid.co.jp/">CustomerData-Driven Solution を一緒に創りませんか？ | PLAID Ecosystem</a></li>
</ul>
<p>↓ PLAIDで働きたい</p>
<ul>
<li><a href="https://recruit.plaid.co.jp/requisitions/ecosystem-engineer">Ecosystem Engineer | 募集ポジション | 株式会社プレイド</a></li>
<li><a href="https://recruit.plaid.co.jp/requisitions/general-customer-engineer">General Customer Engineer | 募集ポジション | 株式会社プレイド</a></li>
</ul>


KARTEで「クーポン在庫の順次払い出し」施策を実現する方法について紹介します。KARTE Craft側は、先日リリースされたCraft Counterの特性をうまく利用してシンプルに実装することができます。

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

<p>こんにちは、Customer Engineerの道畑です！最近は「雨と君と」という漫画のたぬき(犬)にドはまりしています！ハマりすぎて自宅のデスクがたぬき(犬)の人形だらけです(笑)。</p>
<p>さて、今回はDatahubで実行したクエリの実行結果をCraft Key-Value Store (Craft KVS)に格納してみました。</p>
<p>Craft Functionsを使ってユーザー固有の接客を実装したいとき、事前に接客情報をCraft KVSに登録しておく必要があります。例えば、ユーザーに固有のクーポンを払い出したいときなどです。初期導入時のコストとハードルを少しでも下げるために、カラム名を変更するだけで使える汎用的なCraft Functionsを作成しました。カラム名を変更するだけで実行できるようにしたので、是非コピペして試してみてください！</p>
<h1>全体像</h1>
<p>実現する処理の全体像は、次の通りです。<br>
DatahubのJobflowからクエリを実行して、実行結果をCraft Functionに渡して、それをCraft KVSに格納するというとてもシンプルなものです。<br>
<img src="https://ik.imagekit.io/plaid/520c53ab-40d2-4ac3-b265-94e3aa45c176/%E6%A7%8B%E6%88%90%E5%9B%B3.jpg" alt="構成図.jpg"></p>
<h1>実装手順</h1>
<p>実装の手順は次の通りです。</p>
<ol>
<li>Craft KVSに格納したいデータを取得できるSQLを書く</li>
<li>Craft KVSに格納するCraft Functionsを作る</li>
<li>SQLの結果をCraft Functionsに渡すJobflowを作成する</li>
</ol>
<p>順番に説明します。</p>
<h2>1. Craft KVSに格納したいデータを取得できるSQLを書く</h2>
<p>まずはSQLを作成します。「Datahub &gt; クエリ &gt; 作成 &gt; クエリを作成」から下記のようにクエリを作成してください。</p>
<pre><code>SELECT
  coupon_id,
  already_used,
  user_id
FROM
  `prd-karte-per-client.xxxx_table名`
</code></pre>
<p>今回はクーポン情報を管理しているテーブルを丸ごと抽出するSQLをテスト用に用意しました。このテーブルは「coupon_id」が一意キーとなるようにテーブルが作られています。「coupon_id」はCraft KVSでもキーになるように後述のサンプルコードを作成しています。一番最初のSELECT項目がCraft KVSのキーになることをご注意ください。例えば、user_idをCraft KVSのキーにしたい場合は次の様にSQLを作成します。</p>
<p>例)user_idをCraft KVSのキーにしたい場合のSQL</p>
<pre><code>SELECT
  user_id,
  already_used,
  coupon_id
FROM
  `prd-karte-per-client.xxxx_table名`
</code></pre>
<h2>2. Craft kvsに格納するCraft Functionsを作る</h2>
<p>次に、実行したクエリ結果をCraft KVSに格納するCraft Functionsを作ります。次のコードを利用して、Craft Functionsを新規作成します。</p>
<p><a href="https://github.com/plaidev/craft-codes/tree/main/craft-functions/datahub-to-kvs">craft-codes/craft-functions/datahub-to-kvs at main · plaidev/craft-codes</a></p>
<p>実際に利用する際には以下の2つに気をつけてください。</p>
<ol>
<li>「HEADER_COLUMNS」の部分は、SQLのカラムに合わせて修正してください。</li>
<li>「MINUTES_TO_EXPIRE 」はCraft KVSにデータを保存する期間を保持しています。必要に応じて変更してください。<a href="https://developers.karte.io/docs/craft-key-value-store#write">詳しくはこちらをご確認ください。</a></li>
</ol>
<p>「modules」は次のキャプチャの様に空欄でOKです。</p>
<p><img src="https://ik.imagekit.io/plaid/a7b2ab6a-7067-4e25-85bd-ebf52bdde7a7/%E3%82%B9%E3%82%AF%E3%83%AA%E3%83%BC%E3%83%B3%E3%82%B7%E3%83%A7%E3%83%83%E3%83%882023-09-2612.05.18.png" alt="スクリーンショット2023-09-2612.05.18.png"></p>
<p>Datahubからデータが渡された想定でこちらのCraft Functionsを実行すると、下記のようにCraft KVSに格納されます。「Key」に該当レコードの1つ目のカラム情報が入り、「Value」に「{カラム名：レコード情報}」がカンマ区切りで格納されます。</p>
<h6>テーブル情報</h6>
<table>
<thead>
<tr>
<th>coupon_id</th>
<th>already_used</th>
<th>user_id</th>
</tr>
</thead>
<tbody>
<tr>
<td>coupon_id01</td>
<td>FALSE</td>
<td>U-001</td>
</tr>
<tr>
<td>coupon_id02</td>
<td>FALSE</td>
<td>U-002</td>
</tr>
<tr>
<td>coupon_id03</td>
<td>FALSE</td>
<td>U-003</td>
</tr>
<tr>
<td>coupon_id04</td>
<td>FALSE</td>
<td>U-004</td>
</tr>
</tbody>
</table>
<h6>Craft KVS格納イメージ</h6>
<table>
<thead>
<tr>
<th>Key</th>
<th>Value</th>
</tr>
</thead>
<tbody>
<tr>
<td>coupon_id01</td>
<td>{&quot;coupon_id&quot;:&quot;coupon_id01&quot;,&quot;already_used&quot;:&quot;false&quot;,&quot;user_id&quot;:&quot;U-001&quot;}</td>
</tr>
<tr>
<td>coupon_id02</td>
<td>{&quot;coupon_id&quot;:&quot;coupon_id02&quot;,&quot;already_used&quot;:&quot;false&quot;,&quot;user_id&quot;:&quot;U-002&quot;}</td>
</tr>
<tr>
<td>coupon_id03</td>
<td>{&quot;coupon_id&quot;:&quot;coupon_id03&quot;,&quot;already_used&quot;:&quot;false&quot;,&quot;user_id&quot;:&quot;U-003&quot;}</td>
</tr>
<tr>
<td>coupon_id04</td>
<td>{&quot;coupon_id&quot;:&quot;coupon_id04&quot;,&quot;already_used&quot;:&quot;false&quot;,&quot;user_id&quot;:&quot;U-004&quot;}</td>
</tr>
</tbody>
</table>
<h2>3. SQLの結果をCraft Functionsに渡すJobflowを作成する</h2>
<p>最後に、作成したSQLとCraft Functionsを繋ぐJobflowを作成します。Jobflowを下記の内容で新規作成してください。</p>
<ul>
<li>エクスポート元：作成したクエリ</li>
<li>エクスポート先：外部サービス</li>
<li>接続先：Craft</li>
<li>function名：作成したCraft Functions</li>
<li>行ごとにqueue をpublishする：チェックを入れる</li>
</ul>
<p>「行ごとにqueue をpublishする」のチェックを忘れると、今回作成したCraft Functionsでは正しく動作しないので気をつけてください。</p>
<p><img src="https://ik.imagekit.io/plaid/5ad2b621-10ab-4d66-89f9-a0bf63f75347/%E3%82%B9%E3%82%AF%E3%83%AA%E3%83%BC%E3%83%B3%E3%82%B7%E3%83%A7%E3%83%83%E3%83%882023-09-2612.25.32.png" alt="スクリーンショット2023-09-2612.25.32.png"></p>
<p>このJobflowを実行するとSQLの実行結果をCraft FunctionsでCraft KVSに格納できます。<br>
<img src="https://ik.imagekit.io/plaid/ea854668-0d07-4499-bb53-85379ea22e6d/%E3%82%B9%E3%82%AF%E3%83%AA%E3%83%BC%E3%83%B3%E3%82%B7%E3%83%A7%E3%83%83%E3%83%882023-09-2613.06.08.png" alt="スクリーンショット2023-09-2613.06.08.png"></p>
<h1>おわりに</h1>
<p>今回はDatahubクエリの結果をCraft KVSに格納する方法をご紹介しました。Craft KVSにはCraft Functionsからしかアクセスできないという制約がありますが、今回のサンプルコードを使えばDatahubクエリの結果をジョブフローの設定だけで簡単にCraft KVSにエクスポートできます。Craft FunctionsからDatahubのデータを参照できるに近しい動きができるようになるので、ぜひ皆さん使ってみてください！</p>
<hr>
<p>プレイドでは、世の中にインパクトを与える新しいソリューションを一緒につくる仲間を募集しています！<br>
ぜひ気軽にお問い合わせください。</p>
<p>↓ パートナー企業になりたい</p>
<ul>
<li><a href="https://ecosystem.plaid.co.jp/">CustomerData-Driven Solution を一緒に創りませんか？ | PLAID Ecosystem</a></li>
</ul>
<p>↓ PLAIDで働きたい</p>
<ul>
<li><a href="https://recruit.plaid.co.jp/requisitions/ecosystem-engineer">Ecosystem Engineer | 募集ポジション | 株式会社プレイド</a></li>
<li><a href="https://recruit.plaid.co.jp/requisitions/general-customer-engineer">General Customer Engineer | 募集ポジション | 株式会社プレイド</a></li>
</ul>


Datahubで実行したクエリ結果をCraft kvsに格納する方法をご紹介します！