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 Developers のダッシュボードから各インストーラーやデータをダウンロードするには、ArcGIS 開発者アカウントでログインする必要があります。アカウントをお持ちでない場合は、サインアップ (無料) してください。アカウントの作成方法は「開発者アカウントの作成」をご覧ください。

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 Iguana 2023.2.1 Patch 1 を使用します。最適な結果を得るには、このバージョン以降の Android Studio を使用してください。

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

settings.gradle.kts ファイルの repositories ブロック (dependencyResolutionManagement 内にネストされています) で、Esri の Maven リポジトリ URL を指定して maven ブロックを追加します。Esri のリポジトリはオープンソースではないため、google() や mavenCentral() からは使用できないため、この URL を指定する必要があります。

settings.gradle.kts
```
dependencyResolutionManagement {
    repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS)
    repositories {
        google()
        mavenCentral()

        // Esri の Maven リポジトリを追加
        maven {
            url = uri("https://esri.jfrog.io/artifactory/arcgis")
        }
    }
}
```
module レベルの build.gradle.kts (Module :app) ファイルの dependencies ブロック内で、ArcGIS Maps SDK for Kotlin の依存関係をアプリに追加します。

この依存関係を、ArcGIS Maps SDK for Kotlin を使用する各モジュールに追加する必要があります。

build.gradle.kts (Module: app)
```
dependencies {
    ...
    // ArcGIS Maps SDK for Kotlin の依存関係を追加
    implementation 'com.esri:arcgis-maps-kotlin:200.4.0'
}
```
Esri が公開しているすぐに使用できる Compose コンポーネントを提供する依存関係を追加します。ArcGIS Maps SDK for Kotlin Toolkit で定義されているこれらの Compose コンポーネントは、ArcGIS Maps SDK for Kotlin の標準 API のクラスにアクセスします。Toolkit は、Compose ベースで ArcGIS Maps SDK for Kotlin と互換性のあるテスト済みの UI 要素を含めるための最も効率的な方法です。

geoview-compose という名前の Toolkit モジュールへの依存関係を宣言します。このモジュールには、マップビューとシーンビューを実相するためのコンポーザブルな関数が含まれています。Toolkit には、他にもいくつかの便利な Compose ベースのモジュールが含まれています。使用する他の Toolkit モジュールを dependency ブロックに追加します。

build.gradle.kts (Module: app)
```
dependencies {
    . . .
    // ArcGIS Maps SDK for Kotlin の依存関係を追加
    implementation("com.esri:arcgis-maps-kotlin:200.4.0")
    // ツールキットの依存関係を追加
    implementation("com.esri:arcgis-maps-kotlin-toolkit-geoview-compose:200.4.0")
    // 追加のツールキットのモジュールが必要な場合、以下のように記述します
    // implementation("com.esri:arcgis-maps-kotlin-toolkit-authentication:200.4.0")
}
```
アーティファクトのバージョン管理 (代替方法)
これまでのコードでは、ツールキットの依存関係でアーティファクトのバージョンを指定しています。この方法の他に、ツールキットの BOM (Bill of Materials), に依存することもできます。BOM には、互いに互換性のある個々のツールキットコンポーネントのバージョンが指定されています。これらのバージョン番号は、BOM の .pom ファイルをから確認できます。詳細は、ツールキットリポジトリのトップレベルの README を参照してください。Toolkit BOM 自体にもバージョン番号があることに注意してください。

Gradle バージョンカタログは、依存関係のバージョンを管理する最先端の方法です。gradle/libs.versions.toml ファイルでは、各依存関係の Maven 名の変数とバージョン番号の変数を宣言します。ここには、Toolkit BOM、Toolkit モジュール、ArcGIS Maps SDK for Kotlin、Kotlin ライブラリ、Android ライブラリなど、すべての依存関係を宣言できます。Android Studio の最近のリリースでは、[New Project] ウィザードによってこのファイルが作成されます。

Toolkit BOM を使用するように変更すると、build.gradle.kts コードは以下のようになります。libs.arcgis.map.kotlin.toolkit.bom や libs.arcgis.maps.kotlin.toolkit.geoview.compose などの変数は、gradle/libs.versions.toml がバージョンを管理しているため、バージョンを指定しないことに注意してください。

build.gradle.kts (Module: app)
```
dependencies {
    ・・・
    // ArcGIS Maps SDK for Kotlin の SDK 依存関係
    implementation(libs.arcgis.maps.kotlin)
    // Toolkit の依存関係
    implementation(platform(libs.arcgis.maps.kotlin.toolkit.bom))
    implementation(libs.arcgis.maps.kotlin.toolkit.geoview.compose)
    // 追加のツールキットのモジュールが必要な場合、以下のように記述します
    // implementation(libs.arcgis.maps.kotlin.toolkit.authentication)
}
```

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

build.gradle.kts (Module: app)

android {
        . . .
        kotlinOptions {
            jvmTarget = "1.8"
        }
        buildFeatures {
            compose = true // このプロジェクトで Jetpack Compose を有効にします
        }

        composeOptions {
            kotlinCompilerExtensionVersion = "1.5.11"
        }
        . . .
}

必要な権限と機能

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

GeoView-Compose：MapView と SceneView クラスのコンポーザブルな実装を提供します。

Toolkit には、Compose に対応した他の特別なコンポーネントも含まれています。

Authenticator：ネットワークおよび ArcGIS 認証の必要なリクエストが発生すると、ユーザーインターフェイスが表示されます。
Compass：地図が回転するとコンパスがその方向を示します。地図が北を指している場合は自動的に非表示になります。
FeatureForm：外部から設定された FeatureForm API を使用して、レイヤーのフィーチャのフィールド値を編集できるようにします。
FloorFilter：GeoView で、敷地、敷地内の建物、または建物内のフロアでフロアプランデータをフィルタリングできます。

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

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

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

使用する ArcGIS Runtime SDK のドキュメントをダウンロードします。ダウンロードしたファイルは、.zip アーカイブ形式になっています。
アーカイブをローカルフォルダに解凍します。解凍されたアーカイブには、public と install という 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 のトピックを参照してください。