初期化コードの実装

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

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

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

  1. Kii Cloud SDK の初期化

  2. Thing-IF SDK の初期化（オーナー定義とスキーマ定義を含む）

  3. デバイスのインストール

  4. 初期登録の実行

Kii Cloud SDK の初期化

下記のコードを、AppDelegate の application:didFinishLaunchingWithOptions メソッドに追加します。

func application(application: UIApplication, didFinishLaunchingWithOptions launchOptions: [NSObject: AnyObject]?) -> Bool {

    // Initialize the Kii Cloud SDK. Call this method before any other Kii SDK API calls.
    Kii.beginWithID("___APPID___", andKey: "___APPKEY___", andSite: KiiSite.JP)

    // Override point for customization after application launch.
    return true
}

ここで、___APPID___ は開発者ポータルで取得した AppID を、___APPKEY___ は任意の値を設定します。

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

Thing-IF SDK の初期化

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

// Instantiate your application on Kii Cloud.
let app = App(appID: "___APPID___", appKey: "___APPKEY___", site: Site.JP)

// Instantiate a Thing-IF API from a ThingIFAPIBuilder instance.
let api = ThingIFAPIBuilder(app: app, owner: owner).build()

実行後、api として、ThingIFAPI インスタンスを取得できます。

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

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

  • owner は Thing のオーナーとなるユーザーを表します。取得方法は オーナーの定義 をご覧ください。

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

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

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

デバイスのインストール

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

デバイスのインストール

デバイスをインストールするには、上記で取得した ThingIFAPI のインスタンスを利用して、以下のように実行します。

// Register the device token for the thing owner to Kii Cloud.
api.installPush(deviceToken, development: true, completionHandler: { (installationID: String?, error: ThingIFError?) -> Void in
  if error != nil {
    // Handle the error.
    return
  }
})
  • deviceToken には、application:didRegisterForRemoteNotificationsWithDeviceToken メソッドのパラメータによって取得したデバイストークン deviceToken を NSData で指定します。Thing-IF 向けの変更 をご覧ください。
  • development パラメータで開発環境か（true）、配布環境か（false）を選択します。
  • この API はノンブロッキング API のため、バックグラウンドで実行されます。実行が完了すると completionHandler が呼び出されます。

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

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

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

// Unregister the device token for the thing owner from Kii Cloud.
api.uninstallPush(nil, completionHandler: { (error: ThingIFError?) -> Void in
  if error != nil {
    // Handle the error.
    return
  }
})

このコードはデバイスのインストールが完了している前提です。uninstallPush メソッドの第 1 引数には、installPush の completionHandler で受け取った installationID を渡します。nil を渡すと、ThingIFAPI（api）内部で保持している ID を解放します。

この API は非同期で実行され、完了すると completionHandler が呼び出されます。

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

初期登録の実行

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

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

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

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

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

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

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

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

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

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

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

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

// Set the thing credentials.
let vendorThingID = "nbvadgjhcbn"
let thingPassword = "123456"

// Set onboarding options.
let thingType = "AirConditioner"
let interval = DataGroupingInterval.INTERVAL_15_MINUTES
let options = OnboardWithVendorThingIDOptions(thingType: thingType, thingProperties: nil, interval: interval)

// Onboard the thing.
api.onboardWithVendorThingID(vendorThingID, thingPassword: thingPassword, options: options, completionHandler: { (target: Target?, error: ThingIFError?) -> Void in
  if error != nil {
    // Handle the error.
    return
  }
})

onboard メソッドには以下の値を設定しています。

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

completionHandler には Target とエラー情報が通知されます。Target は ThingIFAPI（api）内で保持されるため、ここでは無視しても問題ありません。

なお、初期登録を一旦行うと、その端末で thingType、thingProperties、interval を指定しても無視されます。

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

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

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

target は、onboard の completionHandler の引数から取得することもできます。

// Instantiate the thing.
let target = api.target

// Get the thing ID.
let thingID = target.typedID.id

// Get the thing access token.
let thingAccessToken = target.accessToken

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

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

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

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

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

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

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

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

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

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

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

以下の処理を行います。

// Set the thing credentials.
let vendorThingID = "nbvadgjhcbn"
let thingPassword = "123456"

// Set the data grouping interval option.
let interval = DataGroupingInterval.INTERVAL_15_MINUTES
let options = OnboardWithVendorThingIDOptions(interval: interval)

// Onboard the thing.
api.onboardWithVendorThingID(vendorThingID, thingPassword: thingPassword, options: options, completionHandler: { (target: Target?, error: ThingIFError?) -> Void in
  if error != nil {
    // Handle the error.
    return
  }
})

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

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

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

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