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

このページでは、Navigation SDK を開発プロジェクトに統合する方法について説明します。

プロジェクトに Navigation SDK を追加する

Navigation SDK は、Google Maven リポジトリから入手できます。SDK をプロジェクトに追加するには、Gradle build.gradle または Maven pom.xml 構成を使用します。

注: この方法は、以前のアーティファクト ID を介して Navigation SDK に依存する一部のライブラリと互換性がありません。これには、Driver SDK v4.4 以前のリリースが含まれます。

1. Gradle または Maven の構成に次の依存関係を追加します。VERSION_NUMBER プレースホルダは、Navigation SDK for Android の目的のバージョンに置き換えます。

   Gradle

   モジュール レベルの build.gradle に次の行を追加します。

   dependencies {
           ...
           implementation 'com.google.android.libraries.navigation:navigation:VERSION_NUMBER'
   }
   

   Maven

   pom.xml に次の行を追加します。

   <dependencies>
     ...
     <dependency>
       <groupId>com.google.android.libraries.navigation</groupId>
       <artifactId>navigation</artifactId>
       <version>VERSION_NUMBER</version>
     </dependency>
   </dependencies>
   

   注: Mobility Services のお客様が元の非公開 Maven リポジトリからアップグレードする場合は、グループ名とアーティファクト名が変更され、com.google.cloud.artifactregistry.gradle-plugin プラグインが不要になったことに注意してください。

2. Maps SDK を使用する依存関係がある場合は、Maps SDK に依存する宣言された依存関係ごとに依存関係を除外する必要があります。

   Gradle

   最上位の build.gradle に次の行を追加します。

   allprojects {
           ...
           // Required: you must exclude the Google Play service Maps SDK from
           // your transitive dependencies to make sure there won't be
           // multiple copies of Google Maps SDK in your binary, as the Navigation
           // SDK already bundles the Google Maps SDK.
           configurations {
               implementation {
                   exclude group: 'com.google.android.gms', module: 'play-services-maps'
               }
           }
   }
   

   Maven

   pom.xml に次の行を追加します。

   <dependencies>
     <dependency>
     <groupId>project.that.brings.in.maps</groupId>
     <artifactId>MapsConsumer</artifactId>
     <version>1.0</version>
       <exclusions>
         <!-- Navigation SDK already bundles Maps SDK. You must exclude it to prevent duplication-->
         <exclusion>  <!-- declare the exclusion here -->
           <groupId>com.google.android.gms</groupId>
           <artifactId>play-services-maps</artifactId>
         </exclusion>
       </exclusions>
     </dependency>
   </dependencies>
   

ビルドを構成する

プロジェクトを作成したら、Navigation SDK を正常にビルドして使用できるように設定を構成します。

ローカル プロパティを更新する

• Gradle Scripts フォルダで、local.properties ファイルを開き、android.useDeprecatedNdk=true を追加します。

Gradle ビルド スクリプトを更新する

• build.gradle (Module:app) ファイルを開き、次のガイドラインに沿って、Navigation SDK の要件を満たすように設定を更新します。また、最適化オプションの設定も検討してください。

  Navigation SDK に必要な設定

  1. minSdkVersion を 24 以上に設定します。
  2. targetSdkVersion を 36 以上に設定します。
  3. javaMaxHeapSize を増やす dexOptions 設定を追加します。
  4. 追加のライブラリの場所を設定します。
  5. Navigation SDK の repositories と dependencies を追加します。
  6. 依存関係のバージョン番号を、利用可能な最新バージョンに置き換えます。

  ビルド時間を短縮するためのオプション設定

  • R8/ProGuard を使用してコード圧縮とリソース圧縮を有効にし、依存関係から未使用のコードとリソースを削除します。R8/ProGuard のステップの実行に時間がかかりすぎる場合は、開発作業でMultidexを有効にすることを検討してください。
  • ビルドに含まれる言語翻訳の数を減らす: 開発中は 1 つの言語に resConfigs を設定します。最終ビルドでは、実際に使用する言語に resConfigs を設定します。デフォルトでは、Gradle には、Navigation SDK でサポートされているすべての言語のリソース文字列が含まれています。

  Java 8 サポートの脱糖を追加する

  • Android Gradle プラグイン 4.0.0 以上を使用してアプリをビルドする場合、このプラグインは、多数の Java 8 言語 API のサポートを拡張します。詳細については、Java 8 の脱糖サポートをご覧ください。コンパイル オプションと依存関係オプションについては、以下のビルド スクリプト スニペットの例をご覧ください。
  • Navigation SDK のバージョンに一致する Gradle、Android Gradle プラグイン（AGP）、Desugar ライブラリのバージョンを使用します。次の表をご確認ください。
  • Desugar ライブラリは、app モジュールと、Navigation SDK に直接依存するモジュールで有効にする必要があります。

次の表に、Navigation SDK の各バージョンに必要な Gradle、AGP、Desugar ライブラリのバージョンを示します。

Navigation SDK のバージョン	Gradle のバージョン	AGP バージョン	Desugar ライブラリ
8.0.0 以降	9.1.0	9.0.1	com.android.tools:desugar_jdk_libs_nio:2.1.5
7.7.0 ～ 7.9.0	8.13	8.13.2	com.android.tools:desugar_jdk_libs_nio:2.1.5
7.3.0 ～ 7.6.0	8.11.1	8.10.0	com.android.tools:desugar_jdk_libs_nio:2.0.3

以下は、アプリの Gradle ビルド スクリプトの例です。使用している Navigation SDK のバージョンがこのドキュメントより少し新しいか古い可能性があるため、サンプルアプリで更新された依存関係のセットを確認してください。

apply plugin: 'com.android.application'

ext {
    navSdk = "__NAVSDK_VERSION__"
}

android {
    compileSdk 33
    buildToolsVersion='28.0.3'

    defaultConfig {
        applicationId "<your id>"
        // Navigation SDK supports SDK 23 and later.
        minSdkVersion 23
        targetSdkVersion 34
        versionCode 1
        versionName "1.0"
        // Set this to the languages you actually use, otherwise you'll include resource strings
        // for all languages supported by the Navigation SDK.
        resConfigs "en"
        multiDexEnabled true
    }

    dexOptions {
        // This increases the amount of memory available to the dexer. This is required to build
        // apps using the Navigation SDK.
        javaMaxHeapSize "4g"
    }
    buildTypes {
        // Run ProGuard. Note that the Navigation SDK includes its own ProGuard configuration.
        // The configuration is included transitively by depending on the Navigation SDK.
        // If the ProGuard step takes too long, consider enabling multidex for development work
        // instead.
        all {
            minifyEnabled true
            proguardFiles getDefaultProguardFile('proguard-android.txt'), 'proguard-rules.pro'
        }
    }
    compileOptions {
        // Flag to enable support for the new language APIs
        coreLibraryDesugaringEnabled true
        // Sets Java compatibility to Java 8
        sourceCompatibility JavaVersion.VERSION_1_8
        targetCompatibility JavaVersion.VERSION_1_8
    }
}

repositories {
    // Navigation SDK for Android and other libraries are hosted on Google's Maven repository.
    google()
}

dependencies {
    // Include the Google Navigation SDK.
    // Note: remember to exclude Google Play service Maps SDK from your transitive
    // dependencies to avoid duplicate copies of the Google Maps SDK.
    api "com.google.android.libraries.navigation:navigation:${navSdk}"

    // Declare other dependencies for your app here.

    annotationProcessor "androidx.annotation:annotation:1.7.0"
    coreLibraryDesugaring 'com.android.tools:desugar_jdk_libs_nio:2.1.5'
}

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

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

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

Android 用 Secrets Gradle プラグインをインストールして API キーを保存するには:

1. Android Studio で最上位レベルの build.gradle.kts または build.gradle ファイルを開き、plugins ブロックに次のコードを追加します。

   Kotlin

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

   Groovy

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

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

   Kotlin

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

   Groovy

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

3. Android Studio を使用している場合は、プロジェクトを Gradle と同期します。
4. 最上位レベルのディレクトリで secrets.properties ファイルを開き、次のコードを追加します。YOUR_API_KEY は実際の API キーに置き換えてください。API キーがバージョン管理システムにチェックインされないように、secrets.properties を .gitignore ファイルに追加します（または、バージョン管理システムから除外します）。
   注: secrets.properties ファイルがない場合は、local.properties ファイルと同じフォルダに作成します。

   MAPS_API_KEY=YOUR_API_KEY

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

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

   MAPS_API_KEY=DEFAULT_API_KEY

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

6. API キーを AndroidManifest.xml ファイルに追加するか、プログラムで API キーを指定します。
   • AndroidManifest.xml に API キーを追加します。

     <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（Navigation SDK for Android など）の認証に使用できます。下位互換性を確保するため、API では com.google.android.maps.v2.API_KEY という名前もサポートされています。この従来の名前は、Android Maps API v2 の認証にのみ使用できます。アプリでは、API キーのメタデータ名を 1 つのみ指定できます。両方を指定すると、API から例外がスローされます。

   • プログラムで API キーを指定します。

     Secrets Gradle プラグインにより、BuildConfig クラスでキーが使用可能になります。 アプリの初期化時（Application.onCreate() メソッドなど）に、次のようにメソッドを呼び出します。

     Kotlin

     1. 次の import ステートメントを追加します。

        import com.google.android.libraries.navigation.NavigationApi

     2. Application.onCreate() メソッドに次のコードを追加します。

        NavigationApi.setApiKey(BuildConfig.MAPS_API_KEY)

     Java

     1. 次の import ステートメントを追加します。

        import com.google.android.libraries.navigation.NavigationApi;

     2. Application.onCreate() メソッドに次のコードを追加します。

        NavigationApi.setApiKey(BuildConfig.MAPS_API_KEY);

     注: setApiKey() を使用する場合、次の点に注意してください。

     • null 以外、空以外の API キーを指定してください。
     • setApiKey() は、アプリのライフサイクル中に 1 回だけ呼び出します。このメソッドを 2 回以上呼び出すと、IllegalStateException がスローされます。
     • Navigator などの他の Navigation SDK コンポーネントを初期化する前に、setApiKey() を呼び出します。
     • このメソッドで指定したキーは、AndroidManifest.xml の API キーをオーバーライドします。
     • Navigation SDK バージョン 7.6 以降を使用します。

7. 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 root directory (the same folder as the root 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"
   }

   Groovy

   secrets {
       // To add your Maps API key to this project:
       // 1. If the secrets.properties file does not exist, create it in the root directory (the same folder as the root 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"
   }

アプリに必要な帰属表示を含める

アプリで Navigation SDK for Android を使用する場合は、アプリの法的通知セクションに帰属表示テキストとオープンソース ライセンスを含める必要があります。

要点: 帰属表示を含めるには、独立したメニュー項目として、または [このアプリについて] メニューの項目として追加します。

必要な帰属表示テキストとオープンソース ライセンスは、Navigation SDK for Android の ZIP ファイルにあります。

• NOTICE.txt
• LICENSES.txt

Mobility または Fleet Engine Deliveries のお客様の場合

Mobility または Fleet Engine Deliveries のお客様は、Mobility のドキュメントで課金についてご確認ください。取引の記録について詳しくは、課金の設定、課金対象の取引の記録、レポート、課金対象の取引の記録（Android）をご覧ください。

手動の依存関係（Gradle/Maven 以外）

ビルドシステムが推移的な依存関係を解決しない場合（Bazel など）、または AAR を手動で統合する場合は、これらの依存関係をプロジェクトに追加する必要があります。Gradle と Maven は、これらを自動的に解決します。

• androidx.datastore:datastore-core
• androidx.datastore:datastore-guava
• com.google.guava:listenablefuture
• androidx.concurrent:concurrent-futures