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

<html><head></head><body>こんにちは、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" target="_blank" rel="noreferrer">『容疑者Xの献身』</a>を読みました。とても良かったので、Netflixで映画まで見てしまいました。
さて、KARTEでは「いま何人がこの商品を見ています」のようにアイテム別の閲覧人数をWebサイト上に簡単に表示できる機能があります。具体的には、接客サービスのアクションで <a href="https://developers.karte.io/reference/static-variables" target="_blank" rel="noreferrer">page_user_count</a> という特別な静的変数を使うことで配信先ページの閲覧人数を参照できます。
<img src="https://ik.imagekit.io/plaid/b2cbf1cb-ed8b-4fe7-8b0c-dbd72b1ab3e0/page_user_count.png" alt="page_user_count.png">
一方で、この <code>page_user_count</code> 変数で取得できる値の計算ロジックはKARTE全体で固定であり、カスタマイズができません。たとえば次のような難点があります。
<ul>
<li>「直近何分間の閲覧を対象にするか？」を自由に設定できない</li>
<li>ページ閲覧しかカウントできず、たとえば「何人が購入しました」といったカウントはできない</li>
<li>WebとAppで閲覧人数を合算できない</li>
</ul>
KARTE Datahubとアクションテーブルを利用すればこうしたカスタマイズ要望にも対応できますが、今度はデータが最大でも毎時更新になるためリアルタイム性が損なわれてしまいます。
そこで今回は、KARTE Craftを使ってこの「いま何人がこの商品を見ています」のリアルタイム集計ロジックを独自実装する方法について紹介します。
<h1 id="アウトプットイメージ">アウトプットイメージ</h1>
最終的なアウトプットイメージは次の通りです。
<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">
構成図は次の通り。Craft側のデータベースはCraft Counterを使います。 
<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">
<h1 id="API設計">API設計</h1>
今回は、Craft Functionsを使って接客サービスのJavaScriptからcallできる「閲覧人数取得API」を実装する形になります。1リクエストで閲覧人数のincrementとgetを実現します。
リクエストとレスポンスの内容は、次のように設計しました。
リクエスト
<div class="TableScroll"><table>
<thead>
<tr>
<th>パラメータ</th>
<th>サンプル値</th>
<th>説明</th>
</tr>
</thead>
<tbody>
<tr>
<td>itemId</td>
<td><code>"011"</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></div>
レスポンス
<div class="TableScroll"><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></div>
<h1 id="手順">手順</h1>
設定手順は次の通りです。
<ol>
<li>Craft Functionsを作成する</li>
<li>Craft Functionsのエンドポイントを作成する</li>
<li>Functionと連携する接客サービスを作成する</li>
</ol>
順番に説明します。
<h2 id="1. Craft Functionsを作成する">1. Craft Functionsを作成する</h2>
まずは接客サービスからのリクエストを受け付けるCraft FunctionsのFunctionを作成します。サンプルとなるソースコードは、Craft FunctionsのテンプレートとしてGitHubで公開しています。
<a href="https://github.com/plaidev/craft-codes/tree/main/craft-functions/uu-per-item-counter" target="_blank" rel="noreferrer">craft-codes/craft-functions/uu-per-item-counter at main · plaidev/craft-codes</a>
作成手順は次の通りです。
<ul>
<li>[Craft &gt; ファンクション &gt; 作成 &gt; テンプレートから作成] を選択</li>
<li><code>「いま何人がこの商品を見ています」施策をKARTE Craftで独自実装する</code> というテンプレートを検索し「取得」ボタンをクリック</li>
<li>「反映」ボタンをクリック</li>
<li>Functionを有効化して保存</li>
</ul>
サンプルコードの実装の特徴は次の通りです。
<ul>
<li><code>HOW_MANY_MINUTES_AGO</code> という定数で「直近何分間の閲覧を対象にするか」を自由に設定できる</li>
<li>1分間のtimewindow毎に閲覧UU数をCraft Counter上でカウントし、対象期間のレコード群を取得して合計値を返す</li>
</ul>
Craft Counter側の設計について補足します。まずCraft Counterのkeyは次のような形式になっています。
<ul>
<li><code>${COUNTER_KEY_PREFIX}_${timewindow}_${itemId}</code></li>
</ul>
<div class="TableScroll"><table>
<thead>
<tr>
<th>項目</th>
<th>サンプル値</th>
<th>説明</th>
</tr>
</thead>
<tbody>
<tr>
<td>COUNTER_KEY_PREFIX</td>
<td><code>"item-view-uu"</code></td>
<td>定数で指定する固定のprefix</td>
</tr>
<tr>
<td>timewindow</td>
<td><code>"202301011259"</code></td>
<td>閲覧日時を <code>yyyyMMddHHmm</code> の形式でフォーマットしたもの</td>
</tr>
<tr>
<td>itemId</td>
<td><code>"011"</code></td>
<td>対象のアイテムID</td>
</tr>
</tbody>
</table></div>
たとえば2023年1月1日12時59分には、Craft Counter側の関連レコードは次のようになっていたとします。
<div class="TableScroll"><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></div>
定数 <code>HOW_MANY_MINUTES_AGO</code> が仮に3だった場合、直近3分間の閲覧人数を取得するので、取得対象のtimewindowは 202301011257 〜 202301011259 になります。その合計は14 + 17 + 11で42です。これがレスポンスに含まれるcountの値になります。
定数 <code>HOW_MANY_MINUTES_AGO</code> の値を変更すると、それに応じて取得対象のレコード数が増える形になります。
<h2 id="2. Craft Functionsのエンドポイントを作成する">2. Craft Functionsのエンドポイントを作成する</h2>
Craft Functionsが作成できたら、接客サービスから実行出来るようにするためのエンドポイントを作成します。
<ul>
<li>作成したファンクションの編集画面で [設定] タブを開く</li>
<li>[エンドポイント] 欄の [作成] ボタンを押す</li>
</ul>
作成したエンドポイントのURLは接客サービス側の実装で利用するので手元に控えておきます。
<h2 id="3. Functionと連携する接客サービスを作成する">3. Functionと連携する接客サービスを作成する</h2>
最後に、Craftで実装した「閲覧人数取得API」を利用する接客サービスを実装し、アイテム詳細ページで配信します。
細かい接客サービスの設定方法は割愛して、アクションのJavaScriptについてサンプル実装を掲載します。
<h3 id="接客アクションのJavaScript例">接客アクションのJavaScript例</h3>
<ul>
<li>実装のポイント
<ul>
<li>同一ユーザーが同じアイテムを複数回見た場合の重複カウントを防ぐため、localStorageで閲覧済みアイテムを管理し毎回チェックする</li>
<li>配信直後にCraft側にリクエストを送信し、結果が取得できたら閲覧人数を表示</li>
</ul>
</li>
</ul>
<pre><code class="language-js hljs">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 id="実際に動かしてみる">実際に動かしてみる</h1>
実際に動作を確認してみましょう。
Craft側の動作に問題がなければ、接客サービスの表示確認をしてみましょう。次のように閲覧人数が表示されるはずです。
<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">
ユーザーはブラウザ単位で区別されるので、同一ページを別々のブラウザやシークレットウィンドウで開いてみてください。開いた数に応じて人数が加算されて表示されれば成功です。
<h1 id="おわりに">おわりに</h1>
今回はKARTE Craftで「いま何人がこの商品を見ています」施策を独自実装する方法について紹介しました。
サンプルコードでの実装は、KARTEの標準機能であるpage_user_count変数と次の点で自由度が高いものになっています。
<ul>
<li>「直近何分間の閲覧を対象にするか」を自由に設定できる</li>
<li>itemIdをリクエストパラメータに直接渡して集計対象に指定できる</li>
</ul>
応用として、たとえば次のようなシナリオの実現でも利用することができます。
<ul>
<li>(例) アイテム詳細ページを閲覧中のユーザーに対して「直近1時間で何人が購入しました」のように表示する
<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>
また、 WebとAppの両方にアイテム詳細画面がある場合も、同じCraft Functionsエンドポイントを共有すればWeb/App横断で数値を合算して表示することができます。
「いま何人が見ています」や「直近1時間で何人が購入しました」といった施策は、臨場感がありエンドユーザーにとっても強く訴求できるものです。ぜひCraftを使って自由度高く実現してみてはいかがでしょうか？
<hr>
プレイドでは、世の中にインパクトを与える新しいソリューションを一緒につくる仲間を募集しています！ 
ぜひ気軽にお問い合わせください。
↓ パートナー企業になりたい
<ul>
<li><a href="https://ecosystem.plaid.co.jp/" target="_blank" rel="noreferrer">CustomerData-Driven Solution を一緒に創りませんか？ | PLAID Ecosystem</a></li>
</ul>
↓ PLAIDで働きたい
<ul>
<li><a href="https://recruit.plaid.co.jp/requisitions/general-customer-engineer" target="_blank" rel="noreferrer">Customer Engineer | 募集ポジション | 株式会社プレイド</a></li>
<li><a href="https://recruit.plaid.co.jp/requisitions/product-engineer" target="_blank" rel="noreferrer">Product Engineer | 募集ポジション | 株式会社プレイド</a></li>
</ul>
</body></html>

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