SSIクライアントAPI
このセクションでは、Appstore SDKに含まれるシンプルサインインAPIについて説明します。APIリファレンスの全文は、最新のAppstore SDK APIリファレンスで参照できます。
共通データ型
以下は、シンプルサインイン（SSI）APIの操作中に出現する可能性のある一般的なデータ型です。
RequestStatus
RequestStatus列挙型は、アプリがSSIメソッドに対して行うリクエストのステータスを示します。リクエストの成功または失敗を示す列挙値がレスポンスに含まれます。以下の表は、列挙値とその説明を示しています。
| 値 | 説明 |
|---|---|
SUCCESSFUL |
SSIはリクエストを正常に処理しました。 |
FAILURE |
SSIがリクエストを処理する際に、再試行できないエラーが発生しました。 |
RETRYABLE_FAILURE |
SSIがリクエストを処理する際に、再試行可能な一時的なエラーが発生しました。たとえば、タイムアウトやサービスを利用できないエラーなどです。 |
NOT_SUPPORTED |
SSIは指定されたデバイスでリクエストを処理できません。たとえば、デバイスがSSI機能を含む最新のソフトウェアにアップグレードされていない場合などです。 |
NOT_AVAILABLE |
SSI機能はサポートされているものの、特定の公開停止ルールが原因で現在利用できません。理由は以下のとおりです。 - 機能がユーザーのマーケットプレイスで無効になっている。 - 機能が特定のアプリでブロックされている。 - 機能がサポートされていないモードでデバイスが動作している。モードの例：Fireタブレットの子ども用プロフィールモード、Fire TVのゲストユーザーモード。 |
DUPLICATE_REQUEST |
アプリが重複したリクエストを送信しました。 |
FEATURE_TURNED_OFF |
ユーザーが機能をオフにしています。 |
INVALID_LINK_SIGNING_KEY_ENCRYPTION |
Amazonは、linkUserAccount()メソッドのリクエストで指定されたLinkSigningKeyを復号化することはできません。 |
INVALID_LINK_SIGNING_KEY |
linkUserAccount()メソッドのリクエストで指定されたLinkSigningKeyは、SSIトークンに署名するための有効なプライベートキーではありません。 |
RequestId
SSIは、アプリがSSIに対して行う各リクエストに一意の識別子を割り当てます。RequestIdオブジェクトはこのIDのラッパーです。
| フィールド | タイプ | 必須 （○/×） |
説明 |
|---|---|---|---|
id |
文字列 | ○ | このリクエストに割り当てられた一意のID。 |
Token
Tokenは、リクエストオブジェクトとレスポンスオブジェクトでリンクトークンとSSIトークンの両方を表す複合型です。
| フィールド | タイプ | 必須 （○/×） |
説明 |
|---|---|---|---|
token |
文字列 | ○ | エンコードされたトークンペイロード。 |
schema |
文字列 | ○ | トークンのスキーマ識別子。サポートされているスキーマは以下のとおりです。 - リンクトークン： LINK-TOKEN-1.0- SSIトークン： SSI-TOKEN-1.0 |
Link
Linkは、ユーザーのAmazonユーザーIDとアプリのユーザーIDのアカウントリンク関係、および関連するメタデータを表します。
| フィールド | タイプ | 必須 （○/×） |
説明 |
|---|---|---|---|
linkId |
文字列 | ○ | Amazonによって割り当てられる一意のID。ユーザーID間のアカウントリンク関係を表します。 |
amazonUserId |
文字列 | ○ | アカウントリンク関係の一部であるAmazonユーザーアカウントのスコープ識別子。 |
partnerUserId |
文字列 | ○ | アカウントリンク設定中にユーザーIDを表すために発行する不透明な識別子。 |
identityProviderName |
文字列 | ○ | システムでユーザーを認証するために使用するIDプロバイダーの名前。 |
ssiToken |
Token | ○ | Amazonが発行するSSIトークン。 |
linkedTimestamp |
long | ○ | アカウントリンクが設定されたときのタイムスタンプ（エポック）。 |
linkUserAccountメソッド
linkUserAccount()メソッドは、ユーザーのアプリアカウントのアカウントリンクを開始するために使用されます。このソリューションでは、Amazonとアプリアカウントの間の多対多マッピングが可能になります。1つのAmazonアカウントに複数のアプリアカウントをリンクさせることができ、また、1つのアプリアカウントに複数のAmazonアカウントを同時にリンクさせることもできます。
アカウントリンクを設定する前に、シンプルサインインクライアントがユーザー同意画面を表示してユーザーに同意を促します。ユーザーの同意を得る際、SSIは、リンクデータとlinkTokenをシンプルサインインサーバーに保存します。ユーザーがアカウントリンクへの同意を拒否した場合、リンクプロセスは終了し、SSIはユーザーから受け取ったlinkTokenを破棄します。
linkUserAccountのリクエストとレスポンス
linkUserAccount()メソッドのリクエストオブジェクトは、LinkUserAccountRequest型を使用します。これには以下のフィールドが含まれます。
| フィールド | タイプ | 必須 （○/×） |
説明 |
|---|---|---|---|
partnerUserId |
文字列 | ○ | Amazonに対してユーザーのIDを表すために使用される不透明な識別子。この識別子は、アプリアカウントが既にAmazonアカウントにリンクされている場合に、アカウントリンクリクエストの重複を排除するために使用されます。 |
identityProviderName |
文字列 | ○ | アプリにサインインしているユーザーを認証するために使用するIDプロバイダーの名前。IDプロバイダーを表す意味のある文字列値を選択できます。 |
userLoginName |
文字列 | ○ | ユーザー同意画面に表示される、アプリアカウントに関連付けられたログイン名。 |
linkToken |
Token | ○ | アカウントのリンク関係を表すリンクトークン。Token型の定義については、Tokenを参照してください。 |
linkSigningKey |
文字列 | ○ | LinkKeyPairのプライベートキー部分。アプリのリビジョンに対応するAppStoreKeyPairからPublicKeyを使用して暗号化されます。 |
レスポンスオブジェクトでは、LinkUserAccountResponse型を使用します。これには以下のフィールドが含まれます。
| フィールド | タイプ | 必須 （○/×） |
説明 |
|---|---|---|---|
requestId |
RequestId | ○ | 一般的なデータ型セクションの RequestIdを参照してください。 |
requestStatus |
RequestStatus | ○ | 一般的なデータ型セクションのRequestStatusを参照してください。 |
successCode |
SuccessCode | × | アカウントリンクリクエストが正常に処理されると、SuccessCode列挙型がより詳細なステータスを示します。名前： LinkAlreadyExists説明： 指定されたIDペアにアカウントリンク関係が既に存在するため、リクエストが重複排除されました。 名前： LinkEstablished説明： ユーザーの同意が得られ、アカウントリンク関係が正常に設定されました。 名前： ConsentDenied説明： ユーザーがアカウントリンクへの同意を拒否し、リクエストが中止されました。 |
linkId |
文字列 | × | Amazonによって割り当てられる一意のID。ユーザーID間のアカウントリンク関係を表します。 |
getUserAndLinksメソッド
getUserAndLinks()メソッドを使用して、デバイス上のアクティブなAmazonユーザーのシンプルサインイン関連のデータを取得します。レスポンスには以下のデータが含まれます。
- アクティブなリンク済みアカウントのリスト、および各アカウントの新しいSSIトークン。
- AmazonユーザーのスコープID。トークン生成時に
linkTokenの範囲をAmazonユーザーに限定するために使用されます。
getUserAndLinksのリクエストとレスポンス
getUserAndLinks()メソッドは、ユーザー（開発者）のIDをリクエストします。
| フィールド | タイプ | 必須 （○/×） |
説明 |
|---|---|---|---|
identityProviderName |
文字列 | ○ | IDプロバイダーの名前。この名前には、意味のある文字列値を選択できます。アカウントリンク時にlinkUserAccount()メソッドに提供されたものと一致している必要があります。 |
レスポンスオブジェクトでは、GetUserAndLinksResponse型を使用します。これには以下のフィールドが含まれます。
| フィールド | タイプ | 必須 （○/×） |
説明 |
|---|---|---|---|
requestId |
RequestId | ○ | 一般的なデータ型セクションの RequestIdを参照してください。 |
requestStatus |
RequestStatus | ○ | 一般的なデータ型セクションのRequestStatusを参照してください。 |
amazonUserId |
文字列 | × | デバイスでアクティブなAmazonユーザーアカウントのスコープ識別子。 |
links |
List<Link> | × | リンクされたアプリのユーザーアカウントを表すLinkオブジェクトから成るコレクション。ユーザーがリンク済みアカウントを持っていない場合は、空のコレクションが返されます。 |
showLoginSelectionメソッド
showLoginSelection()メソッドを使用して、アプリでユーザーにログイン画面を表示します。showLoginSelection()を開始する前に、アプリはgetUserAndLinks()によって返される各リンク済みアカウントについて、ユーザーが認識しやすい識別子（ログイン名／メールアドレス／プロファイル名）をアプリサーバーから取得する必要があります。このデータをshowLoginSelection()リクエストに含めてください。アプリはこのデータを画面に表示し、ユーザーがリンクされたアプリアカウントを簡単に認識できるようにします。
showLoginSelectionのリクエストとレスポンス
showLoginSelection()メソッドは、リンクされたアプリユーザーアカウントのログイン名のマップをリクエストします。
| フィールド | タイプ | 必須 （○/×） |
説明 |
|---|---|---|---|
loginNames |
Map<String, String> | ○ | ユーザーが認識できるログイン名へのlinkIdのマップ。アプリがすべてのリンク済みアカウントを取得するためにgetUserAndLinks()を呼び出し、Linkオブジェクトのリストを取得すると、linkId文字列が返されます。 |
レスポンスオブジェクトでは、ShowLoginSelectionResponse型を使用します。これには以下のフィールドが含まれます。
| フィールド | タイプ | 必須 （○/×） |
説明 |
|---|---|---|---|
requestId |
RequestId | ○ | 一般的なデータ型セクションの RequestIdを参照してください。 |
requestStatus |
RequestStatus | ○ | 一般的なデータ型セクションのRequestStatusを参照してください。 |
userSelection |
UserSelection | × | ログイン画面でユーザーが行った選択の列挙型。使用可能な値は次のとおりです。 名前： ManualSignIn説明： リンク済みアカウントを無視して手動でログインすることをユーザーが選択しました。 名前： LoginSelected説明： 提供されているリンク済みアカウントのいずれかからサインインするアカウントをユーザーが選択しました。 |
links |
List<Link> | × | リンクされたアプリのユーザーアカウントを表すLinkオブジェクトから成るコレクション。ユーザーがリンク済みアカウントを持っていない場合は、空のコレクションが返されます。 |
recordMetricEventメソッド
アプリでは、recordMetricEvent()メソッドを使用して、指標を公開するイベントを記録できます。シンプルサインインのビジネス指標レポートは、開発者コンソールの [レポート] タブでダウンロードできます。これらの指標は、SSIの統合によるビジネス価値や影響を把握するためのものです。
recordMetricEventのリクエストとレスポンス
recordMetricEvent()のリクエストオブジェクトは、SSIEventRequest型を使用します。これには以下のフィールドが含まれます。
| フィールド | タイプ | 必須 （○/×） |
説明 |
|---|---|---|---|
event |
SSIEvent | ○ | 指標イベントの記録リクエストの場合、SSIEventは公開可能な指標を示す列挙型です。値は以下のとおりです。 名前： LOGIN_SUCCESS説明： これは、SSIを使用したログインに成功したことを表します。 名前： LOGIN_FAILURE説明： これは、SSIを使用したログインに失敗したことを表します。 名前： MANUAL_SIGNIN_SELECTED説明： ユーザーが（2回目以降のサインイン試行時に）以前にリンクされたアカウントを無視して手動でのサインインを選択する場合を表します。 |
epochTimestamp |
文字列 | ○ | 特定のイベントがトリガーされたときのタイムスタンプ（エポック）。 |
failureReason |
FailureReason | × | FailureReasonは、SSIを使用したログインが失敗した場合に、考えられる失敗の理由を表す列挙型です。LOGIN_FAILUREイベントの場合は必須です。値は以下のとおりです。名前： UNAUTHORIZED説明： ユーザーにログインする権限がありません。 名前： BAD_REQUEST説明： リクエストが破損しています。 名前： NOT_FOUND説明： ユーザーが探しているログインページが見つかりません。 名前： FORBIDDEN説明： ログイン機会がありません。 名前： INTERNAL_SERVER_ERROR説明： ログインに何らかの問題があります。 |
レスポンスオブジェクトでは、RecordMetricsEventResponse型を使用します。これには以下のフィールドが含まれます。
| フィールド | タイプ | 必須 （○/×） |
説明 |
|---|---|---|---|
requestId |
RequestId | ○ | 一般的なデータ型セクションの RequestIdを参照してください。 |
requestStatus |
RequestStatus | ○ | 一般的なデータ型セクションのRequestStatusを参照してください。 |
Last updated: 2026年2月17日
