初期化コードの実装

SDK を導入するアプリケーションから初期化処理を実行する必要があります。

このページでは、Thing をスタンドアローンで使用する場合の初期化方法を示しています。Thing Interaction Framework のゲートウェイ機能を使用して接続する場合は、初期化コードの実装（ゲートウェイ）の初期化方法を使用してください。

初期化処理は次の順番で実行するように実装します。

Kii Cloud SDK の初期化
Thing-IF SDK の初期化（オーナー定義とスキーマ定義を含む）
デバイスのインストール
初期登録の実行

Kii Cloud SDK の初期化

アプリケーションクラスから、以下の処理を実行します。これはアプリの起動時に呼び出されます。

アプリケーションクラスの名前は、Thing-IF SDK の導入手順において、AndroidManifest.xml で指定したものです。

// 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, false);
  }
}

___APPID___ と ___APPKEY___ の項目は、開発者ポータルにて取得した AppID と任意の値を設定してください（アプリケーションの作成を参照してください）。

第 5 引数の false は、Kii Cloud SDK のアプリ分析機能を使用しないことを意味します。アプリから Kii Cloud SDK の機能を本格的に使用し、アプリ分析機能を併用する場合を除いて false を指定します。

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

Thing-IF SDK の初期化

次に、Thing-IF SDK を初期化します。この処理は、上記 Kii Cloud SDK の初期化後であれば、アプリ中のどの位置で実行しても問題ありません。

ThingIFAPI api;

// Instantiate your application on Kii Cloud.
KiiApp app = new KiiApp("___APPID___", "___APPKEY___", Site.JP);

// Instantiate a ThingIFAPIBuilder object.
ThingIFAPIBuilder ib = ThingIFAPIBuilder.newBuilder(getApplicationContext(), app, owner);

// Add a schema to the ThingIFAPIBuilder instance.
ib.addSchema(schema);

// Instantiate a Thing-IF API from the ThingIFAPIBuilder instance.
api = ib.build();

ソースコード中、以下の情報を指定します。

___APPID___ と ___APPKEY___ の項目は、開発者ポータルにて取得した AppID と任意の値を設定してください（アプリケーションの作成を参照してください）。

Site の代わりに api-jp.kii.com のようなサーバーのホスト名を指定して初期化することもできます。詳細は Javadoc をご覧ください。
owner は Thing のオーナーとなるユーザーを表します。取得方法はオーナーの定義をご覧ください。

ユーザーの指定方法は、モバイルアプリのデザインによって様々な形式が考えられます。本ガイドでは、仮ユーザー（Pseudo User）を使って明示的なユーザー作成やログインを行わずにユーザーを利用する方法を案内しています。明示的にログイン操作を行うデザインを採用した場合は、ログイン画面を用意し、ログイン処理の完了時に Thing-IF SDK を初期化することになります。
schema は Thing に送信するコマンドのスキーマ定義を表します。設定方法はスキーマの定義をご覧ください。

初期化が完了すると、API を実装しているインスタンスを取得できます。ThingIFAPIBuilder の build メソッドを呼び出すと、Thing-IF SDK が初期化されて ThingIFAPI インスタンスが返されます。ThingIFAPI インスタンスは、クラスのフィールドや Activity クラスに保持するなどして、後続の処理で呼び出せる状態にしておきます。また、初期化済みの情報の保存と復元に示す方法によって、プロセス再起動時にインスタンスを再生成したり、保存や読み込みを行ったりできます。

複数個の ThingIFAPI を初期化して、複数のスキーマまたは Thing を扱うこともできます。この場合、ib の setTag メソッドの引数に、各 ThingIFAPI を識別するための一意の名前をタグとして与えます。タグは saveInstance や loadFromStoredInstance によって保存や読み込みを行う際にインスタンスを識別するために使用します。

デバイスのインストール

Thing-IF SDK を利用するには、Thing からの応答を受け取れるよう、デバイスをインストールします。この操作により、オーナーと FCM のデバイストークンが Kii Cloud 上で紐付きます。

デバイスのインストール

デバイスをインストールするには、Thing-IF SDK の初期化で取得した ThingIFAPI のインスタンスを使って以下のように実行します。パラメーターについて詳しくは、後の実装例をご覧ください。

try {
  // Register the device token for the thing owner to Kii Cloud.
  api.installPush(token, PushBackend.GCM);
} catch (ThingIFException e) {
  // Handle the error.
}

デバイスのインストールが完了すると、ThingIFAPI 作成時に指定したオーナーは、指定されたデバイストークンと紐付けて Thing Interaction Framework に登録されます。既存のデバイストークンはインストールによって上書きされるため、以前紐付いていたオーナーへのプッシュ通知はこのデバイスに届かなくなります。

実装例

この例では、Android (FCM) プッシュ通知設定チュートリアルのコードを Thing-IF 向けに変更するものとして説明します。プッシュ通知チュートリアルの例では、MainActivity のメインスレッドからインストール処理を実行する必要があるため、JDeferred を使ってデバイスのインストール処理を非同期で実行する例を示します。

Hello Thing-IF チュートリアルのように、API 呼び出しのため作業スレッドを作成している場合は、JDeferred を使った実装を行わず、作業スレッドから installPush を呼び出せば目的の処理を実装できます。

まずは、JDeferred による Promise を使用して、次のような API 実行用のメソッドを用意します。

private Promise<Void, Throwable, Void> installFCMPush(final ThingIFAPI api, final String token) {
  return mAdm.when(new DeferredAsyncTask<Void, Void, Void>() {
    @Override
    protected Void doInBackgroundSafe(final Void... params) throws Exception {
      // Register the device token for the thing owner to Kii Cloud.
      api.installPush(token, PushBackend.GCM);
      return null;
    }
  });
}

さらに、この処理の呼び出し部分を MainActivity に組み込みます。

private AndroidDeferredManager mAdm = new AndroidDeferredManager();

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

  // Get a FCM token.
  String fcmToken = FirebaseInstanceId.getInstance().getToken();
  if (fcmToken == null) {
    Toast.makeText(MainActivity.this, "Error FCM is not ready", Toast.LENGTH_LONG).show();
    return;
  }

  // Register the device token for the thing owner to Kii Cloud.
  mAdm.when(installFCMPush(apiEndNode1, fcmToken)
  ).then(new DoneCallback<Void>() {
    @Override
    public void onDone(Void param) {
      Toast.makeText(MainActivity.this, "Succeeded push registration", Toast.LENGTH_LONG).show();
    }
  }).fail(new FailCallback<Throwable>() {
    @Override
    public void onFail(final Throwable tr) {
      Toast.makeText(MainActivity.this, "Error push registration:" + tr.getLocalizedMessage(), Toast.LENGTH_LONG).show();
    }
  });
  ......
}

デバイスのアンインストール

インストールしたデバイスをアンインストールしたい場合は、以下のコードを実行します。

try {
  // Unregister the push notification for the thing owner.
  api.uninstallPush(api.getInstallationID());
} catch (ThingIFException e) {
  // Handle the error.
}

このコードはデバイスのインストールが完了していることを前提としています。getInstallationID メソッドは、installPush でインストールが成功していない場合 null を返します。

成功すると、Thing Interaction Framework からのプッシュ通知がこの端末に届かなくなります。

初期登録の実行

モバイルアプリから Thing を制御するには、モバイルアプリと Thing を紐付ける操作が必要です。この紐付け操作を 初期登録（Onboarding） と呼びます。

初期登録には、モバイルアプリから紐付ける方法と、Thing とモバイルアプリ両方から紐付ける方法の 2 通りがあります。いずれの方法でも同じ結果が得られますが、双方で共有すべき情報が異なります。Thing 側の実装も含めて検討し、どちらを採用するかを決めます。

ここでは、以下のどちらか一方の手順を実行します。

モバイルアプリから紐付ける場合
Thing とモバイルアプリ両方から紐付ける場合

サービス全体での初期登録の流れや手順の決定方法の詳細については、機能ガイドの初期登録をご覧ください。

初期登録を行わずに ThingIFAPI を使って初期登録以外の処理（コマンドの実行やステートの取得など）を開始すると、エラーになります。

初期登録の API を含め、Thing-IF SDK で提供する API はすべてブロッキング API です。ブロッキング API をメインスレッドから呼び出すと、ユーザーインターフェイスが停止する問題を起こします。Thing-IF SDK の API は、実装上の注意点に挙げるような非同期処理の技術を使うか、自分で作成した作業スレッドから呼び出すようにしてください。

モバイルアプリから紐付ける場合

この方式では、モバイルアプリ上で Thing Interaction Framework への紐付けリクエストをまとめて行います。

機能ガイドの初期登録に示すとおり、この方法では初期登録の実装がシンプルになりますが、モバイルアプリと Thing との間で Bluetooth などでの通信手段を確保する必要があります。

ステップ 1：モバイルアプリからの初期登録

モバイルアプリからの初期登録を行うため、初期登録に必要な情報を Thing から受け取ります。下記に示すように Thing の vendorThingID と thingPassword が必要です。

モバイルアプリに通知を行う方法は任意です。転送方法の例は、こちらをご覧ください。

モバイルアプリで初期登録を実行するには、以下の処理を行います。

try {
  // Set the thing credentials.
  String vendorThingID = "nbvadgjhcbn";
  String thingPassword = "123456";

  // Set onboarding options.
  OnboardWithVendorThingIDOptions.Builder builder = new OnboardWithVendorThingIDOptions.Builder();
  builder.setThingType("AirConditioner");
  builder.setThingProperties(new JSONObject());
  builder.setDataGroupingInterval(DataGroupingInterval.INTERVAL_15_MINUTES);
  OnboardWithVendorThingIDOptions options = builder.build();

  // Onboard the thing.
  api.onboard(vendorThingID, thingPassword, options);
} catch (ThingIFException e) {
  // Handle the error.
}

ここでは以下の値を設定しています。

vendorThingID：ベンダーが定義した Thing の ID です。詳細はこちらをご覧ください。アプリケーション内で一意であれば、200 文字までの英数字、ハイフン、アンダースコアおよびピリオドが利用可能です。なお、このフィールド値は後で変更できません。
thingPassword：Thing のパスワードです。Thing Interaction Framework 上に登録された Thing の領域をセキュアにするため、Thing ごとに異なるパスワードを設定するのが基本です。一旦設定したパスワードは変更できません。
setThingType()：Thing タイプです。100 文字までの英数字、ハイフン、アンダースコアおよびピリオドが利用可能です。スキーマで指定したものと同じものを指定します。
setThingProperties()：Thing の属性を JSONObject で指定できます。Kii Cloud SDK を併用する場合に利用する項目のため、ここでは空の JSONObject を指定します。
setDataGroupingInterval()：ステート履歴を保存する場合、履歴をグループ化する間隔を指定します。指定のない場合はステート履歴は保存されません。指定可能な値は INTERVAL_1_MINUTE、INTERVAL_15_MINUTES、INTERVAL_30_MINUTES、INTERVAL_1_HOUR、INTERVAL_12_HOURS のいずれかです。詳しくはこちらをご参照ください。

なお、初期登録を一旦行うと、その端末で setThingType()、setThingProperties()、setDataGroupingInterval() を指定しても無視されます。

モバイルアプリからの初期登録が行われるまで、ステート履歴は利用できない点にご注意ください。初めのモバイルアプリが紐付くまでの間に Thing はステートをアップロードできますが、そのステートは履歴に保存されません。

ステップ 2：Thing 側の初期化

モバイルアプリからの初期登録では、登録の結果取得できた値を Thing 側に転送する必要があります。以下のコードにより、取得した thingID と Thing のアクセストークンを取得し、これらを Thing に転送します。

// Instantiate the thing.
Target target = api.getTarget();

// Get the thing ID.
String thingID = target.getTypedID().getID();

// Get the thing access token.
String thingAccessToken = target.getAccessToken();

Thing 側では、受け取った値を使って初期化を行います（Thing 側では Thing Interaction Framework にアクセスせずに初期登録が完了します）。詳細はこちらをご参照ください。

アクセストークンはパスワードと同様に機密情報であるため、万一、漏洩すると、その Thing は他のユーザーによって制御される恐れがあります。転送には Bluetooth などの安全な手段を使用してください。

Thing とモバイルアプリ両方から紐付ける場合

この方式では、まず Thing から Thing Interaction Framework への紐付けリクエストを行い、次にモバイルアプリからの紐付けリクエストを行います。

実際にはどちらを先に実行しても問題ありませんが、両方の初期登録が完了するまでコマンドの送信やステートのやりとりは実行できません。

機能ガイドの初期登録に示すとおり、この方法では、モバイルアプリと Thing の両方で Thing Interaction Framework にアクセスして初期登録を行う必要がありますが、モバイルアプリと Thing の間で直接の通信を行う必要はありません。

ステップ 1：Thing からの初期登録

Thing からの初期登録を行い、ステートの登録やコマンドの受信ができるようにします。

詳細はこちらをご覧ください。

ステップ 2：モバイルアプリからの初期登録

次にモバイルアプリからの初期登録を行い、モバイルアプリからのコマンド送信やステートの取得ができるようにします。

以下の処理を行います。

try {
  // Set the thing credentials.
  String vendorThingID = "nbvadgjhcbn";
  String thingPassword = "123456";

  // Set the data grouping interval option.
  OnboardWithVendorThingIDOptions.Builder builder = new OnboardWithVendorThingIDOptions.Builder();
  builder.setDataGroupingInterval(DataGroupingInterval.INTERVAL_15_MINUTES);
  OnboardWithVendorThingIDOptions options = builder.build();

  // Onboard the thing.
  api.onboard(vendorThingID, thingPassword, options);
} catch (ThingIFException e) {
  // Handle the error.
}

ここでは以下の値を設定しています。

vendorThingID：ベンダーが定義した Thing の ID です。詳細はこちらをご覧ください。ステップ 1 で設定済の vendorThingID を指定します。
thingPassword：Thing のパスワードです。Thing Interaction Framework 上に登録された Thing の領域をセキュアにするため、ユーザーと同様に、Thing ごとに異なるパスワードを設定します。ステップ 1 で設定済のパスワードを指定します。
setDataGroupingInterval()：ステート履歴を保存する場合、履歴をグループ化する間隔を指定します。指定のない場合はステート履歴は保存されません。指定可能な値は INTERVAL_1_MINUTE、INTERVAL_15_MINUTES、INTERVAL_30_MINUTES、INTERVAL_1_HOUR、INTERVAL_12_HOURS のいずれかです。詳しくはこちらをご参照ください。

なお、API 上は、Thing 側で取得した thingID を Bluetooth などでデバイスに転送し、vendorThingID の代わりに thingID を指定してモバイルアプリ側の初期登録を実行することもできます。