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

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

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

開発環境の概要

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

Android デバイスを設定する

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

• Android デバイスを使用する場合は、ハードウェア デバイス上でのアプリの実行の手順を踏んでください。
• Android Emulator を使用する場合は、Android Studio に付属している Android Virtual Device（AVD）Manager を使用して仮想デバイスを作成し、エミュレータをインストールしてください。

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（Lollipop、Android 5.0）以降）よりも大きいバージョンを選択する必要があります。SDK バージョン要件についての最新情報はリリースノートでご確認ください。

   • [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 ファイルを開きます。アクティビティの名前が異なる場合がありますが、これはセットアップ時に設定した名前になります。

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

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

gcloud projects create "PROJECT"

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

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

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

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

このタスクを効率化するには、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 はバージョン管理システムにチェックインされないため、このファイルにキーを保存します。

   MAPS_API_KEY=YOUR_API_KEY

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

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

   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}" />

   Note: com.google.android.geo.API_KEY is the recommended metadata name for the API key. A key with this name can be used to authenticate to multiple Google Maps-based APIs on the Android platform, including the Maps SDK for Android. For backwards compatibility, the API also supports the name com.google.android.maps.v2.API_KEY. This legacy name allows authentication to the Android Maps API v2 only. An application can specify only one of the API key metadata names. If both are specified, the API throws an exception.

10. In Android Studio, open your module-level build.gradle.kts or build.gradle file and edit the secrets property. If the secrets property does not exist, add it.

    Edit the properties of the plugin to set propertiesFileName to secrets.properties, set defaultPropertiesFileName to local.defaults.properties, and set any other 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")
}

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

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 言語機能の一部を利用できるようになります。