Kii Cloud SDK の導入手順

Android Studio 上で Kii Cloud を利用するために必要な設定を行います。

Kii Cloud SDK の追加

まず始めに Kii ライブラリーをプロジェクトに追加する必要があります。

ライブラリーは 2 通りの方法で追加可能です。

Maven リポジトリからのダウンロード
手動ダウンロード

リモートに設置された Kii SDK ライブラリーを自動的にダウンロードする Maven 方式の利用を推奨しますが、開発者ポータルより手動で AAR パッケージファイルをダウンロードすることもできます。

Maven リポジトリからのダウンロード

Gradle を使って Maven リポジトリから SDK をダウンロードできます。

まずルートプロジェクトディレクトリにあるトップレベルの "settings.gradle" に以下の repositories を追加します。

dependencyResolutionManagement {
  repositories {
    maven { url 'https://dl.cloudsmith.io/public/kii/kii-maven/maven' }
  }
}

次にビルド対象のモジュール配下にある "build.gradle"（デフォルトでは app ディレクトリの直下）に、以下の dependencies を追加します。追加する内容は Android Studio のバージョンによって異なります。

dependencies {
  implementation ('com.kii:cloud-sdk:XX.YY.ZZ'){
    transitive=true
  }
}

dependencies {
  compile ('com.kii:cloud-sdk:XX.YY.ZZ'){
    transitive=true
  }
}

com.kii:cloud-sdk:XX.YY.ZZ のバージョン部分 XX.YY.ZZ は、ダウンロードしたいファイルのバージョンに書き換えてください。最新版のバージョン番号は、開発者ポータルの "ダウンロード" のリンクより確認できます。

Version 2.4.12 以降は上記の指定方法を利用してください。Version 2.4.12 未満を指定する場合は、com.kii:cloud-sdk:XX.YY.ZZ の代りに com.kii:cloud-sdk:XX.YY.ZZ:library@aar と指定してください。Version 2.4.12 未満をすでに利用しており、Version 2.4.12 以降に変更する場合も上記の指定方法を利用してください。Version 2.4.12 以降では com.kii:cloud-sdk:XX.YY.ZZ:library@aar という指定方法を利用できません。

手動ダウンロード

まずはライブラリーをダウンロードします。開発者ポータル（https://developer.kii.com）にログインし、"ダウンロード" ページで SDK のリンクをクリックするとライブラリーがダウンロードされます。

ダウンロード後、下記の手順に従ってライブラリーをアプリケーションのプロジェクトに追加してください。

ダウンロードした Kii ライブラリー（android-cloud-sdk-vXX.YY.ZZ.aar）をプロジェクトの "libs" ディレクトリにコピーします。

コピー先は、ビルド対象のモジュールディレクトリ直下にある "libs" ディレクトリで、デフォルトでは "app/libs" です。
ビルド対象のモジュール直下（デフォルトでは app ディレクトリの直下）にある build.gradle に以下を追加します。

追加する内容は Android Studio のバージョンによって異なります。
- Android Studio 3.0 以降
- Android Studio 2.x 以前
- ```
repositories {
  flatDir {
    dirs 'libs'
  }
}

dependencies {
  implementation 'com.example.library:android-cloud-sdk-vXX.YY.ZZ@aar'
  implementation 'com.squareup.okhttp3:okhttp:3.10.0'
  implementation 'com.squareup.okhttp3:okhttp-apache:3.10.0'
}
```
- ```
repositories {
  flatDir {
    dirs 'libs'
  }
}

dependencies {
  compile 'com.example.library:android-cloud-sdk-vXX.YY.ZZ@aar'
  compile 'com.squareup.okhttp:okhttp:2.7.2'
  compile 'com.squareup.okhttp:okhttp-apache:2.7.2'
}
```
- repositories を新しく追加します。
- dependencies に implementation または compile の 3 行を追加します。android-cloud-sdk-vXX.YY.ZZ@aar のバージョン部分 XX.YY.ZZ は、ダウンロードしたファイルのバージョンに書き換えてください。com.example.library 部分はそのままで問題ありません。
Version 2.2.0 より、Analytics SDK が統合されています。バージョンアップした場合、dependencies に android-analytics-sdk-xxx@aar 行が残っているとエラーになるため、削除してください。また、既存コードから KiiAnalytics.initialize() の呼び出しを削除してください。

Kii Cloud SDK は HTTP 通信に OkHttp というオープンソースのライブラリーを使用しているため、依存関係も追記しています。

JAR ファイルの抽出

従来のように JAR ファイルを利用する場合、以下の手順で AAR ファイルから JAR ファイルを抽出してプロジェクトに追加してください。

android-cloud-sdk-vXX.YY.ZZ.aar ファイルを任意の解凍ツールを使って解凍します。AAR ファイルの実態は ZIP フォーマットの圧縮ファイルです。
解凍してできたディレクトリに含まれる classes.jar が Kii Cloud SDK のライブラリー本体です。これをプロジェクトにコピーします。
依存ライブラリーの OkHttp、OkHttpApache、Okio をダウンロードしてプロジェクトにコピーします。

プロジェクトの設定

以下の手順に従いプロジェクトを設定します。

プロジェクトを同期します。

Android Studio での設定の反映が必要な場合、"Sync Now" が表示されています。クリックしてプロジェクトの同期を行います。また、モバイルアプリをリビルドします。

これにより、Kii SDK のシンボルを補完できるようになります。
AndroidManifest.xml を更新し、必要なパーミッションを追加します。

以下のパーミッションを XML ファイルの manifest 直下に追加します。
```
<uses-permission android:name="android.permission.INTERNET" />
```
Object body のアップロード・ダウンロードにおいてパーミッションが必要な読み込み・書き込み先ファイルを利用する場合は、以下のパーミッションを追加します。READ_EXTERNAL_STORAGE/WRITE_EXTERNAL_STORAGE の詳細については Android の公式ドキュメントを参照ください。

なお、Android 6.0 以降（API レベル 23 以降）で動作させる場合は、READ_EXTERNAL_STORAGE/WRITE_EXTERNAL_STORAGE の設定に加えて実行時パーミッションの取得が必要です。実装方法の詳細は、実行時パーミッションの取得を参照してください。

読み取りアクセスのみが必要な場合は次のパーミッションを追加します。
```
<uses-permission android:name="android.permission.READ_EXTERNAL_STORAGE" />
```
読み取りアクセスと書き込みアクセスの両方が必要な場合は次のパーミッションを追加します。
```
<uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE" />
```
Analytics 機能を利用する場合は、次のサービスを追加します。
```
<application>
    <service android:name="com.kii.cloud.analytics.EventUploadService" />
</application>
```
Android 9.0 以降（API レベル 28 以降）で動作させる場合は、次の設定を追加します。
```
<application>
    <uses-library android:name="org.apache.http.legacy" android:required="false" />
</application>
```
また、application 要素の name 属性にアプリケーションクラスの名前を指定します。アプリケーションクラスはアクティビティの初期化に先立って実行されるクラスで、この手順では SDK を初期化します。ここでは、MobileApp としています。
```
<application
    android:allowBackup="true"
    android:icon="@drawable/ic_launcher"
    android:label="@string/app_name"
    android:theme="@style/AppTheme"
    android:name=".MobileApp" >
```
追加後は以下のようになります。
```
<?xml version="1.0" encoding="utf-8"?>
<manifest xmlns:android="http://schemas.android.com/apk/res/android"
    package="com.example.myapp" >

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

    <application
        android:allowBackup="true"
        android:icon="@drawable/ic_launcher"
        android:label="@string/app_name"
        android:theme="@style/AppTheme"
        android:name=".MobileApp" >

        <service android:name="com.kii.cloud.analytics.EventUploadService" />
     ...
```
SDK を導入するアプリケーションクラスに以下のコードを追加して SDK を初期化します。

アプリケーションクラスの名前は AndroidManifest.xml で指定したものです。
```
import com.kii.cloud.storage.*;
import android.app.Application;

// The MobileApp class should be declared in your mobile app's AndroidManifest.xml.
public class MobileApp extends Application {
  @Override
  public void onCreate() {
    super.onCreate();
    // Initialize the Kii Cloud SDK. Call this method before any other Kii SDK API calls.
    // This method can be called multiple times.
    Kii.initialize(getApplicationContext(), "___APPID___", "___APPKEY___", Kii.Site.JP, true);
  }
}
```
___APPID___ には開発者ポータルにて取得した AppID を、___APPKEY___ には任意の値を設定してください。

第 5 引数の true は、アプリ分析機能を使用することを意味します。false にするとアプリ分析機能は使用できませんが、モバイルアプリの起動が少し速くなります。

AppID をモバイルアプリに埋め込んでも、アクセス制御を正しく行えば安全性は確保できます。詳細は、セキュリティをご覧ください。

Proguard の設定

Kii Cloud SDK に対する Proguard の難読化の設定は、SDK の AAR ファイルに含まれています。特に設定を追加する必要はありません。