初期登録

Thing-IF SDK を利用するためには、Thing とモバイルアプリとのユーザーとの間で紐付け操作が必要です。この紐付け操作を初期登録（Onbording）と呼び、初期化処理の一部として実行する必要があります。

初期登録を行うことで、紐付けを初めとした Thing Interaction Framework 上での初期化処理を実行するとともに、Thing を操作できるユーザーを明確にしてセキュリティを確保することができます。

このページでは、初期登録の仕組みと、初期登録の実装で必要になる Thing Interaction Framework の機能について示します。

アクセストークン

Thing-IF SDK で多数の Thing とモバイルアプリユーザーを扱うため、それらを識別する必要があります。

モバイルアプリでは、モバイルアプリを操作するユーザーを KiiUser として Thing Interaction Framework 上に登録し、そのアクセストークンを入手する必要があります。KiiUser は Kii Cloud SDK で提供される ユーザー管理 機能で取り扱うオブジェクトです。

アクセストークンは Thing Interaction Framework へのリクエストの際に SDK が自動的に送信します。Thing Interaction Framework は、アクセストークンによって、そのユーザーがアクセスできるリソースの範囲を識別するため、適切なセキュリティを確保できます。たとえば、他人の領域や他人と紐付けられた Thing へはアクセスできません。

Thing Interaction Framework を使用する場合、本来はモバイルアプリを操作するユーザーをユーザー名とパスワードを使って作成する必要があります。アプリ開発ガイドでは、簡易的に、仮ユーザー（Android、iOS、JavaScript、REST）を使って KiiUser を作成する方法を案内しています。

Thing でも同様に、デバイスとしての自分自身の存在を Thing Interaction Framework 上に登録し、アクセストークンを入手します。ユーザーの場合と同様に、SDK がリクエストの際にアクセストークンを使うことで、その Thing からアクセスできる範囲が決まります。

アクセストークンの実装方法は、こちら（Android、iOS、JavaScript）をご覧ください。

Thing オーナー

Thing Interaction Framework では、Thing を使うユーザーやグループを Thing のオーナーとして関連付ける処理を行います。

グループは KiiGroup として登録される Kii Cloud のオブジェクトです。グループをオーナーにすることで、複数のユーザーをグループとしてまとめ、Thing を共有できます。

オーナーとなったユーザーやグループは、その Thing へのコマンドを送信したり、ステートを確認したりできます。

オーナーの関係はクラウド側の機能として構築されているため、強固なセキュリティを確保できます。REST API などを直接使って強制的にリクエストを発行しても、自分がオーナーとなっている Thing 以外、操作することはできません。

Thing の識別子

Thing Interaction Framework 上の Thing を識別するため、1 つの Thing に対して、以下の 2 つの ID を使用します。

  • vendorThingID

    vendorThingID は、開発者の側で自由に決めることができる ID です。Thing Interaction Framework のアプリケーションの中で一意であれば、出荷前に ID を割り当てても、初回起動時に UUID のような値を ID として振り出しても構いません。

    vendorThingID がシリアル番号のように予測可能な文字列になっていると、第三者からの攻撃のリスクが高まります。できるだけ予測不可能なランダムな文字列を使用することをおすすめします。

    なお、Thing を Thing Interaction Framework に登録する際に必要な Thing のパスワード（説明や図では thingPassword と表現することもあります）も vendorThingID と同様に開発者が設定できますが、Thing の初回登録時に利用者に決めてもらうこともできます。

  • thingID

    thingID は、Thing Interaction Framework に Thing を登録した際、Thing Interaction Framework が割り当てる ID です。開発者が決めることはできません。Thing Interaction Framework のアプリケーション中、一意の値を取ります。

ID の共有

モバイルアプリと Thing を関連付けるには、これらの ID をモバイルアプリと Thing の間で、何らかの方法を使って共有する必要があります。

ゲートウェイを使用する場合、ゲートウェイとエンドノードの ID は、SDK によって自動的に共有されるため、下記は該当しません。代わりに、モバイルアプリは接続先ゲートウェイを IP アドレス等で識別する必要があります。

たとえば、以下のような方法で共有できます。

  • vendorThingID、thingID とも、Bluetooth や Wi-Fi などで通信して ID の文字列を渡すことで、ID を共有できます。これらの通信手段は、Thing-IF SDK で準備されていないため、別途作り込む必要があります。
  • vendorThingID を出荷時に一意の値として割り当て、Thing 側の不揮発メモリなどに記録できるような場合は、通信を行わずにアナログ的な方法で共有することもできます。たとえば、紙媒体に印刷したものをデバイスに添付してモバイルアプリで手入力したり、紙媒体で QR コードを添付してモバイルアプリに読み取らせたりすることができます。thingID は Thing Interaction Framework 側で動的に決まるため、この方法は使用できません。

Kii Cloud SDK との互換性

Thing Interaction Framework で指定した vendorThingID はそのまま Kii Cloud SDK for Thing でも指定することができます。

Thing Interaction Framework で割り当てられた thingID は、Kii Cloud SDK との間で互換性があります。thingID は、th.0123456789ab-cdef-0123-4567-89abcdef のような形式を持った文字列です。Kii Cloud SDK ではこの形式の thingID をそのまま扱います。Thing Interaction Framework の SDK では、この形式の thingID に、Thing であるという型情報を加えたものを TypedID として指定します（ユーザーやグループも同様に Kii Cloud の ID と型情報を組み合わせます）。SDK では TypedID クラスのメソッドやプロパティによって thingID を容易に取得することができます。

なお、開発者ポータルで Thing 情報を確認 する際には、vendorThingID や thingID が直接表示されます。

初期登録

初期登録とは、Thing Interaction Framework 上で行われる初期設定です。ユーザーやグループと、Thing を紐付け、それらの間でデータのやりとりを行うための設定を行います。Thing Interaction Framework 上では、Thing の登録、オーナーとの関連付け、コマンド等の格納領域の確保、プッシュ通知で利用する内部オブジェクトやデバイスの登録などの様々な設定が行われます。

初期登録は、次の 2 通りのいずれかの方法を選択できます。どちらの方法でも初期登録できますが、モバイルアプリと Thing の間で必要なやりとりなどの実装に対する要件が異なります。実現したいサービス全体で見たとき、実装しやすい方を選択できます。

なお、いずれの方法でも、初期登録は SDK から複数回実行できます。2 回目以降の実行では、Thing Interaction Framework 上ですでに設定されている登録処理や設定処理は行われません。

モバイルアプリから初期登録を行う方法

この方法では、モバイルアプリ上で、Thing まで含めた初期登録処理をすべて行います。初期登録の結果得られた thingID と Thing のアクセストークンを、Bluetooth などのセキュアな方法で Thing に転送し、Thing 側の初期化を行います。

初期登録は以下の手順で行います。図中の番号が以下の説明文に対応します。

  1. 準備として、モバイルアプリ側で事前に KiiUser を登録し、アクセストークンを取得しておきます。
  2. vendorThingID と thingPassword をモバイルアプリに用意します。thingPassword は Thing の登録時に使用するパスワードで、これによってセキュリティを確保します。vendorThingID は様々な方法で用意できます。Thing の工場出荷時に割り当てておいて紙媒体や Bluetooth 経由でモバイルアプリに用意しても、モバイルアプリが UUID などを使って動的に生成しても構いません。
  3. モバイルアプリから初期登録を実行します。リクエストには、vendorThingID と thingPassword を含むパラメータが必要です。
  4. Thing Interaction Framework 上で初期登録が実行されます。この際、登録処理の一部として、Thing の作成と、KiiUser または KiiGroup との紐付け（オーナー登録）が同時に行われます。Thing がすでに登録されていた場合（2 台目のデバイスに紐付ける場合など）、Thing の作成処理等は行われません。
  5. 初期登録リクエストの戻り値として、SDK は thingID と Thing のアクセストークンを取得できます。
  6. モバイルアプリでは、SDK から thingID と Thing のアクセストークンを取得し、ユーザープログラム側の実装によって、これを Thing に転送します。転送のための実装は Thing-IF SDK とは別に作り込む必要があります。
  7. Thing 側では、渡された thingID と Thing のアクセストークンを使って SDK を初期化します。

thingPassword や Thing のアクセストークンは機密情報です。これが漏洩すると、そのデバイスは他のユーザーから不正に操作されるリスクが発生します。

実装方法はこちら（Android、iOS、JavaScript、REST API、Thing）をご覧ください。

この方法には、以下のようなメリットとデメリットがあります。

メリット

  • ID の観点では、生成された thingID があれば Thing 側の初期化が可能であるため、以下の実装が可能です。
    • vendorThingID はモバイルアプリ側で UUID 等によって自動生成することもできます。モバイル環境では Thing に比べて UUID の生成が容易です。モバイルアプリで生成する場合は、工場出荷時、ハードウェアごとに vendorThingID を割り当てておく必要がありません。
    • Thing のハードウェアを交換した場合でも、モバイルアプリから Thing へ thingID を再転送すれば、元の Thing の情報をそのまま引き継げます。
  • アプリ側でまとめて初期化処理を行えるため、Thing 側の実装がシンプルになります。

vendorThingID を UUID によって生成する場合、極めて低確率ですが同一の UUID が生成されるケースが存在しえます。初期登録の時点で同じ vendorThingID の Thing がすでにある場合、既存の Thing を対象とした再リクエストと見なします。通常は、vendorThingID が一致しても、パスワードが不一致となるため、初期登録がエラーとなり、これを契機に UUID の再生成を行うことができます。万一、Thing のパスワードまで一致した場合は、既存のデバイスに紐付いてしまいます。

デメリット

  • モバイルアプリから Thing への通信手段を確保する必要があります。

Thing とモバイルアプリの両方で初期登録を行う方法

この方法では、Thing とモバイルアプリの両方で初期登録を行います。この方法では、Thing とモバイルアプリとの通信を省略できるケースが出てきます。

初期登録は以下の手順で行います。図中の番号が以下の説明文に対応します。Thing とモバイルアプリのどちらから先に初期登録を行っても問題ありません。

モバイルアプリ側

  1. 準備として、モバイルアプリ側で事前に KiiUser を登録し、アクセストークンを取得しておきます。
  2. vendorThingID と thingPassword をモバイルアプリに用意します。thingPassword は Thing の登録時に使用するパスワードで、これによってセキュリティを確保します。Thing の識別子 に記載のとおり、このステップは vendorThingID の提供方式によっては紙媒体を使って省略することができます。Bluetooth 等で転送しても問題ありません。
  3. モバイルアプリから初期登録を実行します。リクエストには、vendorThingID と thingPassword を含むパラメータが必要です。
  4. Thing Interaction Framework 上で初期登録が実行されます。この際、登録処理の一部として、Thing の作成と、KiiUser または KiiGroup との紐付け（オーナー登録）が同時に行われます。Thing がすでに登録されていた場合（2 台目のデバイスに紐付ける場合や、Thing 側の初期登録が先に実行された場合など）、Thing の作成処理等は行われません。
  5. 初期登録リクエストの戻り値として、SDK は thingID と Thing のアクセストークンを取得できます。この方法では戻り値を無視することができます。

実装方法はこちら（Android、iOS、JavaScript、REST API）をご覧ください。

Thing 側

  1. Thing から初期登録を実行します。リクエストには vendorThingID と thingPassword を含むパラメータが必要です。
  2. Thing Interaction Framework 上で初期登録が実行されます。この際、各種登録処理の一部として、Thing の作成と KiiUser との紐付け（オーナー登録）が同時に行われます。モバイルアプリ側の初期登録が先に実行された場合は Thing の登録処理等は行われません。
  3. 初期登録リクエストの戻り値として、SDK は thingID と Thing のアクセストークンを取得できます。SDK 内部では、この値を SDK に保持して初期登録を終わります。

thingPassword や Thing のアクセストークンは機密情報です。これが漏洩すると、そのデバイスは他のユーザーから不正に操作されるリスクが発生します。

実装方法は モバイルアプリから紐付ける場合 をご覧ください。

メリット

  • vendorThingID と thingPassword の共有方法が解決されれば、Thing とモバイルアプリの間での通信処理を作り込む必要はありません。

デメリット

  • Thing 側でも初期登録処理が必要になるため、初期登録が多少煩雑になります。