ソフトウェアアップデート手順

THINKLET向けに開発したソフトウェアのアップデート手順について説明します。

ソフトウェアアップデートの概要

CWS APIでは、THINKLET向けに開発したソフトウェアを、同一のアプリケーションに所属するTHINKLETへ、オンラインで配信できます。

ソフトウェアアップデートは、次の流れで実施します。

1. 配信するソフトウェアのパッケージ名・バージョン情報をCWS APIに登録する。
2. バイナリ（apk ファイル）をアップロードするためのURLを発行する。
3. 返却されたアップロードURLを使って、パッケージ名・バージョンに対応するバイナリ（apkファイル）をCWSへアップロードする。
4. パッケージ名・バージョン情報を指定して、ソフトウェアの配信を開始する。
5. 配信中のソフトウェアとバージョンを指定して、THINKLETに対してアップデート（インストール）指示を行う。
6. トランザクション結果通知、またはトランザクション参照APIでアップデート（インストール）結果を確認する。

補足

バイナリ（apk ファイル）をCWSアップロードしただけでは、THINKLETにはインストールされません。 THINKLETへ反映するには、別途アップデート（インストール）を行うためのAPI実行が必要です。

アップデート（インストール）結果は非同期で処理されます。APIレスポンスで返却されるtransactionIdを用いて、配信状況や実行結果を追跡してください。

前提条件

ソフトウェアアップデートを実施するには、次の準備が必要です。

• CWS APIが利用可能な状態である。
• 配信対象のTHINKLETがアプリケーションに所属している。
• 配信するTHINKLET向けのソフトウェアを作成している。

上記に加えて、トランザクション結果通知を受け取るWebhook URLが設定されていると、アップデート状況が詳細に把握できます。

補足

CWS APIの利用準備については、利用開始の手順を参照してください。

トランザクション結果通知や状態遷移の詳細は、トランザクション仕様を参照してください。

THINKLET向けのソフトウェア作成にあたっては、THINKLET開発者ポータルやTHINKLET App SDKを参照してください。

CWS APIで配信するソフトウェアのファイルサイズは、5GB以内としてください。

ソフトウェアの管理

CWS APIに登録したソフトウェアの情報を登録・確認・更新・削除できます。

配信可能なソフトウェアの一覧、パッケージ情報、バージョン情報、バイナリのアップロード状態、配信設定などを確認したり、不要になったソフトウェア、バージョン、バイナリ、配信設定を削除したりできます。

このセクションでは、ソフトウェアのパッケージやバージョンをより細かく管理するためのAPIについて説明します。

補足

単純にソフトウェアを配信するだけであれば、配信手順の一例で説明しているソフトウェアをアップロードするためのURLを作成するAPIを利用できます。このAPIは、パッケージ・バージョンの登録、バイナリのアップロードURL発行、配信の有効化を一度に行います。

一方、このセクションで説明するAPI群を利用すると、これらの手順を個別に実行できます。例えば、先にパッケージとバージョン情報のみを登録しておき、後からバイナリをアップロードする、といった柔軟な運用が可能です。

ソフトウェア情報の登録

CWS APIにソフトウェアのパッケージおよびバージョンを個別に登録できます。

パッケージの登録

CWS APIのソフトウェア（パッケージ）を登録するを実行します。

特記事項

• packageは、CWS API全体で一意である必要があります。
• ai.fdで始まるpackageは使用できません。

実行例

使用シーン例: 新しいソフトウェアcom.example.appをCWS APIに登録する。

curl -X POST 'https://apis.thinklet.fd.ai/v1/applications/{applicationId}/packages' \
  --header 'Authorization: Bearer {access_token}' \
  --header 'Content-Type: application/json' \
  --data '{
    "package": "com.example.app",
    "displayName": "サンプルアプリケーション"
  }'

レスポンス例：

{
  "package": "com.example.app",
  "displayName": "サンプルアプリケーション",
  "registerDate": "2025-11-28T14:15:22.123456",
  "updateDate": "2025-11-28T14:15:22.123456"
}

バージョンの登録

CWS APIの指定したソフトウェア（パッケージ）のバージョンを登録するを実行します。

特記事項

• バージョンは、セマンティック・バージョニングに基づく名称を使用することを推奨します。セマンティック・バージョニングでないバージョンは、APIでバージョン一覧を取得した際に意図しない順序で表示されることがあります。
• 同一のソフトウェアに対して、同じバージョンを重複して登録することはできません。

注意事項

• CWS APIにソフトウェアの情報を登録する際、CWS APIに登録したversionと、登録するソフトウェアのVersionNameは一致させてください。異なる場合、THINKLETへのインストールは実施されますが、アップデート指示時に指定したバージョンとインストール後のバージョンが一致しないため、エラーとして通知されます。

• 既に配信済みのソフトウェアをアップデートする場合、アップデート用のソフトウェアでは、THINKLETにインストール済みのバージョンより大きいVersionCodeを設定する必要があります。VersionCodeが同一かそれより古い場合、THINKLETへのインストールは失敗します。

実行例

使用シーン例: パッケージcom.example.appのバージョン1.0.0をCWS APIに登録する。

curl -X POST 'https://apis.thinklet.fd.ai/v1/applications/{applicationId}/packages/com.example.app/versions' \
  --header 'Authorization: Bearer {access_token}' \
  --header 'Content-Type: application/json' \
  --data '{
    "version": "1.0.0",
    "description": "初期リリース版"
  }'

レスポンス例：

{
  "package": "com.example.app",
  "version": "1.0.0",
  "description": "初期リリース版",
  "registerDate": "2025-11-28T14:15:22.123456",
  "updateDate": "2025-11-28T14:15:22.123456"
}

バイナリのアップロードURLの発行

指定したソフトウェア、バージョンのバイナリをアップロードするためのURLは、ソフトウェアのバイナリをアップロードするためのURLを作成するで発行できます。

特記事項

• このAPIを使用するには、あらかじめパッケージの登録およびバージョンの登録が完了している必要があります。
• マルチパートアップロードには対応していません。
• 発行されたURLへのアップロード方法は、バイナリのアップロードを参照してください。

実行例

使用シーン例: パッケージcom.example.appのバージョン1.0.0のバイナリアップロード用URLを発行する。

curl -X POST 'https://apis.thinklet.fd.ai/v1/applications/{applicationId}/packages/com.example.app/versions/1.0.0/binaries' \
  --header 'Authorization: Bearer {access_token}'

レスポンス例：

{
  "urlList": [
    {
      "uploadUrl": "https://s3.amazonaws.com/...",
      "startTimestamp": 1633014000,
      "endTimestamp": 1633017600,
      "expireIn": 3600
    }
  ]
}

バイナリのアップロード

ソフトウェアのバイナリをアップロードするためのURLを作成するで発行したURLに、THINKLETに配信するソフトウェアをアップロードします。

このURLは、Amazon S3のPresigned URLです。

アップロードを実施する際は、Content-Typeにapplication/vnd.android.package-archiveを指定してください。

アップロード可能なファイルサイズは、5GB以内です。

実行例

アップロードを実施するコマンド例：

curl -X PUT '{CWS APIから取得したアップロードURL}' \
  --header 'Content-Type: application/vnd.android.package-archive' \
  --upload-file '{パッケージファイルのパス}'

ソフトウェア情報の確認

CWS APIに登録したソフトウェアの各種情報を確認できます。

配信可能なソフトウェアの確認

CWS APIの配信可能なソフトウェアとバージョンの一覧を取得するを実行します。

特記事項

一覧のソート順は、ソフトウェアが昇順、バージョンは降順となります。セマンティック・バージョニングで付与されたバージョン以外は、意図しないソート結果となる場合があります。

実行例

使用シーン例1: パッケージcom.example.appの配信可能なバージョン一覧を取得する。

curl -X GET 'https://apis.thinklet.fd.ai/v1/applications/{applicationId}/apps?package=com.example.app' \
  --header 'Authorization: Bearer {access_token}'

使用シーン例2: すべてのパッケージの最新バージョンのみを取得する。

curl -X GET 'https://apis.thinklet.fd.ai/v1/applications/{applicationId}/apps?mode=latest' \
  --header 'Authorization: Bearer {access_token}'

パッケージ情報の確認

登録したすべてのソフトウェアの一覧は、登録したソフトウェア（パッケージ）の一覧を取得するで取得できます。

実行例

使用シーン例: 登録したすべてのパッケージ情報を確認する。

curl -X GET 'https://apis.thinklet.fd.ai/v1/applications/{applicationId}/packages' \
  --header 'Authorization: Bearer {access_token}'

バージョン情報の確認

指定したソフトウェアのバージョン一覧は、指定したソフトウェア（パッケージ）のバージョンの一覧を取得するで取得できます。

実行例

使用シーン例: パッケージcom.example.appのバージョン一覧を取得する。

curl -X GET 'https://apis.thinklet.fd.ai/v1/applications/{applicationId}/packages/com.example.app/versions' \
  --header 'Authorization: Bearer {access_token}'

バイナリのアップロード状態の確認

指定したソフトウェア、バージョンのバイナリの状態（存在有無、ファイルサイズ、アップロード日時）は、ソフトウェアのバイナリアップロード状態を取得するで取得できます。

実行例

使用シーン例: パッケージcom.example.appのバージョン1.0.0のバイナリアップロード状態を確認する。

curl -X GET 'https://apis.thinklet.fd.ai/v1/applications/{applicationId}/packages/com.example.app/versions/1.0.0/binaries' \
  --header 'Authorization: Bearer {access_token}'

配信設定の確認

指定したソフトウェア、バージョンの配信設定の有無は、ソフトウェアの配信設定の状態を取得するで取得できます。

実行例

使用シーン例: パッケージcom.example.appのバージョン1.0.0の配信設定状態を確認する。

curl -X GET 'https://apis.thinklet.fd.ai/v1/applications/{applicationId}/packages/com.example.app/versions/1.0.0/distributions' \
  --header 'Authorization: Bearer {access_token}'

ソフトウェア情報の更新

CWS APIに登録したソフトウェアのパッケージ表示名やバージョンの説明を更新できます。

パッケージ表示名の更新

登録したパッケージの表示名は、ソフトウェア（パッケージ）の表示名を更新するで更新できます。

特記事項

• 本APIは、実行元のアプリケーションだけでなく、同一デベロッパーに属する全アプリケーションのソフトウェアのpackageの表示名を更新します。
• 表示名を削除する場合は、displayNameにnullを指定してください。

実行例

使用シーン例: パッケージcom.example.appの表示名を更新する。

curl -X PATCH 'https://apis.thinklet.fd.ai/v1/applications/{applicationId}/packages/com.example.app' \
  --header 'Authorization: Bearer {access_token}' \
  --header 'Content-Type: application/json' \
  --data '{
    "displayName": "更新されたアプリケーション"
  }'

レスポンス例：

{
  "package": "com.example.app",
  "displayName": "更新されたアプリケーション",
  "registerDate": "2025-11-28T14:15:22.123456",
  "updateDate": "2025-12-01T09:00:00.000000"
}

バージョンの説明の更新

指定したバージョンの説明は、指定したソフトウェア（パッケージ）のバージョンの説明を更新するで更新できます。

特記事項

• 本APIは、実行元のアプリケーションだけでなく、同一デベロッパーに属する全アプリケーションのソフトウェアのバージョンの説明を更新します。
• 説明を削除する場合は、descriptionにnullを指定してください。

実行例

使用シーン例: パッケージcom.example.appのバージョン1.0.0の説明を更新する。

curl -X PATCH 'https://apis.thinklet.fd.ai/v1/applications/{applicationId}/packages/com.example.app/versions/1.0.0' \
  --header 'Authorization: Bearer {access_token}' \
  --header 'Content-Type: application/json' \
  --data '{
    "description": "バグ修正版"
  }'

レスポンス例：

{
  "package": "com.example.app",
  "version": "1.0.0",
  "description": "バグ修正版",
  "registerDate": "2025-11-28T14:15:22.123456",
  "updateDate": "2025-12-01T09:00:00.000000"
}

配信の開始

指定したソフトウェア、バージョンの配信を開始するには、ソフトウェアの配信を開始するを実行します。

配信を開始したバージョンのみ、ソフトウェアをすぐにアップデートさせるでデバイスへのアップデートを実行できます。

特記事項

• バイナリをアップロード後に配信を開始することを推奨します。バイナリが存在しない状態でソフトウェアをすぐにアップデートさせるを実行すると、エラーとなります。
• 配信を停止するには、配信停止を参照してください。

実行例

使用シーン例: パッケージcom.example.appのバージョン1.0.0の配信を開始する。

curl -X POST 'https://apis.thinklet.fd.ai/v1/applications/{applicationId}/packages/com.example.app/versions/1.0.0/distributions' \
  --header 'Authorization: Bearer {access_token}'

レスポンス例：

{
  "package": "com.example.app",
  "version": "1.0.0",
  "distributable": true,
  "distributionDate": "2026-02-12T10:30:45.123456"
}

ソフトウェア情報の削除

CWS APIに登録したソフトウェアの情報を削除できます。

削除する際は、配信停止とバイナリの削除を先に行ってから、バージョン情報、パッケージ情報の順に削除する必要があります。

削除が必要なシーン例

• 配信を停止したい場合: 特定バージョンのソフトウェアに不具合が見つかり、配信を停止したい。
• バイナリを削除したい場合: CWSにアップロードした不要なバイナリファイルを削除したい。
• バージョンを削除したい場合: テスト用にアップロードしたバージョンを削除したい。
• パッケージを削除したい場合: 開発を中止したソフトウェアのパッケージ情報を完全に削除したい。

配信停止

指定したソフトウェア、バージョンの配信を停止するには、ソフトウェアの配信設定を削除するを実行します。

補足

この操作は、すでにTHINKLETにインストールされているソフトウェアには影響しません。

実行例

使用シーン例: パッケージcom.example.appのバージョン1.2.0に不具合が見つかったため、配信を停止する。

curl -X DELETE 'https://apis.thinklet.fd.ai/v1/applications/{applicationId}/packages/com.example.app/versions/1.2.0/distributions' \
  --header 'Authorization: Bearer {access_token}'

配信停止後、修正版1.2.1をアップロードして配信できます。

バイナリの削除

指定したソフトウェア、バージョンのバイナリを削除するには、ソフトウェアのバイナリを削除するを実行します。

特記事項

• 配信設定が行われている状態で、バイナリを削除するとソフトウェアをすぐにアップデートさせるで400エラーとなります。配信を停止後、バイナリを削除することを推奨します。
• バイナリを削除後、THINKLETで該当のソフトウェアのアップデートが行われると、アップデートが失敗します。

実行例

使用シーン例: パッケージcom.example.appのバージョン1.0.0のバイナリを削除する（配信停止済みの前提）。

curl -X DELETE 'https://apis.thinklet.fd.ai/v1/applications/{applicationId}/packages/com.example.app/versions/1.0.0/binaries' \
  --header 'Authorization: Bearer {access_token}'

バージョン情報の削除

指定したソフトウェアから、指定したバージョンを削除するには、指定したソフトウェア（パッケージ）のバージョンを削除するを実行します。

特記事項

バージョンを削除するには、以下を全て削除する必要があります：

• ソフトウェアに登録されているバージョンの配信停止
• ソフトウェアに登録されているバージョンに対応するバイナリ

実行例

使用シーン例: パッケージcom.example.appのバージョン1.0.0を削除する（配信停止とバイナリ削除済みの前提）。

curl -X DELETE 'https://apis.thinklet.fd.ai/v1/applications/{applicationId}/packages/com.example.app/versions/1.0.0' \
  --header 'Authorization: Bearer {access_token}'

パッケージ情報の削除

登録したソフトウェアの情報を削除するには、登録したソフトウェア（パッケージ）の情報を削除するを実行します。

特記事項

ソフトウェアを削除するには、以下を全て削除する必要があります：

• ソフトウェアに登録されているバージョンの配信停止
• ソフトウェアに登録されているバージョンに対応するバイナリ
• ソフトウェアに登録されているバージョン情報

削除手順の例

パッケージcom.example.appを完全に削除する場合：

各バージョンに対して以下の手順を実施します（例：バージョン1.0.0の場合）：

1. 配信を停止する

   curl -X DELETE 'https://apis.thinklet.fd.ai/v1/applications/{applicationId}/packages/com.example.app/versions/1.0.0/distributions' \
     --header 'Authorization: Bearer {access_token}'

2. バイナリを削除する

   curl -X DELETE 'https://apis.thinklet.fd.ai/v1/applications/{applicationId}/packages/com.example.app/versions/1.0.0/binaries' \
     --header 'Authorization: Bearer {access_token}'

3. バージョン情報を削除する

   curl -X DELETE 'https://apis.thinklet.fd.ai/v1/applications/{applicationId}/packages/com.example.app/versions/1.0.0' \
     --header 'Authorization: Bearer {access_token}'

すべてのバージョン（1.0.0、1.2.0、1.2.1など）を削除後、パッケージ情報を削除します：

4. パッケージ情報を削除する

   curl -X DELETE 'https://apis.thinklet.fd.ai/v1/applications/{applicationId}/packages/com.example.app' \
     --header 'Authorization: Bearer {access_token}'

THINKLETへのソフトウェア配信

CWS APIのソフトウェアをすぐにアップデートさせるを実行します。

特記事項

個別のAPIでパッケージやバージョンを登録した場合、配信を実行するには対象ソフトウェアバージョンの配信の開始を完了させておく必要があります。ソフトウェアをアップロードするためのURLを作成する APIを利用した場合は、この手順は不要です。

実行例

使用シーン例: 特定のデバイスに、ソフトウェアcom.example.appのバージョン1.0.0を配信する。

curl -X PUT 'https://apis.thinklet.fd.ai/v1/applications/{applicationId}/devices/{deviceId}/apps' \
  --header 'Authorization: Bearer {access_token}' \
  --header 'Content-Type: application/json' \
  --data '{
    "package": "com.example.app",
    "version": "1.0.0"
  }'

レスポンス例：

{
  "transactionId": 12345
}

レスポンスで返却されるtransactionIdを使用して、デバイスへのインストール状況を追跡できます。

指定したデバイスがオンラインの場合、ソフトウェアが配信されます。

指定したデバイスがオフラインの場合は、デバイスがオンラインになったタイミングで指定したソフトウェアが配信されます。

デバイスへのソフトウェアのインストール状況を確認するには、以下の方法があります：

• Webhook通知で確認: トランザクション結果通知(ソフトウェア/ファームウェアのアップデート)により、インストール完了時に登録したWebhook URLに通知が送信されます。
• APIで確認: トランザクションの情報を取得するを実行し、transactionIdを指定することで、デバイスの受付状態を確認できます。

注意事項

THINKLETにインストールされているソフトウェアと同一か、それより古いVersionCodeを持つソフトウェアを配信した場合、THINKLETへのインストールは失敗します。

配信手順の一例

ここでは、THINKLETにソフトウェアを配信する手順の一例を紹介します。

実際の運用では、使用するAPIや手順の組み合わせは異なる場合があります。

各APIの詳細は前述のセクションを参照してください。

1. THINKLETに配信するソフトウェアを作成する

THINKLET向けのソフトウェアを作成します。

作成にあたっては、次のドキュメント等を参照してください。

• THINKLET開発者ポータル
• THINKLET App SDK

CWS APIで配信するソフトウェアのファイルサイズは、5GB以内としてください。

注意事項

既に配信済みのソフトウェアをアップデートする場合は、次の点に注意してください。

アップデート用のソフトウェアでは、THINKLETにインストール済みのバージョンより大きいVersionCodeを設定する必要があります。VersionCodeが同一かそれより古い場合、THINKLETへのインストールは失敗します。

2. THINKLETに配信するソフトウェアの情報をCWS APIに登録する

CWS APIのソフトウェアをアップロードするためのURLを作成するにて、THINKLETに配信するソフトウェアの情報（package、version、fileSize）をCWS APIに登録します。

レスポンスデータとして、THINKLETに配信するソフトウェアをCWS APIにアップロードするためのURLが返却されます。

ここで返却されたURLは次の手順で使用します。

URLの有効期限は60分です。

CWS APIに登録済みのpackageとversionを指定した場合は、登録済みのソフトウェアを上書きアップロードするためのURLが返却されます。

実行例

使用シーン例: 新しいソフトウェアcom.example.appのバージョン1.0.0をCWS APIに登録し、アップロード用URLを取得する。

curl -X POST 'https://apis.thinklet.fd.ai/v1/applications/{applicationId}/apps' \
  --header 'Authorization: Bearer {access_token}' \
  --header 'Content-Type: application/json' \
  --data '{
    "package": "com.example.app",
    "version": "1.0.0",
    "fileSize": 123456789
  }'

レスポンス例：

{
  "appFileExists": false,
  "chunkPartSize": 123456789,
  "uploadId": null,
  "urlList": [
    {
      "uploadUrl": "https://s3.amazonaws.com/...",
      "startTimestamp": 1633014000,
      "endTimestamp": 1633017600,
      "expireIn": 3600
    }
  ]
}

注意事項

CWS APIにソフトウェアの情報を登録する際は、次の点に注意してください。

CWS APIに登録したversionと、登録するソフトウェアのVersionNameは一致させてください。異なる場合、THINKLETへのインストールは実施されますが、アップデート指示時に指定したバージョンとインストール後のバージョンが一致しないため、エラーとして通知されます。

3. THINKLETに配信するソフトウェアをCWS APIにアップロードする

前の手順で取得した、THINKLETに配信するソフトウェアをCWS APIにアップロードするためのURLに、THINKLETに配信するソフトウェアをアップロードします。

このURLは、Amazon S3のPresigned URLです。

アップロードを実施する際は、Content-Typeにapplication/vnd.android.package-archiveを指定してください。

アップロード可能なファイルサイズは、5GB以内です。

実行例

アップロードを実施するコマンド例：

curl -X PUT '{CWS APIから取得したアップロードURL}' \
  --header 'Content-Type: application/vnd.android.package-archive' \
  --upload-file '{パッケージファイルのパス}'

4. CWS APIよりTHINKLETにソフトウェアを配信する

CWS APIのソフトウェアをすぐにアップデートさせるを実行します。

実行例

使用シーン例: 特定のデバイスに、ソフトウェアcom.example.appのバージョン1.0.0を配信する。

curl -X PUT 'https://apis.thinklet.fd.ai/v1/applications/{applicationId}/devices/{deviceId}/apps' \
  --header 'Authorization: Bearer {access_token}' \
  --header 'Content-Type: application/json' \
  --data '{
    "package": "com.example.app",
    "version": "1.0.0"
  }'

レスポンス例：

{
  "transactionId": 12345
}

詳細はTHINKLETへのソフトウェア配信を参照してください。

注意事項

パッケージ情報、バージョン情報、バイナリ、配信設定の確認・更新・削除を行うAPIの一部は、実行元のアプリケーションだけでなく、同一デベロッパーに属する全アプリケーションを対象に操作を行います。

該当のAPIは以下の通りです。

• 登録したソフトウェア（パッケージ）の一覧を取得する
• ソフトウェア（パッケージ）の表示名を更新する
• 登録したソフトウェア（パッケージ）の情報を削除する
• 指定したソフトウェア（パッケージ）のバージョンの一覧を取得する
• 指定したソフトウェア（パッケージ）のバージョンの説明を更新する
• 指定したソフトウェア（パッケージ）のバージョンを削除する
• ソフトウェアのバイナリアップロード状態を取得する
• ソフトウェアのバイナリを削除する
• ソフトウェアの配信設定を削除する
• ソフトウェアの配信設定の状態を取得する
• ソフトウェアの配信設定を削除する