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にファイル保存する

KARTEのセグメント所属ユーザー数が大幅に変化した場合に、Craft Functionsを使ってSlackに通知する方法です。いつの間にかセグメントに所属するユーザー数が減ってしまったにも関わらず、接客を配信して無駄になってしまうことを防ぐために、セグメントのユーザー数が減ったりした場合にSlackに通知します。

KARTEのセグメント所属ユーザー数が大幅に変化した場合に、Craft Functionsを使ってSlackに通知する方法

Craft FunctionsからCustom Search APIとPageSpeed insights APIを使い、検索上位記事のメタデータとパフォーマンスの相関分析を行う方法です。カスタムサーチAPIとページスピードインサイトのAPIを使うことで、上位コンテンツの分析や自社のコンテンツ戦略策定に役立ちます。

Craft FunctionsからCustom Search APIとPageSpeed insights APIを使い、検索上位記事のメタデータとパフォーマンスの相関分析を行う方法

<p>こんにちは、Customer Engineerの神谷です！最近、ムエタイを習い始めました。今年は総合格闘技の試合にも出たく、打撃にも本腰入れて頑張っていきます！ちなみに得意な打撃技は、ローキックと右オーバーハンドです。</p>
<p>さて今回は、KARTE Talkで新規チャット問い合わせがあった場合に、Craft Functionsを使ってSlackに通知する方法をご紹介します。なぜKARTE Talkで新規チャット問い合わせが来たらSlackに通知できると便利なのか、まずその理由を押さえておきましょう。主に、以下の2つではないでしょうか。</p>
<ul>
<li>問い合わせがあった際にすぐ気づける
<ul>
<li>常にKARTE Talkの画面を注視していられればいいものの、実際はそうもいかない場面もあると思います</li>
<li>そのため、ユーザーから問い合わせが来た際にSlackに通知すれば、そのことに気づきやすくなり、対応も素早くできるようになるでしょう</li>
</ul>
</li>
<li>チームの皆で情報共有可能
<ul>
<li>Slackに通知した際に、グループメンションなどをつけておけば、チーム内の全員に通知が届きます</li>
<li>それにより、対応漏れなどのリスクも低減できる可能性があります</li>
</ul>
</li>
</ul>
<p>このように、KARTE Talkで新規チャット問い合わせが発生した際にSlackに通知することで、ユーザーへの素早い対応やチーム内での情報共有がやりやすくなるでしょう。</p>
<h2>アウトプットイメージ</h2>
<p>KARTE Talkで新規チャット問い合わせが発生した際にSlackに通知することの意義はご理解いただけたと思うので、最終的なアウトプットイメージを、以下に示します。</p>
<p><img src="https://ik.imagekit.io/plaid/2a023ad1-a125-4417-b723-cd228e23c49b/%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-1317.33.19.png" alt="スクリーンショット2024-03-1317.33.19.png"></p>
<p>今回は、問い合わせをしてきたユーザーのユーザーID及び、問い合わせ内容やどこのページで問い合わせが発生したのかをお知らせします。更にKARTE Talkの一覧画面への遷移URLも貼っておけば、それをクリックするだけで、すぐにKARTE Talkを開けます。</p>
<p>続いて、処理の全体像を以下に示します。</p>
<p><img src="https://ik.imagekit.io/plaid/226662ad-a2a1-42ae-be1f-9a38eabdd6d3/%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-1317.32.26.png" alt="スクリーンショット2024-03-1317.32.26.png"></p>
<p>今回は、KARTE TalkとCraft Functionsを連携するのに、以下の2つの機能を利用します。</p>
<ul>
<li><a href="https://developers.karte.io/reference/message-hook-v2">Hook v2 の Message Hook</a>
<ul>
<li>KARTE Talk で新規チャット問い合わせが来たことを外部に連携します</li>
</ul>
</li>
<li><a href="https://craft.developers.karte.io/craft-functions/triggers/hook-v2/index.html">Craft Hook v2 トリガー</a>
<ul>
<li>Hook v2 起動時に Craft Functions を実行します</li>
</ul>
</li>
</ul>
<h2>設定手順</h2>
<p>設定の手順は次の通りです。</p>
<ol>
<li>Slack appを作成し、対象Slackチャンネルに追加する</li>
<li>API v2アプリを作成する</li>
<li>Slack appの OAuth Token を Craft Secret Manager に登録する</li>
<li>Craft Functionsのファンクションを作成する</li>
<li>API v2 アプリにCraft Functions の Hook v2 トリガーを設定する</li>
</ol>
<p>順番に見てみましょう。</p>
<h3>1. Slack appを作成し、対象Slackチャンネルに追加する</h3>
<p>まず、SlackのAPIを利用するためのSlack appを作成してチャンネルへ追加します。</p>
<ul>
<li><a href="https://api.slack.com/apps">SlackのApplications画面</a> から[Create New App]をクリック</li>
<li>Create an appの画面で [From scratch] を選択</li>
<li>Slack app名を入力し、Slackの対象ワークスペースを選択</li>
</ul>
<p><img src="https://ik.imagekit.io/plaid/2de46e75-afc9-4d6f-92a5-444e6a1aa71e/%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-07-1812.57.49.png" alt="スクリーンショット2023-07-1812.57.49.png"></p>
<ul>
<li>作成したappを選択し、[OAuth &amp; Permissions]をクリック</li>
<li>[Scopes &gt; Bot Token Scopes] から次のscopeを追加し保存
<ul>
<li><code>chat:write</code></li>
</ul>
</li>
</ul>
<p><img src="https://ik.imagekit.io/plaid/0696d92f-ec7b-4c5d-9327-cddfbc143039/%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-07-1813.01.11.png" alt="スクリーンショット2023-07-1813.01.11.png"></p>
<ul>
<li>[OAuth &amp; Permissions &gt; Install to Workspace] をクリック</li>
<li>認証画面で [許可する] をクリック</li>
<li>生成された [Bot User OAuth Token] をメモする</li>
</ul>
<p><img src="https://ik.imagekit.io/plaid/f96bb42a-bb85-4fea-9fea-c202d26aaab5/add_slack_app_to_channel.png" alt="add_slack_app_to_channel.png"></p>
<ul>
<li>Slackの画面から、通知したいSlackチャンネルを開く</li>
<li>[インテグレーション &gt; アプリを追加する] から、作成したSlack appをチャンネルに追加</li>
</ul>
<h3>2. 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>talk.message.get</code>を選択します</li>
</ul>
</li>
</ul>
<p>「アプリタイプ」は後から変更できないため、誤って作成した場合は、アプリを再度作成し直してください。</p>
<h3>3. Slack appの OAuth Token を Craft Secret Manager に登録する</h3>
<p>作成したSlack appのOAuthトークンをCraft Functionsから安全に利用するために、Craft Secret Manager に登録します。</p>
<p><img src="https://ik.imagekit.io/plaid/de246508-2c91-40ac-a04a-c214af6542c7/create_slack_token_secret.png" alt="create_slack_token_secret.png"></p>
<ul>
<li>[Craft &gt; シークレット] からシークレットを新規作成</li>
<li>[名前] に、わかりやすい名前を入力</li>
<li>メモしておいたBot User OAuth Tokenの値を [シークレットの値] に入力し、作成</li>
<li>シークレット名をメモしておく</li>
</ul>
<h3>4. 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>KARTE Talkで新規チャット問い合わせがあった場合に、Craft Functionsを使ってSlackに通知する</strong> 」というテンプレートを検索し[取得]ボタンをクリック</li>
<li>[反映] ボタンをクリック</li>
<li>[変数] タブで次の変数の値を設定する
<ul>
<li><code>SLACK_TOKEN_SECRET</code>
<ul>
<li>Slackアプリの Bot User OAuth Tokenを登録したシークレット名です</li>
</ul>
</li>
<li><code>SLACK_CHANNEL_ID</code>
<ul>
<li>通知対象のSlackチャンネルIDです</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/talk-new-message-slack-mention">craft-codes/craft-functions/talk-new-message-slack-mention at main · plaidev/craft-codes</a></p>
<p>ここから、Craft Functionsのコードで重要な部分について、かいつまんでご説明します。</p>
<pre><code>// talk.message.getのパラメータを設定
  const userId = data.jsonPayload.data.user_id;
  const contentText = data.jsonPayload.data.content.text;
  const accessUrl = data.jsonPayload.extra.access_uri.url;

  let msg = '';
  msg += `新規チャット問い合わせが来ました！\n`;
  msg += `問い合わせをしたユーザーのID：${userId}\n`;
  msg += `問い合わせ内容：${contentText}\n`;
  msg += `問い合わせが発生したURL：${accessUrl}\n`;
  msg += `Talk一覧はこちら：https://admin.karte.io/communication/v2/workspace/`;
</code></pre>
<p>この部分で、ユーザーから問い合わせがあった際に、そのユーザーIDや問い合わせ内容及び問い合わせが発生したページのURLを取得し、それらを通知メッセージにセットしています。この通知内容はあくまでも一例で、<code>msg</code>の中身を改変することにより、通知内容を自由にカスタマイズすることができます。</p>
<h3>5. API v2 アプリにCraft Functions の Hook v2 トリガーを設定する</h3>
<p>作成したAPI v2アプリの設定で、Craft Functions の Hook v2 トリガーを追加します。</p>
<p><img src="https://ik.imagekit.io/plaid/ee276388-cd91-4190-ae84-d4e169536080/add_hook_v2_trigger.png" alt="add_hook_v2_trigger.png"></p>
<ul>
<li>[ストア &gt; API v2設定] から作成したアプリを選択</li>
<li>[hook設定 &gt; 編集] をクリック</li>
<li>[トリガー設定] で次のトリガーを追加
<ul>
<li><code>KARTE Talk: ユーザーからのメッセージ送信時 </code></li>
</ul>
</li>
<li>[チャネル設定 &gt; Craft &gt; hook status &gt; 有効にする] にチェックを付け、作成したファンクションを選択</li>
<li>アプリ設定を保存</li>
</ul>
<h2>実際に動かしてみる</h2>
<p>実際に動作を確認してみましょう。問題なく設定ができていれば、ユーザーからチャット問い合わせが来た際に、Slackに通知が届くはずです。</p>
<p><img src="https://ik.imagekit.io/plaid/2a023ad1-a125-4417-b723-cd228e23c49b/%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-1317.33.19.png" alt="スクリーンショット2024-03-1317.33.19.png"></p>
<p>余裕があれば、冒頭にグループメンションなどをつけてみて、ちゃんとメンションが届くかなども確かめてみてください。メンションのつけ方も、念の為に軽く紹介しておきます。基本的には、通知内容の冒頭にそれぞれ必要な要素を追加するだけです。</p>
<h3>チャンネル全体にメンションしたい場合</h3>
<pre><code>msg += `&lt;!channel&gt;\n新規チャット問い合わせが来ました！\n`;
</code></pre>
<ul>
<li>冒頭に<code>&lt;!channel&gt;</code>を追加することで、通知時に@channelの全体メンションが発生します</li>
</ul>
<h3>特定のグループにメンションしたい場合</h3>
<pre><code>msg += `&lt;!subteam^グループID&gt;\n新規チャット問い合わせが来ました！\n`;
</code></pre>
<ul>
<li>ユーザーグループのグループIDは、 <code>その他 &gt; 自分のオーガナイゼーション &gt; メンバーディレクトリ</code> の順に進むと確認できます</li>
</ul>
<h3>個人にメンションしたい場合</h3>
<pre><code>msg += `&lt;@ユーザーID&gt;\n新規チャット問い合わせが来ました！\n`;
</code></pre>
<ul>
<li>SlackのユーザーIDは、ユーザー名をクリックして、<code>プロフィールとアカウント</code>を選択すると確認できます</li>
<li>https://your-workspace.slack.com/team/U12345678の場合、<code>U12345678</code>がそれに該当します</li>
</ul>
<h2>おわりに</h2>
<p>今回は、KARTE Talkで新規チャット問い合わせがあった場合に、Craft Functionsを使ってSlackに通知する方法をご紹介しました！このソリューションを活用して、KARTE Talkをより便利に使っていただければ嬉しいです。KARTE TalkとCraft Functionsを使った有益なアイデアがまた思いつけば、皆さんにご紹介します。</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 Talkで新規チャット問い合わせがあった場合に、Craft Functionsを使ってSlackに通知する方法です。KARTE Talkでユーザーからの新規問い合わせがあったら、それをSlackに通知することで、素早く対応できます。KARTE Talkをお使いの方は、是非お試しください。

KARTE Talkで新規チャット問い合わせがあった場合に、Craft Functionsを使ってSlackに通知する方法

KARTEで特定のイベントが発生した際に、Craft FunctionsからSendGridのAPI経由でメールを送信する方法の紹介です。Craft FunctionsのNode.jsからSendGridのAPIを使ってメールを送ることで、購入イベント発生時などにお礼メールを自動で送れたりします。

KARTEで特定のイベントが発生した際に、Craft FunctionsからSendGridのAPI経由でメールを送信する方法

<p>こんにちは、Customer Engineerのgamiです！最近、いまさら『RRR』を見ました。ナートゥ熱い。</p>
<p>さて、KARTEでは「接客サービス」機能で様々なチャネルに対するアクションを配信できます。通常、接客サービスは管理画面経由で編集するため、同じような接客サービスを日々複製するような使い方をする場合、作業コストがかかったり、作業ミスのリスクがあったりします。</p>
<p>実は、こうした課題を解決するために <strong>「接客サービス」や「接客アクション」をプログラムから更新するためのWeb APIが提供されています</strong> 。</p>
<p>そこで今回は、Craft Functions経由でKARTEのAPI v2を利用するケースを想定し、「接客サービス」や「接客アクション」を更新するAPIの利用方法について紹介します。</p>
<h2>想定ユースケースと利用API</h2>
<p>想定するユースケースは、たとえば次のようなものです。</p>
<ul>
<li>毎月繰り返し実施する接客サービスを、スプレッドシートやSlack上のボタン1つで自動作成したい</li>
<li>検証環境用KARTEプロジェクトで作成した接客サービスを、本番環境用KARTEプロジェクトに簡単に複製したい</li>
<li>ほぼ同じ設定の複数の接客サービスを、スプレッドシート上に記載した設定一覧を元に一括作成したい</li>
</ul>
<p>こうした自動化を実現するためには、次のAPIを利用します。</p>
<ul>
<li>接客サービス関連
<ul>
<li><a href="https://developers.karte.io/reference/post_v2beta-action-campaign-findbyid">Fetch a campaign by id</a></li>
<li><a href="https://developers.karte.io/reference/post_v2beta-action-campaign-create">Create campaign</a></li>
<li><a href="https://developers.karte.io/reference/post_v2beta-action-campaign-update">Update campaign</a></li>
</ul>
</li>
<li>接客アクション関連
<ul>
<li><a href="https://developers.karte.io/reference/post_v2beta-action-action-findbyid">Find action</a></li>
<li><a href="https://developers.karte.io/reference/post_v2beta-action-action-create">Create action</a></li>
<li><a href="https://developers.karte.io/reference/post_v2beta-action-action-update">Update action</a></li>
</ul>
</li>
</ul>
<p>今回の記事では、上記APIの利用方法や検証方法について紹介します。</p>
<p>なお、上で例を挙げた各種ユースケースの実現方法についても、後日ブログ記事にする予定です。</p>
<h2>接客サービス更新系APIを利用するコツ</h2>
<p>APIリファレンスを見るとわかるように、接客サービスや接客アクションの設定項目は非常に複雑です。そこで、基本的には次のような利用方法を推奨します。</p>
<ul>
<li>
<p><strong>接客サービス/接客アクションの作成時</strong></p>
<ol>
<li><strong>予め複製元の接客サービス/接客アクションを作成しておく</strong></li>
<li>複製元の接客サービス/接客アクションの設定情報をAPI経由で取得する</li>
<li>2で取得した設定情報を流用して、接客サービス/接客アクションをAPI経由で作成する</li>
</ol>
</li>
<li>
<p><strong>接客サービス/接客アクションの更新時</strong></p>
<ol>
<li>更新対象の接客サービス/接客アクションの設定情報をAPI経由で取得する</li>
<li>1で取得した設定情報の一部を変更した上で、そのデータを使って接客サービス/接客アクションをAPI経由で更新する</li>
</ol>
</li>
</ul>
<p>要するに、 <strong>作成や更新のためのコンテンツデータを一から作成するのではなく、すでにある接客サービス/接客アクションのデータを取得し、その一部を変更したデータをAPIに渡す</strong> のがおすすめです。後述するサンプルコードでも、そのような方針で実装されています。</p>
<h2>注意点</h2>
<p>前提として、次の点に注意をしてください。</p>
<ul>
<li>次の機能が有効化されたKARTEプロジェクトが利用できることを前提としています
<ul>
<li>接客サービス機能</li>
<li><a href="https://developers.karte.io/docs/how-to-use-api-v2">API v2機能</a></li>
</ul>
</li>
</ul>
<h2>設定手順</h2>
<p>APIの動作検証をするために必要な設定の手順は次の通りです。</p>
<ol>
<li>API v2 アプリを作成する</li>
<li>API v2 アプリの アクセストークンを Craft Secret Manager に登録する</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>token</code> に設定</li>
<li>必要なscopeを追加
<ul>
<li><code>beta.action.campaign.findById</code></li>
<li><code>beta.action.campaign.create</code></li>
<li><code>beta.action.campaign.update</code></li>
<li><code>beta.action.action.findById</code></li>
<li><code>beta.action.action.create</code></li>
<li><code>beta.action.action.update</code></li>
</ul>
</li>
<li>アプリを保存し、一度だけ表示されるアクセストークンをメモしておく</li>
</ul>
<p>なお、scopeが表示されない場合は必要な設定が足りない可能性があります。サポートまでお問い合わせください。</p>
<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. 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>後述するコードを [コード] タブで入力</li>
<li>後述するモジュール設定を [モジュール] タブで入力</li>
<li>[保存] する</li>
<li>デプロイ完了後、[設定 &gt; ファンクションの有効化] にチェックを付ける</li>
</ul>
<p>サンプルコードは次の通りです。</p>
<p><strong>モジュール</strong></p>
<pre><code class="language-json">{
  &quot;api&quot;: &quot;6.1.1&quot;
}
</code></pre>
<p><strong>コード</strong></p>
<pre><code class="language-js">import api from 'api';

const LOG_LEVEL = 'DEBUG';
const KARTE_API_TOKEN_SECRET = ''; // API v2 アプリのアクセストークンを登録したシークレット名
const CAMPAIGN_ID = ''; // 参照先の接客サービスのID
const ACTION_ID = ''; // 参照先の接客アクションのID
const TEMPLATE_ID = ''; // [アクション作成時のみ] 作成するアクションに登録するテンプレートID

const sdk = api('@dev-karte/v1.0#1kus635lt838w9s');

// create campaign &amp; action
export default async function (data, { MODULES }) {
  const { initLogger, secret } = MODULES;
  const logger = initLogger({logLevel: LOG_LEVEL});
  const secrets = await secret.get({keys: [KARTE_API_TOKEN_SECRET]});
  const token = secrets[KARTE_API_TOKEN_SECRET];

  sdk.auth(token);

  try {
    // 複製元の接客サービスを取得
    const { data: c } = await sdk.postV2betaActionCampaignFindbyid({id: CAMPAIGN_ID});
    logger.debug(`[oldCampaign] id: ${c.id}, title: ${c.title}`);

    // 接客サービスを作成。変更したい設定については、対応する項目の値を変える
    const nc = await sdk.postV2betaActionCampaignCreate({
      campaign: {
        // 公開ステータス
        enabled: false,
        // タイトル
        title: 'API経由で複製した接客サービス',
        // 説明文
        description: 'API経由で複製した接客サービスです。',
        // ゴール設定
        goal: c.goal,
        // ビジターのみ/メンバーのみ
        user_type: c.user_type,
        // 対象ユーザー &gt; セグメント
        segments_details: c.segments_details,
        // 配信トリガー
        trigger: c.trigger,
        // スケジュール設定
        // start_date: c.start_date, // nullはエラーになるので必要なときのみ指定する
        // end_date: c.end_date, // nullはエラーになるので必要なときのみ指定する
        dist_days_and_hours: c.dist_days_and_hours,
        // 同時配信設定
        coexist_policy: c.coexist_policy,
        // 配信停止条件
        max_number_of_display: c.max_number_of_display,
        max_number_of_display_per_day: c.max_number_of_display_per_day,
        max_number_of_close: c.max_number_of_close,
        max_number_of_close_per_day: c.max_number_of_close_per_day,
        max_number_of_click: c.max_number_of_click,
        max_number_of_click_per_day: c.max_number_of_click_per_day,
        // アーカイブ状態
        is_archived: false
      }
    });
    const newCampaign = nc.data.campaign;
    logger.debug(`[newCampaign] id: ${newCampaign.id}, title: ${newCampaign.title}`);

    // 複製元の接客アクションを取得
    const { data: a } = await sdk.postV2betaActionActionFindbyid({action_id: ACTION_ID});

    logger.debug(`[oldAction] id: ${a.id}, title: ${a.content.title}`);

    // 接客アクションを作成。変更したい設定については、対応する項目の値を変える
    await sdk.postV2betaActionActionCreate({
      query: {
        content: {
          html: a.content.html,
          source_html: a.content.source_html,
          style: a.content.style,
          less: a.content.less,
          source_script: a.content.source_script,
          script: a.content.script,
        },
        variables: a.variables
      },
      campaign_id: newCampaign.id,
      template_id: TEMPLATE_ID,
    });
  } catch(e) {
    logger.error(e.data?.error || e);
  }
}

// update campaign &amp; action
// export default async function (data, { MODULES }) {
//   const { initLogger, secret } = MODULES;
//   const logger = initLogger({logLevel: LOG_LEVEL});
//   const secrets = await secret.get({keys: [KARTE_API_TOKEN_SECRET]});
//   const token = secrets[KARTE_API_TOKEN_SECRET];

//   sdk.auth(token);

//   try {

//     // 更新前の接客サービスを取得
//     const { data: c } = await sdk.postV2betaActionCampaignFindbyid({id: CAMPAIGN_ID});
//     logger.debug(`[oldCampaign] id: ${c.id}, title: ${c.title}`);

//     // 接客サービスを更新。変更したい設定については、対応する項目の値を変える
//     await sdk.postV2betaActionCampaignUpdate({
//       id: CAMPAIGN_ID,
//       query: {
//         // 公開ステータス
//         enabled: false,
//         // タイトル
//         title: c.title+'!', // titleに!を付加する
//         // 説明文
//         description: c.description,
//         // ゴール設定
//         goal: c.goal,
//         // ビジターのみ/メンバーのみ
//         user_type: c.user_type,
//         // 対象ユーザー &gt; セグメント
//         segments_details: c.segments_details,
//         // 配信トリガー
//         trigger: c.trigger,
//         // スケジュール設定
//         // start_date: c.start_date, // nullはエラーになるので必要なときのみ指定する
//         // end_date: c.end_date, // nullはエラーになるので必要なときのみ指定する
//         dist_days_and_hours: c.dist_days_and_hours,
//         // 同時配信設定
//         coexist_policy: c.coexist_policy,
//         // 配信停止条件
//         max_number_of_display: c.max_number_of_display,
//         max_number_of_display_per_day: c.max_number_of_display_per_day,
//         max_number_of_close: c.max_number_of_close,
//         max_number_of_close_per_day: c.max_number_of_close_per_day,
//         max_number_of_click: c.max_number_of_click,
//         max_number_of_click_per_day: c.max_number_of_click_per_day,
//         // アーカイブ状態
//         is_archived: false
//       }
//     });

//     // 更新前の接客アクションを取得
//     const { data: a } = await sdk.postV2betaActionActionFindbyid({action_id: ACTION_ID});

//     logger.debug(`[oldAction] id: ${a.id}, title: ${a.content.title}`);

//     // 静的変数headingの値に!を付加する
//     a.variables = a.variables.map(v =&gt; {
//       if (v.name === 'heading') {
//         v.value = v.value+'!'
//       }
//       return v;
//     });

//     // 接客アクションを更新。変更したい設定については、対応する項目の値を変える
//     await sdk.postV2betaActionActionUpdate({
//       action_id: ACTION_ID,
//       query: {
//         content: {
//           html: a.content.html,
//           source_html: a.content.source_html,
//           style: a.content.style,
//           less: a.content.less,
//           source_script: a.content.source_script,
//           script: a.content.script,
//         },
//         variables: a.variables,
//       },
//     });
//   } catch(e) {
//     logger.error(e.data?.error || e);
//   }
// }
</code></pre>
<p>サンプルコードは前半が「接客サービス/接客アクションの <strong>作成</strong> 」、後半が「接客サービス/接客アクションの <strong>更新</strong> 」に関するサンプルになっています。利用しない方をコメントアウトして使ってください。</p>
<p>コードの冒頭にある定数の値は、それぞれの環境に合わせて設定してください。なお、「接客サービスID」、「アクションID」、「テンプレートID」は、管理画面URLから取得できます。</p>
<ul>
<li>アクション編集画面URL
<ul>
<li><code>https://admin.karte.io/p/#{プロジェクトID}/service/#{接客サービスID}/wizard/action/#{アクションID}/basic</code></li>
</ul>
</li>
<li>テンプレート詳細画面URL
<ul>
<li><code>https://admin.karte.io/p/#{プロジェクトID}/template/#{テンプレートID}/basic</code></li>
</ul>
</li>
</ul>
<p>ちなみに接客アクションの作成時にテンプレートIDが必要なのは、管理画面上は接客アクションがテンプレートから作成されるためです。作成するアクションの元となるのに相応しいテンプレートをテンプレート一覧から選択し、そのテンプレートIDを利用してください。</p>
<h2>実際に動かしてみる</h2>
<p>検証用の接客サービスを作成し、作成したCraft Functionsを実行してその接客サービスを複製したり更新したりしてみましょう。</p>
<p>簡易的にファンクションをテスト実行するには、エンドポイントを作成しそのURLをWebブラウザで叩くか、スケジュール設定で「毎分実行」など高頻度なスケジュールを一時的に設定するのがおすすめです。</p>
<p>設定が問題なければ、接客サービスや接客アクションが自動で作成/更新されるはずです。実際に更新がうまくいったか、管理画面で確認してみてください。</p>
<p>なお、サンプルコードでは変化がわかりやすいように次のような処理が入っています。</p>
<ul>
<li>接客サービス作成時
<ul>
<li>titleを <code>API経由で複製した接客サービス</code> にする</li>
<li>descriptionを <code>API経由で複製した接客サービスです。</code> にする</li>
</ul>
</li>
</ul>
<p><img src="https://ik.imagekit.io/plaid/632a9099-f107-48c6-9e62-78b8b6bc502e/%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-0917.12.37.png" alt="スクリーンショット2024-03-0917.12.37.png"></p>
<ul>
<li>接客サービス更新時
<ul>
<li>titleの末尾に <code>!</code> を1つ付ける</li>
</ul>
</li>
<li>接客アクション更新時
<ul>
<li><code>heading</code> という名称の静的変数の値の末尾に <code>!</code> を1つ付ける</li>
<li>※ 更新対象の変数を変える場合は、コード中の静的変数名を書き換えてください</li>
</ul>
</li>
</ul>
<p><img src="https://ik.imagekit.io/plaid/9f84f412-1647-4dec-8d01-835d7f3bcc79/%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-0917.08.58.png" alt="スクリーンショット2024-03-0917.08.58.png"></p>
<p>うまくいかない場合は、ファンクションのログにエラーが出ていないか確認してみてください。たとえばリクエストbodyに必要なプロパティが無い場合は、次のようなエラーが出力されます。</p>
<p><img src="https://ik.imagekit.io/plaid/a0dd3e45-f359-4efa-82c7-13a36f0acc19/%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-118.23.13.png" alt="スクリーンショット2024-03-118.23.13.png"></p>
<p>逆に余計なプロパティが含まれているケースでもエラーが出るようです。</p>
<p>なお、サンプルコードはシンプルにするために全ての処理を1つのtry/catchで囲んでいます。どのAPI callでエラーが出ているか知りたい場合は、try/catchをAPI call毎に分けてエラーメッセージを出し分けるように実装するのがおすすめです。</p>
<h2>おわりに</h2>
<p>今回はAPI経由でKARTEの接客サービスやアクションを更新する方法について紹介しました。</p>
<p>接客サービス画面で細かい配信設定ができるのは、KARTEのとても便利な点です。一方で、ほぼ同じような接客サービスをたくさん作る場合などは、APIを使って自動化した方が圧倒的に運用が楽になります。ぜひ皆さんも試してみてください！</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の接客サービスを管理画面経由で編集すると、同じような接客サービスを日々複製するような使い方をする場合、作業コストがかかったり、作業ミスのリスクがあったりします。今回は、Craft Functions経由でKARTEのAPI v2を利用するケースを想定し、「接客サービス」や「接客アクション」を更新するAPIの利用方法について紹介します。