SSIクライアントAPI

このセクションでは、Appstore SDKに含まれるシンプルサインインAPIについて説明します。APIリファレンスの全文は、最新のAppstore SDK APIリファレンスで参照できます。

• 一般的なデータ型
  • RequestStatus
  • RequestId
  • トークン
  • リンク
• LinkUserAccount API
  • リクエストとレスポンス
• GetUserAndLinks API
  • リクエストとレスポンス
• ShowLoginSelection API
  • リクエストとレスポンス
• RecordMetricEvent API
  • リクエストとレスポンス

一般的なデータ型

以下は、シンプルサインイン（SSI）APIの操作中に出現する可能性のある一般的なデータ型です。

RequestStatus

RequestStatusは、SSI APIへのリクエストのステータスを示す列挙型です。リクエストの成功または失敗を示す列挙値がレスポンスに含まれます。返される可能性のあるさまざまな値とその意味は、次の表のとおりです。

名前	説明
SUCCESSFUL	リクエストが正常に処理されたことを示します。
FAILURE	リクエストの処理中に再試行できないエラーが発生したことを示します。
RETRYABLE_FAILURE	リクエストの処理中に再試行できる一時的なエラー（タイムアウトやサービスを利用できないエラーなど）が発生したことを示します。
NOT_SUPPORTED	特定のデバイスでリクエストを処理できない場合（SSI機能を含む最新のソフトウェアにデバイスがアップグレードされていない場合など）に返されます。
NOT_AVAILABLE	機能はサポートされているものの、特定の公開停止ルールが原因で現在利用できない場合に返されます。理由は以下のとおりです。 - 機能がユーザーのマーケットプレイスで無効になっている。 - 機能が特定のアプリでブロックされている。 - 機能がサポートされていないモードでデバイスが動作している。モードの例：Fireタブレットの子ども用プロフィールモード、Fire TVのゲストユーザーモード。
DUPLICATE_REQUEST	別のリクエストが行われたときに、リクエストが重複していることを示します。
FEATURE_TURNED_OFF	ユーザーが機能をオフにしました。
INVALID_LINK_SIGNING_KEY_ENCRYPTION	linkUserAccount() APIリクエストで指定されたLinkSigningKeyを、Amazon側で復号化できません。
INVALID_LINK_SIGNING_KEY	linkUserAccount() APIリクエストで指定されたLinkSigningKeyが、SSIトークンに署名するための有効なプライベートキーではない場合に返されます。

RequestId

RequestIdは、アプリからのリクエストごとに、SSI APIによって割り当てられた一意の識別子をラップします。

フィールド	型	必須 （Y/N）	説明
id	文字列	Y	このリクエストに割り当てられた一意のID。

トークン

トークンは、APIリクエストオブジェクトとレスポンスオブジェクトでリンクトークンとSSIトークンの両方を表す複合型です。

フィールド	型	必須 （Y/N）	説明
token	文字列	Y	エンコードされたトークンペイロード。
schema	文字列	Y	トークンのスキーマ識別子。サポートされているスキーマは以下のとおりです。 - リンクトークン： LINK-TOKEN-1.0 - SSIトークン： SSI-TOKEN-1.0

リンク

リンクは、ユーザーのAmazonユーザーIDとアプリのユーザーIDのアカウントリンク関係、および関連するメタデータを表します。

フィールド	型	必須 （Y/N）	説明
linkId	文字列	Y	Amazonによって割り当てられる一意のID。ユーザーID間のアカウントリンク関係を表します。
amazonUserId	文字列	Y	アカウントリンク関係の一部であるAmazonユーザーアカウントのスコープ識別子。
partnerUserId	文字列	Y	アカウントリンク設定中にユーザーIDを表すために発行する不透明な識別子。
identityProviderName	文字列	Y	システムでユーザーを認証するために使用するIDプロバイダーの名前。
ssiToken	トークン	Y	Amazonが発行するSSIトークン。
linkedTimestamp	long	Y	アカウントリンクが設定されたときのタイムスタンプ（エポック）。

LinkUserAccount API

linkUserAccount() APIは、ユーザーのアプリアカウントのアカウントリンクを開始するために使用されます。このソリューションでは、Amazonとアプリアカウントの間の多対多マッピングが可能になります。1つのAmazonアカウントに複数のアプリアカウントをリンクさせることができ、また、1つのアプリアカウントに複数のAmazonアカウントを同時にリンクさせることもできます。

アカウントリンクを設定する前に、シンプルサインインクライアントがユーザー同意画面を表示してユーザーに同意を促します。ユーザーの同意を得る際、リンクデータとlinkTokenはシンプルサインインサーバーに保存されます。ユーザーがアカウントリンクへの同意を拒否した場合、リンクプロセスは中止され、ユーザーから受け取ったlinkTokenは破棄されます。

リクエストとレスポンス

このAPIのリクエストオブジェクトは、LinkUserAccountRequest型を使用します。これには以下のフィールドが含まれます。

フィールド	型	必須 （Y/N）	説明
partnerUserId	文字列	Y	Amazonに対してユーザーのIDを表す不透明な識別子。この識別子は、アプリアカウントが既にAmazonアカウントにリンクされている場合に、アカウントリンクリクエストの重複排除に使用されます。
identityProviderName	文字列	Y	アプリにサインインしているユーザーを認証するために使用するIDプロバイダーの名前。IDプロバイダーを表す意味のある文字列値を選択できます。
userLoginName	文字列	Y	ユーザー同意画面に表示される、アプリアカウントに関連付けられたログイン名。
linkToken	トークン	Y	アカウントのリンク関係を表すリンクトークン。トークン型の定義については、トークンを参照してください。
linkSigningKey	文字列	Y	LinkKeyPairのプライベートキー部分。アプリのリビジョンに対応するAppStoreKeyPairからPublicKeyを使用して暗号化されます。

レスポンスオブジェクトでは、LinkUserAccountResponse型を使用します。これには以下のフィールドが含まれます。

フィールド	型	必須 （Y/N）	説明
requestId	RequestId	Y	一般的なデータ型のRequestIdを参照してください。
requestStatus	RequestStatus	Y	一般的なデータ型のRequestStatusを参照してください。
successCode	SuccessCode	N	アカウントリンクリクエストが正常に処理されると、SuccessCode列挙型がより詳細なステータスを示します。 名前： LinkAlreadyExists 説明： 指定されたIDペアにアカウントリンク関係が既に存在するため、リクエストが重複排除されました。 名前： LinkEstablished 説明： ユーザーの同意が得られ、アカウントリンク関係が正常に設定されました。 名前： ConsentDenied 説明： ユーザーがアカウントリンクへの同意を拒否し、リクエストが中止されました。
linkId	文字列	N	Amazonによって割り当てられる一意のID。ユーザーID間のアカウントリンク関係を表します。

GetUserAndLinks API

getUserAndLinks() APIは、リクエスト元のアプリを介して、デバイスで現在アクティブなAmazonユーザーのシンプルサインイン関連データを取得するために使用されます。APIレスポンスには、以下のデータが含まれます。

• アクティブなリンク済みアカウントのリスト、および各アカウントの新しいSSIトークン。
• AmazonユーザーのスコープID。トークン生成時にlinkTokenの範囲をAmazonユーザーに限定するためにアプリで使用されます。

リクエストとレスポンス

APIは、開発者のIDをリクエストします。

フィールド	型	必須 （Y/N）	説明
identityProviderName	文字列	Y	IDプロバイダーの名前。この名前には、意味のある文字列値を選択できます。アカウントリンク時にlinkUserAccount() APIに提供されたものと一致している必要があります。

レスポンスオブジェクトでは、GetUserAndLinksResponse型を使用します。これには以下のフィールドが含まれます。

フィールド	型	必須 （Y/N）	説明
requestId	RequestId	Y	一般的なデータ型のRequestIdを参照してください。
requestStatus	RequestStatus	Y	一般的なデータ型のRequestStatusを参照してください。
amazonUserId	文字列	N	デバイスでアクティブなAmazonユーザーアカウントのスコープ識別子。
links	List<Link>	N	リンクされたアプリのユーザーアカウントを表すLinkオブジェクトから成るコレクション。ユーザーがリンク済みアカウントを持っていない場合は、空のコレクションが返されます。

ShowLoginSelection API

showLoginSelection() APIは、ユーザーにログイン画面を表示するために使用されます。showLoginSelection()を開始する前に、getUserAndLinks()を使用して取得されるリンク済みアカウントごとに、アプリはユーザーが認識しやすい識別子（ログイン名／Eメールアドレス／プロファイル名）をアプリサーバーから取得し、このデータをリクエストに含めます。このデータは画面に表示され、リンクされたアプリアカウントをユーザーが認識しやすくするために使用されます。

リクエストとレスポンス

このAPIは、リンクされたアプリユーザーアカウントのログイン名のマップをリクエストします。

フィールド	型	必須 （Y/N）	説明
loginNames	Map<String, String>	Y	ユーザーが認識できるログイン名へのlinkIdのマップ。アプリがすべてのリンク済みアカウントを取得するためにgetUserAndLinks()を呼び出し、Linkオブジェクトのリストを取得すると、linkId文字列が返されます。

レスポンスオブジェクトでは、ShowLoginSelectionResponse型を使用します。これには以下のフィールドが含まれます。

フィールド	型	必須 （Y/N）	説明
requestId	RequestId	Y	一般的なデータ型のRequestIdを参照してください。
requestStatus	RequestStatus	Y	一般的なデータ型のRequestStatusを参照してください。
userSelection	UserSelection	N	ログイン画面でユーザーが行った選択の列挙型。使用可能な値は次のとおりです。 名前： ManualSignIn 説明： リンク済みアカウントを無視して手動でログインすることをユーザーが選択しました。 名前： LoginSelected 説明： 提供されているリンク済みアカウントのいずれかからサインインするアカウントをユーザーが選択しました。
links	List<Link>	N	リンクされたアプリのユーザーアカウントを表すLinkオブジェクトから成るコレクション。ユーザーがリンク済みアカウントを持っていない場合は、空のコレクションが返されます。

RecordMetricEvent API

recordMetricEvent() APIは、指標公開用に記録する必要があるイベントをトリガーするために使用されます。シンプルサインインのビジネス指標レポートは、開発者コンソールの [レポート] タブでダウンロードできます。これらの指標は、SSIの統合によるビジネス価値や影響を把握するためのものです。

リクエストとレスポンス

このAPIのリクエストオブジェクトは、SSIEventRequest型を使用します。これには以下のフィールドが含まれます。

フィールド	型	必須 （Y/N）	説明
event	SSIEvent	Y	指標イベントの記録リクエストの場合、SSIEventは公開可能な指標を示す列挙型です。値は以下のとおりです。 名前： LOGIN_SUCCESS 説明： SSIを使用したログインに成功したことを表します。 名前： LOGIN_FAILURE 説明： SSIを使用したログインに失敗したことを表します。 名前： MANUAL_SIGNIN_SELECTED 説明： ユーザーが（2回目以降のサインイン試行時に）以前にリンクされたアカウントを無視して手動でのサインインを選択する場合を表します。
epochTimestamp	文字列	Y	特定のイベントがトリガーされたときのタイムスタンプ（エポック）
failureReason	FailureReason	N	SSIを使用したログインが失敗した場合に、考えられる失敗の理由を表す列挙型。LOGIN_FAILUREイベントの場合は必須です。値は以下のとおりです。 名前： UNAUTHORIZED 説明： ユーザーにログインする権限がありません。 名前： BAD_REQUEST 説明： リクエストが破損しています。 名前： NOT_FOUND 説明： ユーザーが探しているログインページが見つかりません。 名前： FORBIDDEN 説明： ログイン機会がありません。 名前： INTERNAL_SERVER_ERROR 説明： ログインに何らかの問題があります。

レスポンスオブジェクトでは、RecordMetricsEventResponse型を使用します。これには以下のフィールドが含まれます。

フィールド	型	必須 （Y/N）	説明
requestId	RequestId	Y	一般的なデータ型のRequestIdを参照してください。
requestStatus	RequestStatus	Y	一般的なデータ型のRequestStatusを参照してください。