Login with Amazon SDK for Android 3.x Migration Guide

This guide explains how to migrate your app from using the Login with Amazon SDK for Android v2.0.2 (or lower) to the Login with Amazon Android for Android v3.x.

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

What version of the Login with Amazon SDK for Android is my app using?
How to Upgrade
- Handle the Login Button and Get User Profile Data
  - Initialize RequestContext and registerListener.
  - Get customer profile data in the onSuccess() method of the AuthorizeListener().
- Call RequestContext.onResume
  - Call AuthorizationManager.authorize method with an AuthorizeRequest object.
  - Add scopes to AuthorizeRequest.
Fetch User Profile Data
Clear Authorization Data and Log Out a User

To determine the version of the Login with Amazon SDK for Android your app is using:

Open a Mac/Unix terminal.
Navigate to the folder containing the Login with Amazon SDK for Android (login-with-amazon-sdk.jar) in your Android app. Typically, this is the root directory of your project.

Run the following command to print the version number of the SDK:

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

How to Upgrade

Download the latest version of the Login with Amazon SDK for Android.
Extract the files to a directory on your hard drive and navigate to the LoginWithAmazon folder.
Use the login-with-amazon-sdk.jar in this folder to replace the older SDK .jar file in your Android app. You can do this by copying the new .jar file to your clipboard, then pasting it into the folder of your Android project where the old .jar file is stored (typically the root directory of your project).
Migrate to the new APIs introduced in the Login with Amazon 3.0 library as instructed below.

Initialize RequestContext and registerListener.

The new LWA SDK for Android no longer requires you to initialize an AuthorizationManager instance. Instead, you will need to declare a RequestContext variable and create a new instance of the class. The best place to initialize RequestContext is in the onCreate method of your Android activity or fragment. After the RequestContext instance is created, create the AuthorizeListener interface in-line with a registerListener call.

Get customer profile data in the onSuccess() method of the AuthorizeListener().

The onSuccess() method of the new AuthorizeListener class has changed its input argument type to AuthorizeResult. An AuthorizeResult object contains the response from the LWA authorization server when the AuthorizationManager.authorize call succeeds:

user: If you requested a profile scope, the AuthorizeResult object contains a User object that includes the requested profile data from a customer. You no longer need to call AuthorizationManager.getProfile from within the onSuccess method of AuthorizeListener (required in previous versions of the LWA SDK for Android). For more information on obtaining profile data, see the class reference for the User class in the SDK documentation.

accessToken: If you requested an access token (occurs by default), the LWA authorization server returns an access token in the response. You no longer need to call AuthorizationManager.getToken within the onSuccess method of AuthorizeListener (required in previous versions of the LWA SDK for Android).

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

requestContext.registerListener(new AuthorizeListener() {

/* Authorization was completed successfully. */
@Override
public void onSuccess(AuthorizeResult result) {
/* Your app is now authorized for the requested scopes */
}

/* There was an error during the attempt to authorize the
 application. */
@Override
public void onError(AuthError ae) {
/* Inform the user of the error */
}

/* Authorization was cancelled before it could be completed. */
@Override
public void onCancel(AuthCancellation cancellation) {
/* Reset the UI to a ready-to-login state */
}
});
}

@Override
protected void onCreate(Bundle savedInstanceState) { super.onCreate(savedInstanceState);
/* Previous onCreate declarations omitted */

// Find the button with the login_with_amazon ID
// and set up a click handler
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());
});
}
}

Call `RequestContext.onResume`

In order to accommodate the Android application lifecycle, implement the onResume method in your activity or fragment. This will trigger all listeners registered with registerListener in the event that your app is closed by the operating system before the user completes an authorization flow.

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

Call AuthorizationManager.authorize method with an AuthorizeRequest object.

The new LWA SDK for Android introduces changes to the AuthorizationManager.authorize method. The input to AuthorizationManager.authorize is now an AuthorizeRequest object. We recommend you create the request object using the Builder class defined in the AuthorizeRequest class. Some properties commonly passed to the AuthorizeRequest object are:

scopes: Defines what scopes to request authorization for. The Profile 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.
requestContext: The requestContext object you created earlier.

For a full list of properties in the AuthorizeRequest object, see the class references included in the SDK documentation.

Add scopes to AuthorizeRequest.

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

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

Scope name Method in ProfileScope class

profile ProfileScope.profile()

postal_code ProfileScope.postalCode()

profile:user_id ProfileScope.userId()
Alternatively, you can create a Scope object using ScopeFactory:
```
ScopeFactory.scopeNamed("profile");
```

Scope name	Method in ProfileScope class
profile	ProfileScope.profile()
postal_code	ProfileScope.postalCode()
profile:user_id	ProfileScope.userId()

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

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 SDK for Android introduces the User class to help you better manage customer profile data. Some of the commonly used customer profile data is defined as properties in this class:

userID: the unique identifier of an customer.
name: the name of the customer.
email: the email address of the customer.
postalCode: the postal code of the customer.
userInfo: A map that contains all available profile data of the customer.

Note: To obtain this customer data, you will first need to request authorization for one or more profile scopes as described above.

The new LWA SDK for Android provides you two options to request customer profile data, compared to older versions of the SDK which required a call to AuthorizationManager.getProfile:

When the customer is not signed in to your app, call AuthorizationManager.getProfile to retrieve a User object in the result object of your onSuccess() method.

If the customer is currently signed in to your app, call User.fetch to get the most up-to-date customer profile data.

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

/* fetch completed successfully. */
@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);
}
});
}

/* There was an error during the attempt to get the profile. */
@Override
public void onError(AuthError ae) {
/* Retry or inform the user of the error */
}
});
}

Clear Authorization Data and Log Out a User

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

@Override
protected void onCreate(Bundle savedInstanceState) {
super.onCreate(savedInstanceState);
/* Previous onCreate declarations omitted */

// Find the button with the logout ID and set up a click handler 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) {
// Set logged out state in UI
}
@Override
public void onError(AuthError authError) {
// Log the error
}
});
}
});
}