IDの取得手順とAPIの叩き方

IDの取得手順と、APIのたたき方について記載します。

IDの取得手順

各IDの基本的な取得手順は下記になります。

  1. BOTへのClient Secretの割当
  2. Client SecretからDevice(アプリ)ごとにDevice IDを発行の割当
  3. Device IDをユーザアカウントへのヒモ付
  4. Device Tokenの発行と保持
  5. Device Tokenを利用したドコモAIエージェントAPIの利用

ID取得の詳細なシーケンス

IDの取得に関して下記の通りの実装上の注意点を考慮してください。

  • デバイスの状態について
  • Device Tokenの取得について
  • モバイルデバイスにおけるDevice Token取得の例
  • Device Tokenの削除
  • Device Tokenを用いた対話利用シーケンス
  • Device Tokenの再取得

デバイスの状態について

デバイス側は2つのモードを持ちます。Device TokenがないNo RegistrationとDevice TokenがあるActiveです。

No Registrationモード時にはRequest Device Token(シーケンスの#1)を定期的にたたいてください。ユーザ起因でたたいても構いません。返り値はデバイスが登録されていればDevice Tokenが返ります。

Device Tokenが返ってきたら、それを保存してActiveになり、Request Device Token(シーケンスの#1)を定期的にたたくのをやめてください。(2回目以降たたいても結果はInvalidになります)

次はDevice Tokenを使ってValidate Device Token(#2)をたたきます。ValidであればShadow IDが返ります。(これはどのタイミングでもOKです)

Validate Device Token(#2)がInvalidで返ったとき、もしくはSDKからSPFにアクセスしてDevice TokenがInvalidであることがわかったら保存しているDevice Tokenを削除し、Device IDを使ってRequest Device Token(#1)をたたき始めてください(No Registration』に移行)。

モバイルアプリからのシーケンスは3-1bを参照して下さい。Webviewからのデバイス登録とDevice Token取得が連動できます。

Device Tokenの取得について

Device Tokenは取得するためにはユーザがDevice IDを自分のアカウントに紐付ける必要があります。

その間、デバイスはDevice Tokenを定期的(10秒間隔以上を推奨)、もしくはユーザから明示的に取得を要求する必要があります。紐付けられていない場合はRequest Device Tokenの応答値はエラーになります。

モバイルデバイスにおけるDevice Token取得の例

デバイスがモバイルアプリの場合は予めDevice IDを割り振ることができませんので、Device IDを割り振る仕組みを別途実装するか、始めにMDSにClient Secretを用いてDevice IDを取得する部分を実装してください(シーケンス図の#0)。

この場合のDevice IDはユーザにインストールされたアプリ個体を識別する識別子になります。

実際のアプリを実装する際には、下記のよう利用します。

Device Tokenの削除

Device Tokenを用いた対話利用シーケンス

Device Tokenの再取得

Device Tokenの有効期限について

Device Tokenには有効期限があります。
Device Tokenは有効期限が切れると、音声制御ライブラリでは下記のエラーが表示されます。

エラータイプ エラーコード エラー詳細
COMMUNICATION_AUTHORIZE 40101 client.hpp:943: close code: 40101 (Unknown), close reason: UDS:DeviceToken Invalid

各トークンの有効期限は下記です。

Device Token Refresh Token
30日間 90日間

Device Tokenの有効期限切れの対処法については、こちらのドキュメントをご参照ください。