インストール ガイド

出典:ArcGIS Maps SDK for Kotlin - Guide - Install and set up

このインストール ガイドでは、ArcGIS Maps SDK for Kotlin (バージョン 200.x) のインストールとセットアップ手順を紹介します。マップを表示する方法については「アプリの作成」のチュートリアルをご覧ください。

ArcGIS Maps SDK for Kotlin をインストールする前に、開発マシンが 動作環境 を満たしていることを確認してください。アプリを実行するすべてのターゲット デバイスには、Android API レベルの最小バージョンが必要です。詳細については、システム要件を参照してください。

Gradle を使用してインストールすることをお勧めします。これにより、Esri の Maven リポジトリから必要な依存関係と SDK バイナリがインストールされます。

Gradle で API を取得する

Android Studio で [New Project] ウィザードを実行する際、[Phone and Tablet]、[Empty Activity] の順に選択します。Empty Activity オプションは Compose 対応アプリを作成するために必要な Android からの Jetpack Compose 依存関係を提供します。

以下の手順では、Android Studio Koala 2024.1.1 を使用します。最適な結果を得るには、このバージョン以降の Android Studio を使用してください。

Android Studio の [New Project] ウィザードで作成したプロジェクトで、次のセットアップ手順を実行します。

  1. プロジェクト ツール ウィンドウから、[Gradle Scripts] > [build.gradle.kts (Project: Display_a_map)] を開きます。ファイルの内容を次のコードに置き換えます。

    build.gradle.kts (Project: Display_a_map)

    // すべてのサブプロジェクト/モジュールに共通の構成オプションを追加できる最上位のビルド ファイル
    plugins {
        alias(libs.plugins.android.application) apply false
        alias(libs.plugins.jetbrains.kotlin.android) apply false
    }
    
  2. プロジェクト ツール ウィンドウから、[Gradle Scripts] > [build.gradle.kts (Module: app)] を開きます。ファイルの内容を次のコードに置き換えます。

    build.gradle.kts (Module: app)

    plugins {
        alias(libs.plugins.android.application)
        alias(libs.plugins.jetbrains.kotlin.android)
    }
    
    android {
        namespace = "com.example.app"
        compileSdk = libs.versions.compileSdk.get().toInt()
    
        defaultConfig {
            applicationId = "com.example.app"
            minSdk = libs.versions.minSdk.get().toInt()
            targetSdk = libs.versions.targetSdk.get().toInt()
            versionCode = 1
            versionName = "1.0"
            testInstrumentationRunner = "androidx.test.runner.AndroidJUnitRunner"
            vectorDrawables {
                    useSupportLibrary = true
            }
        }
    
        buildTypes {
            release {
                isMinifyEnabled = false
                proguardFiles(getDefaultProguardFile("proguard-android-optimize.txt"), "proguard-rules.pro")
            }
        }
        compileOptions {
            sourceCompatibility = JavaVersion.VERSION_17
            targetCompatibility = JavaVersion.VERSION_17
        }
    
        kotlinOptions {
            jvmTarget = "17"
        }
    
        buildFeatures {
            compose = true
        }
    
        composeOptions {
            kotlinCompilerExtensionVersion = "1.5.11"
        }
    
        packaging {
            resources {
                excludes += "/META-INF/{AL2.0,LGPL2.1}"
            }
        }
    }
    
    dependencies {
    
        implementation(libs.androidx.core.ktx)
        implementation(libs.androidx.lifecycle.runtime.ktx)
        implementation(libs.androidx.activity.compose)
        implementation(platform(libs.androidx.compose.bom))
        implementation(libs.androidx.ui)
        implementation(libs.androidx.ui.graphics)
        implementation(libs.androidx.ui.tooling.preview)
        implementation(libs.androidx.material3)
        testImplementation(libs.junit)
        androidTestImplementation(libs.androidx.junit)
        androidTestImplementation(libs.androidx.espresso.core)
        androidTestImplementation(platform(libs.androidx.compose.bom))
        androidTestImplementation(libs.androidx.ui.test.junit4)
        debugImplementation(libs.androidx.ui.tooling)
        debugImplementation(libs.androidx.ui.test.manifest)
    
        // ArcGIS Maps for Kotlin - SDK dependency
        implementation(libs.arcgis.maps.kotlin)
        // Toolkit dependencies
        implementation(platform(libs.arcgis.maps.kotlin.toolkit.bom))
        implementation(libs.arcgis.maps.kotlin.toolkit.geoview.compose)
        // Additional modules from Toolkit, if needed, such as:
        // implementation(libs.arcgis.maps.kotlin.toolkit.authentication)
    
    }
    

    Android Studio の [New Project] ウィザードで生成されるモジュール レベルの build.gradle.kts ファイルでは、Android と Kotlin のツールのバージョンが宣言されます。Kotlin Compiler (kotlinOptions ブロック) のオプションは互換性がなければなりません。互換性は Android の Compose to Kotlin Compatibility Map を参照することで確認できます。

    build.gradle.kts (Module: app)

    kotlinOptions {
        jvmTarget = "17"
    }
    
    composeOptions {
        kotlinCompilerExtensionVersion = "1.5.11"
    }
    
  3. プロジェクト ツール ウィンドウから、[Gradle Scripts] > [libs.versions.toml] を開きます。[version] セクションで、ArcGIS Maps SDK for Kotlin のバージョン番号を宣言します。また、[libraries] セクションには、以下のライブラリの宣言を追加します。

    • ArcGIS Maps SDK for Kotlin SDK
    • ArcGIS Maps SDK for Kotlin Toolkit BOM
    • 必要な Toolkit コンポーネント
      このチュートリアルでは、コンポーザブル MapView を含む geoview-compose コンポーネントのみが必要です。

    Toolkit BOM のバージョンは、宣言したすべての Toolkit コンポーネントに適用されます。

    Gradle バージョン カタログは依存関係のバージョンを宣言するための標準的な Android のアプローチです。build.gradle.kts でバージョン番号を指定したり、version.gradle でバージョン番号を列挙するよりも推奨されます。Android Studio の最近のリリースでは、[New Project Wizard] がこの標準をサポートする build.gradle.ktsgradle/libs.version.toml ファイルを生成します。

    Gradle バージョン カタログでは、BOM ファイルを使用して、BOM 内のすべての成果物に対して単一のバージョン番号を指定することもできます。詳細については、ArcGIS Maps SDK for Kotlin Toolkit の README の Using the BOM を参照してください。

    gradle/libs.versions.toml

    [versions]
    arcgisMapsKotlin = "200.5.0"
    
    [libraries]
    arcgis-maps-kotlin = { group = "com.esri", name = "arcgis-maps-kotlin", version.ref = "arcgisMapsKotlin" }
    arcgis-maps-kotlin-toolkit-bom = { group = "com.esri", name = "arcgis-maps-kotlin-toolkit-bom", version.ref = "arcgisMapsKotlin" }
    arcgis-maps-kotlin-toolkit-geoview-compose = { group = "com.esri", name = "arcgis-maps-kotlin-toolkit-geoview-compose" }
    # Additional modules from Toolkit, if needed, such as:
    # arcgis-maps-kotlin-toolkit-authentication = { group = "com.esri", name = "arcgis-maps-kotlin-toolkit-authentication" }
    

    libs.versions.toml を手で編集しないでください。代わりに、以下のコードを展開し、展開した内容をすべてコピーして libs.versions.toml ファイルに貼り付け、新規プロジェクト ウィザードで生成された元の内容を置き換えてください。

    [versions]
    arcgisMapsKotlin = "200.5.0"
    
    # Version numbers added by Android Studio New Project Wizard
    agp = "8.3.2"
    kotlin = "1.9.23"
    coreKtx = "1.13.0"
    junit = "4.13.2"
    junitVersion = "1.1.5"
    espressoCore = "3.5.1"
    lifecycleRuntimeKtx = "2.8.3"
    activityCompose = "1.9.0"
    composeBom = "2024.04.01"
    
    # Other version numbers
    compileSdk = "34"
    minSdk = "26"
    targetSdk = "34"
    
    [libraries]
    arcgis-maps-kotlin = { group = "com.esri", name = "arcgis-maps-kotlin", version.ref = "arcgisMapsKotlin" }
    arcgis-maps-kotlin-toolkit-bom = { group = "com.esri", name = "arcgis-maps-kotlin-toolkit-bom", version.ref = "arcgisMapsKotlin" }
    arcgis-maps-kotlin-toolkit-geoview-compose = { group = "com.esri", name = "arcgis-maps-kotlin-toolkit-geoview-compose" }
    # Additional modules from Toolkit, if needed, such as:
    # arcgis-maps-kotlin-toolkit-authentication = { group = "com.esri", name = "arcgis-maps-kotlin-toolkit-authentication" }
    
    androidx-core-ktx = { group = "androidx.core", name = "core-ktx", version.ref = "coreKtx" }
    junit = { group = "junit", name = "junit", version.ref = "junit" }
    androidx-junit = { group = "androidx.test.ext", name = "junit", version.ref = "junitVersion" }
    androidx-espresso-core = { group = "androidx.test.espresso", name = "espresso-core", version.ref = "espressoCore" }
    androidx-lifecycle-runtime-ktx = { group = "androidx.lifecycle", name = "lifecycle-runtime-ktx", version.ref = "lifecycleRuntimeKtx" }
    androidx-activity-compose = { group = "androidx.activity", name = "activity-compose", version.ref = "activityCompose" }
    androidx-compose-bom = { group = "androidx.compose", name = "compose-bom", version.ref = "composeBom" }
    androidx-ui = { group = "androidx.compose.ui", name = "ui" }
    androidx-ui-graphics = { group = "androidx.compose.ui", name = "ui-graphics" }
    androidx-ui-tooling = { group = "androidx.compose.ui", name = "ui-tooling" }
    androidx-ui-tooling-preview = { group = "androidx.compose.ui", name = "ui-tooling-preview" }
    androidx-ui-test-manifest = { group = "androidx.compose.ui", name = "ui-test-manifest" }
    androidx-ui-test-junit4 = { group = "androidx.compose.ui", name = "ui-test-junit4" }
    androidx-material3 = { group = "androidx.compose.material3", name = "material3" }
    
    [plugins]
    android-application = { id = "com.android.application", version.ref = "agp" }
    jetbrains-kotlin-android = { id = "org.jetbrains.kotlin.android", version.ref = "kotlin" }
    
  4. プロジェクト ツール ウィンドウから、[Gradle Scripts] > [settings.gradle.kts] を開きます。ファイルの内容を次のコードに置き換えます。

    settings.gradle.kts (Display a map)

    pluginManagement {
        repositories {
            google {
                content {
                    includeGroupByRegex("com\\.android.*")
                    includeGroupByRegex("com\\.google.*")
                    includeGroupByRegex("androidx.*")
                }
            }
    
            mavenCentral()
            gradlePluginPortal()
        }
    }
    
    dependencyResolutionManagement {
        repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS)
        repositories {
            google()
            mavenCentral()
            maven { url = uri("https://esri.jfrog.io/artifactory/arcgis") }
        }
    }
    
    rootProject.name = "Display a map"
    include(":app")
    

必要な権限と機能

Android は、権限が分離されたオペレーティング システムです。アプリで使用する ArcGIS の機能によっては、マニフェストに権限を追加する必要がある場合があります。アプリに含まれていない機能の権限を含めないようにしてください。

アプリが Android API バージョン 22 以前で実行されている場合、インストール時にすべての権限が要求されます(許可または拒否)。アプリが Android API バージョン 23 以降で実行されている場合、アクセス許可が要求され、インストール時に自動的に付与されます。ただし、潜在的に危険な権限は実行時にリクエストする必要があり、そのためにはアプリにコードを追加する必要があります。まだ許可されていない場合は、Android フレームワークまたは Android サポート ライブラリが、権限を確認して要求するために使用されます。詳細については、アプリの権限を宣言するアプリの権限をリクエストするをご覧ください。

アクセス許可が必要な ArcGIS Maps SDK for Kotlin の機能

  • インターネットへのアクセス(ほとんどのアプリはこれを必要とします):Android API 23 以降の標準の権限
  • デバイスの GPS にアクセスするための FINE_LOCATION の権限:Android API 23 以降での危険な権限

次のコード例(AndroidManifest.xml ファイルの場合)には、これらの権限が含まれています。

AndroidManifest.xml

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

Android のストレージと権限

Android API Level 30 では、すべてのアプリは Android デバイスのファイルシステムにアクセスするために対象範囲別ストレージを使用します。対象範囲別ストレージを使用すると、アプリは (1) 自身のファイル、および (2) メディア ストア内の共有ファイルにアクセスすることができます。下記のパーミッションの宣言は、サポートされていません。

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

Android のストレージは、API レベル 29 以降、劇的に変化しています。Android のストレージとパーミッションの詳細については、次のリンクを参照してください。

OpenGL ES バージョンの宣言

Android マニフェストに uses-feature 要素を追加すると、Play ストアでアプリを正しいタイプのデバイスで利用できるようになります。

MapView(2D)を使用するアプリには、最小でも OpenGL ES 2.x が必要です。

<uses-feature android:glEsVersion="0x00020000" android:required="true" />

SceneView(3D)を使用するアプリには、OpenGL ES 3.x が必要です。

<uses-feature android:glEsVersion="0x00030000" android:required="true" />

追加のダウンロード

開発プロジェクトを強化するために、サンプル コードデータの追加リソースを利用できます。このガイドを、スタンドアロンの開発者ドキュメントとしてダウンロードすることもできます。

サンプル コード

ドキュメントでサンプルの包括的なリストを参照するか、GitHub リポジトリからサンプル コードをダウンロードしてください。

また、Google Play ストアからサンプル ビューアー アプリをダウンロードし、お使いのデバイスでライブ サンプルをご覧いただくこともできます。

ArcGIS Maps SDK for Kotlin Toolkit

ArcGIS Maps SDK for Kotlin Toolkit には、アプリ開発を簡素化する Compose に対応したコンポーネント (コントロールとユーティリティ) が含まれています。MapViewSceneView のコンポーザブル関数を使用するには、モジュール レベルの build.gradle.kts に次の依存関係を含めます。

implementation(platform("com.esri:arcgis-maps-kotlin-toolkit-bom:200.5.0"))
implementation("com.esri:arcgis-maps-kotlin-toolkit-geoview-compose")

GeoView-ComposeMapViewSceneView クラスのコンポーザブルな実装を提供します。

Toolkit には、Compose に対応した他の特別なコンポーネントも含まれています。詳細は Toolkit を参照してください。

スタンドアロンの開発者向けドキュメント

ダウンロード ページ から、開発者向けドキュメントをアーカイブとしてダウンロードできます。アーカイブには、ローカル Web サーバからドキュメントを提供する手順が含まれているため、インターネットに接続しなくてもドキュメントにアクセスできます。スタンドアロン ドキュメントには、開発者ガイド、API リファレンス、チュートリアル、およびサンプル ドキュメントが含まれています。このドキュメントは、ローカルのスタンドアロン コンピューターまたは内部ネットワーク上で実行するように設計されており、パブリックなインターネット上では実行できません。

ローカルでドキュメントを公開する方法:

  • 使用する SDK のドキュメントをダウンロードします。ダウンロードしたファイルは、.zip アーカイブ形式になっています。
  • アーカイブをローカル フォルダに解凍します。解凍されたアーカイブには、publicinstall という 2 つのサブフォルダがあります。
  • install フォルダ内の README.md ファイルを開き、選択した Web サーバーの指示に従います。

ライブ ドキュメント サイトはリリース時及びリリースの間に定期的に更新されますが、スタンドアロン ドキュメントは静的で、最初のリリース後は更新されません。

追加のデータ

Projection Engine データ

測地系変換は、ある空間基準から別の空間基準へジオメトリを投影する際に、2つの空間基準の基礎となる測地系に違いがある場合に使用されます。測地系変換は、数学的に定義する(方程式ベースの変換)ことも、外部のサポート ファイルに依存する(グリッド ベースの変換)ことも可能です。アプリでグリッドベースの変換を使用する場合、Projection Engine ファイルが存在する必要があります。API は、必要なファイルがローカルのファイルシステムで利用可能かどうかを検出することができます。Projection Engine ファイルが無い状態で変換をしようとすると、エラーが発生します。API は、必要なファイルがローカル ファイル システムで利用可能かどうかを検出できます。

グリッド ベースの変換を使用している場合は、ダウンロード ページからサポートする Projection Engine ファイルをダウンロードしてください。座標系、投影法、測地系変換の操作の詳細については、Spatial references のトピックを参照してください。

Electronic Navigational Charts (ENC)

航海用電子海図(ENC)は、水路や海上の情報を可視化し、分析するためのジオリファレンスされたベクター データセットです。SDK は、国際水路機関(IHO)S-57 規格 に準拠した ENC をサポートしています。

航海用電子海図 (ENC) を使用する場合は、ダウンロード ページから hydrography データをダウンロードします。ENC データの操作の詳細については、Display electronic navigational charts のトピックを参照してください。