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无法在亚马逊端解密。
INVALID_LINK_SIGNING_KEY	当linkUserAccount() API请求中提供的LinkSigningKey不是用于签署SSI令牌的有效私钥时返回。

RequestId

RequestId封装SSI API为您的应用发出的每个请求分配的唯一标识符。

字段	类型	必需 （是/否）	描述
id	字符串	是	为此请求分配的唯一ID。

令牌

Token是一种复杂类型，用于表示API请求和响应对象中的关联令牌和SSI令牌。

字段	类型	必需 （是/否）	描述
token	字符串	是	编码的令牌有效负载。
schema	字符串	是	令牌的架构标识符。支持的架构如下。 - 关联令牌： LINK-TOKEN-1.0 - SSI令牌： SSI-TOKEN-1.0

关联

Link表示客户的亚马逊用户身份和他们源自您的用户身份之间的账户关联关系，以及相关的元数据。

字段	类型	必需 （是/否）	描述
linkId	字符串	是	亚马逊分配的唯一ID，表示客户身份之间的账户关联关系。
amazonUserId	字符串	是	属于账户关联关系一部分的亚马逊用户账户的开发者限定范围的标识符。
partnerUserId	字符串	是	在账户关联设置过程中，您为表示用户身份而发放的不透明标识符。
identityProviderName	字符串	是	您用于对系统中的用户进行身份验证的身份提供方的名称。
ssiToken	令牌	是	由亚马逊发放的SSI令牌。
linkedTimestamp	长字符串	是	设置账户关联时的时间戳(epoch)。

LinkUserAccount API

linkUserAccount() API用于启动用户应用账户的账户关联。该解决方案允许在亚马逊和应用账户之间进行N:N映射。可以有多个应用账户与一个亚马逊账户关联，一个应用账户可以同时关联多个亚马逊账户。

在设置账户关联之前，简单登录客户端会显示用户同意屏幕，提示用户予以同意。在获得用户同意后，关联数据和linkToken一起存储在简单登录服务器上。如果用户拒绝同意账户关联，则关联过程将中止，并丢弃从您收到的linkToken。

请求和响应

此API的请求对象使用类型LinkUserAccountRequest，该类型包含以下字段。

字段	类型	必需 （是/否）	描述
partnerUserId	字符串	是	一个不透明的标识符，用于表示您的亚马逊用户身份。如果应用账户已经与其亚马逊账户关联，则此标识符用于消除账户关联请求的重复。
identityProviderName	字符串	是	用于对登录您应用的用户进行身份验证的身份提供方的名称。您可以选择一个有意义的字符串值来表示您的身份提供方。
userLoginName	字符串	是	要在用户同意屏幕上显示的与应用账户关联的登录名。
linkToken	令牌	是	表示账户关联关系的关联令牌。有关类型令牌的定义，请参阅令牌。
linkSigningKey	字符串	是	LinkKeyPair的私钥部分，使用AppStoreKeyPair加密→与应用修订版相对应的PublicKey。

响应对象使用类型LinkUserAccountResponse，该类型包含以下字段。

字段	类型	必需 （是/否）	描述
requestId	RequestId	是	请参阅常见数据类型下的RequestId。
requestStatus	RequestStatus	是	请参阅常见数据类型下的RequestStatus。
successCode	SuccessCode	否	对于成功处理的账户关联请求，SuccessCode枚举表示更细致的状态。 名称： LinkAlreadyExists 描述： 给定的身份对已经存在账户关联关系，并且已对该请求消除重复数据。 名称： LinkEstablished 描述： 已征求并获得用户同意，并成功建立了账户关联关系。 名称： ConsentDenied 描述： 用户已拒绝同意账户关联，请求已中止。
linkId	字符串	否	亚马逊分配的唯一ID，表示客户身份之间的账户关联关系。

GetUserAndLinks API

getUserAndLinks() API用于通过请求应用获取设备上当前有效亚马逊用户的简单登录相关数据。API响应包括以下数据段。

• 有效关联账户的列表，以及每个账户的新SSI令牌。
• 您的亚马逊用户限定范围的身份，应用在令牌生成期间使用该身份将linkToken范围限定为亚马逊用户。

请求和响应

API请求您的（开发者的）身份。

字段	类型	必需 （是/否）	描述
identityProviderName	字符串	是	您身份提供方的名称。您可以为此名称选择一个有意义的字符串值。它必须与账户关联期间提供给linkUserAccount() API的值一致。

响应对象使用类型GetUserAndLinksResponse，该类型包含以下字段。

字段	类型	必需 （是/否）	描述
requestId	RequestId	是	请参阅常见数据类型下的RequestId。
requestStatus	RequestStatus	是	请参阅常见数据类型下的RequestStatus。
amazonUserId	字符串	否	您在设备上有效的亚马逊用户账户限定范围的标识符。
links	List<Link>	否	Link对象的集合，其中每个对象代表一个关联的应用用户账户。如果客户没有任何关联账户，则返回空集合。

ShowLoginSelection API

showLoginSelection() API用于向用户显示登录屏幕。在启动showLoginSelection()之前，对于使用getUserAndLinks()提取的每个关联账户，应用应该从应用服务器检索一个友好的用户可识别的标识符（登录名/电子邮件地址/个人资料名称），并将此数据包含在请求中。此数据显示在屏幕上，用于帮助客户轻松识别关联的应用账户。

请求和响应

API请求每个关联的应用用户账户的登录名映射。

字段	类型	必需 （是/否）	描述
loginNames	Map<String, String>	是	linkId指向用户可识别登录名的映射。当您的应用调用getUserAndLinks()来获取所有关联账户并获取Link对象列表时，它会获取linkId字符串。

响应对象使用类型ShowLoginSelectionResponse，该类型包含以下字段。

字段	类型	必需 （是/否）	描述
requestId	RequestId	是	请参阅常见数据类型下的RequestId。
requestStatus	RequestStatus	是	请参阅常见数据类型下的RequestStatus。
userSelection	UserSelection	否	客户在登录屏幕上所做选择的枚举。可能的值如下： 名称： ManualSignIn 描述： 客户已选择忽略关联账户并手动登录。 名称： LoginSelected 描述： 客户已从提供的一个关联账户中选择要登录的账户。
links	List<Link>	否	Link对象的集合，其中每个对象代表一个关联的应用用户账户。如果客户没有任何关联账户，则返回空集合。

RecordMetricEvent API

recordMetricEvent() API用于触发指标发布需要记录的事件。可以在开发者控制台的“报告”选项卡中下载简单登录业务指标报表。利用这些指标，可以深入了解与SSI集成的业务价值和影响。

请求和响应

此API的请求对象使用类型SSIEventRequest，该类型包含以下字段。

字段	类型	必需 （是/否）	描述
event	SSIEvent	是	对于记录指标事件请求，SSIEvent是一个枚举，它提供了可以发布的可能指标。值包括： 名称： LOGIN_SUCCESS 描述： 这表示使用SSI成功登录。 名称： LOGIN_FAILURE 描述： 这表示使用SSI登录失败。 名称： MANUAL_SIGNIN_SELECTED 描述： 这表示客户在第2次及随后的登录尝试中选择手动登录，忽略之前关联的账户。
epochTimestamp	字符串	是	触发特定事件时的时间戳(epoch)
failureReason	FailureReason	否	FailureReason是一个枚举，表示使用SSI登录失败时可能的失败原因。对于LOGIN_FAILURE事件为必要项。值包括： 名称： UNAUTHORIZED 描述： 用户未获得登录授权。 名称： BAD_REQUEST 描述： 请求已损坏。 名称： NOT_FOUND 描述： 找不到用户正在查找的登录页面。 名称： FORBIDDEN 描述： 无登录机会可用。 名称： INTERNAL_SERVER_ERROR 描述： 登录出现错误。

响应对象使用类型RecordMetricsEventResponse，该类型包含以下字段。

字段	类型	必需 （是/否）	描述
requestId	RequestId	是	请参阅常见数据类型下的RequestId。
requestStatus	RequestStatus	是	请参阅常见数据类型下的RequestStatus。