HMS Map Kit Android SDKの導入方法について

#1. 概要
[HMS Map Kit](https://developer.huawei.com/consumer/jp/hms/huawei-MapKit/)はHMSの地図サービスであり、現時点では以下の5つのサービスを提供しています。

1. [Android SDK](https://developer.huawei.com/consumer/en/doc/development/HMS-Guides/hms-map-v4-abouttheservice)
2. [JavaScript API](https://developer.huawei.com/consumer/en/doc/development/HMS-Guides/hms-map-js-about-the-service)
3. [Web API](https://developer.huawei.com/consumer/en/doc/development/HMS-Guides/hms-map-directions-api)
4. [React Native SDK](https://developer.huawei.com/consumer/en/doc/development/HMS-Guides/hms-map-v4-abouttheservice-rn)
5. [Xamarin SDK](https://developer.huawei.com/consumer/en/doc/development/HMS-Guides/hms-map-v4-xamarin-abouttheservice)

現時点では、どのSDK/APIも無料で使えます。
今回はAndroid SDKの導入方法について説明したいと思います。

#2. Map Kit Android SDKを使用する流れ

全体の流れは以下のようになります。

1. 開発者アカウントの登録
2. 開発者コンソール（AppGallery Connect）でプロジェクトを作成
3. コンソールでプロジェクトの詳細を設定
4. Androidプロジェクトに必要なファイルの導入、依頼関係の追加
5. コーディング

次に各ステップについて詳細に説明します。

#3. 詳細ステップ

##3.1 開発者アカウントの登録
HMSのSDKを使用するには、Huawei開発者アカウントを取得する必要があります。
アカウントの申請には主に以下の2つのステップがあります。

1. Huawei IDの取得（すてにHuawei IDをもっている人はこのステップが不要となります）
2. 開発者認証

詳しいガイドは以下のサイト（英語）を参照してください。
Huawei ID申請ガイド：https://developer.huawei.com/consumer/en/doc/10104
開発者認証（個人の場合）：https://developer.huawei.com/consumer/en/doc/10122

##3.2 Appgallery Connectにてアプリプロジェクトの作成とプロジェクトの設定

###3.2.1 プロジェクトの作成
[AppGallery Connect（リンク）](https://developer.huawei.com/consumer/en/console)はHuaweiの開発者サイトです。
開発者サイトにログインしたら、最初は以下のページが表示されます。
![1.PNG](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/674503/c7bc7f2c-0bbe-fa2a-8b57-7a95ca0989d1.png)
このページから、AppGallery Connectをクリックしてコンソールに入ります。
クリックしたら以下のページが表示されます。
![2.PNG](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/674503/43e7bfbc-8d25-3daa-c937-c84f0c8d8ba9.png)
次に、Map appsをクリックしてアプリ管理画面に入ります。
![3.PNG](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/674503/fa2214ce-648a-4811-46d5-a861fa30c423.png)
My appsページの右上の「New app」をクリックして新しいプロジェクトを作成します。
「New apps」をクリックしたら次に下のページが表示されます。
![4.PNG](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/674503/061722b7-3c6c-931e-7492-d11328852b7b.png)
このページでは、アプリの種類（APK：Androidアプリの場合、RPK：[QuickApp](https://developer.huawei.com/consumer/en/huawei-quickApp/)の場合）、アプリ名やデフォルト言語を設定できます。
**また、ここでは「Add to project」にチェックを入れる必要があります。**

入力が完了したら、「OK」をクリックして作成が完了となります。
「OK」をクリックしたらアプリの詳細ページが表示されます。

次に、プロジェクトのAPI設定やFingerprint設定をする必要がありますので、左上のMy appsより、My projectsを選択してプロジェクトの詳細設定ページに入ります。

![5.PNG](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/674503/da3cba30-776b-28ab-e4b2-27c6e69a34ee.png)

###3.2.2 プロジェクトの設定
プロジェクト詳細ページでは、以下のようにアプリの詳細情報が表示されています。
まずは、Map APIを有効にする必要がありますので、Manage APIsをクリックします。
![7.PNG](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/674503/8a45599c-1706-a0e4-6c32-154f257212cf.png)
Manage APIsページで使用したいAPIを有効にします。今回はMap Kitを有効にしました。
![8.PNG](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/674503/4712e7fe-8100-073a-92e9-fbf7dad8f3b5.png)

次に、fingerprintを設定し、コンフィグファイル（agconnect-services.json）をダウンロードします。
![9.PNG](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/674503/c143a170-9669-3c73-9b1b-aea86639e27e.png)

以上の操作で、Map Kitを使用する準備が完了となります。

詳しいガイドは以下のサイト（英語）を参照してください。
https://developer.huawei.com/consumer/en/doc/development/HMS-Guides/hms-map-configuringinagc

##3.3 Android Studioでの前準備（SDK導入）

###3.3.1 コンフィグファイルの導入
先ほどダウンロードしたagconnect-services.jsonファイルをappフォルダに入れます。
**このファイルは、アプリの認証情報が記載されたコンフィグファイルとなります。このファイルがないと、HMS SDKが機能しなくなる可能性が高いですのでかならずプロジェクトに導入してください**
![10.PNG](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/674503/3df05a62-6e91-07d1-1fd9-1eb066c84074.png)

###3.3.2 gradleファイルに依頼関係を追加

次に、gradleファイルに依頼関係を追加します。
まずはProjectのgradleに、以下のコメントの下の行を追加します。

```gradle:build.gradle(Project)
buildscript {
    repositories {
        google()
        jcenter()

        //HMS Core SDKのMavenを追加します
        maven {url 'https://developer.huawei.com/repo/'}
    }
    dependencies {
        classpath "com.android.tools.build:gradle:4.1.0"

        //agcpのclasspathを追加します
        classpath 'com.huawei.agconnect:agcp:1.4.1.300'
    }
}

allprojects {
    repositories {
        google()
        jcenter()

        //HMS Core SDKのMavenを追加します
        maven {url 'https://developer.huawei.com/repo/'}
    }
}

```

追加したら一度Syncし、次にappのgradleに以下のように依頼関係を追加します。

```gradle:build.gradle(app)
plugins {
    id 'com.android.application'

    //'com.android.application'の後に以下の行を追加します
    id 'com.huawei.agconnect'
}

android {
    compileSdkVersion 30
    buildToolsVersion "30.0.2"

    //signingConfigsを追加します
    signingConfigs {
        config {
            storeFile file("Your_KeyStore")
            storePassword "Your_Password"
            keyAlias "Your_KeyAlias"
            keyPassword "Your_Password"
            v2SigningEnabled true
        }
    }

    defaultConfig {
        applicationId "com.example.mapdemoqiita"

        //HMS Map Kitを使うには、minSdkVersionを19以上にする必要があります
        minSdkVersion 21
        targetSdkVersion 30
        versionCode 1
        versionName "1.0"

        testInstrumentationRunner "androidx.test.runner.AndroidJUnitRunner"
    }

    buildTypes {
        release {
            minifyEnabled false
            proguardFiles getDefaultProguardFile('proguard-android-optimize.txt'), 'proguard-rules.pro'

            //signingConfigsを追加します
            signingConfig signingConfigs.config
        }
        debug{
            //signingConfigsを追加します
            signingConfig signingConfigs.config
        }
    }
    compileOptions {
        sourceCompatibility JavaVersion.VERSION_1_8
        targetCompatibility JavaVersion.VERSION_1_8
    }
}

dependencies {

    ...

    //HMS Map SDKを追加します。最新のバージョンは以下のリンクから確認できます。
    //https://developer.huawei.com/consumer/en/doc/development/HMSCore-Guides-V5/android-sdk-version-change-history-0000001050156688-V5
    implementation 'com.huawei.hms:maps:5.0.3.301'
}
```

完了したらSyncをクリックしてSDKの導入が完了となります。


詳しいガイドは以下のサイト（英語）を参照してください。
https://developer.huawei.com/consumer/en/doc/development/HMS-Guides/hms-map-integratingthehmssdk

##3.4 コーディング

###3.4.1 Permissionの追加
Map Kitを使用するにはManifestに以下のPermissionを追加する必要があります。

```xml:AndroidManifest.xml
 　　<!--  Map Kitを使うには以下のpermissionを追加する必要があります  -->
    <uses-permission android:name="android.permission.INTERNET"/>
    <uses-permission android:name="android.permission.ACCESS_NETWORK_STATE"/>
    <uses-permission android:name="com.huawei.appmarket.service.commondata.permission.GET_COMMON_DATA"/>
    <!--  現在位置を表示したい場合には以下のpermissionを追加する必要があります  -->
    <!--  <uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION"/>  -->
    <!--  <uses-permission android:name="android.permission.ACCESS_FINE_LOCATION"/>  -->

```

###3.4.2 Mapの作成
現時点では、Map KitはMapFragmentとMapViewをサポートしています。
今回はMapFragmentを使って、Mapのinstanceを作成する方法を示します。
詳しいガイドは、[Huawei Developerオフィシャルサイト](https://developer.huawei.com/consumer/en/doc/development/HMS-Guides/hms-map-createmap)から確認できます。

まずは、LayoutファイルにMapFragmentを追加します。

```xml:activity_main.xml
<?xml version="1.0" encoding="utf-8"?>
<androidx.constraintlayout.widget.ConstraintLayout xmlns:android="http://schemas.android.com/apk/res/android"
    xmlns:app="http://schemas.android.com/apk/res-auto"
    xmlns:tools="http://schemas.android.com/tools"
    android:layout_width="match_parent"
    android:layout_height="match_parent"
    tools:context=".MainActivity">

    <!-- 　MapFragmentを追加します。  -->
    <fragment
        android:id="@+id/map_fragment"
        class="com.huawei.hms.maps.SupportMapFragment"
        android:layout_width="match_parent"
        android:layout_height="match_parent"
        />

</androidx.constraintlayout.widget.ConstraintLayout>
```

次に、ActivityでMapのInstanceを作成します。

```java:MainActivity.java
public class MainActivity extends AppCompatActivity implements OnMapReadyCallback {

    HuaweiMap mMap;

    @Override
    protected void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);

        setContentView(R.layout.activity_main);

        //MapFragmentをロードし、getMapAsyncでコールバックを設定します
        SupportMapFragment supportMapFragment = (SupportMapFragment) getSupportFragmentManager().findFragmentById(R.id.map_fragment);
        supportMapFragment.getMapAsync(this);
    }

    public void onMapReady(HuaweiMap huaweiMap) {
        //ここでmapの詳細設定をすることができます
        mMap = huaweiMap;
    }
}
```

最後に、API Keyを設定します。
HMS Android Map SDK 5.0.0.300から、Mapをロードする前に、API Keyを設定する必要があるようになっていますので、以下のようにApplicationでAPI Keyを設定できます。
API Keyの設定については、こちらの記事も合わせて参考できます：[HMS CoreのMap KitとSite KitにおけるAPI Keyの利用の注意点](https://qiita.com/Rei_2020/items/f66e9435aa74a20b28ab)

```java:MainApplication.java
public class MainApplication extends Application {
    @Override
    public void onCreate() {
        super.onCreate();
        
        //API Keyを設定します
        MapsInitializer.setApiKey("YOUR_API_KEY");
    }
}
```

これで実行すると、以下のようにHuawei Mapが表示されました。
![map.jpg](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/674503/28702ac3-c77f-51be-883b-8024a53fc26e.jpeg)

より詳しい開発ガイドは以下のリンクより確認できます。
Creating a Map：https://developer.huawei.com/consumer/en/doc/development/HMS-Guides/hms-map-createmap
Interacting with a Map: https://developer.huawei.com/consumer/en/doc/development/HMS-Guides/hms-map-mapinteraction
Draring on a Map: https://developer.huawei.com/consumer/en/doc/development/HMS-Guides/hms-map-drawonthemap


#4. トラブルシューティング
Mapが表示されない場合には、以下の項目を確認したらいいと思います。

1. Map APIが有効になっているかどうか
2. fingerprintは正しくコンソールに登録できているかどうか
3. agconnect-services.jsonファイルはプロジェクトに導入しているかどうか
4. Permissionは追加したかどうか
5. API Keyが設定されているかどうか

#5. その他リソース
APIリファレンス：https://developer.huawei.com/consumer/en/doc/development/HMS-References/hms-map-cameraupdate
サンプルコード：https://developer.huawei.com/consumer/en/doc/development/HMS-Examples/hms-map-v4-example