适用于Android 的Login with Amazon SDK 3.x 迁移指南

本指南介绍如何将您的应用从使用适用于Android的Login with Amazon SDK v2.0.2（或更低版本）迁移到使用适用于Android的Login with Amazon SDK v3.x。

如果您尚未将Login with Amazon集成到您的应用中，请查看我们的Android开始使用指南中的全套说明。

我的应用使用的是什么版本的适用于Android的Login with Amazon SDK？
升级方法
- 处理登录按钮并获取用户配置文件数据
  - 初始化RequestContext和registerListener。
  - 在AuthorizeListener() 的onSuccess() 方法中获取客户配置文件数据。
- Call RequestContext.onResume
  - 使用AuthorizeRequest对象调用AuthorizationManager.authorize方法。
  - 向AuthorizeRequest添加范围。
获取用户配置文件数据
清除授权数据并注销用户

要确定应用使用的适用于Android的Login with Amazon SDK版本，请按照以下步骤操作：

打开Mac/Unix终端。
在您的Android应用中导航到包含适用于Android的Login with Amazon SDK (login-with-amazon-sdk.jar) 的文件夹。通常，其所在位置是项目的根目录。

运行以下命令以输出SDK的版本号：

`javap -classpath ./login-with-amazon-sdk.jar -constants com.amazon.identity.auth.map.device.utils.MAPVersionInfo | grep -o "LWA_VERSION = .*"`

升级方法

下载最新版本的适用于Android的Login with Amazon SDK。
将文件解压缩到硬盘上的某个目录中，然后导航到LoginWithAmazon文件夹。
使用此文件夹中的login-with-amazon-sdk.jar替换Android应用中较旧的SDK .jar文件。要进行该操作，您可以将新的.jar文件复制到剪贴板，然后将其粘贴到存储旧.jar文件的Android项目文件夹中（通常是项目的根目录）。
按照以下说明迁移到Login with Amazon 3.0库中引入的新API。

初始化RequestContext和registerListener。

新的适用于Android的LWA SDK不再要求您初始化AuthorizationManager实例。相反，您需要声明一个RequestContext变量并创建类的新实例。初始化RequestContext的最佳位置是在您的Android活动或片段的onCreate方法中。创建RequestContext实例后，创建与registerListener调用内联的AuthorizeListener接口。

在AuthorizeListener() 的onSuccess() 方法中获取客户配置文件数据。

新AuthorizeListener类的onSuccess() 方法已将其输入参数类型更改为AuthorizeResult。AuthorizeResult对象包含AuthorizationManager.authorize调用成功时来自LWA授权服务器的响应：

user：如果您请求了profile范围，AuthorizeResult对象将包含一个User对象，后一对象包含从客户端请求的配置文件数据。您不再需要从AuthorizeListener的onSuccess方法中调用AuthorizationManager.getProfile（在之前版本的适用于Android的LWA SDK中为必需）。有关获取配置文件数据的更多信息，请参阅SDK文档中User类的类参考。

accessToken：如果您请求了访问令牌（默认会进行该请求），LWA授权服务器将在响应中返回一个访问令牌。您不再需要在AuthorizeListener的onSuccess方法中调用AuthorizationManager.getToken（在之前版本的适用于Android的LWA SDK中为必需）。

@Override
protected void onCreate(Bundle savedInstanceState) {
super.onCreate(savedInstanceState);
requestContext = RequestContext.create(this);

requestContext.registerListener(new AuthorizeListener() {

/* 授权已成功完成。*/
@Override
public void onSuccess(AuthorizeResult result) {
/* 您的应用现已获得所请求范围的授权 */
}

/* 尝试对应用授权时
 出错。*/
@Override
public void onError(AuthError ae) {
/* 将错误告知用户 */
}

/* 授权在完成之前被取消。*/
@Override
public void onCancel(AuthCancellation cancellation) {
/* 将用户界面重置为准备好登录的状态 */
}
});
}

@Override
protected void onCreate(Bundle savedInstanceState) { super.onCreate(savedInstanceState);
/* 省略之前的onCreate声明 */

// 找到带有login_with_amazon ID的按钮
// 并设置单击处理程序
View loginButton = findViewById(R.id.login_with_amazon);
loginButton.setOnClickListener(new View.OnClickListener() {
@Override
public void onClick(View v) {
AuthorizationManager.authorize(new AuthorizeRequest
.Builder(requestContext)
.addScopes(ProfileScope.profile(), ProfileScope.postalCode())
.build());
});
}
}

调用`RequestContext.onResume`

为了适应Android应用的生命周期，请在您的活动或片段中实现onResume方法。如果您的应用在用户完成授权流程之前由操作系统关闭，这将触发通过registerListener注册的所有侦听器。

@Override
protected void onResume() {
super.onResume();
requestContext.onResume();
}

使用AuthorizeRequest对象调用AuthorizationManager.authorize方法。

新的适用于Android的LWA SDK引入了对AuthorizationManager.authorize方法的更改。AuthorizationManager.authorize的输入现在是AuthorizeRequest对象。我们建议您使用AuthorizeRequest类中定义的Builder类来创建请求对象。通常传递给AuthorizeRequest对象的一些属性包括：

scopes：定义请求授权的范围。Profile类定义Login with Amazon提供的范围。如果您将API用于其他亚马逊产品，则会发现这些产品支持的范围包含在它们自己的文档中。
requestContext：您之前创建的requestContext对象。

有关AuthorizeRequest对象中属性的完整列表，请参阅SDK文档中包含的类参考。

向AuthorizeRequest添加范围。

在新的适用于Android的LWA SDK中，我们使用Scope对象来表示范围。要请求范围，您需要将Scope对象添加到您的AuthorizeRequest中。有两个选项：

要请求Login with Amazon提供的客户配置文件范围，请使用ProfileScope类中定义的方法：

范围名称 ProfileScope类中的方法

profile ProfileScope.profile()

postal_code ProfileScope.postalCode()

profile:user_id ProfileScope.userId()
或者，您可以使用ScopeFactory创建Scope对象：
```
ScopeFactory.scopeNamed("profile");
```

范围名称	ProfileScope类中的方法
profile	ProfileScope.profile()
postal_code	ProfileScope.postalCode()
profile:user_id	ProfileScope.userId()

使用此替代方法请求其他亚马逊产品提供的范围。

获取用户配置文件数据

只要用户登录并已对您的应用授权，您就可以随时获取其用户配置文件数据。新的适用于Android的LWA SDK引入了User类，以帮助您更好地管理客户配置文件数据。一些常用的客户配置文件数据被定义为此类中的属性：

userID：客户的唯一标识符。
name：客户的姓名。
email：客户的电子邮件地址。
postalCode：客户的邮政编码。
userInfo：包含客户所有可用配置文件数据的映射。

注意： 要获取该客户数据，您首先需要对上述一个或多个profile范围申请授权。

新的适用于Android的LWA SDK为您提供了两个请求客户配置文件数据的选项，而相比之下，旧版本的SDK需要调用AuthorizationManager.getProfile：

当客户未登录您的应用时，调用AuthorizationManager.getProfile，以在您的onSuccess() 方法的result对象中检索User对象。

如果客户当前已登录您的应用，请调用User.fetch以获取最新的客户配置文件数据。

private void fetchUserProfile() {
User.fetch(this, new Listener<User, AuthError>() {

/* 获取成功完成。*/
@Override
public void onSuccess(User user) {
final String name = user.getUserName();
final String email = user.getUserEmail();
final String account = user.getUserId();
final String zipcode = user.getUserPostalCode();

runOnUiThread(new Runnable() {
@Override
public void run() {
updateProfileData(name, email, account, zipcode);
}
});
}

/* 尝试获取配置文件时出错。*/
@Override
public void onError(AuthError ae) {
/* 重试或将错误告知用户 */
}
});
}

清除授权数据并注销用户

使用新的适用于Android的LWA SDK提供的新signOut API，它取代了clearAuthorizationState。

@Override
protected void onCreate(Bundle savedInstanceState) {
super.onCreate(savedInstanceState);
/* 省略之前的onCreate声明 */

// 找到带有注销ID的按钮并设置单击处理程序View logoutButton = findViewById(R.id.logout);

logoutButton.setOnClickListener(new View.OnClickListener() {

@Override
public void onClick(View v) {
AuthorizationManager.signOut(getApplicationContext(), new Listener<Void, AuthError>() {
@Override
public void onSuccess(Void response) {
// 在用户界面中设置注销状态
}
@Override
public void onError(AuthError authError) {
// 记录错误
}
});
}
});
}