Changes Required in your App

Make these changes to your app in order to implement Simple Sign-in.

• Integrate with the Appstore SDK
• Integrate Simple Sign-in APIs
  • Step 1: Handle asynchronous response messages
  • Step 2: Register a concrete implementation
  • Step 3: Modify your sign-in flows to enable Simple Sign-in
  • Step 4: Handling app upgrade scenarios
    • Guidance for implementation
• Testing Simple Sign-in integration

Integrate with the Appstore SDK

The Simple Sign-in feature is offered through the Appstore SDK. To integrate your app with Simple Sign-in, integrate with the Appstore SDK and consume the Simple Sign-in APIs in your code.

See Integrate the Appstore SDK for the required steps to add the Appstore SDK to your project. Amazon's Appstore SDK also includes other functionalities, such as In-App Purchasing (IAP), and Digital Rights Management (DRM). The integration steps for your existing apps will vary depending on whether you already use In-App Purchasing (IAP) or Amazon-managed DRM. For more information, see Transitioning from IAP v2.0 to the Appstore SDK.

Integrate Simple Sign-in APIs

The package com.amazon.device.simplesignin within the SDK contains classes and interfaces to integrate with Simple Sign-in. There are two main files in this package.

SimpleSignInService class

This class is the entry point that exposes methods and holds other constructs for apps to integrate with Simple Sign-in. Methods in this class allow your app to communicate with the Simple Sign-in server.

The SimpleSignInService contains the following methods.

• registerResponseHandler(Context appContext, ISimpleSignInResponseHandler responseHandler): Before calling any other SimpleSignInService APIs, you must create an instance of ISimpleSignInResponseHandler and pass it to this method along with the application context to register your response handler. If you call any other API before invoking this method, an IllegalStateException is thrown.
• linkUserAccount(LinkUserAccountRequest linkUserAccountRequest): This method initiates a request to link the user's account with their Amazon account. When the response is available, the callback method onLinkUserAccountResponse() is invoked in ISimpleSignInResponseHandler.
• getUserAndLinks(String identityProviderName): Call this method to initiate a request to retrieve the link data available at Amazon for the currently logged-in user. When the response is available, the callback method onGetUserAndLinksResponse is invoked in ISimpleSignInResponseHandler. The identityProviderName parameter is the unique SSI ID received during SSI onboarding.
• showLoginSelection(Map <String, String> loginNames): Call this method to initiate a request to show a list of linked accounts available and allow the user to choose from it. The loginNames parameter is a map of linkId to a user-recognizable identifier. When the user makes a selection, the callback method onShowLoginSelectionResponse() is invoked in ISimpleSignInResponseHandler.
• recordMetricEvent(SSIEventRequest ssiEventRequest): Call this method to initiate a request to record an SSI event for metric publishing. When the response is available, callback method onRecordMetricsEventResponse() is invoked in ISimpleSignInResponseHandler.

ISimpleSignInServiceResponseHandler interface

This interface contains definitions for callback methods that send asynchronous responses to your app when you initiate a request through the SimpleSignInService. You must create an implementation of this interface and register your implementation with SimpleSignInService by calling the registerResponseHandler() method. Your instance of ISimpleSignInServiceResponseHandler should implement the following methods.

• onLinkUserAccountResponse(LinkUserAccountResponse linkUserAccountResponse): This callback method is invoked when you call SimpleSignInService.linkUserAccount() and the LinkUserAccountResponse object is available from Amazon.
• onGetUserAndLinksResponse(GetUserAndLinksResponse getUserAndLinksResponse): This callback method is invoked when you call SimpleSignInService.getUserAndLinks() and the GetUserAndLinksResponse object is available from Amazon.
• onShowLoginSelectionResponse(ShowLoginSelectionResponse showLoginSelectionResponse): This callback method is invoked when you call SimpleSignInService.showLoginSelection() and the ShowLoginSelectionResponse object is available from Amazon.
• onRecordMetricsEventResponse(RecordMetricsEventResponse recordMetricsEventResponse): This callback method is invoked when you call SimpleSignInService.recordMetricEvent() and the RecordMetricsEventResponse object is available from Amazon.

Step 1: Handle asynchronous response messages

Supply an implementation for ISimpleSignInServiceResponseHandler to handle asynchronous response messages from the Simple Sign-in service.

Example: Here is how you can handle response messages from Simple Sign-in.

public class ResponseHandlerImpl implements ISimpleSignInResponseHandler {
  public void onLinkUserAccountResponse(LinkUserAccountResponse response) {
    // Add custom logic to notify customers. This is optional and you
    // can choose the customer experience.
  }

  public void onGetUserAndLinksResponse(GetUserAndLinksResponse response) {
    /*
     * (a) During new account linking, extract a directed ID for the Amazon user account
     *     that's active on the device from the response and use it in linkToken generation.
     * (b) During new sign-in attempts, extract SSI tokens for the linked user accounts
     *     from the response and use it to authenticate the customer at your end. Optionally,
     *     prompt for customer confirmation from the login selection screen by invoking the
     *     ShowLoginSelection API.
     */
  }
  public void onShowLoginSelectionResponse(ShowLoginSelectionResponse response) {
    /*
     * Depending on the selection the customer has made from the login selection screen,
     * either log them in using the SSI token corresponding to the selected linked account,
     * or take the customer through the standard sign-in experience.
     */
  }
  public void onLinkUserAccountResponse(LinkUserAccountResponse response) {
    // Add custom logic to notify customers. This is optional and you
    // can choose the customer experience.
  }
  public void onRecordMetricsEventResponse(RecordMetricsEventResponse recordMetricsEventResponse) {
    // You can add logging here to track if the metrics are published succesfully.
    // This is optional.
  }
}

To receive response messages as Android Intents from the SSI client, declare the following broadcast receiver in your app's manifest file.

<receiver android:name="com.amazon.device.simplesignin.BroadcastHandler" >
    <intent-filter>
        <action android:name="com.amazon.simplesignin.NOTIFY" android:permission="com.amazon.simplesignin.Permission.NOTIFY" />
    </intent-filter>
</receiver>

Step 2: Register a concrete implementation

During app initialization, register an instance of a concrete implementation of ISimpleSignInServiceResponseHandler with SimpleSignInService from your main activity class.

@Override
protected void onCreate(Bundle savedInstanceState) {

  final ISimpleSignInResponseHandler responseHandler = new ResponseHandlerImpl();
  SimpleSignInService.registerResponseHandler(getApplicationContext(), responseHandler);
}

Step 3: Modify your sign-in flows to enable Simple Sign-in

When a user navigates to the sign-in flow within your app, check for any linked accounts that can be used to enable Simple Sign-in by querying getUserAndLinks().

• If there are no linked accounts found, gracefully fall back to your standard sign-in flow.
• Otherwise, invoke showLoginSelection() to display the SSI login screen and prompt users to select an account to use for sign-in.

When a user signs in by entering their credentials manually, on a successful sign-in,

• Send a recordMetricEvent() request with SSI Event: MANUAL_SIGNIN_SELECTED.
• Send a linkUserAccount() request to seek user consent for account linking and initiate the linking process.

When a user signs in using a link token, without entering credentials manually,

• On successful sign-in, send a recordMetricEvent() request with SSI Event: LOGIN_SUCCESS.
• On failed sign-in using a link token, send a recordMetricEvent() request with SSI Event: LOGIN_FAILURE, and gracefully fall back to your standard sign-in flow.

When a user signs up for a new account, on successful sign-up, send a linkUserAccount() request to seek user consent for account linking and initiate the linking process.

For more detailed descriptions of client APIs, see SSI Client APIs.

Step 4: Handling app upgrade scenarios

For customers who signed in to your app before Simple Sign-in was added, provide an option to let them link their accounts when they upgrade to the latest version of your app that supports Simple Sign-in. When they launch the app for the first time after the upgrade, generate a link token for the logged-in user and invoke linkUserAccount() to set up account linking. To implement this, use the following guidance.

Guidance for implementation

The Amazon Appstore recommends an account linking setup flow during the launch of an app, but you can choose to implement this as you prefer. For instance, rather than showing an account linking dialog when the app launches, you can wait until the customer navigates to the account settings page on the app. Make sure the SSI consent screen is not displayed again if the customer already consented to use Simple Sign-in earlier.

You can implement this using conditional logic based on two persistent state properties maintained locally, such as using Shared Preferences by the app.

• Property #1: (Data type: Boolean) Indicates whether a user has signed in to the app or not. In most cases, you can infer the login status based on the data (such as auth tokens, user settings) which they have cached on their device, without introducing a new state variable to track it.
• Property #2: (Data type: Boolean) Indicates whether the user currently signed in was already given an option to link their app user account with their Amazon account.
  • A value of TRUE means the user was shown the SSI consent dialog, regardless of whether they consented.
  • A value of null or FALSE means the user has not yet been shown the SSI consent dialog.

For example, if the two properties above are named loginStatus and ssiConsentStatus respectively. The logic is as follows.

if (loginStatus == Boolean.TRUE && ssiConsentStatus != Boolean.TRUE) {
  /*
  The user who has logged in was never given an option to link
  their accounts for SSI. Either the SSI feature was not available
  on the device/app when the customer logged in or the customer
  had the SSI feature turned OFF when they logged in.
  */

  //Initiate account linking flow

  /*
  Steps:

  1. Call the getUserAndLinks API to get directedAmazonUserId for their Amazon account.
  2. Proceed to next steps only if resultStatus of getUserAndLinks is SUCCESSFUL.
  3. Call your backend server to generate linkToken.
  4. Call the linkUserAccount API to set up account linking.
  5. Update the ssiConsentStatus property based on the resultStatus returned
  in the linkUserAccount API response.
  5a. If resultStatus is SUCCESSFUL, set ssiConsentStatus to TRUE
  */
}

When a customer installs the app, the ssiConsentStatus field is initially unset (a default of FALSE). When the customer signs in or signs out, the ssiConsentStatus field must be updated as follows.

User signs in:

• When a customer signs into an app manually and was given the SSI user consent dialog by invoking linkUserAccount(), ssiConsentStatus might be updated depending upon the response from linkUserAccount(). If resultStatus is SUCCESSFUL, ssiConsentStatus must be updated to TRUE.
• When a customer signs in to SSI using a previously linked account, they don't need to be asked for SSI account linking consent again. Therefore, ssiConsentStatus must be set to TRUE.

User signs out:

• When a user logs out and has an SSI linked account, inquire whether the user wants to
  • Sign out of the app and out of the Simple Sign-in feature on their device.
  • Sign out of the app but retain Simple Sign-in for future sign-ins.
  • Sign out of all instances of the app where Simple Sign-in is used for their account.
• The baseline behavior should be the first option, to sign out of the app and out of the Simple Sign-in feature on their device.
• When a customer signs out of an app, the ssiConsentStatus field must be reset, which is done by deleting the property or setting the value to FALSE.

Testing Simple Sign-in integration

You can install the App Tester APK on your test devices and run your app in sandbox mode to test Simple Sign-in behavior on your apps before publishing to the Appstore. See Test your App with App Tester for more details.

Next step: Changes Required in your Backend

Last updated: May 22, 2024