Maps SDK for Android のクイックスタート

Android Studio 用の Google マップ ビュー テンプレートを使用して、地図を表示する Android アプリを作成します。既存の Android Studio プロジェクトをセットアップする場合は、Android Studio プロジェクトをセットアップするをご覧ください。

このクイックスタートは、Kotlin または Java を使用する基本的な Android 開発に精通しているデベロッパーを対象としています。

開発環境の概要

このクイックスタートは、Android Studio Hedgehog と Android Gradle プラグイン バージョン 8.2 を使用して開発されました。

注: 開発環境で別のバージョンの Android Studio または Gradle を使用している場合は、環境に応じて手順の変更が必要になる場合があります。Android Studio と Gradle のバージョンについて詳しくは、Android Gradle プラグインと Android Studio の互換性を参照してください。

Android デバイスを設定する

Maps SDK for Android を使用するアプリを実行するには、Android 5.0 以降をベースとし Google API を含む Android デバイスまたは Android Emulator にアプリをデプロイする必要があります。

• Android デバイスを使用する場合は、ハードウェア デバイス上でのアプリの実行の手順に従ってください。
• Android Emulator を使用する場合は、Android Studio に付属している Android Virtual Device（AVD）Manager を使用して仮想デバイスを作成し、エミュレータをインストールしてください。
  注: Android Emulator を使用する場合は、必ず [Play ストア] 列に再生アイコン が表示されているデバイスを選択してください。 このアイコンは、プロファイルが CTS に完全に対応しており、Google Play ストア アプリを含むシステム イメージを使用できることを示しています。

  

Android Studio で Google マップ プロジェクトを作成する

Android Studio で Google マップ プロジェクトを作成する手順は、Android Studio Flamingo 以降のリリースで変更されました。

1. Android Studio を開き、[Welcome to Android Studio] ウィンドウで [New Project] をクリックします。

2. [New Project] ウィンドウで、[Phone and Tablet] カテゴリの [No Activity] を選択し、[Next] をクリックします。

3. [New Project] フォームに次のように入力します。

   • [Language] を Java または Kotlin に設定します。Maps SDK for Android では、どちらの言語も完全にサポートされています。Kotlin について詳しくは、Kotlin で Android アプリを開発するをご覧ください。

   • [Minimum SDK] は、テストするデバイスと互換性がある SDK のバージョンに設定します。Maps SDK for Android 19.0.x の要件を満たすバージョンを選択してください。現在は Android API レベル 21（Android 5.0 Lollipop）以上が必要です。SDK バージョン要件についての最新情報は、リリースノートでご確認ください。

     注: Android SDK の適切なバージョンがわからない場合は、[Help me choose] を選択すれば、サポートされている各バージョンの普及比率を確認できます。たとえば、Android API レベル 21（Android 5.0 Lollipop）を選択すれば、99% 以上の Android デバイスで実行できるアプリになります。

   • [Build configuration language] を Kotlin DSL または Groovy DSL に設定します。 両方のビルド構成言語のスニペットは、下記の手順で示します。

4. [Finish] をクリックします。

   Android Studio により Gradle が開始され、プロジェクトがビルドされます。しばらく時間がかかることがあります。

5. Google Maps Views Activity を追加します。

   1. プロジェクトの app フォルダを右クリックします。

   2. [New] > [Google] > [Google Maps Views Activity] を選択します。

      

   3. [New Android Activity] ダイアログ ボックスで、[Launcher Activity] チェックボックスをオンにします。

   4. [Finish] を選択します。

      詳しくは、テンプレートからコードを追加するをご覧ください。

6. ビルドが完了すると、Android Studio が AndroidManifest.xml ファイルと MapsActivity ファイルを開きます。アクティビティの名前が異なる場合がありますが、これはセットアップ時に設定した名前になります。

   注意: AndroidManifest.xml ファイルには、Google Maps API キーを取得して local.properties ファイルに追加する手順が記載されていますが、実際には local.properties ファイルに API キーを保存しないように注意してください。この保存方法では、後述の方法ほど安全に API キーを保存できません。代わりに、Google Cloud プロジェクトをセットアップするの手順に沿って、Cloud プロジェクトを作成し、API キーの設定を行います。

Google Cloud プロジェクトをセットアップする

以下の各タブをクリックして、Cloud コンソールの設定を完了してください。

ステップ 1

コンソール

1. Google Cloud コンソールの [プロジェクトの選択] ページで [新しいプロジェクト] をクリックし、新しい Cloud プロジェクトの作成を開始します。

   [プロジェクトの選択] ページに移動

2. Cloud プロジェクトで お支払いが有効になっていることを確認します。

   Google Cloud では、無料トライアルを提供しています。トライアルは、90 日が経過するか、アカウントの費用が 300 ドルに達した時点のいずれか早い方の時点で終了します。解約はいつでも可能です。Google Maps Platform では、クレジット（毎月 200 ドル分）が付与されます。詳しくは、請求先アカウントのクレジットおよび Google Maps Platform の料金をご覧ください。

Cloud SDK

gcloud projects create "PROJECT"

詳しくは、Google Cloud SDK、Cloud SDK のインストール、および以下のコマンドをご覧ください。

• gcloud projects create

注: 演習で作成するリソースを今後使用する予定がない場合は、既存のプロジェクトを選択するのではなく、新しいプロジェクトを作成してください。新しく作成したプロジェクトを演習の終了後に削除すると、このプロジェクトに関連するすべてのリソースを削除できます。

ステップ 2

Google Maps Platform を使用するには、プロジェクトで使用する API または SDK を有効にする必要があります。

コンソール

Maps SDK for Android を有効化

Cloud SDK

gcloud services enable \
    --project "PROJECT" \
    "maps-android-backend.googleapis.com"

詳しくは、Google Cloud SDK、Cloud SDK のインストール、および以下のコマンドをご覧ください。

• gcloud services enable
• gcloud services disable

ステップ 3

このステップでは API キーを作成します。本番環境で API キーを使用する場合は、キーの使用を制限することを強くおすすめします。詳しくは、各サービスの API キーの使用ページをご覧ください。

API キーは、プロジェクトに関連付けられたリクエストを認証し、リクエストの使用回数を追跡して課金するために使われる一意の識別子です。少なくとも 1 つの API キーをプロジェクトに関連付ける必要があります。

API キーを作成するには:

コンソール

1. [Google Maps Platform] > [認証情報] ページに移動します。

   [認証情報] ページに移動

2. [認証情報] ページで、[認証情報を作成] > [API キー] をクリックします。
   [API キーを作成しました] ダイアログで、新しく作成された API キーが表示されます。
3. [閉じる] をクリックします。
   新しい API キーは、[認証情報] ページの [API キー] に一覧で表示されます。
   （本番環境で使用する前に必ず API キーを制限するようにしてください）

Cloud SDK

gcloud alpha services api-keys create \
    --project "PROJECT" \
    --display-name "DISPLAY_NAME"

詳しくは、Google Cloud SDK、Cloud SDK のインストール、および以下のコマンドをご覧ください。

• gcloud alpha services api-keys create

アプリに API キーを追加する

このセクションでは、アプリで安全に参照されるように API キーを保存する方法を説明します。API キーは、バージョン管理システムにはチェックインせず、プロジェクトのルート ディレクトリにある secrets.properties ファイルに保存することをおすすめします。secrets.properties ファイルについて詳しくは、Gradle プロパティ ファイルをご覧ください。

このタスクを効率化するには、Android 用 Secrets Gradle プラグインの使用をおすすめします。

注: 最新のシステム要件とインストール手順について詳しくは、GitHub にある Android 用 Secrets Gradle プラグインのドキュメントをご覧ください。

Android 用 Secrets Gradle プラグインを Google マップ プロジェクトにインストールする手順は以下のとおりです。

1. Android Studio で最上位レベルの build.gradle.kts ファイルか build.gradle ファイルを開き、buildscript の配下にある dependencies 要素に次のコードを追加します。

   Kotlin

   buildscript {
       dependencies {
           classpath("com.google.android.libraries.mapsplatform.secrets-gradle-plugin:secrets-gradle-plugin:2.0.1")
       }
   }

   Groovy

   buildscript {
       dependencies {
           classpath "com.google.android.libraries.mapsplatform.secrets-gradle-plugin:secrets-gradle-plugin:2.0.1"
       }
   }

2. モジュール レベルの build.gradle.kts ファイルか build.gradle ファイルを開き、次のコードを plugins 要素に追加します。

   Kotlin

   plugins {
       // ...
       id("com.google.android.libraries.mapsplatform.secrets-gradle-plugin")
   }

   Groovy

   plugins {
       // ...
       id 'com.google.android.libraries.mapsplatform.secrets-gradle-plugin'
   }

3. モジュール レベルの build.gradle.kts ファイルか build.gradle ファイルで、targetSdk と compileSdk を 34 に設定します。
4. ファイルを保存して、プロジェクトを Gradle と同期します。
5. 最上位レベルのディレクトリで secrets.properties ファイルを開き、次のコードを追加します。YOUR_API_KEY は実際の API キーに置き換えてください。secrets.properties はバージョン管理システムにチェックインされないため、このファイルにキーを保存します。
   注: secrets.properties ファイルがない場合は、local.properties ファイルと同じフォルダに作成します。

   MAPS_API_KEY=YOUR_API_KEY

6. ファイルを保存します。

7. 最上位レベルのディレクトリ（secrets.properties ファイルと同じフォルダ）に local.defaults.properties ファイルを作成し、次のコードを追加します。

   注: コードはここに示されているとおりに入力します。DEFAULT_API_KEY を API キーに置き換えないでください。

   MAPS_API_KEY=DEFAULT_API_KEY

   このファイルの目的は、secrets.properties ファイルがない場合に API キーのバックアップ場所を提供し、ビルドが失敗しないようにすることです。この状況は、secrets.properties を省略したバージョン管理システムからアプリのクローンを作成し、API キーを提供するために secrets.properties ファイルをまだローカルに作成していない場合に発生する可能性があります。

8. ファイルを保存します。
9. AndroidManifest.xml ファイルで com.google.android.geo.API_KEY に移動し、android:value attribute を更新します。 <meta-data> タグがない場合は、<application> タグの子として作成します。

   <meta-data
       android:name="com.google.android.geo.API_KEY"
       android:value="${MAPS_API_KEY}" />

   注: com.google.android.geo.API_KEY は、API キーとして推奨されるメタデータ名です。この名前のキーは、Android プラットフォームで Google マップベースの複数の API（Maps SDK for Android など）の認証に使用できます。下位互換性を確保するため、API では com.google.android.maps.v2.API_KEY という名前もサポートされています。この従来の名前は、Android Maps API v2 の認証にのみ使用できます。アプリでは、API キーのメタデータ名を 1 つのみ指定できます。両方を指定すると、API から例外がスローされます。

10. Android Studio でモジュール レベルの build.gradle.kts ファイルか build.gradle ファイルを開き、secrets プロパティを編集します。secrets プロパティがない場合は追加します。

    プラグインのプロパティを編集して propertiesFileName を secrets.properties に、defaultPropertiesFileName を local.defaults.properties に設定し、他のプロパティも設定します。

    Kotlin

    secrets {
        // To add your Maps API key to this project:
        // 1. If the secrets.properties file does not exist, create it in the same folder as the local.properties file.
        // 2. Add this line, where YOUR_API_KEY is your API key:
        //        MAPS_API_KEY=YOUR_API_KEY
        propertiesFileName = "secrets.properties"
    
        // A properties file containing default secret values. This file can be
        // checked in version control.
        defaultPropertiesFileName = "local.defaults.properties"
    
        // Configure which keys should be ignored by the plugin by providing regular expressions.
        // "sdk.dir" is ignored by default.
        ignoreList.add("keyToIgnore") // Ignore the key "keyToIgnore"
        ignoreList.add("sdk.*")       // Ignore all keys matching the regexp "sdk.*"
    }
            

    Groovy

    secrets {
        // To add your Maps API key to this project:
        // 1. If the secrets.properties file does not exist, create it in the same folder as the local.properties file.
        // 2. Add this line, where YOUR_API_KEY is your API key:
        //        MAPS_API_KEY=YOUR_API_KEY
        propertiesFileName = "secrets.properties"
    
        // A properties file containing default secret values. This file can be
        // checked in version control.
        defaultPropertiesFileName = "local.defaults.properties"
    
        // Configure which keys should be ignored by the plugin by providing regular expressions.
        // "sdk.dir" is ignored by default.
        ignoreList.add("keyToIgnore") // Ignore the key "keyToIgnore"
        ignoreList.add("sdk.*")       // Ignore all keys matching the regexp "sdk.*"
    }
            

コードを確認する

テンプレートで提供されるコードを確認します。特に、Android Studio プロジェクト内の以下のファイルを確認してください。

マップ アクティビティ ファイル

マップ アクティビティ ファイルは、アプリのメイン アクティビティです。このファイルには、地図を管理し表示するためのコードが格納されます。アクティビティを定義するファイルのデフォルトの名前は MapsActivity.java です（アプリの言語として Kotlin を設定した場合は MapsActivity.kt）。

マップ アクティビティの主な要素は次のとおりです。

• SupportMapFragment オブジェクトは、アプリの UI の親要素であり、地図のライフサイクルを管理します。

• GoogleMap オブジェクトは、地図のデータおよびビューへのアクセスを提供します。これは、Maps SDK for Android のメインクラスです。SupportMapFragment オブジェクトと GoogleMap オブジェクトについて詳しくは、地図オブジェクトのガイドをご覧ください。

• moveCamera 関数は、オーストラリアのシドニーの LatLng 座標に地図の中心を合わせます。通常、地図を追加する際に最初に設定するのは、地図の場所とカメラの設定（傾斜角、地図の向き、ズームレベルなど）です。詳しくは、カメラとビューのガイドをご覧ください。

• addMarker 関数は、シドニーの座標にマーカーを追加します。詳しくは、マーカーのガイドをご覧ください。

モジュールの Gradle ファイル

モジュールの build.gradle.kts ファイルには、Maps SDK for Android で必要とされる以下のマップの依存関係が含まれています。

dependencies {

    // Maps SDK for Android
    implementation("com.google.android.gms:play-services-maps:19.0.0")
}

注: 正確なバージョンは、Maps SDK for Android の現行バージョンに応じて異なることがあります。

マップの依存関係の管理については、バージョニングをご覧ください。

XML レイアウト ファイル

activity_maps.xml ファイルは、アプリの UI の構造を定義する XML レイアウト ファイルです。このファイルは res/layout ディレクトリにあります。activity_maps.xml ファイルは、以下の要素を含むフラグメントを宣言します。

• tools:context は、フラグメントのデフォルト アクティビティを MapsActivity に設定します。このアクティビティは、マップ アクティビティ ファイルで定義されています。
• android:name は、フラグメントのクラス名を SupportMapFragment に設定します。これは、マップ アクティビティ ファイルで使用されているフラグメントのタイプです。

XML レイアウト ファイルには、以下のコードが含まれています。

<fragment xmlns:android="http://schemas.android.com/apk/res/android"
    xmlns:map="http://schemas.android.com/apk/res-auto"
    xmlns:tools="http://schemas.android.com/tools"
    android:id="@+id/map"
    android:name="com.google.android.gms.maps.SupportMapFragment"
    android:layout_width="match_parent"
    android:layout_height="match_parent"
    tools:context=".MapsActivity" />

アプリをデプロイして実行する

アプリが正常に実行されると、次のスクリーンショットのように、オーストラリアのシドニーを中心とする地図が表示され、シドニーにマーカーが配置されます。

アプリをデプロイして実行するには:

1. Android Studio で [Run] メニュー オプション（またはプレイボタンのアイコン）をクリックして、アプリを実行します。
2. デバイスを選択するよう求めるプロンプトが表示されたら、以下のいずれかのオプションを選択します。
   • コンピュータに接続されている Android デバイスを選択します。
   • または、[Launch emulator] ラジオボタンをオンにして、以前に設定した仮想デバイスを選択します。
3. [OK] をクリックします。Android Studio によって Gradle が起動され、アプリのビルドが完了すると、デバイスまたはエミュレータに結果が表示されます。アプリが起動するまで、数分かかることがあります。

次のステップ

• 地図を設定する: このドキュメントでは、カメラの位置、地図のタイプ、UI コンポーネント、操作など、地図の初期設定およびランタイム設定を行う方法について説明します。

• 地図を Android アプリに追加する（Kotlin）: この Codelab では、Maps SDK for Android の主な機能のいくつかを実際にアプリで使用する方法について説明します。

• Maps Android KTX ライブラリを使用する: この Kotlin 拡張機能（KTX）ライブラリを使用すると、Maps SDK for Android の使用中に Kotlin 言語機能の一部を利用できるようになります。