ArcGIS Developers 開発リソース集 > 技術 Tips 集 > ArcGIS Maps SDK for Kotlin > インストールガイド

インストールガイド

出典：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 の [New Project] ウィザードで作成したプロジェクトで、次のセットアップ手順を実行します。

プロジェクトツールウィンドウで、ドロップダウンメニューから [Android ビュー]を選択します。[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.kotlin.android) apply false
        alias(libs.plugins.kotlin.compose) apply false
}

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

build.gradle.kts (Module: app)

plugins {
        alias(libs.plugins.android.application)
        alias(libs.plugins.kotlin.android)
        alias(libs.plugins.kotlin.compose)
}

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
        }
        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)
        implementation(libs.arcgis.maps.kotlin.toolkit.authentication)

}

Kotlin 2.0+では、Compose Compiler Gradle プラグインが必要です。このプラグインは、build.gradle.kts(Module :app)の plugins ブロックで alias(libs.plugins.kotlin.compose) として参照され、libs.versions.toml ファイルでは kotlin-compose = { id = "org.jetbrains.kotlin.plugin.compose", version.ref = "kotlin" } として宣言されています。Compose Compiler Gradle プラグインと Kotlin Android プラグインのバージョンは同じです。

2.0 より前の Kotlin バージョンを使用している場合は、Compose コンパイラーと Kotlin コンパイラーのバージョンが互換性があることを確認する必要があります。詳細については、Compose to Kotlin Compatibility Map を参照してください。

Android ビューから、[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
アプリで使用するすべてのツールキットコンポーネント。マップビューまたはシーンビューを表示するには、コンポーザブルな MapView とSceneView を含む geoview-compose モジュールの宣言が必要です。ユーザー認証を実装するには、authentication モジュールが必要です。

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

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

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

gradle/libs.versions.toml

[versions]
arcgisMapsKotlin = "200.7.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" }
arcgis-maps-kotlin-toolkit-authentication = { group = "com.esri", name = "arcgis-maps-kotlin-toolkit-authentication" }

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

[versions]
arcgisMapsKotlin = "200.7.0"

# Version numbers added by Android Studio New Project Wizard
agp = "8.7.3"
kotlin = "2.0.0"
coreKtx = "1.15.0"
junit = "4.13.2"
junitVersion = "1.2.1"
espressoCore = "3.6.1"
lifecycleRuntimeKtx = "2.8.7"
activityCompose = "1.9.3"
composeBom = "2024.11.00"

# Other version numbers
compileSdk = "35"
minSdk = "26"
targetSdk = "35"

[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" }
kotlin-android = { id = "org.jetbrains.kotlin.android", version.ref = "kotlin" }
kotlin-compose = { id = "org.jetbrains.kotlin.plugin.compose", version.ref = "kotlin" }

Android ビューから、[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 の機能によっては、マニフェストに権限を追加する必要がある場合があります。アプリに含まれていない機能の権限を含めないようにしてください。

ArcGIS Maps SDK for Kotlin の機能に必要な権限

ArcGIS Maps SDK for Kotlinの機能の中には、アプリで使用する際にAndroidの権限が必要なものがあります。

インターネットへのアクセス。ほとんどのアプリで必要になります。
詳細な位置情報。デバイスの GPS にアクセスするには、詳細な位置情報の権限が必要です。これは Android 開発において危険な権限とされています。

次のコード例（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 レベル 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 に対応したコンポーネント (コントロールとユーティリティー) が含まれています。MapView と SceneView のコンポーザブル関数を使用するには、モジュールレベルの build.gradle.kts に次の依存関係を含めます。

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

明示的なバージョン番号の代わりに、libs.versions.toml を使用している場合は以下のように記述します。

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

build.gradle.kts(Module： app) および libs.versions.toml に含めるべきコードの詳細な指示については、上記の Gradle で API を取得するを参照してください。

ツールキットの主要なモジュールには以下が含まれます。

GeoView-Compose は、MapView および SceneView クラスのコンポーザブルな実装を提供します。

Authentication モジュールは、ArcGIS Maps SDK for Kotlin での認証の課題を解決するためのプラグアンドプレイソリューションを提供します。

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

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

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

ダウンロードしたドキュメントのアーカイブを解凍するには、無料のオープンソースファイルアーカイブユーティリティー 7-Zip をお勧めします。

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

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

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

追加のデータ

投影エンジンデータ

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

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

Electronic Navigational Charts (ENC)

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

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

インストール ガイド

Gradle で API を取得する

必要な権限と機能

ArcGIS Maps SDK for Kotlin の機能に必要な権限

Android のストレージと権限

OpenGL ES バージョンの宣言

追加のダウンロード

サンプル コード

ArcGIS Maps SDK for Kotlin Toolkit

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

追加のデータ

投影エンジン データ

Electronic Navigational Charts (ENC)

インストールガイド

サンプルコード

投影エンジンデータ