适用于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迁移到AMZNAuthorizationManager
或AMZNUser
下的新API。
如果您的应用尚未集成Login with Amazon,请参阅iOS入门指南中的完整说明。
如何升级
- 下载适用于iOS的最新版本亚马逊应用和游戏服务开发工具包。
- 将文件解压到硬盘目录。
- 更新库和框架,然后构建项目(如需了解详细说明,请参阅创建Login with Amazon项目):
- 如果您使用的库是Login with Amazon 1.0或2.0,请在Frameworks文件夹中删除login-with-amazon-sdk目录和login-with-amazon-sdk.a。在主菜单中单击Edit(编辑),然后选择Delete(删除)。此外,如果您的项目正在使用旧版本的LoginWithAmazon.framework参考,请将其删除任何引用。
- 在Xcode中打开项目,选择Frameworks文件夹,在主菜单中单击File(文件),然后选择Add files to
<project>
(将文件添加到<项目>)。在对话框中,选择LoginWithAmazon.framework (v3.0.x)然后单击Add(添加)。 - 在项目的Build Phases(构建阶段)中,展开Link Binary with Libraries(链接二进制与库),然后单击加号为项目添加以下框架: Security.framework, SafariServices.framework, CoreGraphics.framework.
- 选择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库路径的任何参考。
- 在主菜单中单击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
对象来表示范围。要请求范围,则需要添加为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
块包含三项参数:
-
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
的参考类,以了解更过关于获取个人资料数据的信息。
userDidCancel
: 布尔标记,如果客户在登录流程中选择取消,则设置为true。-
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
类来帮助您更好地管理客户个人资料数据。常用的客户个人资料数据类在本类中定义为属性,具体如下:
userID
:客户的唯一标识符。name
:客户的名称。email
:客户的电子邮件地址。postalCode
:客户的邮政编码。profileData
: 包含客户所有可用个人资料数据的词典。
profile
范围的授权(如上所述)。适用于iOS的新LWA SDK提供了两种请求客户个人资料数据的选项,替换了对 getProfile:
的调用 旧版本SDK要求的API:
- 如果客户未登录到您的应用,则调用
authorize:withHandler:
,在AMZNAuthorizationRequestHandler
块的result
对象中检索AMZNUser
对象。 -
如果客户当前已登录到您的应用,则调用
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授权服务器的错误。
}
}];