KARTEでレコメンドを実装してみた

<html><head></head><body><p>こんにちは。プレイドの矢澤です。</p>
<p>この記事は前後編の後編です。前編はこちらです。</p>
<p><a href="https://solution.plaid.co.jp/karte-craft-improve-customer-data-utilization-1">KARTEとKARTE Craftでユーザー情報の活用の幅が広がる話 (前編)</a></p>
<p>前回の記事では、KARTEとKARTE Craftについてエンジニアの方向けに紹介いたしました。KARTEのユーザーを「知る」機能の仕組みと、ユーザー状態の変化をKARTE Craftで外部に連携することで、KARTEをユーザー情報解析のバックエンドにできるのではないか、という話をしました。</p>
<p>とはいえ実際にKARTEとKARTE Craftを触ってみないとその感覚はわからないかと思います。そこで、後編ではユーザーの状態変化をリアルタイムに外部連携するサンプル実装を作ってみようと思います。</p>
<h1 id="作るもの">作るもの</h1>
<p>今回は、KARTE内で発生するイベントをキッカケにユーザー情報をGoogle BigQueryに連携するサンプルを作成してみようと思います。動作を簡単に図で表現すると以下の通りです。</p>
<p><img src="https://ik.imagekit.io/plaid/dddec887-dfaa-469b-a109-76848506357a/craft_bigquery_sample.png" alt="craft_bigquery_sample.png"></p>
<ul>
<li>KARTEを利用しているページで、URLアンカーに特定の文字列が含まれていたらCraft Functionを発火する</li>
<li>受け取ったユーザー情報と閲覧しているWebサイトのURLをBigQueryのテーブルに記録する</li>
</ul>
<p>ユースケース的には微妙ではありますが、KARTEのデータがリアルタイムに外部サービスで利用できる感覚は持っていただけるかと思います。</p>
<h1 id="準備">準備</h1>
<p>2023年4月現在、KARTE Craftはβ版として提供しています。利用にあたっては以下のページからの申し込みが必要です。</p>
<p><a href="https://docs.google.com/forms/d/e/1FAIpQLSfxNJl-HttTQPVZiqM3hyBzceSyzLNJ9BlLxwOWC1USoZmt_A/viewform" target="_blank" rel="noreferrer">KARTE Craft 利用申請</a></p>
<p>このサンプルではBigQueryを利用するので、Google Cloudが利用できる環境をご準備ください。データの書き込み・読み取りにあたってはGoogle Cloudの利用料金が発生するので注意してください。</p>
<h1 id="手順">手順</h1>
<p>では実装していきましょう。作業は大まかに分けて2つあります。</p>
<ul>
<li>BigQueryのテーブルにデータを書き込むファンクションの作成</li>
<li>サイト来訪ユーザーの閲覧 (View) をトリガーにCraft Functionsを起動するアクションの作成</li>
</ul>
<p>順番に説明します。</p>
<h2 id="BigQueryのテーブルにデータを書き込むファンクションを作成する">BigQueryのテーブルにデータを書き込むファンクションを作成する</h2>
<p>まずはBigQueryのテーブルにデータを書き込む処理を実装します。</p>
<h3 id="BigQuery のテーブルを作成する">BigQuery のテーブルを作成する</h3>
<p>事前にBigQueryのテーブルを作成しておきます。ドキュメントを参考にスキーマ定義つきのテーブルを作成します。<br>
<a href="https://cloud.google.com/bigquery/docs/tables?hl=ja#create_an_empty_table_with_a_schema_definition" target="_blank" rel="noreferrer">テーブルの作成と使用 &nbsp;|&nbsp; BigQuery &nbsp;|&nbsp; Google Cloud</a></p>
<p>今回はイベント発生時刻、ビジターID、閲覧先URLのみを連携するので、スキーマには以下を設定します。</p>
<div class="TableScroll"><table>
<thead>
<tr>
<th>フィールド</th>
<th>型</th>
<th>モード</th>
</tr>
</thead>
<tbody>
<tr>
<td>datetime</td>
<td>DATETIME</td>
<td>REQUIRED</td>
</tr>
<tr>
<td>visitor_id</td>
<td>STRING</td>
<td>REQUIRED</td>
</tr>
<tr>
<td>url</td>
<td>STRING</td>
<td>REQUIRED</td>
</tr>
</tbody>
</table></div>
<h3 id="Google Cloudの認証情報をSecret Managerに登録する">Google Cloudの認証情報をSecret Managerに登録する</h3>
<p>ファンクションを作成する前に、Google Cloudの認証情報をCraft Secret Managerに登録します。Craft Secret ManagerはKARTE Craft用のシークレット管理機能です。APIキーやトークンなど、コードに直接記入することが非推奨とされる情報をシークレットとして保存して、コードから安全に呼び出せるようにします。</p>
<p>BigQueryテーブルへの書き込み権限を持つサービスアカウントを作成し、JSON形式でキーを発行します。詳しい手順はGoogle Cloudのドキュメントを参照してください。</p>
<p><a href="https://cloud.google.com/iam/docs/creating-managing-service-account-keys?hl=ja" target="_blank" rel="noreferrer">サービス アカウント キーの作成と管理 &nbsp;|&nbsp; IAM のドキュメント &nbsp;|&nbsp; Google Cloud</a></p>
<p>KARTE Craftのシークレット管理画面を開き、シークレットを作成します。</p>
<ul>
<li>シークレット名: <code>GOOGLE_CLOUD_SA_KEY</code></li>
<li>データ: サービスアカウントキーの本文をそのまま貼り付けます</li>
</ul>
<p><img src="https://ik.imagekit.io/plaid/a531ab5a-7ec3-407d-acf8-72ea43a27f9f/craft_secret.png" alt="craft_secret.png"></p>
<h3 id="Craft Functionsを作成する">Craft Functionsを作成する</h3>
<p>ドキュメントの <a href="https://craft.developers.karte.io/craft-functions/edit-craft-funcitons" target="_blank" rel="noreferrer">Craft Functionsを作成する</a> を参考に、管理画面からファンクションを作成します。</p>
<ul>
<li>ファンクション名と説明には任意の名前と説明文を記載してください。</li>
<li>ファンクションのコードは以下のGitHubリポジトリに配置したものを使います。
<ul>
<li><a href="https://github.com/plaidev/craft-codes/tree/main/craft-functions/write-event-to-bq" target="_blank" rel="noreferrer">plaidev/craft-codes/craft/write-event-to-bq</a></li>
<li>write-event-to-bq.js を codes に、 modules.json を packages に貼り付けます。</li>
</ul>
</li>
<li>ここで、<code>BIG_QUERY_DATASET</code> と <code>BIG_QUERY_TABLE</code> に書き込み先のデータセット、テーブルを指定します。</li>
</ul>
<p><img src="https://ik.imagekit.io/plaid/4149fe5f-435e-4929-861d-6e833f6f7baa/craft_function_settings.png" alt="craft_function_settings.png"></p>
<h2 id="アクションを作成する">アクションを作成する</h2>
<p>Craft Functionsの作成が完了したので、次はアクションを設定します。詳細な手順はドキュメントをご確認いただくとして、ここでは各要素の設定値を書いていきます。ここに書いていない必須項目については任意で設定してください。</p>
<p>注意として、今回は検証用のKARTEプロジェクトでの設定を想定してます。本番利用しているプロジェクトで設定する場合はエンドユーザーへの影響を避ける設定（ターゲットの絞り込み、トリガー設定で管理者以外では発生させられないイベントを設定する）を行うようにしてください。</p>
<p>アクションの作成手順は以下をご確認ください。</p>
<p><a href="https://craft.developers.karte.io/craft-functions/triggers/server-side-action" target="_blank" rel="noreferrer">サーバーサイドアクション</a></p>
<p>接客サービス作成の全体の流れと対象ユーザー、トリガーの設定については以下をご確認ください。</p>
<p><a href="https://support.karte.io/post/4yOwCoZkdoPZwpFRvSrkwP" target="_blank" rel="noreferrer">接客サービス作成の流れ | ドキュメント / アクション / 作成・ 配信設定 | KARTEサポートサイト</a><br>
<a href="https://support.karte.io/post/5YTahJyFdwojIWZtYlL65A" target="_blank" rel="noreferrer">4. 対象ユーザーの設定/仕様 | ドキュメント / アクション / 作成・ 配信設定 | KARTEサポートサイト</a><br>
<a href="https://support.karte.io/post/4Ea4RlGZsZmAxRYp4dqCDv" target="_blank" rel="noreferrer">5. Setting and Specifications of Target Event | ドキュメント / アクション / 作成・ 配信設定 | KARTEサポートサイト</a></p>
<p>Craftアクションの設定値は以下の通りです。</p>
<ul>
<li>ファンクション名：先ほど作成したファンクションの名前</li>
<li>ユーザー情報変数
<ul>
<li>変数名 <code>visitor_id</code>
<ul>
<li>「すべての期間」「閲覧」「visitor_id」の「最新の値」</li>
</ul>
</li>
<li>変数名 <code>url</code>
<ul>
<li>「すべての期間」「閲覧」「閲覧ページのURL」の「最新の値」</li>
</ul>
</li>
<li>変数名 <code>datetime</code>
<ul>
<li>「すべての期間」「閲覧」「送信日時」の「最新の値」</li>
</ul>
</li>
</ul>
</li>
<li>data： <code>{ "visitor_id": "#{visitor_id}", "url": "#{url}", "datetime": "#{datetime}" }</code></li>
</ul>
<p><img src="https://ik.imagekit.io/plaid/933df0ed-6125-4f1a-905e-ae7d07f514ce/craft_action_settings.png" alt="craft_action_settings.png"></p>
<p>接客サービスの対象ユーザーには「全員」を指定します。</p>
<p><img src="https://ik.imagekit.io/plaid/e5c81621-f57b-4b0f-baed-5f10e2a82653/craft_action_target_user.png" alt="craft_action_target_user.png"></p>
<p>接客サービスの対象イベントには以下を設定します。</p>
<ul>
<li>閲覧イベント
<ul>
<li>閲覧ページのURLアンカーが次に等しい</li>
<li><code>craft_sample</code></li>
</ul>
</li>
<li>配信頻度: アクセス毎</li>
</ul>
<p><img src="https://ik.imagekit.io/plaid/87191c03-0d17-4cf3-b3ba-6faddd98a277/craft_action_target_event.png" alt="craft_action_target_event.png"></p>
<p>設定後、接客の保存と公開を行えば作業完了です。</p>
<h2 id="動作確認">動作確認</h2>
<p>以上で設定が完了しました。KARTEを設定したWebページに移動して、URLの末尾に <code>#craft_sample</code> とアンカーをつけて開いてみます。</p>
<p><img src="https://ik.imagekit.io/plaid/11b48a9c-dda1-4f1a-901f-7935b0c359bc/craft_bq_trigger_check.png" alt="craft_bq_trigger_check.png"></p>
<p>10〜30秒ほど待ってBigQueryのテーブルにデータが書き込まれていれば成功です。</p>
<p><img src="https://ik.imagekit.io/plaid/fcac7fce-8c11-4326-b328-fe97729b8145/craft_bq_result.png" alt="craft_bq_result.png"></p>
<p>以上で作業は完了です。お疲れさまでした。</p>
<h1 id="まとめ">まとめ</h1>
<p>今回は前後編にわたってKARTEとKARTE Craftを紹介いたしました。後編のこの記事では、実際にKARTEとKARTE Craftを使って、ユーザーの状態変化を外部のストレージに保存する実装を行いました。今回はBigQueryのテーブルにユーザーデータを書き込みましたが、KARTE Craftでは汎用のプログラムが実行できます。様々なストレージサービスにデータを連携したり、外部サービスの情報と組み合わせた処理も実現できるため、さまざまな応用例が考えられます。</p>
<p>今回はエンジニアの方向けにKARTEの仕組みやKARTE Craftのサービスとしての立ち位置にフォーカスして書きましたが、当ブログではKARTEとKARTE Craftを応用したソリューションもどんどん紹介する予定です。この記事をお読みになって具体的な利用方法に興味を持っていただけたら、当ブログの他の記事も見ていただければと思います！</p>
<hr>
<p>プレイドでは、ソリューションを一緒に作っていく仲間を募集しております！プレイドのテクノロジーを駆使し、お客様に新しい価値を提供できるソリューションを一緒に作っていきましょう！</p>
<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>
<li><a href="https://blog.plaid.co.jp/n/nd8a70f686885" target="_blank" rel="noreferrer">2協業案件のリードに、PdMとしての役割も。経験が複利で増えるカスタマーエンジニアの多面性｜PLAID</a></li>
<li><a href="https://blog.plaid.co.jp/n/n6d87538d003f" target="_blank" rel="noreferrer">幅広く活用できるプロダクトの価値を顧客に届ける「カスタマーエンジニア」の道を選択した3人のキャリアを聞きました｜PLAID</a></li>
</ul>
</body></html>

KARTE CraftはKARTE内で発生する種々のイベントをきっかけに汎用のプログラムを実行します。

KARTE Craftの概要

KARTE Craftの使用例として、KARTEのイベントをトリガーに外部サービスにデータを送るサンプルを紹介します。

KARTEとKARTE Craftでユーザー情報の活用の幅が広がる話 (後編)