ProtoPieでダイナミックなマップの作成：Google PlacesとMapboxの連携ガイド

説明: このチュートリアルでは、ProtoPie プロトタイプ内でユーザーの入力に基づいて動的に更新される静的マップ画像を生成する方法を学びます。Google Maps Places API (New) を統合して位置座標を取得し、Mapbox Static Images API を使用してマップを生成します。これらすべては ProtoPie Connect を通じてシームレスに連携されます。

クリエイティブテクノロジストの Jubilee Mayanja 氏によって、すべて ProtoPie で構築された動的マッププロトタイプ「MapSearch」。

必要なもの:

• ProtoPie Studio (最新バージョンを推奨)

• ProtoPie Connect (最新バージョンを推奨)

• プロジェクトがセットアップされ、課金が有効になっている Google Cloud Platform アカウント (無料枠の利用であっても、API アクセスには多くの場合課金設定が必要です)。

• Mapbox アカウント。

• Google Maps Platform (特に Places API) と Mapbox の両方の API キー。

パート 1: API キーのセットアップ

1.1 Google Maps Platform API キーの取得

1. Google Cloud Platform に移動する: console.cloud.google.com にアクセスします。

2. プロジェクトを作成する (まだお持ちでない場合): 上部バーのプロジェクトドロップダウンをクリックし、「新しいプロジェクト」を選択して、プロンプトに従います。

3. 課金を有効にする: 無料枠の利用であっても、ほとんどの Google Maps Platform API では課金を有効にする必要があります。左側のナビゲーションで「お支払い」に移動し、請求先アカウントをセットアップします。

4. API とサービスの有効化:

   • 左側のナビゲーションで、「API とサービス」 > 「有効な API とサービス」に移動します。

   • 「+ API とサービスの有効化」をクリックします。

   • 「Places API (New)」を検索し、有効にします。

   • 任意（推奨）： 「Geocoding API」も検索して有効にします。Places API (New) は通常、座標を直接返しますが、Geocoding は特定の住所から座標への変換が必要な場合の便利なフォールバックとなります。

   

5. API 認証情報を作成する:

• 「API とサービス」 > 「認証情報」に移動します。

• 「+ 認証情報を作成」をクリックし、「API キー」を選択します。

• 生成されたキーをコピーし、安全な場所に保管してください。セキュリティのために後から制限をかけることも可能ですが、現時点ではコピーするだけで構いません。

  注意: API キーは非公開にしてください。パスワードと同様に扱ってください。

1.2 Mapbox アクセストークンの取得

1. Mapbox アカウントに移動する: account.mapbox.com にアクセスします。

2. パブリックトークンを取得する: ダッシュボードに「Default public token」が表示されます。お持ちでない場合は、「Create a token」をクリックして新しいトークンを生成します。

3. このトークンをコピーします。これが Mapbox アクセストークンになります。

   

パート 2: ProtoPie プロトタイプのデザイン

2.1 Figma インポートに向けた ProtoPie Studio の準備

1. ProtoPie Studio を開き、新しい Pie ファイルを作成します。

2. キャンバスサイズを Figma フレームに合わせる: インポートする前に、ProtoPie のキャンバスサイズが Figma からエクスポートするフレームと一致していることを確認してください。これにより、インポートが 1:1 で維持され、スケーリングの問題を回避できます。

   

2.2 Figma からのデザインのインポート

1. Figma でデザインを準備する: Figma ファイルのレイヤーが単一のフレームに整理されていることを確認します。このステップをスキップしたい場合は、提供されている Figma ファイルから開始することもできます。

2. Figma からエクスポートする:

   • 下部ツールバーの「アクション」アイコンをクリックします。

   • 「プラグインとウィジェット」タブを選択します。

   • 「ProtoPie」を検索し、プラグインをクリックします。

   • プラグインウィンドウで「Export」を選択します。デザインが、開いている ProtoPie Studio ファイルに直接インポートされます。

     

2.3 基本的な UI セットアップ

Figma からインポートした場合でも、ProtoPie Studio で直接 UI を作成した場合でも、レイヤーが次のように設定されていることを確認してください。

1. 入力レイヤーを作成する:

   • 「テキスト入力」レイヤーを追加し、locationInput という名前を付けます。ここに、ユーザーが検索したい場所を入力します。

   • 任意: 整理しやすいように、locationInput を Search コンテナ内に移動します。

     

   • テンプレートプロジェクトでは、テキスト入力に以下の設定を使用しています。

     • サイズ: 226 x 40

     • 角丸: 8

     • プレースホルダーの色: D0D0D0

     • ボックスの塗りつぶし: FFFBFB

   2. 画像レイヤーを作成する:

      • マップのプレースホルダーとして機能する「画像」レイヤーを追加または配置し、mapImage という名前を付けます。

パート 3: ProtoPie と Google Places API の接続 (ProtoPie Connect 経由)

ここが ProtoPie Connect の本領発揮です。API プラグインを使用して、Google Places への HTTP リクエストを行います。

3.1 Google Places API (New) の概要

セットアップに入る前に、なぜ Google Places API (New) がこのプロジェクトの中心となるのかを理解しておきましょう。これは Google の最新世代の位置データ API であり、以前のバージョンよりも優れたパフォーマンス、データ品質、および柔軟な料金プランを提供しています。店舗やビジネスから観光名所、一般的な地理的位置まで、あらゆる場所をカバーしています。

このチュートリアルでは、その「テキスト検索 (Text Search)」機能を使用します。これにより、「エッフェル塔」や「ニューヨーク」といったプレーンテキストのクエリを送信し、詳細な場所情報を取得できます。最も重要なのは、正確な緯度 (latitude) と経度 (longitude) の座標を取得できる点です。これは、入力された場所をマップサービスが実際に利用できる形式に変換するための、極めて重要な第一歩です。

3.2 なぜ ProtoPie Connect なのか？

Pie プロトタイプ単体では、直接 API コールを行うことはできません。この隙間を埋めるのが ProtoPie Connect です。Connect は、プロトタイプと外部サービスをつなぐ架け橋（ブリッジ）として機能します。Google Places に HTTP リクエストを送信し、未加工のレスポンスを受信して、Pie に戻すことで、処理と表示を行えるようにします。Connect がなければ、プロトタイプが必要な座標を取得する方法はありません。

3.3 ユーザー入力のキャプチャ

まず、ユーザーが入力した内容をプロトタイプが継続的に追跡し、変数に保存するようにしましょう。

1. 新しいテキスト変数を作成する:

• 変数パネルを開きます (ProtoPie Studio の左下)。

• searchInput という名前の、新しいテキスト変数 (すべてのシーン用 / グローバル) を作成します。ここにユーザーが入力した内容が保持されます。

• タイプが「数値」ではなく「テキスト」に設定されていることを確認してください。

2. Detect トリガーで入力をキャプチャする:

• 「Detect (検出)」トリガーを追加します。

• ターゲット: locationInput → Text (入力フィールドのテキストプロパティを監視します)。

• Detect トリガーの中に、「Assign (代入)」レスポンスを追加します。

  • ターゲット: searchInput 変数

  • 数式: locationInput.text

• この仕組み: ユーザーが入力すると、locationInput.text が変化し、Detect トリガーが作動して、Assign レスポンスが searchInput を最新のテキストで更新します。デバッグを有効にして、変数がリアルタイムで更新される様子を確認しましょう。

• プレビューを開き、フィールドに文字を入力してみてください。デバッグビューで searchInput がリアルタイムに更新されるのが確認できるはずです。

• 注意: 作成するトリガーやレスポンスには、わかりやすい名前を付けておきましょう。後で作業する自分（や他のプロジェクトメンバー）が助かることになります。

3.4 Return キーによる API リクエストのトリガー

1. 2 つの新しいグローバル変数を追加する:

   • googleMapsRequestBody (すべてのシーン用のテキスト変数): Places API (New) 用の完全な JSON リクエストボディを保持します。初期値として以下の文字列をそのまま入力してください：

{

"textQuery": "<INPUT QUERY>", "languageCode": "ja", "regionCode": "jp"

}

• textQuery は、ユーザーの検索クエリ用のフィールドです。

• <INPUT QUERY> は、実際の入力値に動的に置き換えるためのプレースホルダーです。

• languageCode: "ja" で、レスポンスの言語を日本語に設定します。

• regionCode: "jp" で、結果を日本国内に偏らせます。必要に応じて、お使いの地域に合わせて調整してください。

  

• inputQuery (すべてのシーン用のテキスト変数): 動的に入れ替えるためのプレースホルダー変数です。初期値として <INPUT QUERY> を設定します。

  

2. 「Return」トリガーを追加する:

• locationInput レイヤーを選択します。

• 「Return」トリガーを追加します。これは、ユーザーが Enter/Return キーを押したときに作動する、検索フィールドにおける一般的なパターンです。

  

3. リクエストボディを用意して送信する:

• 「Return」トリガーの中に、「Assign」レスポンスを追加します。

  • ターゲット: googleMapsRequestBody

  • 数式: replace(googleMapsRequestBody, inputQuery, searchInput)

  • この仕組み: この数式は、googleMapsRequestBody 内にある inputQuery (初期値は <INPUT QUERY>) をすべて探し出し、ユーザーが入力したばかりのテキスト searchInput に置き換えます。

• 次の検索に備えて inputQuery をリセットするために、もう 1 つ「Assign」レスポンスを追加します。

  • ターゲット: inputQuery

  • 数式: searchInput

  • この仕組み: 置き換え後、inputQuery を現在の検索ワードに更新します。次回実行時には、replace 関数が *その* ワードを探して新しいワードに置き換えるため、検索ごとにハードコーディングする必要がなくなります。

• リクエストを送信するために、「Send (送信)」レスポンスを追加します。

  • チャンネル: ProtoPie Connect/Studio

  • メッセージ: searchTextRequest (ProtoPie Connect が受信を監視するメッセージ)

  • 値: 数式 → googleMapsRequestBody

    

• これにより、動的に構築された完全な JSON リクエストボディが Connect に送信されます。

3.5 レスポンスの受信と Mapbox URL の構築

ProtoPie Connect が Google Places からレスポンスを受信すると、それを Pie に渡します。ここで、データを受信して座標を抽出し、それらを使用して Mapbox Static Images API の URL を動的に構築します。

1. 必要な変数を設定する (すべてのシーン用):

• apiResponseRaw (テキスト変数): ProtoPie Connect から生の JSON を受け取ります。

• latitude (テキスト変数): 抽出された緯度を保存します。

• longitude (テキスト変数): 抽出された経度を保存します。

• mapBox_URL (テキスト変数): 緯度と経度のプレースホルダー (<LAT> および <LON>) を含むベースの Mapbox URL を保持します。

https://api.mapbox.com/styles/v1/mapbox/streets-v12/static/<LON>,<LAT>,14,0/1200x800?access_token=YOUR_MAPBOX_TOKEN

注意: YOUR_MAPBOX_TOKEN は、実際の Mapbox アクセストークンに置き換えてください。

• currentlatitudePlaceholder (テキスト変数): 初期値として <LAT> を設定します。mapBox_URL に挿入された最後の緯度を追跡します。

• currentLongitudePlaceholder (テキスト変数): 初期値として <LON> を設定します。mapBox_URL に挿入された最後の経度を追跡します。

  

2. 「Receive (受信)」トリガーを追加する:

   • チャンネル: ProtoPie Connect/Studio

   • メッセージ: searchLocationReceived

   • 変数に代入: このボックスにチェックを入れ、apiResponseRaw (タイプ: テキスト) を選択します。

     

3. apiResponseRaw に対する 「Detect」トリガーを追加する:

   • ターゲット: apiResponseRaw

   • その中に、座標を抽出するための 2 つの「Assign」レスポンスを追加します。

     • 緯度 (Latitude) — ターゲット: latitude, 数式: parseJson(apiResponseRaw, "places.0.location.latitude")

     • places.0 は places 配列内の最初の結果を指し（API は複数のマッチを返す場合があります）、location.latitude は抽出したい値へのパスです。

       

     • 経度 (Longitude) — ターゲット: longitude, 数式: parseJson(apiResponseRaw, "places.0.location.longitude")

       

4. longitude に対する「Detect」トリガーを追加する:

   • ターゲット: longitude

   • その中身:

     • Assign — ターゲット: mapBox_URL, 数式: replace(mapBox_URL, currentLongitudePlaceholder, longitude)

       

     • Assign — ターゲット: currentLongitudePlaceholder, 数式: longitude

       

     • Assign — ターゲット: isMapReady, 数式: isMapReady + 1

       

5. latitude に対する「Detect」トリガーを追加する:

• ターゲット: latitude

• その中身:

  • Assign — ターゲット: mapBox_URL, 数式: replace(mapBox_URL, currentLatitudePlaceholder, latitude)

    

  • Assign — ターゲット: currentLatitudePlaceholder, 数式: latitude

    

  • Assign — ターゲット: isMapReady, 数式: isMapReady + 1

    

6. isMapReady に対する「Detect」トリガーを追加する (画像を読み込むため):

• ターゲット: isMapReady

• 条件: isMapReady = 2 — これにより、mapBox_URL に両方の座標が揃ったことが確認されます。

  • 「Image」レスポンスを追加 — ターゲット: mapImage, ソース: 数式, 数式: mapBox_URL

  • Assign — ターゲット: isMapReady, 数式: 0 (次の検索に向けてリセット)

3.6 ProtoPie Connect での API プラグインの設定

次に、ProtoPie Connect が searchTextRequest を処理し、Google Places API (New) と通信できるようにセットアップします。

1. ProtoPie ファイルをローカルまたはクラウドに保存します。

2. 保存した .pie ファイルを ProtoPie Connect で開きます。

3. 右上の「Plugin」をクリックします。

4. プラグインリストから「API」を選択し、「+」をクリックします。

5. API プラグインの設定:

   • メソッド (Method): POST

   • URL: https://places.googleapis.com/v1/places:searchText

   • ヘッダー (Header): { "Content-Type": "application/json", "X-Goog-Api-Key": "YOUR_GOOGLE_API_KEY", "X-Goog-FieldMask": "places.location" }

     (YOUR_GOOGLE_API_KEY は、実際の Google API キーに置き換えてください。)

• ボディ (Body): 空欄のままで構いません。Pie から動的に生成されます。

• Message From Pie (Pie からのメッセージ): searchTextRequest

• Override にチェックを入れ、BODY を Message Value に設定します。

• Message To Pie (Pie へのメッセージ): searchLocationReceived

• 「Activate (有効化)」をクリックします。

  

パート 4: プロトタイプのテスト

1. ファイルを最初にロードしてから変更を加えた場合は、ProtoPie Connect で Pie が更新されていることを確認してください。

2. ProtoPie Connect が実行されており、Pie がロードされ、API プラグインが有効化されていることを確認します。

3. ProtoPie Connect のプレビューリンクから、Web ブラウザでプロトタイプを実行します。

4. 入力フィールドに「エッフェル塔」や「タイムズスクエア」などの場所を入力し、Enter キーを押します。

5. 新しい場所を中心に、マップ画像が再ロードされるはずです。

   

   ヒント: 静的マップは常に検索された場所を中心にロードされるため、ProtoPie キャンバスの中心にマーカーを配置しておけば、ユーザーがどこを検索してもマップ上の正しい場所を指し示すようになります。

   

さらなる改善

コアとなるフローが動作するようになったら、マップの取得中にローディング画面を重ねて表示させたり、より洗練された感覚を与えるためにマップのドラッグインタラクションを追加することを検討してみてください。

ご自身で試してみる準備はできましたか？

ProtoPie のプロトタイプに導入できる API は、Google Places と Mapbox だけではありません。今回のパターン（Connect でデータを取得し、数式に流し込み、UI を更新する）を理解すれば、同様の方法で他の位置情報、データ、またはメディアサービスを接続する準備が整ったことになります。

ProtoPie Studio と Connect をダウンロードして、構築を始めましょう。