Amazon Developer

Console

as

Settings
Sign out
Notifications
Alexa
亚马逊应用商店
AWS
文档
Support
Contact Us
My Cases

Console

as

新手入门
设计和开发
应用发布
参考
支持

@amazon-devices/simplesignin

@amazon-devices/simplesignin

简单登录服务API提供的功能允许第三方应用开发者将其用户账户的应用账户与客户注册设备时使用的亚马逊账户关联起来。然后，开发者可以针对后续登录尝试，使用链接无缝地让用户登录。

该API支持以下功能：

  • 将第三方应用用户的账户与亚马逊账户关联。
  • 为第三方应用的用户获取现有链接。
  • 对第三方应用用户显示带有选项的选择界面以进行登录。
  • 记录业务指标。

开始使用

设置

  1. 将以下库依赖项添加到package.json文件的dependencies部分。

    已复制到剪贴板。

     "@amazon-devices/simplesignin": "~1.1",

  2. 在您的manifest.toml中，添加以下权限。

    已复制到剪贴板。

    [[wants.module]]
id = "/com.amazon.dms.ssi@ISimpleSignIn"

[[wants.service]]
id = "com.amazon.dms.ssi.service"

[[wants.interactive]]
id = "com.amazon.dms.ssi.loginselection"

[[wants.interactive]]
id = "com.amazon.dms.ssi.consent"

    这些权限提供对以下事项的访问权限：

    • 简单登录系统服务的访问权限。
    • 允许显示征求用户同意的屏幕。
    • 允许向用户显示登录选项的屏幕。

用法

以下部分介绍如何使用简单登录执行账户关联以及让用户登录。

以下示例发起请求，要求在您的应用所在的设备上，为当前活跃的亚马逊用户提取与简单登录相关的数据。

已复制到剪贴板。

let promise = SimpleSignInService.getUserAndLinks(IDP_NAME);
promise.then(
    (response) => {
        // 处理响应
    }
);

LinkUserAccount

以下示例中，为用户的应用账户启动了账户关联。该示例允许在亚马逊和应用账户之间进行N:N映射。可以有多个应用账户同时与一个亚马逊账户关联，一个应用账户可以关联多个亚马逊账户。

已复制到剪贴板。

let promise = SimpleSignInService.linkUserAccount(request);
promise.then(
    (response) => {
        // 处理响应
    }
);

ShowLoginSelection

以下示例中，打开了一个对话框，向用户显示登录选项。在调用此方法之前，获得每个关联账户的易于用户识别的标识符，并将该标识符添加到请求中。要检索标识符，请调用getUserAndLinks() 方法。用户可识别的标识符包括登录名、电子邮件地址或个人资料名称。该代码在屏幕上显示这些标识符，以帮助客户轻松识别关联的应用账户。

已复制到剪贴板。

let promise = SimpleSignInService.showLoginSelection(request);
promise.then(
    (response) => {
        // 处理响应
    }
);

RecordMetricEvent

以下示例触发一个为发布指标而记录的事件。可以在开发者控制台的报告选项卡中下载简单登录业务指标报表。利用这些指标，可以深入了解与简单登录集成的业务价值和影响。

已复制到剪贴板。

let request = {
    ssiEvent: SSIEvent.***,
    timestamp : <以毫秒为单位的纪元时间戳>,
    failureReason = <FailureReason.***>    // 如果SSIEvent是Failure，则此字段为必填。
};

let promise = SimpleSignInService.recordMetricEvent(request);
promise.then((response) => {
    // 此API中通常没有进行什么处理。
});

实现登录流程

在实现登录流程之前，您需要身份提供者名称 (IDP_NAME)，该名称是在应用的引入过程中在开发者控制台中提供的。这个唯一标识符将您的应用连接到简单登录服务。

开始使用登录

登录过程通常在以下情况下开始：

  • 应用启动时
  • 用户单击登录按钮
  • 会话需要身份验证

以下示例显示如何使用GetUserAndLinks() 方法实现基本登录流程。

已复制到剪贴板。

let getUserAndLinksPromise = SimpleSignInService.getUserAndLinks(IDP_NAME);  // 调用API
getUserAndLinksPromise.then(                                                 // 处理响应
    (response) => {
        if (response.requestStatus != RequestStatus.SUCCESSFUL) {
            // 检查requestStatus。
            // 例如，请求不成功，因为用户已为其账户、该设备或此应用禁用了简单登录。

            // 回退以显示应用的标准登录
        } else if (response.links?.length! > 0) {
            // 这意味着存在用户可以用来登录的链接

            /*
             * 为ShowLoginSelection做准备。
             * 此代码是您的自定义代码。您需要获得
             * 对每个指向用户的关联显示的登录名。
             * 然后您可以从服务器获得登录名。
             */
            let request:LoginNameValue[] = [];
            response.links?.forEach((link) => {
              request.push({loginName: <关联的登录名>, linkId: link.linkId});
            });

            // 调用ShowLoginSelection API
            let showLoginSelectionPromise = SimpleSignInService.showLoginSelection(request);
            showLoginSelectionPromise.then((response) => { // 处理用户选择的内容
                if (response.userSelection == UserSelection.MANUAL_SIGN_IN) {  // 用户选择了使用新账户登录
                    // 显示您应用的标准登录
                } else if (response.userSelection == UserSelection.LOGIN_SELECTED) {  // 用户选择了现有链接进行登录
                    // 将关联ID传递给相应的方法或应用的服务器以进行身份验证
                } else {
                    // 表示用户在15分钟内没有选择任何内容，或者请求失败
                    // 回退以显示应用的标准登录
                }
            });
        } else {
            // 这意味着还没有为用户创建任何链接
            // 回退以显示应用的标准登录
        }
    }
);

账户关联流程

成功进行标准登录后，您应该关联用户的账户，以便为将来的会话启用无缝登录。此过程在用户的亚马逊账户和您的应用的账户之间建立安全连接。

以下示例使用应用的标准登录方法将用户账户关联到您的应用。

用户每次使用应用的标准登录流程登录时，都会调用LinkUserAccount() 方法。

已复制到剪贴板。

let request = {
    partnerUserId: <合作伙伴用户Id>,
    identityProviderName: <IDP名称>,
    userLoginName: <要显示给用户的用户账户的登录名称>,
    linkToken: {
        token: <您的服务器所生成的令牌>
        schema: "LINK-TOKEN-1.0"
    },
    linkSigningKey: <您的服务器生成的关联签名密钥>
};

// 调用LinkUserAccount API
let promise = SimpleSignInService.linkUserAccount(request);
promise.then((response) => {  // 处理响应
    if (response.successCode == LinkAccountSuccessCode.LINK_ESTABLISHED) {
        // 保存响应中返回的关联ID，即在服务器上与您应用的用户帐户对应的关联ID。
        // 使用`response.linkId`。
    } else if (response.successCode == LinkAccountSuccessCode.LINK_ALREADY_EXISTS) {
        // 保存响应中返回的在服务器上与您应用的用户帐户对应的关联ID，因为这是创建的新关联。
        // 使用`response.linkId`。
    } else if (response.successCode != LinkAccountSuccessCode.CONSENT_DENIED) {
        // 表示用户不想关联此账户。
        // 此时不进行任何操作。完成应用登录流程后继续操作。
    } else {
        // 简单登录服务出现了错误。检查requestStatus
        // 如果问题仍然存在，请向亚马逊报告。
    }
});

故障排除

  1. 未显示同意屏幕或登录选择屏幕。
    确保您的清单已更新。

     [[wants.module]]
 id = "/com.amazon.dms.ssi@ISimpleSignIn"

 [[wants.service]]
 id = "com.amazon.dms.ssi.service"

 [[wants.interactive]]
 id = "com.amazon.dms.ssi.loginselection"

 [[wants.interactive]]
 id = "com.amazon.dms.ssi.consent"

  2. API调用在请求状态中返回FEATURE_TURNED_OFF。

    用户已在账户级别、设备级别或针对您的应用禁用了简单登录功能。

  3. API调用在请求状态中返回NOT_AVAILABLE。

    简单登录功能在设备运行时所在的区域不可用。

枚举

类

类型别名

Last updated: 2025年10月23日

关注我们:
amazon_developer_logo

© 2010-2025 年，亚马逊公司或其附属公司. 保留所有权利。

协议

开发人员博客

联系我们