SSI客户端API
本节介绍亚马逊应用商店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 |
亚马逊无法解密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表示客户的亚马逊用户身份和他们源自您的用户身份之间的账户关联关系，以及相关的元数据。
| 字段 | 类型 | 必需 （是/否） |
描述 |
|---|---|---|---|
linkId |
字符串 | 是 | 亚马逊分配的唯一ID，表示客户身份之间的账户关联关系。 |
amazonUserId |
字符串 | 是 | 属于账户关联关系一部分的亚马逊用户账户的开发者限定范围的标识符。 |
partnerUserId |
字符串 | 是 | 在账户关联设置过程中，您为表示用户身份而发放的不透明标识符。 |
identityProviderName |
字符串 | 是 | 您用于对系统中的用户进行身份验证的身份提供方的名称。 |
ssiToken |
令牌 | 是 | 由亚马逊发放的SSI令牌。 |
linkedTimestamp |
长字符串 | 是 | 设置账户关联时的时间戳(epoch)。 |
linkUserAccount方法
使用linkUserAccount() 方法以初始化用户应用账户的账户关联。该解决方案允许在亚马逊和应用账户之间进行N:N映射。可以有多个应用账户与一个亚马逊账户关联，一个应用账户可以同时关联多个亚马逊账户。
在设置账户关联之前，简单登录客户端会显示用户同意屏幕，提示用户予以同意。在获得用户同意后，SSI将关联数据和linkToken一起存储在简单登录服务器上。如果用户拒绝同意账户关联，则关联过程将结束，SSI会丢弃从您那里收到的linkToken。
linkUserAccount请求和响应
linkUserAccount() 方法的请求对象使用类型LinkUserAccountRequest，该类型包含以下字段。
| 字段 | 类型 | 必需 （是/否） |
描述 |
|---|---|---|---|
partnerUserId |
字符串 | 是 | 一个不透明的标识符，用于表示您的亚马逊用户身份。如果应用账户已经与其亚马逊账户关联，则此标识符用于消除账户关联请求的重复。 |
identityProviderName |
字符串 | 是 | 用于对登录您应用的用户进行身份验证的身份提供方的名称。您可以选择一个有意义的字符串值来表示您的身份提供方。 |
userLoginName |
字符串 | 是 | 要在用户同意屏幕上显示的与应用账户关联的登录名。 |
linkToken |
令牌 | 是 | 表示账户关联关系的关联令牌。有关类型令牌的定义，请参阅令牌。 |
linkSigningKey |
字符串 | 是 | LinkKeyPair的私钥部分，使用AppStoreKeyPair加密→与应用修订版相对应的PublicKey。 |
响应对象使用类型LinkUserAccountResponse，该类型包含以下字段。
| 字段 | 类型 | 必需 （是/否） |
描述 |
|---|---|---|---|
requestId |
RequestId | Y | 请参阅常见数据类型部分中的RequestId。 |
requestStatus |
RequestStatus | Y | 请参阅常见数据类型部分中的RequestStatus。 |
successCode |
SuccessCode | 否 | 对于成功处理的账户关联请求，SuccessCode枚举表示更细致的状态。名称： LinkAlreadyExists描述： 给定的身份对已经存在账户关联关系，并且已对该请求消除重复数据。 名称： LinkEstablished描述： 已征求并获得用户同意，并成功建立了账户关联关系。 名称： ConsentDenied描述： 用户已拒绝同意账户关联，请求已中止。 |
linkId |
字符串 | 否 | 亚马逊分配的唯一ID，表示客户身份之间的账户关联关系。 |
getUserAndLinks方法
使用getUserAndLinks() 方法获取设备上活跃亚马逊用户的简单登录相关数据。响应包括以下数据：
- 有效关联账户的列表，以及每个账户的新SSI令牌。
- 您的亚马逊用户限定范围的身份，用于在令牌生成期间将
linkToken范围限定为亚马逊用户。
getUserAndLinks请求和响应
getUserAndLinks() 方法请求您（开发者）的身份。
| 字段 | 类型 | 必需 （是/否） |
描述 |
|---|---|---|---|
identityProviderName |
字符串 | 是 | 您身份提供方的名称。您可以为此名称选择一个有意义的字符串值。它必须与账户关联期间提供给linkUserAccount() 方法的值一致。 |
响应对象使用类型GetUserAndLinksResponse，该类型包含以下字段。
| 字段 | 类型 | 必需 （是/否） |
描述 |
|---|---|---|---|
requestId |
RequestId | Y | 请参阅常见数据类型部分中的RequestId。 |
requestStatus |
RequestStatus | Y | 请参阅常见数据类型部分中的RequestStatus。 |
amazonUserId |
字符串 | 否 | 您在设备上有效的亚马逊用户账户限定范围的标识符。 |
links |
List<Link> | 否 | Link对象的集合，其中每个对象代表一个关联的应用用户账户。如果客户没有任何关联账户，则返回空集合。 |
showLoginSelection方法
使用showLoginSelection() 方法向应用中的用户显示登录界面。在调用showLoginSelection() 之前，对于getUserAndLinks() 返回的每个关联账户，您的应用应从应用服务器获取一个易于识别、容易记忆的标识符（登录名/电子邮件地址/个人资料名称）。在showLoginSelection() 请求中提供这些数据。相关应用在界面中显示这些数据，帮助客户轻松识别其关联的应用帐户。
showLoginSelection请求和响应
showLoginSelection() 方法为每个关联的应用用户帐户请求一个登录名映射。
| 字段 | 类型 | 必需 （是/否） |
描述 |
|---|---|---|---|
loginNames |
Map<String, String> | 是 | linkId指向用户可识别登录名的映射。当您的应用调用getUserAndLinks()来获取所有关联账户并获取Link对象列表时，它会获取linkId字符串。 |
响应对象使用类型ShowLoginSelectionResponse，该类型包含以下字段。
| 字段 | 类型 | 必需 （是/否） |
描述 |
|---|---|---|---|
requestId |
RequestId | Y | 请参阅常见数据类型部分中的RequestId。 |
requestStatus |
RequestStatus | Y | 请参阅常见数据类型部分中的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 |
字符串 | Y | 触发特定事件时的时间戳 (epoch)。 |
failureReason |
FailureReason | 否 | FailureReason是一个枚举，表示使用SSI登录失败时可能的失败原因。对于LOGIN_FAILURE事件为必要项。值包括：名称： UNAUTHORIZED描述： 用户未获得登录授权。 名称： BAD_REQUEST描述： 请求已损坏。 名称： NOT_FOUND描述： 找不到用户正在查找的登录页面。 名称： FORBIDDEN描述： 无登录机会可用。 名称： INTERNAL_SERVER_ERROR描述： 登录出现错误。 |
响应对象使用类型RecordMetricsEventResponse，该类型包含以下字段。
| 字段 | 类型 | 必需 （是/否） |
描述 |
|---|---|---|---|
requestId |
RequestId | Y | 请参阅常见数据类型部分中的RequestId。 |
requestStatus |
RequestStatus | Y | 请参阅常见数据类型部分中的RequestStatus。 |
Last updated: 2026年2月17日
