THINKLET CWS SDK

目次

• 概要
  • 動作要件
  • 利用注意事項
  • ライセンス
  • CWS SDK ドキュメント
  • サンプルコード
• 機能一覧
  • CWS SDK
    • API Document
    • Get Version
    • CWS API Authorization Info
    • Send Message/Send Error Message
    • Reply Command Result
• プロジェクトでの利用方法
  • GitHub Packages経由
  • 更新方法
• Tips
  • AARのバージョンの確認

概要

• THINKLET CWS SDK（以下 CWS SDK）は、CWS APIの機能を使用するためのSDKです。
• CWS API とは、THINKLETに対して遠隔から操作・設定を行うためのAPIです。
• CWS APIの契約を行った上で、THINKLET本体にインストールするアプリケーションでの利用が可能です。

動作要件

• 各機能に対する動作要件は以下です。
  • ファームウェアのバージョンが、下記表の「ファームウェアのバージョン」を満たすこと
  • または、依存アプリである ai.fd.thinklet.app.mdmclient が下記表の「依存アプリの必須VersionName/VersionCode」を満たすこと

機能	CWS APIの契約要否	依存アプリの必須VersionName	依存アプリの必須VersionCode	ファームウェアのバージョン	備考
Get Version	否	-	-	-	-
CWS API Authorization Info	要	0.3.6以上	7以上	3.2.0以上	CWS APIでアクティベート成功後に取得可能
Send Message/Send Error Message	要	0.6.21以上	8以上	7.000.0以上	CWS APIでアクティベート成功後に実行可能
Reply Command Result	要	0.6.21以上	8以上	7.000.0以上	CWS APIでアクティベート成功後に実行可能

• MDMアプリのVersionName/VersionCode は以下でご確認ください。

  $ adb shell dumpsys package ai.fd.thinklet.app.mdmclient | grep version

• ファームウェアのバージョンは以下でご確認ください。

  $ adb shell getprop ro.sys.fd.version

利用注意事項

• 配布するライブラリについては、リバースエンジニアリングを禁止します。
• ライブラリおよびこれを利用するサンプルソースコードは、THINKLET実機でのみ動作します。
• その他の取り扱い情報については、MITライセンス を参照してください。

ライセンス

• SDKとサンプルソースコードはMITライセンスの元で公開します
• ドキュメントはCC BY-SA 4.0の元で公開します

CWS SDK ドキュメント

• dokka を参照ください。

サンプルコード

• sample を参照ください。

機能一覧

CWS SDK

API Document

• API

Get Version

• 動作しているMDM・CWS SDKのバージョン情報を取得します。
• 呼び出し例は以下です。

  val cws = CwsSdk(context = applicationContext)
  Log.d(TAG, "CwsSDK Version: ${cws.getCwsSdkVersion()}")
  Log.d(TAG, "MDM VersionName: ${cws.getMdmVersionName()}")
  Log.d(TAG, "MDM VersionCode: ${cws.getMdmVersionCode()}")

CWS API Authorization Info

• CWS APIの認証情報を取得します。
• 呼び出し例は以下です。

  val completableFuture = cws.getCwsAuthorizationInfo()
  completableFuture.whenComplete { cwsAuthorizationInfo, throwable ->
      Log.d(TAG, "CWS API applicationId: ${cwsAuthorizationInfo?.applicationId}")
      Log.d(TAG, "CWS API clientId: ${cwsAuthorizationInfo?.clientId}")
      Log.d(TAG, "CWS API clientSecret: ${cwsAuthorizationInfo?.clientSecret}")
  }

Send Message/Send Error Message

• 利用者のアプリから、customData に指定した任意の文字列をCWS APIへ送信します。

• このメッセージはCWS API経由で デバイスイベント通知先URL へ トランザクション結果通知(コマンド実行) として 利用者(エンドポイント) へWebhookで送信します。

  • 詳細はCWS APIのAPI仕様 「T-1-7 通知・アクセス設定」 などをご確認ください。

• 本処理の完了は利用者(エンドポイント) への到達を保証するものではありません。最終確認は利用者(エンドポイント) で行ってください。

• 全体のシーケンスは以下です。

  sequenceDiagram
      participant USERAPP as 利用者(アプリ)
      participant CWSAPP as CWS API連携アプリ
      participant CWS as CWS API
      participant USER as 利用者(エンドポイント)
      USERAPP ->> CWSAPP: 利用者のアプリからCWS SDK呼び出し
      CWSAPP ->> CWS: 利用者のアプリから受け取った内容を送信
      Note left of USER: デバイスイベント通知先URL へ トランザクション結果通知(コマンド実行) として送信
      CWS ->> USER: 利用者のアプリから受け取った内容を送信
  

  Loading

• 呼び出し例は以下です。

  // send message
  val sendMessageFuture = cws.sendMessage(customData = "send custom data.")
  sendMessageFuture.whenComplete { _, throwable ->
      var message = "success"
      throwable?.message?.also { throwableMessage ->
          message = throwableMessage
      }
      Log.d(TAG, "sendMessage result message: $message")
  }
  
  // send error message
  val sendErrorMessageFuture = cws.sendErrorMessage(customData = "send custom error data.")
  sendErrorMessageFuture.whenComplete { _, throwable ->
      var message = "success"
      throwable?.message?.also { throwableMessage ->
          message = throwableMessage
      }
      Log.d(TAG, "sendErrorMessage result message: $message")
  }

Reply Command Result

• 「デバイスでコマンドを実行させる」APIの要求に対して、呼び出された利用者のアプリが、その結果をCWS APIへ返却するために使用するインターフェースです。

• 結果返却時に、customData に指定した任意の文字列をCWS APIへ送信します。

• このメッセージはCWS API経由で デバイスイベント通知先URL へ トランザクション結果通知(コマンド実行) としてWebhookで送信します。

  • 詳細はCWS APIのAPI仕様 「T-1-7 通知・アクセス設定」 などをご確認ください。

• 本処理の完了は利用者(エンドポイント) への到達を保証するものではありません。最終確認は利用者(エンドポイント) で行ってください。

• 全体のシーケンスは以下です。

  sequenceDiagram
      participant USERAPP as 利用者(アプリ)
      participant CWSAPP as CWS API連携アプリ
      participant CWS as CWS API
      participant USER as 利用者(エンドポイント)
  
      USER ->> CWS: 「デバイスでコマンドを実行させる」APIを実行
      CWS ->> CWSAPP: 利用者のアプリを呼び出すためのメッセージ送信
      CWSAPP ->> USERAPP: 利用者のアプリを呼び出し（APIでの指定内容）
      USERAPP ->> USERAPP: 任意の処理
      USERAPP ->> CWSAPP: 利用者のアプリからCWS SDK呼び出し
      CWSAPP ->> CWS: 利用者のアプリから受け取った内容を送信
      Note left of USER: デバイスイベント通知先URL へ トランザクション結果通知(コマンド実行) として送信
      CWS ->> USER: 利用者のアプリから受け取った内容を送信
  

  Loading

• 呼び出し例は以下です。

  // intentは、利用者のアプリが呼び出された時に受け取ったintentを指定
  val replyCommandResultFuture = cws.replyCommandResult(
      customData = "send command result.",
      cwsRequestInfo = intent.getCwsRequestInfo(),
      success = true,
  )
  replyCommandResultFuture.whenComplete { _, throwable ->
      var message = "success"
      throwable?.message?.also { throwableMessage ->
          message = throwableMessage
      }
      Log.d(TAG, "replyCommandResult result message: $message")
  }

プロジェクトでの利用方法

GitHub Packages経由

• 詳細な設定は、GitHub 公開されたパッケージの利用 を参照ください。
• また、バージョンの指定や依存ライブラリの追加が必要な場合は、Release に記載しておりますので、適宜ご確認ください。
• 以下に、サンプルを記載します。

  • root build.gradle

    maven {
        name = "GitHubPackages"
        url = uri("https://maven.pkg.github.com/FairyDevicesRD/thinklet.cws.sdk")
        credentials {
            Properties properties = new Properties()
            properties.load(project.rootProject.file('local.properties').newDataInputStream())
            username = properties.getProperty("username") ?: System.getenv("USERNAME")
            password = properties.getProperty("token") ?: System.getenv("TOKEN")
        }
    }
    

  • app/build.gradle

    dependencies {
        implementation 'ai.fd.thinklet:cws-sdk:XXX'
    }
    // XXX にはVersionを指定ください。とにかく最新を使用する場合は、`+` に置き換えてください。
    

更新方法

• implementation で指定するVersionを変更してください。
• その後、プロジェクトをクリーン＆ビルドしてください。

Tips

AARのバージョンの確認

• 各種AARの BuildConfig.LIBRARY_VERSION を参照してください。

val msg = "${ai.fd.thinklet.app.cwssdk.BuildConfig.LIBRARY_PACKAGE_NAME}: ${ai.fd.thinklet.app.cwssdk.BuildConfig.LIBRARY_VERSION}"
Log.v(TAG, msg)