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 API in your code. For steps to add the Appstore SDK to your project, see Integrate the Appstore SDK. 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 the Simple Sign-in API
The packagecom.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 otherSimpleSignInServicemethods, you must create an instance ofISimpleSignInResponseHandlerand pass it to this method along with the application context to register your response handler. If you call any other method before invoking this method, anIllegalStateExceptionis 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 methodonLinkUserAccountResponse()is invoked inISimpleSignInResponseHandler.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 methodonGetUserAndLinksResponseis invoked inISimpleSignInResponseHandler. TheidentityProviderNameparameter 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. TheloginNamesparameter is a map oflinkIdto a user-recognizable identifier. When the user makes a selection, the callback methodonShowLoginSelectionResponse()is invoked inISimpleSignInResponseHandler.recordMetricEvent(SSIEventRequest ssiEventRequest): Call this method to initiate a request to record an SSI event for metric publishing. When the response is available, callback methodonRecordMetricsEventResponse()is invoked inISimpleSignInResponseHandler.
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 callSimpleSignInService.linkUserAccount()and theLinkUserAccountResponseobject is available from Amazon.onGetUserAndLinksResponse(GetUserAndLinksResponse getUserAndLinksResponse): This callback method is invoked when you callSimpleSignInService.getUserAndLinks()and theGetUserAndLinksResponseobject is available from Amazon.onShowLoginSelectionResponse(ShowLoginSelectionResponse showLoginSelectionResponse): This callback method is invoked when you callSimpleSignInService.showLoginSelection()and theShowLoginSelectionResponseobject is available from Amazon.onRecordMetricsEventResponse(RecordMetricsEventResponse recordMetricsEventResponse): This callback method is invoked when you callSimpleSignInService.recordMetricEvent()and theRecordMetricsEventResponseobject is available from Amazon.
Step 1: Handle asynchronous response messages
Supply an implementation forISimpleSignInServiceResponseHandler to handle asynchronous response messages from the Simple Sign-in service.
Example: Here is how you can handle response messages from Simple Sign-in.
Step 2: Register a concrete implementation
During app initialization, register an instance of a concrete implementation ofISimpleSignInServiceResponseHandler with SimpleSignInService from your main activity class.
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 queryinggetUserAndLinks().
- 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.
- 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.
- 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.
linkUserAccount() request to seek user consent for account linking and initiate the linking process.
For more detailed descriptions of the SSI client classes and methods, see SSI Client API.
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 invokelinkUserAccount() 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
TRUEmeans the user was shown the SSI consent dialog, regardless of whether they consented. - A value of null or
FALSEmeans the user has not yet been shown the SSI consent dialog.
- A value of
loginStatus and ssiConsentStatus respectively. The logic is as follows.
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(),ssiConsentStatusmight be updated depending upon the response fromlinkUserAccount(). IfresultStatusisSUCCESSFUL,ssiConsentStatusmust be updated toTRUE. - 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,
ssiConsentStatusmust be set toTRUE.
-
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
ssiConsentStatusfield must be reset, which is done by deleting the property or setting the value toFALSE.

