Android Studio プロジェクトをセットアップする

このページでは、Maps SDK for Android を使用するよう Android Studio プロジェクトを設定する方法について説明します。この手順では、Google マップ テンプレートは利用しません（Google マップ テンプレートを利用する場合は、クイックスタートをご覧ください）。

Google マップ テンプレートは、新しい Android Studio プロジェクトを自動的に設定して、基本の地図を追加します。他の Android Studio テンプレートを使用する Android プロジェクトに地図を追加する場合は、プロジェクトを手動で設定してから、地図を追加する必要があります。

ステップ 1: Android Studio をセットアップする

このドキュメントでは、Android Studio Hedgehog と Android Gradle プラグイン バージョン 8.2 を使用した開発環境について説明します。

ステップ 2: SDK をセットアップする

Maps SDK for Android ライブラリは、Google の Maven リポジトリを通して利用できます。アプリに SDK を追加するには、以下の手順を行います。

  1. 最上位レベルの settings.gradle ファイルで、pluginManagement ブロック以下に Gradle プラグイン ポータル、Google Maven リポジトリ、Maven セントラル リポジトリを含めます。pluginManagement ブロックは、スクリプト内の他のステートメントよりも前に配置する必要があります。
    pluginManagement {
    repositories {
        gradlePluginPortal()
        google()
        mavenCentral()
    }
}
  2. 最上位レベルの settings.gradle ファイルで、dependencyResolutionManagement ブロック以下に Google の Maven リポジトリと Maven セントラル リポジトリを含めます。 
    dependencyResolutionManagement {
    repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS)
    repositories {
        google()
        mavenCentral()
    }
}
  3. モジュール レベルの build.gradle ファイルで、Maps SDK for Android の Google Play 開発者サービス依存関係を追加します。

    Groovy

    dependencies {

    // Maps SDK for Android
    implementation 'com.google.android.gms:play-services-maps:18.2.0'
}

    Kotlin

    dependencies {

    // Maps SDK for Android
    implementation("com.google.android.gms:play-services-maps:18.2.0")
}
  4. モジュール レベルの build.gradle ファイルで、compileSdk と minSdk をそれぞれ次の値に設定します。

    Groovy

    android {
    compileSdk 34

    defaultConfig {
        minSdk 19
        // ...
    }
}

    Kotlin

    android {
    compileSdk = 34

    defaultConfig {
        minSdk = 19
        // ...
    }
}
  5. モジュール レベルの build.gradle ファイルの buildFeatures セクションに BuildConfig クラスを追加します。このクラスを使用すると、この手順で後ほど定義するメタデータの値にアクセスできます。

    Groovy

    android {
  // ...
  buildFeatures {
    buildConfig true
    // ...
  }
}

    Kotlin

    android {
  // ...
  buildFeatures {
    buildConfig = true
    // ...
  }
}

ステップ 3: API キーをプロジェクトに追加する

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

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

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

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

    Groovy

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

    Kotlin

    buildscript {
    dependencies {
        classpath("com.google.android.libraries.mapsplatform.secrets-gradle-plugin:secrets-gradle-plugin:2.0.1")
    }
}
  2. モジュール レベルの build.gradle ファイルを開き、次のコードを plugins 要素に追加します。

    Groovy

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

    Kotlin

    plugins {
    id("com.google.android.libraries.mapsplatform.secrets-gradle-plugin")
}
  3. モジュール レベルの 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 or build.gradle.kts 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.

    Groovy

    secrets {
    // Optionally specify a different file name containing your secrets.
    // The plugin defaults to "local.properties"
    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.*"
}

    Kotlin

    secrets {
    // Optionally specify a different file name containing your secrets.
    // The plugin defaults to "local.properties"
    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.*"
}

ステップ 4: アプリ マニフェストを更新する

このセクションでは、AndroidManifest.xml ファイルに追加する設定について説明します。

Google Play 開発者サービスのバージョン番号

application 要素内に次の宣言を追加します。これにより、このアプリのコンパイルに使用された Google Play 開発者サービスのバージョンが埋め込まれます。

<meta-data
    android:name="com.google.android.gms.version"
    android:value="@integer/google_play_services_version" />

位置情報の利用許可

アプリでユーザーの位置情報を利用する必要がある場合は、AndroidManifest.xml ファイルで位置情報の利用許可をリクエストする必要があります。利用許可には、デバイスの正確な現在地を提供する ACCESS_FINE_LOCATION と、やや精度の低い位置情報を提供する ACCESS_COARSE_LOCATION の 2 つのタイプがあります。詳しくは、位置情報のガイドをご覧ください。

ACCESS_FINE_LOCATION の利用許可をリクエストするには、次のコードを manifest 要素に追加します。

<uses-permission android:name="android.permission.ACCESS_FINE_LOCATION"/>

外部ストレージの利用許可

Google Play 開発者サービス SDK のバージョン 8.3 以降を対象としている場合、WRITE_EXTERNAL_STORAGE の利用許可は必要ありません。これ以前のバージョンの Google Play 開発者サービス SDK を対象としている場合は、manifest 要素内で WRITE_EXTERNAL_STORAGE の利用許可をリクエストする必要があります。

<uses-permission
        android:name="android.permission.WRITE_EXTERNAL_STORAGE" />

Apache HTTP レガシー ライブラリ

com.google.android.gms:play-services-maps:16.0.0 以前を使用していて、アプリが API レベル 28（Android 9.0）以降を対象としている場合は、AndroidManifest.xml の <application> 要素に以下の宣言を追加する必要があります。それ以外の場合は、この宣言は不要です。

<uses-library
    android:name="org.apache.http.legacy"
    android:required="false" />

ステップ 5: Android デバイスをセットアップする

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

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

ステップ 6: 必要に応じて Play 開発者サービスへの対応状況を確認する

Maps SDK for Android を使用するには、アプリをデプロイするデバイスで Google Play 開発者サービスをインストールしておく必要があります。Google では、アプリから呼び出してインストール状況を確認できるメソッドを用意しています。詳しくは、Google Play 開発者サービスがインストールされているかどうかを確認する方法をご覧ください。

次のステップ

プロジェクトの設定が完了したら、地図を追加できます。