アクションテーブル×Craft kvsを使って通知のInbox機能を実現する

<html><head></head><body>こんにちは、Customer EngineerのUGです！最近ノンオイルドレッシングの美味しさに魅了されています！
みなさんはWebページに来訪してくれたユーザーのアクセスしてきた都道府県によってローカルなキャンペーンのバナーを出したいのような位置情報を利用した施策をやってみたいとは思ったことはありませんか？Craft FunctionsとGoogle Maps APIを連携すればエンドユーザーの位置情報から都道府県を特定することが出来るのです！そこで今回は、Google Maps APIを使ってユーザーのアクセス元の都道府県を特定する方法について紹介します。
<h2 id="アウトプットイメージ">アウトプットイメージ</h2>
最終的なアウトプットイメージは次の通りです。下記の画像のようにユーザーの都道府県がイベントとしてKARTE側に発生している状態になります。 
<img src="https://ik.imagekit.io/plaid/4f171edd-6a51-43c3-a0fe-a5b90f3ee7f6/%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-02-2516.20.23.png" alt="スクリーンショット2024-02-2516.20.23.png">
位置情報を利用する前に下記のようなダイアログでエンドユーザーに許諾を取ります。 
<img src="https://ik.imagekit.io/plaid/04581ac8-8397-42f7-8acb-15164106335a/%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-02-2615.45.44.png" alt="スクリーンショット2024-02-2615.45.44.png">
構成図は次の通り。
<img src="https://ik.imagekit.io/plaid/9254f889-dc31-4fc1-919d-397512abd16e/%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-02-2811.16.07.png" alt="スクリーンショット2024-02-2811.16.07.png">
Webブラウザから緯度経度情報を取得してCraft Functionsに連携します。その情報を下に Google Maps APIを利用して、都道府県を特定してKARTEイベントを発生させます。今回のブログでは緯度経度をWebブラウザ側から連携するためにKARTE Actionのスクリプト配信を利用します。スクリプト配信でなくとも今回のCraft Functionsは利用可能です。
<h2 id="注意点">注意点</h2>
前提として、次の点に注意をしてください。
<ul>
<li>CraftのGrowthプラン以上を利用していることを前提としています</li>
<li>KARTE Webのスクリプト配信を利用していることを前提としています
<ul>
<li>スクリプト配信を利用しなくても今回のCraft Functionsは利用可能ですが今回のブログではスクリプト配信を利用することを前提に話していきます</li>
</ul>
</li>
<li>Google Maps Platformの利用を前提としています
<ul>
<li>リクエスト数に応じて<a href="https://developers.google.com/maps/billing/gmp-billing?hl=ja#geocoding" target="_blank" rel="noreferrer">課金が発生する可能性</a>があります</li>
</ul>
</li>
</ul>
<h2 id="設定手順">設定手順</h2>
設定の手順は次の通りです。
<ol>
<li>Craft Functionsのファンクションを作成する</li>
<li>Craft Functionsのエンドポイントを作成する</li>
<li>API v2 アプリを作成する</li>
<li>API v2 アプリの アクセストークンを Craft Secret Manager に登録する</li>
<li>Google Cloud PlatformでAPIキーを発行する</li>
<li>KARTE Actionからスクリプト接客を配信する</li>
</ol>
順番に見てみましょう。
<h3 id="1. Craft Functionsのファンクションを作成する">1. Craft Functionsのファンクションを作成する</h3>
Craft Functionsのファンクションを作成します。作成手順は次の通りです。
<img src="https://ik.imagekit.io/plaid/f54845aa-6834-475f-ad9d-dfaf4b0ef4c5/create_craft_functions.png" alt="create_craft_functions.png">
<ul>
<li>[Craft &gt; ファンクション &gt; 新規作成 &gt; テンプレートから作成] を選択</li>
<li>「 ユーザーの「緯度経度」をCraft Functions × Google Maps APIで「都道府県」に変換してKARTEのイベントを発生させる 」というテンプレートを検索し[取得]ボタンをクリック</li>
<li>[反映] ボタンをクリック</li>
<li>[変数] タブで次の変数の値を設定する
<ul>
<li><code>LOG_LEVEL</code>
<ul>
<li>出力するログのレベルです。ERROR/WARN/INFO/DEBUGから指定してください</li>
</ul>
</li>
<li><code>KARTE_APP_TOKEN_SECRET</code>
<ul>
<li>KARTE API v2アプリのtokenを登録したシークレット名を指定してください</li>
</ul>
</li>
<li><code>GOOGLE_MAPS_APIKEY</code>
<ul>
<li>Google Cloud Platformで発行したAPI Keyを指定してください</li>
</ul>
</li>
<li><code>EVENT_NAME</code>
<ul>
<li>KARTEで発生させるイベント名を指定してください</li>
</ul>
</li>
<li><code>FIELD</code>
<ul>
<li>イベント内で都道府県を連携する際のフィールド名を指定してください</li>
</ul>
</li>
<li>[設定 &gt; ファンクションの有効化] にチェックを付けて [保存]</li>
</ul>
</li>
</ul>
なお、テンプレートのソースコードはGitHubで公開しています。 
<a href="https://github.com/plaidev/craft-codes/tree/main/craft-functions/Identify-prefecture-with-google-maps-api" target="_blank" rel="noreferrer">craft-codes/craft-functions/Identify-prefecture-with-google-maps-api at main · plaidev/craft-codes</a>
<h3 id="2. Craft Functionsのエンドポイントを作成する">2. Craft Functionsのエンドポイントを作成する</h3>
作成したファンクションを外部から実行できるようにするためのエンドポイントを作成します。
<img src="https://ik.imagekit.io/plaid/d76f89a5-49ec-425a-909c-729c7469bfa2/create_craft_functions_endpoint.png" alt="create_craft_functions_endpoint.png">
<ul>
<li>作成したファンクションの編集画面から [設定 &gt; エンドポイント &gt; 作成] をクリック</li>
<li>表示されたエンドポイントURLをメモしておく</li>
</ul>
<h3 id="3. API v2 アプリを作成する">3. API v2 アプリを作成する</h3>
KARTEのAPIを利用するために、API v2アプリを作成します。 
<img src="https://ik.imagekit.io/plaid/a1b20746-4140-441d-8e46-3a5a74dc11ab/create_API_v2_App.png" alt="create_API_v2_App.png">
<ul>
<li>[ストア &gt; API v2設定] からアプリを新規作成</li>
<li>[アプリタイプ] を <code>token</code> に設定</li>
<li>必要なscopeを追加
<ul>
<li><code>track.event.write</code></li>
</ul>
</li>
<li>アプリを保存し、一度だけ表示されるアクセストークンをメモしておく</li>
</ul>
<h3 id="4. API v2 アプリの アクセストークンを Craft Secret Manager に登録する">4. API v2 アプリの アクセストークンを Craft Secret Manager に登録する</h3>
API v2 アプリのアクセストークンをCraft Functionsから安全に利用するために、Craft Secret Manager に登録します。
<img src="https://ik.imagekit.io/plaid/6f229ee9-39aa-4e47-be81-f615f3b448f8/create_craft_secret.png" alt="create_craft_secret.png">
<ul>
<li>[Craft &gt; シークレット] からシークレットを新規作成</li>
<li>[名前] に、わかりやすい名前を入力</li>
<li>メモしておいたAPI v2 アプリのアクセストークンを [シークレットの値] に入力し、作成</li>
<li>シークレット名をメモしておく</li>
</ul>
<h3 id="5. Google Cloud PlatformでAPIキーを発行する">5. Google Cloud PlatformでAPIキーを発行する</h3>
Google Maps APIを利用するために、GCPにてAPIキーを発行します。 
GCPを利用したことがない方に関してはプロジェクトの作成から始めてください。参考までに<a href="https://cloud.google.com/resource-manager/docs/creating-managing-projects?hl=ja" target="_blank" rel="noreferrer">GCPの公式ドキュメントはこちら</a>になります。
<ul>
<li>[APIとサービス &gt; 認証情報 &gt; 認証情報を作成] からAPIキーを作成する</li>
<li>作成したAPIキーが以下のAPIを利用できるか確認してください
<ul>
<li>Geocoding API</li>
</ul>
</li>
</ul>
参考までに私が作成した際のコンソールの画面は下記になります。 
<img src="https://ik.imagekit.io/plaid/04c9c4cc-7e59-468a-a97a-aa3b5762a0af/%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-02-2811.24.28.png" alt="スクリーンショット2024-02-2811.24.28.png">
<h3 id="6. KARTE Actionからスクリプト接客を配信する">6. KARTE Actionからスクリプト接客を配信する</h3>
Webブラウザから緯度経度情報をCraft Functionsに連携するために、KARTE Actionの接客サービスからスクリプト配信します。
<ul>
<li>[KARTE Action &gt; 接客サービス] からスクリプト配信の接客を作成する</li>
<li>緯度経度を取得したいページとタイミングで配信する</li>
</ul>
スクリプトの例として今回のブログの検証では下記のスクリプトを配信しています。参考スクリプトと接客アクションの編集画面は以下になります。 
<img src="https://ik.imagekit.io/plaid/935bb34f-1d7a-4e3c-8541-63cfe829619d/%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-02-2813.59.08.png" alt="スクリーンショット2024-02-2813.59.08.png">
<pre><code class="hljs">if (navigator.geolocation) {
 navigator.geolocation.getCurrentPosition(sendPositionToServer, handleError);
} else {
 alert("Geolocation is not supported by this browser.");
}

function sendPositionToServer(position) {
 var latitude = position.coords.latitude;
 var longitude = position.coords.longitude;

 var endpoint = "xxx"; // 送信先のCraft Functionsのエンドポイントを指定

 // HTTP POSTリクエストの設定
 fetch(endpoint, {
 method: "POST",
 headers: {
 "Content-Type": "application/json",
 },
 body: JSON.stringify({
 latitude: latitude,
 longitude: longitude,
 visitor_id: "#{visitor_id}",
 }),
 })
 .then(function(response) {
 if (!response.ok) {
 throw new Error("Network response was not ok");
 }
 return response.json();
 })
 .then(function(data) {
 console.log("Server response:", data);
 })
 .catch(function(error) {
 console.error("Error during fetch operation:", error);
 });
}

function handleError(error) {
 console.error("Error getting geolocation:", error.message);
}

</code></pre>
問題なければ以下のように緯度経度取得のためのダイアログが表示されます。 
<img src="https://ik.imagekit.io/plaid/04581ac8-8397-42f7-8acb-15164106335a/%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-02-2615.45.44.png" alt="スクリーンショット2024-02-2615.45.44.png">
<h2 id="実際に動かしてみる">実際に動かしてみる</h2>
実際に動作を確認してみましょう。 
まずはスクリプト配信をしているページでユーザーが訪問したら以下のようなダイアログが表示されます。 
<img src="https://ik.imagekit.io/plaid/04581ac8-8397-42f7-8acb-15164106335a/%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-02-2615.45.44.png" alt="スクリーンショット2024-02-2615.45.44.png">
Craft Functions側でエラーが発生しなければ下記のようなイベントが発生するはずです。 
<img src="https://ik.imagekit.io/plaid/4f171edd-6a51-43c3-a0fe-a5b90f3ee7f6/%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-02-2516.20.23.png" alt="スクリーンショット2024-02-2516.20.23.png">
<h2 id="おわりに">おわりに</h2>
今回はWebブラウザ側から取得したユーザーの「緯度経度」をCraft Functions × Google Maps APIで「都道府県」に変換してKARTEに連携する方法について紹介しました。
これにより特定の都道府県のユーザーにカスタマイズしたアクションを配信することができるようになります。ぜひ皆さんも試してみてください！
<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>

Webブラウザ側から取得したユーザーの緯度経度情報をCraft FunctionsからGoogle Maps APIを利用して都道府県情報に変換してKARTEにイベントを発生させる