Solution Blog

Kazuhisa Fukuda

Kazunori Kamiya

Yusuke Kobayashi

Masamichi Kanakubo

Kazuki Shimizu

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のkazです！最近、『チ。-地球の運動について-』に夢中になっています。学生時代に感じた物理への憧れを思い出させてくれる作品で、ぜひ皆さんにもおすすめしたいです。私はピャスト伯が好きです。</p>
<p>さて、近年企業が顧客理解を深めるためにアンケートやレビューなどの1st Partyデータを活用することが一般的になっています。しかし、膨大な量のフリーテキスト回答データを人手で分析するのは大変な作業です。</p>
<p>KARTE Craft AI Modules では、アンケートなどで収集された自由記述データに対して、文意の成分ごとの大きさをベクトルサイズで表現する機能を提供します。これにより、肯定的な感情を含む回答を効率的に抽出したり、回答の傾向を数値化することができます。</p>
<p>具体的な活用事例としては、大規模アンケートの感情分析や、商品・サービスに対するユーザーの評価把握などが考えられます。KARTE Craftのこの機能を使えば、膨大なテキストデータの中から重要なインサイトを見出すことができるでしょう。</p>
<p>ぜひ、KARTE Craft AIモジュールを活用して、テキストデータの高度な分析に挑戦してみてください。</p>
<h2>アウトプットイメージ</h2>
<p>最終的なアウトプットイメージは次の通りです。<br>
今回は、一例として食品についてのレビューに「商品に満足している」「商品に不満がある」という文意が、それぞれどの程度含まれているかを分析しました。</p>
<p>分析を実行すると、スプレッドシーに入力されているテキストごとに、Craft Functions変数で指定したキーワードの文意の含有量が計算され、 Google スプレッドシートに出力されます。</p>
<p><img src="https://ik.imagekit.io/plaid/4ee22366-446e-452e-8653-dbfaa0fdf048/Monosnapsurvey_demo_data-Google%E3%82%B9%E3%83%95%E3%82%9A%E3%83%AC%E3%83%83%E3%83%88%E3%82%99%E3%82%B7%E3%83%BC%E3%83%882024-04-0514-40-59.png" alt="Monosnapsurvey_demo_data-Googleスプレッドシート2024-04-0514-40-59.png"></p>
<p>文意の大きさは 0~1 の数値で 1 に近いほど文意が強いことを表しています。<br>
一例として2行目の商品レビューを例にデータを読み解いてみると、文意の大きさは</p>
<ul>
<li>「商品に満足している」: 0.392</li>
<li>「商品に不満がある」：0.301</li>
</ul>
<p>となっています。そのため、このレビューは「商品に満足している」という意味合いの強いレビューだと解釈することができます。このように、この分析によるアウトプットは膨大な量のフリーテキストから定量的に文意を抽出することで、回答の傾向を数値化するのに役立つでしょう。</p>
<h2>注意点</h2>
<p>前提として、次の点に注意をしてください。</p>
<ul>
<li>KARTE Craft Functions, KARTE Craft AI Modules を利用していることを前提としています。</li>
<li>Google SpreadSheet API を使用することを推奨しています。</li>
<li>本ソリューションは Google Spread Sheet API を通わずに使用することも可能ですが、配布しているテンプレートは SpreadSheet を使ってデータの入出力を行うように作られているため、Spread Sheet APIを使用しない場合は Functions を適宜カスタマイズしてご利用ください。</li>
</ul>
<h2>設定手順</h2>
<p>設定の手順は次の通りです。</p>
<ol>
<li>API v2 アプリを作成する</li>
<li>API v2 アプリの アクセストークンを Craft Secret Manager に登録する</li>
<li>Googleサービスアカウントを作成する</li>
<li>GoogleサービスアカウントのJSONキーファイルの中身を Craft Secret Manager に登録する</li>
<li>Googleサービスアカウントに対象スプレッドシートへの権限を付与する</li>
<li>Craft Functionsのファンクションを作成する</li>
<li>Craft Functionsのエンドポイントを作成する</li>
</ol>
<p>順番に見てみましょう。</p>
<h3>1. API v2 アプリを作成する</h3>
<p>KARTEのAPIを利用するために、API v2アプリを作成します。<br>
<img src="https://ik.imagekit.io/plaid/a1b20746-4140-441d-8e46-3a5a74dc11ab/create_API_v2_App.png" alt="create_API_v2_App.png"></p>
<ul>
<li>[ストア &gt; API v2設定] からアプリを新規作成</li>
<li>[アプリタイプ] を <code>Craft</code> に設定</li>
<li>必要なscopeを追加
<ul>
<li><code>beta.craft.aimodules.openai.embeddings</code></li>
</ul>
</li>
<li>アプリを保存し、一度だけ表示されるアクセストークンをメモしておく</li>
</ul>
<h3>2. API v2 アプリの アクセストークンを Craft Secret Manager に登録する</h3>
<p>API v2 アプリのアクセストークンをCraft Functionsから安全に利用するために、Craft Secret Manager に登録します。</p>
<p><img src="https://ik.imagekit.io/plaid/6f229ee9-39aa-4e47-be81-f615f3b448f8/create_craft_secret.png" alt="create_craft_secret.png"></p>
<ul>
<li>[Craft &gt; シークレット] からシークレットを新規作成</li>
<li>[名前] に、わかりやすい名前を入力</li>
<li>メモしておいたAPI v2 アプリのアクセストークンを [シークレットの値] に入力し、作成</li>
<li>シークレット名をメモしておく</li>
</ul>
<h3>3. Googleサービスアカウントを作成する</h3>
<p>GoogleのサービスでAPIを利用するために、Googleサービスアカウントを作成します。</p>
<ul>
<li>Google Cloudのコンソール画面を開く
<ul>
<li>アカウントやプロジェクトが無い場合は作成してください</li>
</ul>
</li>
<li>[IAMと管理 &gt; サービスアカウント &gt; サービスアカウントを作成] から適当な名称のサービスアカウントを作成</li>
</ul>
<p><img src="https://ik.imagekit.io/plaid/227adf6a-c6bc-42ea-8235-8f3c762422eb/%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-08-1413.15.34.png" alt="スクリーンショット2023-08-1413.15.34.png"></p>
<ul>
<li>作成したサービスアカウントを選択し、[キー &gt; 鍵を追加 &gt; 新しい鍵を作成] からJSON形式のキーファイルをダウンロード</li>
</ul>
<p><img src="https://ik.imagekit.io/plaid/faefbf7a-98af-4a2f-a672-e436f2e8cf0c/%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-08-1413.16.12.png" alt="スクリーンショット2023-08-1413.16.12.png"></p>
<p>ダウンロードしたキーファイルは、後の手順で利用します。</p>
<h3>4. GoogleサービスアカウントのJSONキーファイルの中身を Craft Secret Manager に登録する</h3>
<p>Googleサービスアカウントの認証情報をCraft Functionsから安全に利用するために、Craft Secret Manager に登録します。</p>
<p><img src="https://ik.imagekit.io/plaid/1cb0539c-a074-47aa-b2f4-569647617236/create_service_account_secret.png" alt="create_service_account_secret.png"></p>
<ul>
<li>[Craft &gt; シークレット] からシークレットを新規作成</li>
<li>[名前] に、わかりやすい名前を入力</li>
<li>ダウンロードしたJSONキーファイルの中身を [シークレットの値] にそのまま入力し、作成</li>
<li>シークレット名をメモしておく</li>
</ul>
<h3>5. Googleサービスアカウントに対象スプレッドシートへの権限を付与する</h3>
<p>Google Sheets APIを有効化したとしても、個別のスプレッドシートに対して自由にアクセスできるわけではありません。スプレッドシート毎に、対象のGoogleサービスアカウントに対して権限を付与する必要があります。</p>
<ul>
<li>対象スプレッドシートを開き、右上の [共有]ボタンをクリック</li>
</ul>
<p><img src="https://ik.imagekit.io/plaid/1d490492-2ff5-409a-97e2-8f256b0eee49/%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-08-1514.20.04.png" alt="スクリーンショット2023-08-1514.20.04.png"></p>
<ul>
<li>ダウンロードしたキーファイルに含まれるclient_emailの値を入力し、権限には [編集者] を選択して [送信]</li>
</ul>
<h3>6. Craft Functionsのファンクションを作成する</h3>
<p>Craft Functionsのファンクションを作成します。作成手順は次の通りです。</p>
<p><img src="https://ik.imagekit.io/plaid/f54845aa-6834-475f-ad9d-dfaf4b0ef4c5/create_craft_functions.png" alt="create_craft_functions.png"></p>
<ul>
<li>[Craft &gt; ファンクション &gt; 新規作成 &gt; テンプレートから作成] を選択</li>
<li>「 <strong>自由回答テキストに含まれる文意を Text Embedding で成分ごとにスコア化する</strong> 」というテンプレートを検索し[取得]ボタンをクリック</li>
<li>[反映] ボタンをクリック</li>
<li>[変数] タブで次の変数の値を設定する
<ul>
<li><code>LOG_LEVEL</code>
<ul>
<li>出力するログのレベル</li>
</ul>
</li>
<li><code>CRAFT_APP_TOKEN_SECRET_NAME</code>
<ul>
<li>API v2 アプリのアクセストークンを登録したシークレットの名前です。</li>
</ul>
</li>
<li><code>EMBEDDING_KEYWORDS</code>
<ul>
<li>に用いるキーワード</li>
<li>複数指定する場合はカンマ区切りで指定します。
<ul>
<li>例：<code>商品に満足している,商品に不満がある</code></li>
</ul>
</li>
</ul>
</li>
<li><code>SERVICE_ACCOUNT_KEY_SECRET</code>
<ul>
<li>Googleサービスアカウントを登録したシークレットの名前</li>
</ul>
</li>
<li><code>SPREADSHEET_ID</code>
<ul>
<li>GoogleスプレッドシートID</li>
<li>スプレッドシートのURLの <code>https://docs.google.com/spreadsheets/d/#{SPREADSHEET_ID}/</code> より取得できる英数字です。</li>
</ul>
</li>
<li><code>SHEET_NAME</code>
<ul>
<li>連携対象のGoogleスプレッドシートのシート名</li>
<li>例：<code>Sheet1</code></li>
</ul>
</li>
<li><code>TEXT_EMBEDDING_MODEL</code>
<ul>
<li>Text Embedding に使用するモデル名</li>
<li>現在使用できるモデルは <a href="https://developers.karte.io/reference/post_v2beta-craft-aimodules-openai-embeddings">Developer Portal - Enterprise grade embeddings</a> の <code>BODY PARAMS</code> より確認できます。</li>
</ul>
</li>
</ul>
</li>
<li>[保存] する</li>
<li>デプロイ完了後、[設定 &gt; ファンクションの有効化] にチェックを付ける</li>
</ul>
<p>なお、テンプレートのソースコードはGitHubで公開しています。<br>
<a href="https://github.com/plaidev/craft-codes/tree/main/craft-functions/survey-text-embedding-scoring">craft-codes/craft-functions/survey-text-embedding-scoring at main · plaidev/craft-codes</a></p>
<h2>7. Craft Functionsのエンドポイントを作成する</h2>
<p>作成したファンクションを外部から実行できるようにするためのエンドポイントを作成します。</p>
<p><img src="https://ik.imagekit.io/plaid/d76f89a5-49ec-425a-909c-729c7469bfa2/create_craft_functions_endpoint.png" alt="create_craft_functions_endpoint.png"></p>
<ul>
<li>作成したファンクションの編集画面から [設定 &gt; エンドポイント &gt; 作成] をクリック</li>
<li>表示されたエンドポイントURLをメモしておく</li>
</ul>
<h2>実際に動かしてみる</h2>
<p>実際に動作を確認してみましょう。まずスプレッドシートのA1に <code>input</code> というヘッダを作成し、続くA列のセルに分析したいテキストデータを入力します。</p>
<p><img src="https://ik.imagekit.io/plaid/443c9b62-01f7-4b3b-b660-143bbc5e0d6e/Monosnapsurvey_demo_data-Google%E3%82%B9%E3%83%95%E3%82%9A%E3%83%AC%E3%83%83%E3%83%88%E3%82%99%E3%82%B7%E3%83%BC%E3%83%882024-04-0516-19-46.png" alt="Monosnapsurvey_demo_data-Googleスプレッドシート2024-04-0516-19-46.png"></p>
<p>つづいて、[変数] タブの <code>EMBEDDING_KEYWORDS</code> に文意の大きさを測定したいキーワードを入力し、[保存]します。</p>
<p>最後に、ターミナルなどの適当な実行環境からエンドポイントへのリクエストを送信します。</p>
<pre><code class="language-bash">curl https://t.karte.io/hook/xxxxxxxx/craft/xxxxxxxx
</code></pre>
<p>問題なく設定できていれば、次のような表示が実現できるはずです。</p>
<p><img src="https://ik.imagekit.io/plaid/4ee22366-446e-452e-8653-dbfaa0fdf048/Monosnapsurvey_demo_data-Google%E3%82%B9%E3%83%95%E3%82%9A%E3%83%AC%E3%83%83%E3%83%88%E3%82%99%E3%82%B7%E3%83%BC%E3%83%882024-04-0514-40-59.png" alt="Monosnapsurvey_demo_data-Googleスプレッドシート2024-04-0514-40-59.png"></p>
<p>なおKARTE Datahubの<a href="https://developers.karte.io/docs/datahub-federation-table">フェデレーションテーブル</a>機能を使うことで、スプレッドシート上のデータに対してDatahubからSQLクエリを発行し、スプレッドシート上のデータを直接抽出することができます。その結果をDatahubのダッシュボードで可視化したり、紐付けテーブルにエクスポートしてKARTE上のユーザーに紐付けてセグメント条件に利用したりといった活用もできます。</p>
<h2>補遺1：スコアの算出の仕方</h2>
<p>文意の大きさを算出する際、本ソリューションでは以下の流れで数値計算を行なっています。</p>
<ol>
<li>Craft Functions変数で指定したキーワードを Text Embeddings によりベクトル化</li>
<li>スプレッドシートから入力されたテキストを Text Embeddings によりベクトル化</li>
<li>2つのベクトルのコサイン類似度を計算したものを文意の大きさとして採用</li>
</ol>
<h2>補遺2：ユークリッド距離を使って文意の大きさを算出する</h2>
<p>ユークリッド距離を使って文意の大きさを算出することもできます。ユークリッド距離を用いた文意の大きさの算出を有効化するには Craft Functions の[コード]の中から以下の行を検索し、該当行のコメントアウト、及びコメントインを行った上で[保存]してください。</p>
<pre><code class="language-javascript">async function outputData(sheets, scores) {
  const scoresFlatten = scores.slice(1).map(score =&gt; {
    const wk = [
      score.input,
      // コサイン類似度によりスコアリング
      ...score.scores.map(_score =&gt; _score.scoreDotProduct),
      // ユークリッド距離によりスコアリング
      // （使用するには、コサイン類似度によるスコアリングをコメントアウトし、以下の行をコメントインする）
      // ...score.scores.map(_score =&gt; _score.scoreEuclideanDistance),
    ];
    return wk;
  });
  const header = ['input', ...EMBEDDING_KEYWORDS.split(',')];

  // A1行にデータを出力
  updateSsValues(sheets, `${SHEET_NAME}!A1:Z`, [header, ...scoresFlatten]);
}
</code></pre>
<p>ユークリッド距離を使った算出では、埋め込みベクトル同士の幾何学的な距離（L2ノルム）を文書同士の類似度とみなします。ユークリッド距離を尺度とする場合、数値が0に近いほど元の文書の文意に近いと解釈します。コサイン類似度とは類似度の大小関係が逆になる点に注意してください。また、算出される数値の値域は 0~2 の間となります。</p>
<h2>おわりに</h2>
<p>今回は、KARTE Craft AIモジュールを使ったアンケートデータの高度な分析について紹介しました。大量のテキストデータの中から、感情情報や傾向を効率的に抽出できる強力な機能だと言えるでしょう。</p>
<p>アンケートを活用して顧客理解を深めることは、企業にとって重要な取り組みです。KARTE Craft AIモジュールを活用すれば、そのプロセスを大幅に効率化できます。ぜひ、この機能を活用して、アンケートデータの高度な分析に挑戦してみてください。</p>
<p>より深い顧客洞察が得られることで、製品・サービスの改善にもつながるはずです。KARTE Craft AIモジュールを最大限活用し、顧客理解を深めていきましょう！</p>
<hr>
<p>プレイドでは、世の中にインパクトを与える新しいソリューションを一緒につくる仲間を募集しています！ぜひ気軽にお問い合わせください。</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/general-customer-engineer">Customer Engineer | 募集ポジション | 株式会社プレイド</a></li>
<li><a href="https://recruit.plaid.co.jp/requisitions/product-engineer">Product Engineer | 募集ポジション | 株式会社プレイド</a></li>
</ul>


自由記述のテキストに含まれる感情の強さを、ベクトル埋め込みにより肯定的/否定的などの感情ごとにスコア化します。

AIがテキストの意味的要素を数値化！KARTE Craft AI Modulesを使ったテキスト分析

Craft FunctionsからGoogle Analytics Data APIを利用し、GA4のファネル分析レポートを作成する方法を紹介します。

Craft FunctionsからGoogle Analytics Data APIを利用し、GA4のファネル分析レポートを作成する方法

<p>こんにちは、Customer EngineerのUGです！最近、肩の筋トレの成果が出てきて喜んでいます！</p>
<p>みなさんはWebページに来訪してくれたユーザーが花粉がたくさん飛んでいるエリアからアクセスして来た時に花粉症対策用の製品のレコメンドしたりしたいと考えたことは有りませんか？そこまでピンポイントなことは考えていなくても、ユーザーアクセスしているエリアの花粉情報を使ってなんか施策が考えられるかもなぁくらいは思ったことがあるのではないでしょうか？今回はGoogle Maps Platformの新機能である<a href="https://developers.google.com/maps/documentation/pollen/overview?hl=ja">Pollen API</a>を使って、Webブラウザ側から取得したユーザーの緯度経度のエリアの花粉情報をKARTEにイベントとして連携してみたいと思います！</p>
<h2>アウトプットイメージ</h2>
<p>最終的なアウトプットイメージは次の通りです。下記の画像のようにユーザーのアクセスしてきたエリアの花粉情報がイベントとしてKARTE側に発生している状態になります。<br>
<img src="https://ik.imagekit.io/plaid/a29eaf2f-7eb2-4862-93b3-97bd3261faf7/%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-03-1617.21.24.png" alt="スクリーンショット2024-03-1617.21.24.png"></p>
<p>位置情報を利用する前に下記のようなダイアログでエンドユーザーに許諾を取ります。<br>
<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"></p>
<p>構成図は次の通り。<br>
<img src="https://ik.imagekit.io/plaid/c673bc32-7b0c-4787-a57c-f61be62c3f7d/%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-03-1618.09.55.png" alt="スクリーンショット2024-03-1618.09.55.png"></p>
<p>Webブラウザから緯度経度情報を取得してCraft Functionsに連携します。その情報を下にGoogle Maps PlatformのPollen APIを利用して、花粉情報を取得してKARTEイベントを発生させます。今回のブログでは緯度経度をWebブラウザ側から連携するためにKARTE Actionのスクリプト配信を利用します。スクリプト配信でなくとも今回のCraft Functionsは利用可能です。</p>
<h2>注意点</h2>
<p>前提として、次の点に注意をしてください。</p>
<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">課金が発生する可能性</a>があります</li>
</ul>
</li>
</ul>
<h2>設定手順</h2>
<p>設定の手順は次の通りです。</p>
<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>
<p>順番に見てみましょう。</p>
<h3>1. Craft Functionsのファンクションを作成する</h3>
<p>Craft Functionsのファンクションを作成します。作成手順は次の通りです。</p>
<p><img src="https://ik.imagekit.io/plaid/f54845aa-6834-475f-ad9d-dfaf4b0ef4c5/create_craft_functions.png" alt="create_craft_functions.png"></p>
<ul>
<li>[Craft &gt; ファンクション &gt; 新規作成 &gt; テンプレートから作成] を選択</li>
<li>「 <strong>ブラウザ側から緯度経度の情報を取得して、Craft functionsからGoogle Maps PlatformのPollen APIを利用して花粉情報を取得してKARTEイベントを発生させる</strong> 」というテンプレートを検索し[取得]ボタンをクリック</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>
<p>なお、テンプレートのソースコードはGitHubで公開しています。<br>
<a href="https://github.com/plaidev/craft-codes/tree/main/craft-functions/pollen-api">craft-codes/craft-functions/pollen-api at main · plaidev/craft-codes</a></p>
<h3>2. Craft Functionsのエンドポイントを作成する</h3>
<p>作成したファンクションを外部から実行できるようにするためのエンドポイントを作成します。</p>
<p><img src="https://ik.imagekit.io/plaid/d76f89a5-49ec-425a-909c-729c7469bfa2/create_craft_functions_endpoint.png" alt="create_craft_functions_endpoint.png"></p>
<ul>
<li>作成したファンクションの編集画面から [設定 &gt; エンドポイント &gt; 作成] をクリック</li>
<li>表示されたエンドポイントURLをメモしておく</li>
</ul>
<h3>3. API v2 アプリを作成する</h3>
<p>KARTEのAPIを利用するために、API v2アプリを作成します。<br>
<img src="https://ik.imagekit.io/plaid/a1b20746-4140-441d-8e46-3a5a74dc11ab/create_API_v2_App.png" alt="create_API_v2_App.png"></p>
<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>4. API v2 アプリの アクセストークンを Craft Secret Manager に登録する</h3>
<p>API v2 アプリのアクセストークンをCraft Functionsから安全に利用するために、Craft Secret Manager に登録します。</p>
<p><img src="https://ik.imagekit.io/plaid/6f229ee9-39aa-4e47-be81-f615f3b448f8/create_craft_secret.png" alt="create_craft_secret.png"></p>
<ul>
<li>[Craft &gt; シークレット] からシークレットを新規作成</li>
<li>[名前] に、わかりやすい名前を入力</li>
<li>メモしておいたAPI v2 アプリのアクセストークンを [シークレットの値] に入力し、作成</li>
<li>シークレット名をメモしておく</li>
</ul>
<h3>5. Google Cloud PlatformでAPIキーを発行する</h3>
<p>Google Maps APIを利用するために、GCPにてAPIキーを発行します。<br>
GCPを利用したことがない方に関してはプロジェクトの作成から始めてください。参考までに<a href="https://cloud.google.com/resource-manager/docs/creating-managing-projects?hl=ja">GCPの公式ドキュメントはこちら</a>になります。</p>
<ul>
<li>[APIとサービス &gt; 認証情報 &gt; 認証情報を作成] からAPIキーを作成する</li>
<li>作成したAPIキーが以下のAPIを利用できるか確認してください
<ul>
<li>Pollen API</li>
</ul>
</li>
</ul>
<p>参考までに私が作成した際のコンソールの画面は下記になります。<br>
<img src="https://ik.imagekit.io/plaid/56a350ca-1bcf-477d-b5b0-c455bec7446d/%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-03-1618.19.29.png" alt="スクリーンショット2024-03-1618.19.29.png"></p>
<h3>6. KARTE Actionからスクリプト接客を配信する</h3>
<p>Webブラウザから緯度経度情報をCraft Functionsに連携するために、KARTE Actionの接客サービスからスクリプト配信します。</p>
<ul>
<li>[KARTE Action &gt; 接客サービス] からスクリプト配信の接客を作成する</li>
<li>緯度経度を取得したいページとタイミングで配信する</li>
</ul>
<p>スクリプトの例として今回のブログの検証では下記のスクリプトを配信しています。参考スクリプトと接客アクションの編集画面は以下になります。<br>
<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"></p>
<pre><code>if (navigator.geolocation) {
    navigator.geolocation.getCurrentPosition(sendPositionToServer, handleError);
} else {
    alert(&quot;Geolocation is not supported by this browser.&quot;);
}

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

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

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

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

</code></pre>
<p>問題なければ以下のように緯度経度取得のためのダイアログが表示されます。<br>
<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"></p>
<h2>実際に動かしてみる</h2>
<p>実際に動作を確認してみましょう。<br>
まずはスクリプト配信をしているページでユーザーが訪問したら以下のようなダイアログが表示されます。<br>
<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"></p>
<p>Craft Functions側でエラーが発生しなければ下記のようなイベントが発生するはずです。<br>
<img src="https://ik.imagekit.io/plaid/a29eaf2f-7eb2-4862-93b3-97bd3261faf7/%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-03-1617.21.24.png" alt="スクリーンショット2024-03-1617.21.24.png"></p>
<h2>おわりに</h2>
<p>今回はWebブラウザ側から取得したユーザーの緯度経度のエリアの花粉情報をCraft Functions × Google Maps PlatformのPollen APIで取得してKARTEのに連携してみました。</p>
<p>これによりユーザーが花粉の多い地域からアクセスしてきた場合に花粉対策商品をレコメンドするといったような事が可能になります！これからのシーズン花粉症で苦しむ方も多いと思いますので是非活用してみてください！</p>
<hr>
<p>プレイドでは、世の中にインパクトを与える新しいソリューションを一緒につくる仲間を募集しています！ぜひ気軽にお問い合わせください。</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/general-customer-engineer">Customer Engineer | 募集ポジション | 株式会社プレイド</a></li>
<li><a href="https://recruit.plaid.co.jp/requisitions/product-engineer">Product Engineer | 募集ポジション | 株式会社プレイド</a></li>
</ul>


KARTE Webのスクリプト配信機能を利用してブラウザ側から緯度経度の情報をCraft functionsに連携して、その情報を元にGoogle Maps PlatformのPollen APIを利用して花粉情報を取得してKARTEイベントを発生させるSolution

「緯度経度」からCraft Functions × Google Maps PlatformのPollen APIで「花粉情報」を取得してKARTEに連携する

Craft FunctionsからGoogle Analytics Data APIを利用し、GA4のユーザーセグメント分析レポートを作成する方法の紹介です。Google Analytics Data APIを使うと、GA4のデータ分析を簡単に行うことができ、今回はユーザーセグメント分析の方法をご紹介します。

Craft FunctionsからGoogle Analytics Data APIを利用し、GA4のユーザーセグメント分析レポートを作成する方法

<p>こんにちは、Customer Engineerの島本です！</p>
<p>先日友達と築地にあるトーセイホテル ココネ築地銀座プレミアに行ってきました！サウナよりも湯船に浸かっている時にどこからか吹いてくる冷風が気持ちよかったです。<br>
<img src="https://ik.imagekit.io/plaid/9cdd01c2-38c0-4f90-ba2a-ae3fadb22528/IMG_1719.jpg" alt="IMG_1719.jpg"></p>
<p>さて、Craft Functionsを使用すると、社内外のさまざまなシステムから情報を取得し、KARTEとの連携をスムーズに行うことができます。ただし、1 実行あたりの起動時間の上限が 10 秒という制約や、KARTE のサーバーサイドAPIのリクエスト制限があるため、複数件レコードを一括で連携するには設計上で工夫が必要でした。</p>
<p>しかし、Craft Functionsを使用してGoogle Cloud Storage にファイル保存することで、複数件レコードを一括で連携することができます！</p>
<h2>構成図</h2>
<p>構成図は次の通り。<br>
<img src="https://ik.imagekit.io/plaid/14fa7717-737d-4ff0-b5ab-ad5dcb5b35aa/blog%E7%94%A8.png" alt="blog用.png"></p>
<p>また、そもそも保存先のGCS の用意ができないという方もいると思いますが、<a href="https://developers.karte.io/docs/about-datahub">KARTE Datahub</a> をご利用頂いている場合は、KARTE からGCS バケットを払い出すことができます！<br>
今回はKARTE が払い出したGCS バケットを利用する方法で紹介します。</p>
<h2>注意点</h2>
<p>取得するデータサイズが大きくなると、APIからデータを取得する時間およびGCS への書き込み時間が伸びて、Craft Functions の実行時間制限を超過する可能性があります。</p>
<p>また、取得したデータがメモリサイズを超過することにより、Craft Functions が異常終了する可能性もあります。実際に処理できるデータ量を検証の上で本ソリューションの利用を検討してください。</p>
<h2>設定手順</h2>
<p>設定の手順は次の通りです。</p>
<ol>
<li>KARTE が払い出したGCS バケットへの権限付与を有効化する</li>
<li>Googleサービスアカウントを払い出す</li>
<li>サービスアカウントに対象バケットへの権限を付与する</li>
<li>サービスアカウントのJSONキーファイルの中身を Craft Secret Manager に登録する</li>
<li>Craft Functions でそのサービスアカウントを使ってファイルを保存する</li>
</ol>
<p>順番に見てみましょう。</p>
<h3>1. KARTE が払い出したGCS バケットへの権限付与を有効化する</h3>
<p>まず、KARTE Datahub の管理画面からGCS バケットへの権限付与を有効化します。</p>
<ul>
<li>グローバルナビゲーションの[データハブ設定]を開く</li>
<li>[サービスアカウント管理]のタブを開く</li>
<li>[GCSバケットへの権限付与済みGoogleサービスアカウント]の部分で、[権限付与]ボタンが表示されているか確認</li>
</ul>
<p><img src="https://ik.imagekit.io/plaid/895df45f-3a23-4868-a17c-4f42a9813625/%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-04-0123.19.18.png" alt="スクリーンショット2024-04-0123.19.18.png"></p>
<p>有効化されていない場合は、営業担当にお問い合わせください。</p>
<h3>2. Googleサービスアカウントを作成する</h3>
<p>払い出しGCS バケットへの権限付与をするGoogleサービスアカウントを払い出します。</p>
<ul>
<li>[Datahub設定] &gt; [サービスアカウント管理]タブを開く</li>
<li>[払い出しGoogleサービスアカウント]の[Googleサービスアカウント作成]ボタンを押す</li>
<li>ダウンロードするkeyFileのキータイプを次の選択肢から選ぶ
<ul>
<li>JSON(推奨)</li>
<li>P12</li>
</ul>
</li>
<li>認証用のkeyFileが自動でダウンロードされる
<ul>
<li><strong>一度しかダウンロードできないため、大切に保管してください</strong></li>
</ul>
</li>
</ul>
<p><img src="https://ik.imagekit.io/plaid/836ee1fa-2e98-4aa6-ad9e-6fdc698db791/%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-04-0123.23.35.png" alt="スクリーンショット2024-04-0123.23.35.png"></p>
<p>ダウンロードしたkeyFileは、後の手順で利用します。</p>
<h3>3. サービスアカウントに対象バケットへの権限を付与する</h3>
<p>払い出したサービスアカウントに対して権限を付与します。</p>
<ul>
<li>[GCSバケットへの権限付与済みGoogleサービスアカウント]の領域で、[権限付与]ボタンを押す</li>
<li>プルダウンから、先ほど払い出したサービスアカウントを選択する</li>
</ul>
<p><img src="https://ik.imagekit.io/plaid/fe23e8b4-3690-474d-8689-59656e6a2343/%E3%83%86%E3%82%99%E3%83%BC%E3%82%BF%E3%83%8F%E3%83%95%E3%82%99%E8%A8%AD%E5%AE%9A_-_%E7%A4%BE%E5%86%85%E6%A4%9C%E8%A8%BC%E7%94%A8_kasumi_shimamoto_-_KARTE.png" alt="データハブ設定_-社内検証用_kasumi_shimamoto-_KARTE.png"></p>
<h3>4. サービスアカウントのJSONキーファイルの中身を Craft Secret Manager に登録する</h3>
<p>Googleサービスアカウントの認証情報をCraft Functions から安全に利用するために、Craft Secret Manager に登録します。</p>
<p><img src="https://ik.imagekit.io/plaid/1cb0539c-a074-47aa-b2f4-569647617236/create_service_account_secret.png" alt="create_service_account_secret.png"></p>
<ul>
<li>[Craft &gt; シークレット] からシークレットを新規作成</li>
<li>[名前] に、わかりやすい名前を入力</li>
<li>ダウンロードしたJSONキーファイルの中身を [シークレットの値] にそのまま入力し、作成</li>
<li>シークレット名をメモしておく</li>
</ul>
<h3>5. Craft Functions でそのサービスアカウントを使ってファイルを保存する</h3>
<p>最後に、実際にCraft Functionsから外部APIを叩いて、GCS バケットに保存してみます。<br>
今回は情報を取得するAPIとして、<a href="https://jsonplaceholder.typicode.com/">JSONPlaceholder</a> を利用します。</p>
<p>作成手順は次の通りです。<br>
<img src="https://ik.imagekit.io/plaid/f54845aa-6834-475f-ad9d-dfaf4b0ef4c5/create_craft_functions.png" alt="create_craft_functions.png"></p>
<ul>
<li>[Craft &gt; ファンクション &gt; 新規作成 &gt; テンプレートから作成] を選択</li>
<li>「 <strong>外部APIから取得したデータをGoogle Cloud Storageにファイル保存する</strong> 」というテンプレートを検索し[取得]ボタンをクリック</li>
<li>[反映] ボタンをクリック</li>
<li>[変数] タブで次の変数の値を設定する
<ul>
<li><code>LOG_LEVEL</code>
<ul>
<li>出力するログのレベルです</li>
</ul>
</li>
<li><code>SERVICE_ACCOUNT_KEY_SECRET</code>
<ul>
<li>先ほど作成したシークレットの名前を指定します</li>
</ul>
</li>
<li><code>API_ENDPOINT</code>
<ul>
<li>データ取得元である外部サービスのAPIエンドポイントです</li>
<li>例：https://jsonplaceholder.typicode.com/posts</li>
</ul>
</li>
<li><code>BUCKET_NAME</code>
<ul>
<li>保存する先のGCS のバケット名です</li>
<li>例：karte-data-{{api_key}}
<ul>
<li>{{api_key}}の部分は、実際のapi_keyに置き換えてください</li>
</ul>
</li>
</ul>
</li>
<li><code>FILE_PATH</code>
<ul>
<li>保存するファイルのパスです</li>
<li>例：test/demo_data.json</li>
</ul>
</li>
</ul>
</li>
<li>[保存] する</li>
<li>デプロイ完了後、[設定 &gt; ファンクションの有効化] にチェックを付ける</li>
</ul>
<p>なお、サンプルコードは、下記URLで公開しています。<br>
<a href="https://github.com/plaidev/craft-codes/tree/main/craft-functions/fetch-external-api-and-save-file-to-gcs">craft-codes/craft-functions/fetch-external-api-and-save-file-to-gcs at main · plaidev/craft-codes</a></p>
<p>以下、重要な点をかいつまんで説明します。</p>
<p>サンプルコードでは、GCS バケット上のファイルをKARTE Datahub に連携したいケースを想定して、Datahub で取り込み可能な改行区切りのJSON データに加工しています。</p>
<p>実際に利用する際には、APIのレスポンスデータ形式に合わせて変更してください。</p>
<pre><code>function formatDataToJSONLines(responseData) {
  return responseData.map(obj =&gt; JSON.stringify(obj)).join('\n');
}
</code></pre>
<p>下記関数でバケット名、ファイルのパスを指定してGCS バケットにファイルをアップロードしています。</p>
<pre><code>async function uploadDataToStorage(bucketName, filePath, jsonLinesData, jsonKey, logger) {
  const storage = new Storage({ credentials: jsonKey });
  const bucket = storage.bucket(bucketName);

  const blob = bucket.file(filePath);
  const stream = blob.createWriteStream({
    metadata: {
      contentType: 'application/json',
    },
  });

  return new Promise((resolve, reject) =&gt; {
    stream.on('error', err =&gt; {
      logger.error('Upload Error:', err);
      reject(err);
    });

    stream.on('finish', () =&gt; {
      logger.log(`Uploaded: ${filePath}`);
      resolve();
    });

    stream.end(jsonLinesData);
  });
}
</code></pre>
<p>とても簡単ですね！</p>
<p>最後に定期的にAPI からデータを取得するために、Craft Scheduler の設定をします。</p>
<p><img src="https://ik.imagekit.io/plaid/1a603aa3-3952-4232-ba1a-b4575047dedd/%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-1318.25.41.png" alt="スクリーンショット2024-02-1318.25.41.png"></p>
<ul>
<li>Craft Functionsの<code>設定タブ</code>を開きます</li>
<li>スケジュールを有効化し、cron形式（JST）で実行時間を指定します</li>
</ul>
<p>設定は以上になります。</p>
<h2>実際に動かしてみる</h2>
<p>実際に動作を確認してみましょう！</p>
<p>前述のサンプルコードに必要な定数を入力した内容でCraft Functionsを作成し、実際に実行してみます。</p>
<p><img src="https://ik.imagekit.io/plaid/3fabf6ee-50c0-4ab5-a195-5ad77a389c16/%E3%83%86%E3%82%99%E3%82%B9%E3%82%AF%E3%83%88%E3%83%83%E3%83%95%E3%82%9A_%E2%80%94_-zsh_%E2%80%94_173%C3%9746.png" alt="デスクトップ_—-zsh—_173×46.png"></p>
<p>gsutilを使ってGCS バケット上に保存されていることを確認できました！</p>
<p><img src="https://ik.imagekit.io/plaid/b19f0ee2-7122-409a-aa43-ef9e617ca054/%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-03-2610.03.39.png" alt="スクリーンショット2024-03-2610.03.39.png"><br>
また、ファイルの中身も改行区切りのJSON データで保存されていることが確認できます。<br>
これで問題なくKARTE Datahub に連携できますね！</p>
<h2>おわりに</h2>
<p>今回は外部APIから取得したデータをGoogle Cloud Storageにファイル保存する方法について紹介しました。</p>
<p>このソリューションを活用すれば、社内外のさまざまなシステムから情報を取得してKARTE Datahub に連携することができるため、できることの幅が広がりますね！ぜひ皆さんも試してみてください！</p>
<hr>
<p>プレイドでは、世の中にインパクトを与える新しいソリューションを一緒につくる仲間を募集しています！ぜひ気軽にお問い合わせください。</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/general-customer-engineer">Customer Engineer | 募集ポジション | 株式会社プレイド</a></li>
<li><a href="https://recruit.plaid.co.jp/requisitions/product-engineer">Product Engineer | 募集ポジション | 株式会社プレイド</a></li>
</ul>


外部APIから取得したデータを改行区切りのJSON形式に整形し、Google Cloud Storageにファイル保存します。

外部APIから取得したデータをGoogle Cloud Storageにファイル保存する

<p>こんにちは、Customer Engineerのgamiです！最近ノンフライヤーを買って揚げ物を揚げまくっています。</p>
<p>さて、KARTEにはLINEと連携する機能があります。特に、LINE公式アカウントと対応するMessaging APIチャネルのWebhook URLにKARTE側エンドポイントを登録することで、友だち追加やメッセージ送信などのLINE側のユーザー行動をKARTE側にリアルタイム連携することができます。</p>
<p>一方で、 <strong>LINE Messaging APIチャネルのWebhook URLには「複数URLを登録できない」という仕様があり、これが問題になるケースがあります</strong> 。具体的には、KARTE以外にLINE公式アカウントのWebhookを連携したい外部サービスを利用している場合、LINEのWebhook URLにKARTEのエンドポイントを登録してしまうと、もう一つの外部サービスにLINEのWebhookを送れなくなってしまうという問題です。</p>
<p>実はこの問題は、 <a href="https://craft.developers.karte.io/craft-functions/triggers/line-hook">Craft LINE Hook</a> というトリガーを利用してCraft Functionsを起動することで、解消することができます。</p>
<p>今回は、KARTE CraftでLINEのMessaging API WebhookをKARTE以外の別サービスに分岐させる方法について紹介します。</p>
<h1>想定する状況</h1>
<p>この記事では、次のような状況を想定してます。</p>
<ul>
<li>LINE公式アカウントを運用している</li>
<li>それに紐付くMessaging APIチャネルのWebhook URLには、KARTE以外の外部サービスのエンドポイントが登録されている</li>
<li>その外部サービスとLINEとの連携を維持したまま、LINE Webhookを新たにKARTEにも連携させたい</li>
<li>KARTEプロジェクト側で、KARTEのLINE連携オプションがすでに有効になっている
<ul>
<li>詳細: <a href="https://support.karte.io/post/2Qw6muPU7a5PSKV0M8ler0">LINE連携 - 概要 | ドキュメント / 接客タイプ / LINE | KARTEサポートサイト</a></li>
</ul>
</li>
</ul>
<h1>アウトプットイメージ</h1>
<p>構成図は次の通りです。</p>
<p><img src="https://ik.imagekit.io/plaid/525e0478-5be4-44b0-9a5c-9562bd4990b4/%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-1118.31.01.png" alt="スクリーンショット2023-12-1118.31.01.png"></p>
<p>LINE Messaging APIのWebhookを一度KARTE側エンドポイントで受けた上で、それをCraft Functionsを介して外部サービスに連携します。</p>
<h1>手順</h1>
<p>設定手順は次の通りです。</p>
<ol>
<li>Craft Functionsを作成する</li>
<li>Craft LINE Hookトリガーを設定する</li>
<li>LINE Messaging APIのWebhook URLをKARTE側エンドポイントに切り替える</li>
</ol>
<p>順番に説明します。</p>
<h2>1. Craft Functionsを作成する</h2>
<p>まずはLINE Webhookで受け取ったデータを外部サービスに連携するためのCraft FunctionsのFunctionを作成します。サンプルとなるソースコードは、Craft FunctionsのテンプレートとしてGitHubで公開しています。</p>
<p><a href="https://github.com/plaidev/craft-codes/tree/main/craft-functions/line-webhook-branch">craft-codes/craft-functions/line-webhook-branch at main · plaidev/craft-codes</a></p>
<p>作成手順は次の通りです。</p>
<ul>
<li>[Craft &gt; ファンクション &gt; 作成 &gt; テンプレートから作成] を選択</li>
<li><code>KARTE CraftでLINEのMessaging API Webhookを別サービスに分岐する</code> というテンプレートを検索し「取得」ボタンをクリック</li>
<li>「反映」ボタンをクリック</li>
<li>[変数] タブで次の変数の値を設定する
<ul>
<li><code>TARGET_URL</code>: LINEのWebhookを送信したい外部サービスのエンドポイントURL</li>
</ul>
</li>
<li>Functionを有効化して保存</li>
</ul>
<p>変数TARGET_URLの値には、元々LINE Messaging APIチャネルのWebhook URLに登録していたのと同じ外部サービス側URLを指定してください。</p>
<h2>2. Craft LINE Hookトリガーを設定する</h2>
<p>Craft Functionsが作成できたら、ファンクションをトリガーするためのCraft LINE Hookの設定をします。</p>
<ul>
<li>[Craft &gt; 設定 &gt; LINE Hook 設定] を編集します</li>
<li>次のように設定します
<ul>
<li>[有効化 &gt; 有効にする] にチェック</li>
<li>[起動ファンクション] で作成したファンクションを選択</li>
</ul>
</li>
<li>[保存] します</li>
</ul>
<p><img src="https://ik.imagekit.io/plaid/336156bc-158a-4748-af73-a3fc0a5fa490/%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-1118.42.53.png" alt="スクリーンショット2023-12-1118.42.53.png"></p>
<p>これによって、KARTEがLINEからWebhookを受け取る度に、「起動ファンクション」に設定したファンクションが毎回実行されるようになります。ファンクションには、LINE Webhookから受け取ったデータが実行時に渡されます。</p>
<p>Craft LINE HookやそこからCraft Functionsに送信されるデータの詳細については、下記ドキュメントをご覧ください。<br>
<a href="https://craft.developers.karte.io/craft-functions/triggers/line-hook">Craft LINE hook</a></p>
<h2>3. LINE Messaging APIのWebhook URLをKARTE側エンドポイントに切り替える</h2>
<p>最後に、LINE Developerの管理画面にログインし、Messaging APIのWebhook URLをKARTE側エンドポイントに切り替えます。</p>
<ul>
<li>LINE Developersにログイン</li>
<li>対象のMessaging APIチャネルの設定を開く</li>
<li>[Messaging API設定] タブの [Webhook設定] にKARTE側エンドポイントURLを設定し、保存する
<ul>
<li>URL形式: <code>https://t.karte.io:443/hook/API_KEY/line/line_message</code>
<ul>
<li>※ API_KEYの部分は、対象KARTEプロジェクトのAPIキーを設定します</li>
</ul>
</li>
</ul>
</li>
</ul>
<p><img src="https://ik.imagekit.io/plaid/07218866-abde-4a12-b21d-96be6f407fe5/%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-1214.12.04.png" alt="スクリーンショット2023-12-1214.12.04.png"></p>
<p>なお、すでにKARTE側エンドポイントURLが登録されている場合は変更する必要はありません。</p>
<p>LINE Messaging APIとKARTEの連携設定については下記ドキュメントをご覧ください。<br>
<a href="https://support.karte.io/post/1xH2Z6UG3EVX7hNkJagwgS">LINE連携 - 初期設定 | ドキュメント / 接客タイプ / LINE | KARTEサポートサイト</a></p>
<h1>実際に動かしてみる</h1>
<p>実際に動作を確認してみましょう。</p>
<ul>
<li>KARTE側にLINE Webhook経由のデータが連携されていることを確認する
<ul>
<li>手順例
<ul>
<li>手元のLINEアプリから、当該LINE公式アカウントを友だち追加</li>
<li>当該LINE公式アカウントに対してメッセージ送信</li>
<li>KARTEのイベント画面で、 <code>plugin_line_identify</code> イベントや <code>_line_message</code> イベントが発生していることを確認
<ul>
<li>参考: <a href="https://support.karte.io/post/5MJWz1WC2y2krpincZZhph">LINE関連で発生するイベント | KARTEサポートサイト</a></li>
</ul>
</li>
</ul>
</li>
</ul>
</li>
<li>外部サービス側でLINE Webhook経由のデータが連携されていることを確認する</li>
</ul>
<p>設定に問題がなければ、当該LINE公式アカウント上でのエンドユーザーの友だち追加やメッセージ送信に関するデータが、KARTEと外部サービスの両方にリアルタイム連携されることが確認できます。</p>
<h1>注意点</h1>
<ul>
<li>LINE Messaging APIのWebhookをすでに外部サービスで利用している場合は、Webhook URLの変更によって当該サービスの挙動に影響が出る可能性があります。影響範囲の確認や動作検証を十分に行った上で、設定変更をしてください</li>
<li>Craft Functionsの仕様上、ごく稀にファンクションが重複実行される可能性があります。重複実行の可能性を許容できない場合は、重複実行を回避するためにファンクションの実装を変更してください
<ul>
<li><a href="https://solution.plaid.co.jp/implementing-exactly-once-semantics-in-karte-craft">KARTE Craftでファンクションの重複実行を防ぐ</a></li>
</ul>
</li>
</ul>
<h1>おわりに</h1>
<p>LINEはエンドユーザーとの接点を持つ上で非常に魅力的なプラットフォームです。一方で、LINE Messaging APIチャネルの「Webhook URLを複数登録できない」という仕様によって、複数サービスとの同時連携が難しいという課題があります。</p>
<p>この課題がKARTEとLINEとの連携の障壁になる場合は、ぜひ今回紹介したCraft Functionsを使ったLINE Webhookの分岐をご検討ください！</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/general-customer-engineer">Customer Engineer | 募集ポジション | 株式会社プレイド</a></li>
<li><a href="https://recruit.plaid.co.jp/requisitions/product-engineer">Product Engineer | 募集ポジション | 株式会社プレイド</a></li>
</ul>


LINE Messaging APIチャネルのWebhook URLには「複数URLを登録できない」という仕様があり、複数サービスと連携できないという問題があります。これを回避するためにKARTE CraftでLINEのMessaging API WebhookをKARTE以外の別サービスに分岐させる方法について紹介します。

KARTE CraftでLINEのMessaging API Webhookを別サービスに分岐する

<p>こんにちは、Customer Engineerの池上です！最近は漫画『呪術廻戦』を読み直しています。真希さんかっこいい。</p>
<p>さて、先日PLAIDのCustomer EngineerとAPI開発チームを中心に「ソリューション開発オフサイト」を開催しました。今回はオフサイトの様子と、そこで生まれたソリューションについて紹介します。</p>
<h1>ソリューション開発オフサイトについて</h1>
<p>「ソリューション開発オフサイト」は、丸一日社外のレンタルスペースを借りて実施します。オフサイト中は、ソリューション開発基盤としてのKARTEを使って、参加メンバー各自がもくもくとソリューション開発をします。</p>
<p>今回は2回目の開催で、 <a href="https://ecosystem.plaid.co.jp/product/karte-craft">KARTE Craft</a> を使ったソリューションを中心に、各自でテーマを決めて開発をしました。</p>
<h1>オフサイト会場</h1>
<p>今回の会場も、前回と同じく <a href="https://zen-building.com/">Akasaka Zen Space</a> さん。スタイリッシュな会議室に和室と日本庭園が付いた、快適なレンタルスペースでした。</p>
<p>（※以下、キレイな写真は<a href="https://zen-building.com/">公式サイト</a>より）</p>
<p><img src="https://ik.imagekit.io/plaid/1f2ca545-cae8-448f-8e32-371cee88c50d/17.jpg" alt="17.jpg"></p>
<p><img src="https://ik.imagekit.io/plaid/7cc168d2-fa7f-4b5e-8724-e128df6fcf12/23.jpg" alt="23.jpg"></p>
<h1>当日の様子</h1>
<p>オフサイトには、Customer Engineerと、APIやCraftなどの開発を担当するEcosystem APIチームのエンジニアやデザイナーなど、総勢13名が参加しました。</p>
<p>まず最初に、各自が「今日作るソリューション」の宣言をしました。ソリューションの種となるアイデアは、元々チーム内で「こんなこともできるよね」と話していたものから、自分で独自に考えてきたものまで様々です。</p>
<p>その後は、各自でもくもくと開発。</p>
<p><img src="https://ik.imagekit.io/plaid/14fd366d-6797-410b-865d-1ff15342bb6f/01.png" alt="01.png"></p>
<p>畳スペースで作業するメンバーも。</p>
<p><img src="https://ik.imagekit.io/plaid/ea94dc2d-230d-4faf-8edd-6b2ace8933fb/02.png" alt="02.png"></p>
<p>ときには設計の相談や技術的な質問を他のメンバーにぶつけながら、アウトプットを形にしていきます。</p>
<p>赤坂の街にランチに行った後も、少し眠くなりながら開発を続けました。畳があるので、疲れたらすぐに休憩できていいですね。</p>
<p><img src="https://ik.imagekit.io/plaid/4d51a3a6-108a-44ff-a5f0-e0c331ca7f1c/03.jpg" alt="03.jpg"></p>
<p>オフサイトは夜まで続きました。</p>
<p><img src="https://ik.imagekit.io/plaid/3cca0da3-81f5-4b95-a2de-cac40bc3b861/04.jpg" alt="04.jpg"></p>
<p>最後に、会場のモニターに投影しながら各自が開発したソリューションについてデモを交えながら発表しました。実際に提案できそうなソリューションが出てくると、参加者からの質問もたくさん飛び交い、大盛りあがりでした。</p>
<p><img src="https://ik.imagekit.io/plaid/05d6c4dc-50a1-4529-ac9c-2b0625287e0c/05.png" alt="05.png"></p>
<p>オフサイトの後は打ち上げに行き、楽しい夜を過ごしました。</p>
<p><img src="https://ik.imagekit.io/plaid/4fe97d6d-a595-4cd0-beae-320ddce77812/07.png" alt="07.png"></p>
<h1>オフサイトで生まれた主なソリューション</h1>
<p>すでにソリューションブログに公開されたいくつかの記事は、今回のソリューション開発オフサイトでの開発がネタ元となっています。</p>
<ul>
<li><a href="https://solution.plaid.co.jp/202311-uu-per-item-counter">「いま何人がこの商品を見ています」施策をKARTE Craftで独自実装する</a></li>
<li><a href="https://solution.plaid.co.jp/202311-accountengagement-connect">Account Engagement（旧 Pardot）から取得したプロスペクト情報を KARTE にイベント送信する</a></li>
<li><a href="https://solution.plaid.co.jp/202312-new-assignment-slack-notification">KARTE Talkで担当者がアサインされた場合にSlack通知する</a></li>
</ul>
<p>1日もあればサクッとこのような機能開発ができてしまうのは、開発プラットフォームとしてのKARTEやCraftの魅力ですね！</p>
<h1>おわりに</h1>
<p>今回はソリューション開発オフサイトや、そこで誕生したソリューションについて紹介しました。今後も皆さんの役に立つソリューションを開発 &amp; 発信していきます！</p>
<p><img src="https://ik.imagekit.io/plaid/e8f9e6c3-3070-420e-a1ff-9045b77bef78/06.jpg" alt="06.jpg"></p>
<hr>
<p>プレイドでは、世の中にインパクトを与える新しいソリューションを一緒につくる仲間を募集しています！<br>
ぜひ気軽にお問い合わせください。</p>
<p>↓ PLAIDで働きたい</p>
<ul>
<li><a href="https://recruit.plaid.co.jp/requisitions/general-customer-engineer">Customer Engineer | 募集ポジション | 株式会社プレイド</a></li>
<li><a href="https://recruit.plaid.co.jp/requisitions/product-engineer">Product Engineer | 募集ポジション | 株式会社プレイド</a></li>
</ul>
<p>↓ パートナー企業になりたい</p>
<ul>
<li><a href="https://ecosystem.plaid.co.jp/">CustomerData-Driven Solution を一緒に創りませんか？ | PLAID Ecosystem</a></li>
</ul>


ソリューション開発基盤としてのKARTEやCraftを使って参加メンバー各自がもくもくとソリューション開発をする、「ソリューション開発オフサイト」に行ってきました。

「KARTE & Craft ソリューション開発オフサイト」に行ってきました！ (2023年 秋)

<p>こんにちは、Customer Engineeringの清水です！<br>
最近、休日の朝活にハマっていて週1で皇居ランをしています！</p>
<p>さて、KARTE Talkではチャット・メール・SMS・LINE・プッシュ通知などのツールでお客様とコミュニケーションを取ることが出来ますが、円滑なコミュニケーションをとる目的で「担当者がアサインされた時に通知を飛ばしたい」と思ったことはないでしょうか？</p>
<p>例えば次のようなケースです。</p>
<ul>
<li>自分が担当したいけれど、手が空いてなくて他の人に担当してもらいたい。KARTE Talkで担当者を変更すると、その内容が通知されるようにしたい。</li>
</ul>
<p>今回は、KARTEの「Hook v2」機能と「Craft Functions」を使ってKARTE Talkの担当者がアサインされた時にSlackに通知を飛ばす方法を紹介します。</p>
<p>以下のようなメッセージが、通知されるようになります。<br>
<img src="https://ik.imagekit.io/plaid/d8f28166-35b0-4e86-9751-3cf426730ff6/%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-1111.51.22.png" alt="スクリーンショット2023-12-1111.51.22.png"></p>
<h1>全体像</h1>
<p>実現する処理の全体像は、次の通りです。<br>
<img src="https://ik.imagekit.io/plaid/7d454285-8510-43cd-83a0-642644031264/20231124_1603.png" alt="20231124_1603.png"><br>
KARTE TalkとCraft Functionsの連携では、次の2つの機能を利用します。</p>
<ul>
<li><a href="https://developers.karte.io/reference/assign-hook-v2">Hook v2 の Assign Hook</a>
<ul>
<li>KARTE Talk で担当オペレーターが変更されたことをトリガーに、新しい担当オペレーターの情報を hook する</li>
</ul>
</li>
<li><a href="https://craft.developers.karte.io/craft-functions/triggers/hook-v2">Craft Hook v2 トリガー</a>
<ul>
<li>Hook v2 起動時に Craft Functions を実行する</li>
</ul>
</li>
</ul>
<h1>実装手順</h1>
<p>実装の手順は次の通りです。</p>
<ol>
<li>Slackアプリを作成する</li>
<li>Slackアプリをチャンネルに追加する</li>
<li>API v2アプリを作成する</li>
<li>Slack アプリの OAuth トークンを Craft Secret Manager に登録する</li>
<li>Craft Functions を作成する</li>
<li>Craft Hook v2 トリガーを設定する</li>
</ol>
<p>順番に説明します。</p>
<p>まず、手順1,2,4は以前に投稿した記事、<br>
「<a href="https://solution.plaid.co.jp/202307-hookv2-slack-integration">KARTE CraftでKARTEの接客ステータス変更時にSlack通知をする</a>」<br>
の同見出しの手順と全く同じです。ここでは、手順3,5,6を説明します。</p>
<h2>3. API v2アプリを作成する</h2>
<p>Assign Hookを利用するためのAPI v2アプリを作成します。</p>
<p><img src="https://ik.imagekit.io/plaid/80e19272-b6da-44a6-926b-92b10e97683c/%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-0115.50.16.png" alt="スクリーンショット2023-12-0115.50.16.png"></p>
<ul>
<li>[ストア &gt; API v2設定] からアプリを新規作成</li>
<li>[アプリの種類] を<code>token</code>に設定</li>
<li>Scopeとして<code>talk.operator.get</code>を追加</li>
</ul>
<p>※「アプリの種類」は後から変更できないため、誤って作成した場合は、アプリを再度作成し直してください。</p>
<h2>5. Craft Functions を作成する</h2>
<p>Slackに通知を飛ばすためのCraft Functions のファンクションを作成します。<br>
サンプルとなるソースコードは、Craft FunctionsのテンプレートとしてGitHubで公開しています。</p>
<p><a href="https://github.com/plaidev/craft-codes/tree/main/craft-functions/new-assignment-slack-notification">craft-codes/craft-functions/new-assignment-slack-notification at main · plaidev/craft-codes</a></p>
<p>実装内容は、次のとおりです。</p>
<ol>
<li>Hook v2経由で新しい担当オペレーターの情報を受け取る</li>
<li>Slack に通知するメッセージ内容を作成</li>
<li>Slack API の chat.postMessage を使ってメッセージを送信</li>
</ol>
<p>Craft Functions作成画面のコードタブのコードにサンプルコードのindex.js の内容を貼り付け、モジュール に modules.json の内容を貼り付けます。また、以下の3つをCraft Functions作成画面の変数タブで指定します。</p>
<table>
<thead>
<tr>
<th>変数名</th>
<th>概要</th>
</tr>
</thead>
<tbody>
<tr>
<td>KARTE_PROJECT_ID</td>
<td>KARTEのプロジェクトID</td>
</tr>
<tr>
<td>SLACK_CHANNEL_ID</td>
<td>送信先のSlackチャンネルID</td>
</tr>
<tr>
<td>SLACK_TOKEN_SECRET</td>
<td>手順4でCraft Secret Managerに登録したSlack アプリの OAuth トークン</td>
</tr>
</tbody>
</table>
<p>サンプルコードでは、Slack に通知するメッセージについて、割り当て先が未担当か未担当でないかによって通知するメッセージを出し分けています。</p>
<pre><code>  let msg;
  if (operatorName === '未担当') {
    msg = `KARTE Talkのチャットでアサインが「未担当」になりました。\n`;
  } else {
    msg = `KARTE Talkのチャットでアサインが${operatorName}さんになりました。\n`;
  }
  msg += `新規アサインされた担当のuser_idは${assignedUser}です。\n`;
  msg += `Talk画面はこちらです。https://admin.karte.io/communication/v2/redirect_from_v1/${assignedUser}?project=${KARTE_PROJECT_ID}`;

  // Slack APIのchat.postMessageを使ってメッセージを送信
  await slackClient.chat.postMessage({
    channel: SLACK_CHANNEL_ID,
    text: msg,
  });

</code></pre>
<h2>6. Craft Hook v2 トリガーを設定する</h2>
<p>最後にKARTE Talkでオペレータのアサインが変更される度にファンクションが実行されるように Hook v2 の設定をします。 Hook v2 の設定は API v2 アプリ上で行います。</p>
<p><img src="https://ik.imagekit.io/plaid/26d8dc69-5bff-4c0f-adbb-f56b1ec3f9d4/%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-0115.54.57.png" alt="スクリーンショット2023-12-0115.54.57.png"></p>
<ul>
<li>「2. API v2 アプリを作成する」で作成したアプリの設定画面を開く</li>
<li>[トリガー設定] に <code>KARTE Talk: オペレータのアサイン時</code> を指定</li>
<li>[チャネル設定 &gt; Craft] を有効化し、先ほど作成したファンクション名を入力</li>
</ul>
<p>これで、担当オペレーターが変更された時に先ほど作成したファンクションが実行され、Slackに通知が飛ぶ設定が完了しました。</p>
<h1>実際に動かしてみる</h1>
<p>KARTE Talkで担当者がアサインされた場合にSlack通知する実装が完成しました。<br>
実際に動作を確認してみましょう。</p>
<p>まず、「有効化」にチェックが入っていることを確認します。<br>
<img src="https://ik.imagekit.io/plaid/1b8f0459-cf97-42ea-9875-00d53536d13d/%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-0115.40.54.png" alt="スクリーンショット2023-12-0115.40.54.png"></p>
<p>KARTE Talk画面を開き、担当者を未担当から適当に変更してみます。<br>
<img src="https://ik.imagekit.io/plaid/8773576b-466c-4f94-a75a-4118fb42aa8d/%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-1113.27.15.png" alt="スクリーンショット2023-12-1113.27.15.png"></p>
<p>指定した Slack チャンネルに作成した Slack アプリから通知が飛んできました。<br>
<img src="https://ik.imagekit.io/plaid/ff6ee934-c2e0-4210-9e9f-a38751cca96c/%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-1118.26.24.png" alt="スクリーンショット2023-12-1118.26.24.png"></p>
<h1>おわりに</h1>
<p>今回は「KARTE Talkで担当者がアサインされた場合にSlack通知する」方法を紹介しました。<br>
他にも、Talkのメッセージ送信時など各種トリガーからファンクションの実行が可能となっており、様々な応用が可能です。</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/general-customer-engineer">Customer Engineer | 募集ポジション | 株式会社プレイド</a></li>
<li><a href="https://recruit.plaid.co.jp/requisitions/product-engineer">Product Engineer | 募集ポジション | 株式会社プレイド</a></li>
</ul>


KARTE Craftを使って「KARTE Talkで担当者がアサインされた場合にSlack通知する」方法について紹介します。

KARTE Talkで担当者がアサインされた場合にSlack通知する

人々の暮らしに関わるサービスにおいて、気温はユーザーの購買に影響をもたらすので、気温が10℃付近になった都道府県に対して、購買を促すことをKARTE Craft・Datahub・Messageを使って配信する。

ユーザーの居住地の気温が10℃以下になった地域に KARTE Message で自動メール配信する方法を解説！

<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/general-customer-engineer">Customer Engineer | 募集ポジション | 株式会社プレイド</a></li>
<li><a href="https://recruit.plaid.co.jp/requisitions/product-engineer">Product 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/general-customer-engineer">Customer Engineer | 募集ポジション | 株式会社プレイド</a></li>
<li><a href="https://recruit.plaid.co.jp/requisitions/product-engineer">Product 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/general-customer-engineer">Customer Engineer | 募集ポジション | 株式会社プレイド</a></li>
<li><a href="https://recruit.plaid.co.jp/requisitions/product-engineer">Product 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/general-customer-engineer">Customer Engineer | 募集ポジション | 株式会社プレイド</a></li>
<li><a href="https://recruit.plaid.co.jp/requisitions/product-engineer">Product 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/general-customer-engineer">Customer Engineer | 募集ポジション | 株式会社プレイド</a></li>
<li><a href="https://recruit.plaid.co.jp/requisitions/product-engineer">Product Engineer | 募集ポジション | 株式会社プレイド</a></li>
</ul>


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

Solution Blog

Recent Article

KARTE CraftでLINEのMessaging API Webhookを別サービスに分岐する

「KARTE & Craft ソリューション開発オフサイト」に行ってきました！ (2023年秋)

KARTE Talkで担当者がアサインされた場合にSlack通知する

ユーザーの居住地の気温が10℃以下になった地域に KARTE Message で自動メール配信する方法を解説！

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

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

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

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

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

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

Archives

Writers

Recent Article

KARTE CraftでLINEのMessaging API Webhookを別サービスに分岐する

「KARTE & Craft ソリューション開発オフサイト」に行ってきました！ (2023年 秋)

KARTE Talkで担当者がアサインされた場合にSlack通知する

ユーザーの居住地の気温が10℃以下になった地域に KARTE Message で自動メール配信する方法を解説！

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

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

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

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

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

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

Archives

Writers

「KARTE & Craft ソリューション開発オフサイト」に行ってきました！ (2023年秋)