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

    Kotlin

    dependencies {

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

    Groovy

    dependencies {

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

    Kotlin

    android {
    compileSdk = 34

    defaultConfig {
        minSdk = 21
        // ...
    }
}

    Groovy

    android {
    compileSdk 34

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

    Kotlin

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

    Groovy

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

    注: 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.*"
}

ステップ 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 5.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 開発者サービスがインストールされているかどうかを確認する方法をご覧ください。

次のステップ

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