适用于iOS 3.0.x的Login with Amazon SDK迁移指南

适用于iOS 3.0.x的Login with Amazon SDK迁移指南

本指南介绍了如何将您的应用从适用于iOS v2.1.2(及更低版本)的Login with Amazon SDK迁移到适应于iOS v3.0.x的Login with Amazon SDK。您需要从AIMobileLib类中使用的API迁移到AMZNAuthorizationManagerAMZNUser下的新API。

如果您的应用尚未集成Login with Amazon,请参阅iOS入门指南中的完整说明。

如何升级

  1. 下载适用于iOS的最新版本亚马逊应用和游戏服务开发工具包
  2. 将文件解压到硬盘目录。
  3. 更新库和框架,然后构建项目(如需了解详细说明,请参阅创建Login with Amazon项目):
    1. 如果您使用的库是Login with Amazon 1.0或2.0,请在Frameworks文件夹中删除login-with-amazon-sdk目录和login-with-amazon-sdk.a。在主菜单中单击Edit(编辑),然后选择Delete(删除)。此外,如果您的项目正在使用旧版本的LoginWithAmazon.framework参考,请将其删除任何引用。
    2. 在Xcode中打开项目,选择Frameworks文件夹,在主菜单中单击File(文件),然后选择Add files to<project>(将文件添加到<项目>)。在对话框中,选择LoginWithAmazon.framework (v3.0.x)然后单击Add(添加)
    3. 在项目的Build Phases(构建阶段)中,展开Link Binary with Libraries(链接二进制与库),然后单击加号为项目添加以下框架: Security.framework, SafariServices.framework, CoreGraphics.framework.
    4. 选择Build Settings(构建设置),然后单击All(全部)。确保LoginWithAmazon.framework目录位于Framework Search Paths。如果您正在使用Login with Amazon 1.0或2.0,您可以在Header Search Paths(标头搜索路径)Library Search Paths(库搜索路径)中删除1.0或2.0库路径的任何参考。
    5. 在主菜单中单击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标头。
  4. 按照如下说明,迁移到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对象来表示范围。要请求范围,则需要添加为AMZNAuthorizeRequest添加AMZNScope对象。有两个选项:

  • 要请求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块包含三项参数:

  1. result: AMZNAuthorizeResult对象,如果authorize:withHandler:调用成功,则包含来自Login with Amazon授权服务器的响应。result可能包括:

    • token: 如果您请求的是访问令牌(默认),LWA授权服务器则会在result对象中返回访问令牌。不再需要向getAccessTokenForScopes:withOverrideParams:delegate:作出单独的令牌调用请求。 authorizeUserForScopes:delegate:成功委托方法中的API 先前适用于iOS的LWA SDK所要求的API。
    • user: 如果请求范围为profile,则result对象中的AMZNUser对象中将包含所请求的客户个人资料数据。不再需要从authorizeUserForScopes:delegate:成功委托方法调用getProfile:(先前适用于iOS的LWA SDK则有此要求)。请参阅AMZNUser的参考类,以了解更过关于获取个人资料数据的信息。
  2. userDidCancel: 布尔标记,如果客户在登录流程中选择取消,则设置为true。
  3. error: 适用于iOS的LWA SDK在处理authorize:withHandler:请求时如果发生内部错误,则返回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类来帮助您更好地管理客户个人资料数据。常用的客户个人资料数据类在本类中定义为属性,具体如下:

  1. userID:客户的唯一标识符。
  2. name:客户的名称。
  3. email:客户的电子邮件地址。
  4. postalCode:客户的邮政编码。
  5. profileData: 包含客户所有可用个人资料数据的词典。

适用于iOS的新LWA SDK提供了两种请求客户个人资料数据的选项,替换了对 getProfile:的调用 旧版本SDK要求的API:

  1. 如果客户未登录到您的应用,则调用authorize:withHandler:,在AMZNAuthorizationRequestHandler块的result对象中检索AMZNUser对象。
  2. 如果客户当前已登录到您的应用,则调用fetch: AMZNUser类中用于获取最新客户个人资料数据的API。

    	[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。在AMZNInteractiveStrategyNever中设置AMZNAuthorizeRequest.interactiveStrategy,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;
    }
}];

清除授权数据和注销用户

使用新的signOut: 适用于iOS的新LWA SDK提供的新API,将用来代替clearAuthorizationState:

[[AMZNAuthorizationManager sharedManager] signOut:^(NSError * _Nullable error) {
  if (!error) {
	// 来自SDK或Login with Amazon授权服务器的错误。
  }
}];