Se connecter
Se connecter
Merci de votre visite. Cette page est disponible en anglais uniquement.

Login with Amazon SDK for iOS 3.0.x Migration Guide

This guide explains how to migrate your app from using the Login with Amazon SDK for iOS v2.1.2 (or lower) to the Login with Amazon SDK for iOS v3.0.x. You will need to migrate from using APIs under the AIMobileLib class to new APIs under AMZNAuthorizationManager or AMZNUser.

If you’ve not yet integrated Login with Amazon into your app, review the full set of instructions in our Getting Started Guide for iOS.

How to Upgrade

  1. Download the latest version of the Amazon Apps & Games Services SDK for iOS.
  2. Extract the files to a directory on your hard drive.
  3. Update libraries and frameworks, then build the project (for more detailed instructions, see Creating a Login with Amazon Project):
    1. If you used the Login with Amazon 1.0 or 2.0 library, delete the login-with-amazon-sdk directory and login-with-amazonsdk.a from the Frameworks folder. Click Edit from the main menu and select Delete. Also, remove any reference to old versions of LoginWithAmazon.framework if your project was using one.
    2. With your project open in Xcode, select the Frameworks folder, click File from the main menu, and then select Add files to <project>. In the dialog, select LoginWithAmazon.framework (v3.0.x) and click Add.
    3. In the Build Phases section of your project, expand Link Binary with Libraries and click the plus sign to add the following frameworks to your project: Security.framework, SafariServices.framework, CoreGraphics.framework.
    4. Select Build Settings, then click All. Ensure the LoginWithAmazon.framework directory is in the Framework Search Paths. If you used the Login with Amazon 1.0 or 2.0 library, you can remove any references to the 1.0 or 2.0 library paths in the Header Search Paths or Library Search Paths.
    5. From the main menu, click Product and select Build. The build should complete successfully. Before building your project, if you used the Login with Amazon 1.0 or 2.0 library, replace #import "AIMobileLib.h", #import "AIAuthenticationDelegate.h", or #import "AIError.h" in your source files with #import <LoginWithAmazon/LoginWithAmazon.h>. LoginWithAmazon.h includes all of the Login with Amazon headers at once.
  4. Migrate to the new APIs introduced in the Login with Amazon 3.0 library as instructed below.

Handle the Login Button and Get User Profile Data

Call the authorize:withHandler method.

In the new LWA SDK for iOS, instead of calling authorizeUserForScopes:delegate:options:, switch to call authorize:withHandler:. To call this new API, you need to define an AMZNAuthorizeRequest object. This request object allows you to customize input parameters to the authorize:withHandler: API. Some properties commonly passed to the AMZNAuthorizeRequest class are:

  • scopes: Defines what scopes to request authorization for. The AMZNProfileScope class defines scopes provided by Login with Amazon. If you are using APIs for other Amazon products, you will find scopes supported by those products included in their own documentation.
  • interactiveStrategy: This is a newly-defined property that determines whether to prompt users to sign in when authorize:withHandler: is called. The LWA SDK currently supports following strategies for prompting user sign in:
    • AMZNInteractiveStrategyAuto (default): The SDK looks for a locally stored authorization grant from previous authorize:withHandler: responses. If one is available, valid, and contains all requested scopes, the SDK will return a successful response via AMZNAuthorizationRequestHandler, and will not prompt the user to login. Otherwise, the user will be prompted to login.
    • AMZNInteractiveStrategyAlways: The SDK will always prompt the user to login regardless of whether they have previously been authorized to use the app. When the user is prompted, the SDK will remove all locally cached authorization grants for the app.
    • AMZNInteractiveStrategyNever: The SDK looks for a locally stored authorization grant from previous authorize:withHandler responses. If one is available, valid, and contains all requested scopes, the SDK will return an AMZNAuthorizeResult object that contains an access token and user profile data. Otherwise, it will return an NSError object via AMZNAuthorizationRequestHandler.

For a full list of properties in the AMZNAuthorizeRequest object, see the class reference in the SDK documentation.

Add scopes to AMZNAuthorizeRequest.

In the new LWA SDK for iOS, we use the AMZNScope object to represent a scope. To request scopes, you will need to add AMZNScope objects to your AMZNAuthorizeRequest. There are two options:

  • To request customer profile scopes provided by Login with Amazon, use the methods defined in the AMZNProfileScope class:

    Scope name Method in AMZNProfileScope class
    profile [AMZNProfileScope profile]
    postal_code [AMZNProfileScope postalCode]
    profile:user_id [AMZNProfileScope userID]

  • Alternatively, you can create an AMZNScope object using AMZNScopeFactory:

    [AMZNScopeFactory scopeWithName:@"profile"]

    Use this alternate method to request scopes provided by other Amazon products.

Use a block object to handle the callback.

Instead of using delegate methods, the new LWA SDK for iOS changes to use objective-c block objects to handle callback functions. This change eliminates the need to implement two delegate methods (one for requestDidSucceed: and one for requestDidFail:). Instead, implement a single AMZNAuthorizationRequestHandler block object to process the result of the authorize:withHandler: call. The AMZNAuthorizationRequestHandler block contains three arguments:

  1. result: An AMZNAuthorizeResult object that contains the response from the Login with Amazon authorization server when the authorize:withHandler: call succeeds. The result may include:

    • token: If you requested an access token (occurs by default), the LWA authorization server returns an access token in the result object. You no longer need to request tokens by making a separate call to the getAccessTokenForScopes:withOverrideParams:delegate: API in the success delegate method of the authorizeUserForScopes:delegate: API (a requirement in previous versions of the LWA SDK for iOS).
    • user: If you requested a profile scope, the result object contains an AMZNUser object with the requested customer profile data. You no longer need to call getProfile: from the success delegate method of authorizeUserForScopes:delegate: (a requirement in previous versions of the LWA SDK for iOS). See the class reference for AMZNUser to find more information about obtaining profile data.
  2. userDidCancel: A boolean flag set to true if the customer chooses to cancel during the login flow.

  3. error: An NSError object returned when internal errors occurred in the LWA SDK for iOS while processing the authorize:withHandler: request.

    	- (IBAction)onLogInButtonClicked:(id)sender {
	  // Build an authorize request.
	  AMZNAuthorizeRequest *request = [[AMZNAuthorizeRequest alloc] init];
		 request.scopes = [NSArray arrayWithObjects:
		 // [AMZNProfileScope userID],
		 [AMZNProfileScope profile],
		 [AMZNProfileScope postalCode]];

	  // Make an Authorize call to the Login with Amazon SDK.
	  [[AMZNAuthorizationManager sharedManager] authorize:request
		withHandler:^(AMZNAuthorizeResult *result, BOOL
		userDidCancel, NSError *error) {
		   if (error) {
			// Handle errors from the SDK or authorization server.
		   } else if (userDidCancel) {
			// Handle errors caused when user cancels login.
		   } else {
			// Authentication was successful.
			// Obtain the access token and user profile data.
			NSString *accessToken = result.token;
			AMZNUser *user = result.user;
			NSString *userID = user.userID;
			  }
	  }];
	}

Fetch User Profile Data

As long as a user is logged in and authorized to your app, you can fetch their user profile data at any time. The new LWA iOS SDK for iOS introduces the AMZNUser class to help you better manage customer profile data. Some of the commonly used customer profile data is defined as properties in this class:

  1. userID: the unique identifier of an customer.
  2. name: the name of the customer.
  3. email: the email address of the customer.
  4. postalCode: the postal code of the customer.
  5. profileData: A dictionary that contains all available profile data of the customer.

The new LWA SDK for iOS provides you two new options to request customer profile data, which replace calls to the getProfile: API required by previous versions of the SDK:

  1. When the customer is not signed in to your app, call authorize:withHandler: to retrieve an AMZNUser object in the result object of your AMZNAuthorizationRequestHandler block.

  2. If the customer is currently signed in to your app, call the fetch: API in the AMZNUser class to get the most up-to-date customer profile data.

    	[AMZNUser fetch:^(AMZNUser *user, NSError *error) {
	  if (error) {
		// Error from the SDK, or no user has authorized to the app.
	  } else if (user) {
		NSString *userID = user.userID;
		//NSString *name = user.name;
		//NSString *email = user.email;
		//NSString *postalCode = user.postalCode;

		// To get all available user profile data in a dictionary
		NSDictionary *profileData = user.profileData
	  }
	}];

Check for User Login at Startup

In the new LWA SDK for iOS, you no longer need to call getAccessTokenForScopes:withOverrideParams:delegate:. Instead, switch to call the authorize:withHandler: API to detect whether your app is still authorized. Set AMZNAuthorizeRequest.interactiveStrategy to AMZNInteractiveStrategyNever and the SDK will look for a locally stored authorization grant from previous authorize:withHandler responses. If one is available, valid, and contains all requested scopes, the SDK will return an AMZNAuthorizeResult object that contains an access token and user profile data. Otherwise, it will return an NSError object via AMZNAuthorizationRequestHandler.

// Build an authorize request.
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) {
        // Error from the SDK, indicating the user was not previously authorized to your app for the requested scopes.
    } else {
        // The user was previously authorized to your app.
        // Obtain the access token and user profile data.
         NSString *accessToken = result.token;
         AMZNUser *user = result.user;
         NSString *userID = user.userID;
    }
}];

Clear Authorization Data and Log Out a User

Use the new signOut: API provided by the new LWA SDK for iOS, which replaces clearAuthorizationState:.

[[AMZNAuthorizationManager sharedManager] signOut:^(NSError * _Nullable error) {
  if (!error) {
	// error from the SDK or Login with Amazon authorization server.
  }
}];