KARTEで特定のイベントが発生した際に、Datahubのデータセットにクエリをリアルタイムで実行する方法

<html><head></head><body>こんにちは、Customer Engineerの島本です！ 
こないだ同僚とサウナ旅行で長野県にある「しぇろくまサウナ」と「The Sauna」に行ってきました！大雪が降る中の外気浴はとてつもなく寒かったのですが、とても良い思い出になりました。 
<img src="https://ik.imagekit.io/plaid/52ef7471-407c-43e7-a170-50eccb1c2476/IMG_1694.jpg" alt="IMG_1694.jpg">
さて、KARTE のプロダクト群にはメール配信ができる<a href="https://karte.io/package/message/" target="_blank" rel="noreferrer">KARTE Message</a>があるため、「KARTE でメルマガ登録フォームや資料請求フォームを作ってメールを送りたい！」というお問い合わせをいただくことが多いです。実現するためにはフォームの入力内容をKARTE のユーザーデータとして取得する必要があるのですが、これまで以下の制約がありました。
<ul>
<li>KARTEのアンケート接客サービス等でフォーム入力内容をイベント送信する場合、イベント送信の失敗をフロントエンドで検知できない</li>
<li>フォーム入力内容を直接KARTEの紐付けテーブルに書き込むことができない</li>
</ul>
しかし、KARTE Craft を使えば実現することができるのです！
今回は「フォーム入力データをHTTP経由で受け取ってKARTEのユーザーデータとして書き込む」方法について紹介します。イメージとしてはこんな感じです。 
<img src="https://ik.imagekit.io/plaid/4b5711ba-bf04-4b00-955b-acbb28c11275/%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-12-2512.58.18.png" alt="スクリーンショット2023-12-2512.58.18.png">
<h1 id="処理の流れ">処理の流れ</h1>
全体の処理の流れは、次の通りです。 
今回は、フォームはKARTE Blocks で作成し、KARTEの紐付けテーブルへの書き込みを行う実装をしたいと思います。 
<img src="https://ik.imagekit.io/plaid/c2540177-50bd-4cae-bd0f-a41327eece1a/%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%882024-01-1215.27.50.png" alt="スクリーンショット2024-01-1215.27.50.png">
実現する上で必要なプロダクトやオプションは以下になります。
<ul>
<li><a href="https://karte.io/" target="_blank" rel="noreferrer">KARTE</a></li>
<li><a href="https://ecosystem.plaid.co.jp/product/karte-craft" target="_blank" rel="noreferrer">KARTE Craft</a></li>
<li><a href="https://blocks.karte.io/" target="_blank" rel="noreferrer">KARTE Blocks</a></li>
</ul>
また、Craft Functions とKARTE Blocks との連携では次の2つの機能を利用します。
<ul>
<li><a href="https://craft.developers.karte.io/craft-functions/triggers/endpoint" target="_blank" rel="noreferrer">Craft Endpoint トリガー</a>
<ul>
<li>Craft Functionを実行するためのHTTPエンドポイント</li>
</ul>
</li>
<li><a href="https://developers.karte.io/reference/post_v2beta-track-reftable-row-upsert" target="_blank" rel="noreferrer">Upsert refTable row API</a>
<ul>
<li>紐付けテーブルの行を更新するAPI</li>
</ul>
</li>
</ul>
<h1 id="実装手順">実装手順</h1>
実装の手順は次の通りです。
<ol>
<li>API v2 アプリを作成する</li>
<li>API v2 アプリの アクセストークンを Craft Secret Manager に登録する</li>
<li>紐付けテーブルを作成する</li>
<li>Craft Functions を作成する</li>
<li>Craft Functions の エンドポイントURLを作成する</li>
<li>KARTE Blocksでフォームを作成する</li>
</ol>
順番に見てみましょう。
<h2 id="1. API v2 アプリを作成する">1. API v2 アプリを作成する</h2>
まず、Upsert refTable row API を利用するためのAPI v2アプリを作成します。 
<img src="https://ik.imagekit.io/plaid/6fa4746b-6cd4-4767-a846-76cda4ddaa5e/%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%882024-01-1215.36.00.png" alt="スクリーンショット2024-01-1215.36.00.png">
<ul>
<li>[ストア &gt; API v2設定] からアプリを新規作成</li>
<li>[アプリタイプ] を&nbsp;<code>token</code>&nbsp;に設定</li>
<li>必要なscopeを追加
<ul>
<li><code>beta.track.refTable.row.upsert</code>: Upsert refTable row API に必要</li>
</ul>
</li>
<li>アプリを保存し、一度だけ表示されるアクセストークンを控えておく</li>
</ul>
「アプリタイプ」は後から変更できないため、誤って作成した場合は、アプリを再度作成し直してください。
<h2 id="2. API v2 アプリの アクセストークンを Craft Secret Manager に登録する">2. API v2 アプリの アクセストークンを Craft Secret Manager に登録する</h2>
API v2 アプリのアクセストークンを Craft Secret Manager のシークレットとして登録します。それにより、秘匿すべきアクセストークンをファンクション上に直接記述する必要が無くなります。 
<img src="https://ik.imagekit.io/plaid/116765b1-4d21-4d74-8d3e-e5a4e4431e5b/image(6).png" alt="image(6).png">
<h2 id="3. 紐付けテーブルを作成する">3. 紐付けテーブルを作成する</h2>
フォーム入力データを格納するための紐付けテーブルを作成します。
<ul>
<li>[グローバルメニュー &gt; すべてのメニュー &gt; Insight &gt; 紐付けテーブル] をクリック</li>
<li>右上の [作成 &gt; 空の紐付けテーブルを作成] をクリック</li>
<li>適当なテーブル名をつけて保存</li>
<li>テーブル情報タブの基本情報に記載されているテーブルIDを控えておく</li>
</ul>
テーブルIDはCraft Functions の変数に記載します。
<h2 id="4. Craft Functions を作成する">4. Craft Functions を作成する</h2>
フォームの入力データを紐付けテーブルに書き込んで、イベント送信するためにCraft Functions のファンクションを作成します。サンプルとなるソースコードは、Craft FunctionsのテンプレートとしてGitHubで公開しています。 
<a href="https://github.com/plaidev/craft-codes/tree/main/craft-functions/form-server" target="_blank" rel="noreferrer">craft-codes/craft-functions/form-server at main · plaidev/craft-codes</a>
作成手順は次の通りです。
<ul>
<li>[Craft &gt; ファンクション &gt; 作成 &gt; テンプレートから作成] を選択</li>
<li><code>「フォーム入力データをHTTP経由で受け取ってKARTEのユーザーデータとして書き込む」</code> というテンプレートを検索し「取得」ボタンをクリック</li>
<li>「反映」ボタンをクリック</li>
<li>Functionを有効化して保存</li>
</ul>
サンプルコードの実装の特徴は次の通りです。
<ul>
<li>Craft Functionsの変数で、入力項目の一覧をカンマ区切り文字列で指定することで、受付可能な項目名をサーバーサイドで制限
<ul>
<li>KARTE Blocks 側で作成するフォームの各種input要素のname属性と項目名を合わせてください</li>
</ul>
</li>
<li>Craft Functions の[特別なレスポンス]https://craft.developers.karte.io/craft-functions/triggers/endpoint/index.html#:~:text=%E8%BF%94%E5%8D%B4%E3%81%97%E3%81%BE%E3%81%99%E3%80%82-,%E7%89%B9%E5%88%A5%E3%81%AA%E3%83%AC%E3%82%B9%E3%83%9D%E3%83%B3%E3%82%B9,-Craft%20Functions%E3%81%A7)を利用して各処理においてフロント側にステータスを返す</li>
</ul>
<h2 id="5. Craft Functions の エンドポイントURLを作成する">5. Craft Functions の エンドポイントURLを作成する</h2>
Craft Functionsを作成して一度保存した後に、エンドポイント設定からURLを作成します。 
<img src="https://ik.imagekit.io/plaid/05e089f7-ae4d-4323-b209-f1af08f10d3b/%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-12-2514.43.22.png" alt="スクリーンショット2023-12-2514.43.22.png">
作成したエンドポイントURLはKARTE Blocks で作成するフォームのJavaScript 内に記載します。
<h2 id="6. KARTE Blocks でフォームを作成する">6. KARTE Blocks でフォームを作成する</h2>
今回はサイトに埋め込むフォームを作成するためKARTE Blocks でフォームを作成します。 
細かいKARTE Blocks の設定方法は割愛して、フォームを実装する上でサンプルコードを掲載します。
<h3 id="KARTE Blocks のコードエディターで設定するJavaScript例">KARTE Blocks のコードエディターで設定するJavaScript例</h3>
実装のポイントとしては、Craft の特別なレスポンスのステータスに応じてフロント側のメッセージの表示を出し分けしています。
<pre><code class="hljs">const CRAFT_FUNCTIONS_ENDPOINT = 'https://t.karte.io/hook/xxxxxxxx/craft/xxxxxxxx';
const COOKIE_KEY = 'krt.vis';

const submitButton = document.querySelector('button[type="submit"]');
const errorMessage = document.querySelector('.error-message');

function getVisitorIdFromCookie() {
 const visitorIdMatch = document.cookie.match(new RegExp(`${COOKIE_KEY}=([^;]*)`));
 return visitorIdMatch ? visitorIdMatch[1] : null;
}

function updateResMessage(text) {
 errorMessage.textContent = text;
}

function updateButtonState(buttonState) {
 submitButton.disabled = buttonState;
 submitButton.style.opacity = buttonState ? '1' : '0.8';
 submitButton.style.cursor = buttonState ? 'auto' : 'pointer';
 submitButton.style.backgroundColor = buttonState ? 'gray' : '#2aab9f';
}

async function craftPost(postData) {
 fetch(CRAFT_FUNCTIONS_ENDPOINT, {
 method: 'POST',
 mode: 'cors',
 headers: {
 'Content-Type': 'application/json',
 },
 body: JSON.stringify(postData),
 })
 .then(async result =&gt; {
 if (result.status === 400) {
 updateResMessage('入力内容に問題があります。確認して再度お試しください。');
 updateButtonState(false);
 } else if (result.status === 500) {
 updateResMessage('フォームの送信に失敗しました。間をおいてもう一度お試しください。');
 updateButtonState(false);
 } else if (result.ok) {
 updateResMessage('ありがとうございます。申し込み完了しました。');
 updateButtonState(true);
 } else {
 throw new Error(await result.text());
 }
 })
 .catch(error =&gt; {
 console.error('Error:', error);
 updateResMessage('フォームの送信に失敗しました。間をおいてもう一度お試しください。');
 updateButtonState(false);
 });
}

document.querySelector('.form').onsubmit = async event =&gt; {
 event.preventDefault();

 const form = event.target;
 const postData = {};

 for (const input of form.elements) {
 if (input.name) {
 postData[input.name] = input.value;
 }
 }

 try {
 postData['visitorId'] = getVisitorIdFromCookie();

 updateButtonState(true);
 await craftPost(postData);
 } catch (error) {
 console.error('エラー:', error);
 }
};
</code></pre>
以上で設定は完了です！
<h1 id="実際に動かしてみる">実際に動かしてみる</h1>
実際に動作を確認してみましょう。
まずはフォームに適当な情報を入力して送信を押してみます。 
数秒後に「<code>ありがとうございます。申し込み完了しました。</code>」というメッセージが表示されました。 
<img src="https://ik.imagekit.io/plaid/0178e744-13bd-4f9b-89e9-b62649514a8a/%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%882024-01-0516.10.04.png" alt="スクリーンショット2024-01-0516.10.04.png">
その後、紐付けテーブルに書き込まれているか確認します。 
問題なく紐付けテーブルにレコードが追加されていることを確認できました！ 
<img src="https://ik.imagekit.io/plaid/e33b4347-454e-4668-8816-28d504604097/%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%882024-01-0516.17.05.png" alt="スクリーンショット2024-01-0516.17.05.png">
あえて、意図的にエラーを出すためにCraft Functionsを無効化して送信を押してみます。 
「<code>フォームの送信に失敗しました。間をおいてもう一度お試しください。</code>」というメッセージが表示されました。 
<img src="https://ik.imagekit.io/plaid/68831a8d-df52-40f7-b077-fb358a468dcc/%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%882024-01-0517.04.00.png" alt="スクリーンショット2024-01-0517.04.00.png">
問題なくエラーハンドリングできていますね！
<h1 id="おわりに">おわりに</h1>
今回は「フォーム入力データをHTTP経由で受け取ってKARTE のユーザーデータとして書き込む」方法について紹介しました。
フォームを作成する部分についてKARTE Blocks を使った例を紹介しましたが、もちろんKARTE を使ったポップアップでも同様の事を実現することが可能です。また、冒頭お伝えした通り、KARTE のプロダクト群にはメール配信ができるKARTE Message があるため、ジョブフローを使って紐付けテーブルをデータテーブルにインポートすれば、KARTE Message で配信するリストとしても活用することができます！
ぜひ皆さんも活用してみてください。
<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を使って「フォーム入力データをHTTP経由で受け取ってKARTEのユーザーデータとして書き込む」方法について紹介します。