适用于iOS的Login with Amazon SDK 3.0.x迁移指南
本指南介绍如何将您的应用从使用适用于iOS的Login with Amazon SDK v2.1.2(或更低版本)迁移到使用适用于iOS的Login with Amazon SDK v3.0.x。您需要从使用AIMobileLib类下的API迁移到使用AMZNAuthorizationManager或AMZNUser下的新API。
如果您尚未将Login with Amazon集成到您的应用中,请查看iOS开始使用指南中的全套说明。
升级方法
- 下载最新版本适用于iOS的亚马逊应用和游戏服务SDK。
- 将文件解压缩到硬盘上的目录中。
- 更新库和框架,然后构建项目(如需更多详细说明,请参阅创建Login with Amazon项目):
    - 如果您使用了Login with Amazon 1.0或2.0库,请从Frameworks文件夹中删除login-with-amazon-sdk目录以及login-with-amazonsdk.a。在主菜单中单击Edit(编辑),然后选择Delete(删除)。此外,如果您的项目使用的是旧版本LoginWithAmazon.framework,请删除对旧版本的任何引用。
- 在Xcode中打开项目后,选择Frameworks文件夹,从主菜单中单击File(文件),然后选择Add files to <项目>。在对话框中,选择LoginWithAmazon.framework (v3.0.x),然后单击Add(添加)。
- 在项目的Build Phases(构建阶段)部分,展开Link Binary with Libraries(将二进制文件与库关联),然后单击加号将以下框架添加到您的项目中: Security.framework、SafariServices.framework、CoreGraphics.framework。
- 选择Build Settings(构建设置),然后单击All(全部)。确保LoginWithAmazon.framework目录位于Framework搜索路径中。如果您使用了Login with Amazon 1.0或2.0库,则可以在标题搜索路径或库搜索路径中删除对1.0或2.0库路径的任何引用。
- 在主菜单中,单击Product(产品),然后选择Build(构建)。构建应成功完成。在构建项目之前,如果您使用了Login with Amazon 1.0或2.0库,请将源文件中的#import "AIMobileLib.h"、#import "AIAuthenticationDelegate.h"或#import "AIError.h"替换为#import <LoginWithAmazon/LoginWithAmazon.h>。LoginWithAmazon.h同时包含所有Login with Amazon标头。
 
- 按照以下说明迁移到Login with Amazon 3.0库中引入的新API。
处理登录按钮并获取用户配置文件数据
调用authorize:withHandler方法。
在新的适用于iOS的LWA SDK中,不要调用authorizeUserForScopes:delegate:options:,而是改为调用authorize:withHandler:。要调用这个新的API,您需要定义一个AMZNAuthorizeRequest对象。此请求对象让您可以将输入参数自定义为authorize:withHandler: API。通常传递给AMZNAuthorizeRequest类的一些属性包括:
- scopes: 定义请求授权的范围。- AMZNProfileScope类定义Login with Amazon提供的范围。如果您将API用于其他亚马逊产品,则会发现这些产品支持的范围包含在它们自己的文档中。
- interactiveStrategy: 这是一个新定义的属性,用于确定在调用- authorize:withHandler:时是否提示用户登录。LWA SDK目前支持以下策略来提示用户登录:- AMZNInteractiveStrategyAuto(默认): SDK从之前的- authorize:withHandler:响应中查找本地存储的授权授予。如果有授权授予可用、有效且包含所有请求的范围,则SDK将通过- AMZNAuthorizationRequestHandler返回成功的响应,并且不会提示用户登录。否则,将提示用户登录。
- AMZNInteractiveStrategyAlways: 无论用户之前是否已获得使用应用的授权,SDK始终都将提示用户登录。当系统提示用户时,SDK将删除该应用的所有本地缓存的授权授予。
- AMZNInteractiveStrategyNever: SDK会从之前的- authorize:withHandler响应中寻找本地存储的授权授予。如果有授权授予可用、有效且包含所有请求的范围,SDK将返回一个- AMZNAuthorizeResult对象,其中包含访问令牌和用户配置文件数据。否则,它将通过- AMZNAuthorizationRequestHandler返回- NSError对象。
 
有关AMZNAuthorizeRequest对象中属性的完整列表,请参阅SDK文档中的类参考。
向AMZNAuthorizeRequest添加范围。
在新的适用于iOS的LWA SDK中,我们使用AMZNScope对象来表示范围。要请求范围,您需要将AMZNScope对象添加到您的AMZNAuthorizeRequest中。有两个选项:
- 
    要请求Login with Amazon提供的客户配置文件范围,请使用 AMZNProfileScope类中定义的方法:范围名称 AMZNProfileScope类中的方法 profile [AMZNProfileScope profile] postal_code [AMZNProfileScope postalCode] profile:user_id [AMZNProfileScope userID] 
- 
    或者,您可以使用 AMZNScopeFactory创建AMZNScope对象:[AMZNScopeFactory scopeWithName:@"profile"]使用此替代方法请求其他亚马逊产品提供的范围。 
使用块对象来处理回调。
适用于iOS的新LWA SDK改为使用objective-c块对象来处理回调函数,而不是使用委托方法。此更改无需实现两种委托方法(一种用于requestDidSucceed:,另一种用于requestDidFail:)。可以改为调用单个AMZNAuthorizationRequestHandler块对象来处理authorize:withHandler:调用的结果。AMZNAuthorizationRequestHandler块包含三个参数:
- 
    result:AMZNAuthorizeResult对象,其中包含authorize:withHandler:调用成功时来自Login with Amazon授权服务器的响应。result可能包括:- token: 如果您请求访问令牌(默认情况下出现),LWA授权服务器将在- result对象中返回访问令牌。您不再需要通过单独调用- getAccessTokenForScopes:withOverrideParams:delegate:API来请求访问令牌,即不需要在- authorizeUserForScopes:delegate:API的成功委托方法中进行该单独调用(先前版本的适用于iOS的LWA SDK中的一项要求)。
- user: 如果您请求- profile范围,则- result对象将包含一个- AMZNUser对象,其中包含所请求的客户配置文件数据。您不再需要从- authorizeUserForScopes:delegate:的成功委托方法调用- getProfile:(先前版本的适用于iOS的LWA SDK中的一项要求)。有关获取配置文件数据的更多信息,请参阅- AMZNUser的类参考。
 
- userDidCancel: 如果客户选择在登录流程中取消,则布尔标记设置为true。
- 
    error: 处理authorize:withHandler:请求期间,适用于iOS的LWA SDK中出现内部错误时返回一个NSError对象。- (IBAction)onLogInButtonClicked:(id)sender { // 构建授权请求。 AMZNAuthorizeRequest *request = [[AMZNAuthorizeRequest alloc] init]; request.scopes = [NSArray arrayWithObjects: // [AMZNProfileScope userID], [AMZNProfileScope profile], [AMZNProfileScope postalCode]]; // 对Login with Amazon SDK进行授权调用。 [[AMZNAuthorizationManager sharedManager] authorize:request withHandler:^(AMZNAuthorizeResult *result, BOOL userDidCancel, NSError *error) { if (error) { // 处理来自SDK或授权服务器的错误。 } else if (userDidCancel) { // 处理用户取消登录时导致的错误。 } else { // 身份验证成功。 // 获取访问令牌和用户配置文件数据。 NSString *accessToken = result.token; AMZNUser *user = result.user; NSString *userID = user.userID; } }]; }
获取用户配置文件数据
只要用户登录并已对您的应用授权,您就可以随时获取其用户配置文件数据。新的适用于iOS的LWA SDK引入了AMZNUser类,以帮助您更好地管理客户配置文件数据。一些常用的客户配置文件数据被定义为此类中的属性:
- userID:客户的唯一标识符。
- name:客户的姓名。
- email:客户的电子邮件地址。
- postalCode:客户的邮政编码。
- profileData: 包含客户所有可用个人资料数据的字典。
profile范围申请授权。新的适用于iOS的LWA SDK为您提供了两个请求客户配置文件数据的新选项,它们取代了对之前版本SDK要求的getProfile: API的调用:
- 当客户未登录您的应用时,调用authorize:withHandler:以在您的AMZNAuthorizationRequestHandler块的result对象中检索AMZNUser对象。
- 
    如果客户当前已登录您的应用,请调用 fetch:API(在AMZNUser类中),以获取最新的客户配置文件数据。[AMZNUser fetch:^(AMZNUser *user, NSError *error) { if (error) { // SDK出错,或者没有用户对应用授权。 } else if (user) { NSString *userID = user.userID; // NSString *name = user.name; // NSString *email = user.email; // NSString *postalCode = user.postalCode; // 获取字典中所有可用的用户配置文件数据 NSDictionary *profileData = user.profileData } }];
启动时检查用户登录
在新的适用于iOS的LWA SDK中,您不再需要调用getAccessTokenForScopes:withOverrideParams:delegate:。可以改为调用authorize:withHandler: API来检测您的应用是否仍处于已获授权状态。将AMZNAuthorizeRequest.interactiveStrategy设置为AMZNInteractiveStrategyNever,SDK将从之前的authorize:withHandler响应中寻找本地存储的授权授予。如果有授权授予可用、有效且包含所有请求的范围,则SDK将返回一个包含访问令牌和用户配置文件数据的AMZNAuthorizeResult对象。否则,它将通过AMZNAuthorizationRequestHandler返回NSError对象。
// 构建授权请求。
AMZNAuthorizeRequest *request = [[AMZNAuthorizeRequest alloc] init];
request.scopes = [NSArray arrayWithObjects:
// [AMZNProfileScope userID],
[AMZNProfileScope profile],
[AMZNProfileScope postalCode]];
request.interactiveStrategy = AMZNInteractiveStrategyNever;
[[AMZNAuthorizationManager sharedManager] authorize:request
 withHandler:^(AMZNAuthorizeResult *result, BOOL
  userDidCancel, NSError *error) {
    if (error) {
        // SDK出错,表示用户之前未针对所请求的范围对应用授权。
    } else {
        // 用户之前已对您的应用授权。
        // 获取访问令牌和用户配置文件数据。
         NSString *accessToken = result.token;
         AMZNUser *user = result.user;
         NSString *userID = user.userID;
    }
}];
清除授权数据并注销用户
使用新的适用于iOS的LWA SDK提供的新signOut: API,它取代了clearAuthorizationState:。
[[AMZNAuthorizationManager sharedManager] signOut:^(NSError * _Nullable error) {
  if (!error) {
	// SDK或Login with Amazon授权服务器出错。
  }
}];

