Set Up Quick Subscribe
For an overview of Quick Subscribe, see Quick Subscribe Overview. When you're ready to get started, contact your Amazon representative to have them enable Quick Subscribe on your account. Then, follow the steps on this page.
- Step 1: Configure Quick Subscribe in the Developer Console
- Step 2: Configure security profile
- Step 3: Implement getPurchaseUpdates
- Step 4: Integrate with RVS
- Step 5: Send fulfillment result to Amazon
- Step 6: Integrate with RTN
- Step 7: Integrate one-click account information sharing
- Step 8: Test Quick Subscribe with LAT
- Related topics
Step 1: Configure Quick Subscribe in the Developer Console
Any subscriptions available for customers to purchase in-app should also be available to purchase through Quick Subscribe, and any subscriptions available in Quick Subscribe should be available to purchase in-app. An exception to this is if you have five or more subscriptions available in-app. Then you must choose four subscriptions and offer them through Quick Subscribe.
To configure Quick Subscribe for your app, follow these steps
- Sign in to the Developer Console.
- In your app list, find the app you want to set up with Quick Subscribe.
- In the In-App Items column, click the link to open the In-App Items screen.
- Select Create Quick Subscription.
- An overlay pop-up appears as shown in the following image.
In the Choose default subscription drop down, the list is populated with your existing IAP subscriptions. Choose the subscription on which you want to enable Quick Subscribe.
- In the Select term drop down, choose a term for the quick subscription.
- If you would like to offer additional subscriptions for Quick Subscribe, select Add another quick subscription. You can add a maximum of four quick subscriptions.
- Choose your target devices for Quick Subscribe by checking the boxes.
- Choose whether to create the quick subscription for Live App Testing (LAT) only or for both LAT and your live app.
- To create a quick subscription for LAT only, select Create Quick Subscription for Test.
- To create the quick subscription for both LAT and the live app, select Create Quick Subscription for Test and Live.
Note: For details on how to use LAT to test Quick Subscribe, see Test Quick Subscribe with LAT.
After you create a quick subscription, you can delete or modify it by selecting Actions next to the Quick Subscribe item.
Step 2: Configure security profile
To configure a security profile for your app, follow these steps
- Sign in to the Developer Console.
- Open the app list and select your app.
- Select App Services and scroll to the Security Profile section.
- Click Select existing security profile or create new to expand the options.
- Use the drop-down to select the security profile that you want to map to this app, then click Enable Security Profile. Alternatively, you can create a new security profile by clicking Create Security Profile.
Step 3: Implement getPurchaseUpdates
getPurchaseUpdates()
in the onResume()
method.The getPurchaseUpdates()
method gets the user's receipts. Quick Subscribe uses the information from getPurchaseUpdates()
to verify your user's purchase status, ensuring that the user has access to the content to which they are entitled.
Call getPurchaseUpdates()
in the onResume()
method. The getPurchaseUpdates()
method takes one boolean parameter, reset
. Set reset
to false
to return only the new receipts since the last time you called this method. Set reset
to true
to return all of the receipts for this user.
@Override
protected void onResume() {
super.onResume();
//...
PurchasingService.getUserData();
//...
PurchasingService.getPurchaseUpdates(false);
}
For more information on how to integrate the getPurchaseUpdates()
method, see IAP API documentation:
- Android—Implement getPurchaseUpdates method
- Web app—getPurchaseUpdates(reset)
Implementation requirements
Follow these requirements to properly implement the getPurchaseUpdates()
method.
- You must call
getPurchaseUpdates()
in theonResume()
lifecycle method of the Android activity. - Always use the
false
flag while callinggetPurchaseUpdates()
inonResume()
to get the latest receipts. If you use thetrue
flag, it returns the full history of receipts, and you would have to add extra filtering logic to handle the response. - Add a "Restore Purchases" option in your app which calls
getPurchaseUpdates()
with thetrue
flag when selected by a customer. - The receipts received through
getPurchaseUpdates()
must always be persisted and must be mapped to the app's login ID. Use this mapping to unlock the subscribed content to customers when they open the app.
Step 4: Integrate with RVS
The Receipt Verification Service (RVS) lets you validate purchases made by your app's users. When you make a request to the RVS server, the JSON response returned includes a purchaseMetadataMap
field. If the purchase was initiated using Quick Subscribe, the purchaseMetadataMap
appears as {"QuickSubscribe":"true"}
, as seen in the following example.
{
"autoRenewing": true,
"betaProduct": false,
"binCountryCode": null,
"cancelDate": 1641131573000,
"cancelReason": 2,
"deferredDate": null,
"deferredSku": null,
"freeTrialEndDate": null,
"fulfillmentDate": 1641131345000,
"fulfillmentResult": "FULFILLED",
"gracePeriodEndDate": null,
"parentProductId": null,
"productId": "IntroFreeTrial.sku",
"productType": "SUBSCRIPTION",
"promotions": null,
"purchaseDate": 1641131345000,
"purchaseMetadataMap": {
"QuickSubscribe": "true"
},
"quantity": null,
"receiptId": "k9om1rUS7gZJIg8RMfw7AlbxA3aP56ay-vdgeLU40zw=:3:11",
"renewalDate": null,
"term": "1 Month",
"termSku": null,
"testTransaction": false
}
If the purchase wasn't initiated using Quick Subscribe, purchaseMetadataMap
appears as null. The following table provides a description for all fields in the response object.
Field | Data Type | Description |
---|---|---|
autoRenewing |
Boolean | Indicates if customer's subscription will auto renew. |
betaProduct |
Boolean | Indicates whether the product purchased is a Live App Testing product. |
cancelDate |
Long integer | The date the purchase was canceled, or the subscription expired. The field is null if the purchase was not canceled. Time is in milliseconds. |
cancelReason |
Integer | Indicates why a product was canceled. Possible values are null, 0, 1, or 2, where each integer represents a cancellation reason: null - The purchase was not canceled. 0 - The cancel reason is currently unavailable and will render at a later time. 1 - Your customer canceled the order. 2 - The purchase was canceled by Amazon's system. For example, a customer purchases a subscription with an invalid payment and the purchase could not be completed in the grace period. This code is also returned if Amazon customer support canceled the order at the request of a customer. |
freeTrialEndDate |
Long integer | Indicates that the subscription is in a free trial. Provides the free trial end date of the subscription in epoch (milliseconds). The field is null if the subscription is not in a free trial period. |
fulfillmentDate |
Long integer | In a subscription purchase, the date of the acknowledgement of fulfillment. Stored as the number of milliseconds since the epoch. Null if subscription fulfillment isn't confirmed. Always null for consumables and entitlements. |
fulfillmentResult |
String | In a subscription purchase, the status of fulfillment. Valid values:
|
gracePeriodEndDate |
Long integer | Indicates that the subscription is in grace period. Provides the grace period end date of the subscription in epoch (milliseconds). The field is null if the subscription is not in a grace period. |
parentProductId |
String | Null. Reserved for future use. |
productId |
String | The SKU that you defined for this item in your app. |
productType |
String | Type of product purchased. Valid product types are CONSUMABLE , SUBSCRIPTION , and ENTITLED . |
promotions |
List<Promotion> | Details of the promotional pricing or retention offer of a subscription purchase. Null if there is no promotion. See Promotions in RVS. |
purchaseDate |
Long integer | The date of the purchase, stored as the number of milliseconds since the epoch. For subscription items, purchaseDate represents the initial purchase date, not the purchase date of subsequent renewals. |
purchaseMetadataMap |
Map <String, String> | If the purchase was initiated via Quick Subscribe, the value is {"QuickSubscribe":"true"} . Otherwise null. |
quantity |
Integer | Quantity purchased. Always null or 1. |
receiptId |
String | Globally unique identifier for the purchase. |
renewalDate |
Long integer | The date that a subscription purchase needs to be renewed. The date is stored as the number of milliseconds since the epoch. |
term |
String | Duration that a subscription IAP will remain valid (the term starts on the date of purchase). The term consists of a number and a time period (Day, Week, Month, Year), such as 1 Week or 2 Months. |
termSku |
String | Unique SKU that corresponds to the subscription term. |
testTransaction |
Boolean | Indicates whether this purchase was made as a part of Amazon's publishing and testing process. |
For more details on RVS, see Receipt Verification Service for Appstore SDK IAP.
Step 5: Send fulfillment result to Amazon
When you send a fulfillment result, you ensure that Amazon can confirm whether users can access the content that they paid for. Always communicate the fulfillment result to Amazon. To do this, use the notifyFulfillment()
method included in the Appstore SDK.
After a customer signs in, call notifyFulfillment()
with status FULFILLED
when the subscription is fulfilled. If the customer already has a subscription, call notifyFulfillment()
with status UNAVAILABLE
to indicate that the customer has signed in but the purchase isn't applicable. For more information about the notifyFulfillment()
method, see Send fulfillment result to Amazon and grant item to the user.
If you've previously integrated with the Acknowledge Receipt API, you can continue to use it in place of the notifyFulfillment()
method. You must use either the notifyFulfillment()
method or the Acknowledge Receipt API in your app to communicate the fulfillment result to Amazon.
Implementation requirements
Follow these requirements to properly implement the notifyFulfillment()
method.
- You must call
notifyFulfillment()
every time the customer opens the app and tries to access content. - If you successfully map a customer to a receipt and unlock subscription content for the customer, you must call
notifyFulfillment()
with theFULFILLED
status. - If you identify that the customer has an existing subscription, you must call
notifyFulfillment()
with theUNAVAILABLE
status. - If you called
notifyFulfillment()
withUNAVAILABLE
due to an issue, make sure to callnotifyFulfillment()
with theFULFILLED
status when you successfully map the customer to the receipt and unlock the subscription content for the customer.
Acknowledge Receipt API
notifyFulfillment()
method included in the Appstore SDK rather than the Acknowledge Receipt API. If you've already integrated the Acknowledge Receipt API, you can continue to use it.Step 6: Integrate with RTN
With Quick Subscribe, customers subscribe to your app through Amazon, rather than through your app. This could lead to your app missing some information about a customer's purchase state. The getPurchaseUpdates()
method sends data only when an app is opened.
Real Time Notifications (RTN) provides customer purchase information for all transactions, including the ones that occur outside your app. When your server receives a purchase notification from Amazon's RTN server, use the Receipt Verification Service for Appstore SDK IAP (RVS) to validate the receipt.
For details about how to set up RTN, see Use Real-Time Notifications.
Step 7: Integrate one-click account information sharing
Use this guide to integrate your app with the one-click account information sharing feature.
Prerequisites
- Integrate with the Login with Amazon SDK. For details, see Install the Login with Amazon SDK for Android.
- Integrate with the Appstore SDK version 3.0.5 or higher. For details, see Integrate the Appstore SDK.
Update app manifest
To indicate to the Appstore that your app supports the one-click account information sharing feature, update your app's manifest with the following code.
<uses-feature android:name="amazon.lwa.quicksignup.supported"/>
Implement getUserData changes and integrate Login with Amazon
To determine if a customer provided consent to share their Amazon account details, in the onCreate()
method of your app's main activity, call the getUserData()
method with the setFetchLWAConsentStatus()
flag of the UserDataRequest
object set to true.
The following example shows how to build a UserDataRequest
object and pass it to getUserData()
when the customer has given consent to Login with Amazon (LWA) to obtain their details.
@Override
protected void onCreate(Bundle savedInstanceState)
{
super.onCreate(savedInstanceState);
//...
// Pass the reference of PurchasingListener to be registered
PurchasingService.registerListener(this.getApplicationContext(), purchasingListener);
// Implement logic to identify customer logged in status inside isLoggedIn()
if (!isLoggedIn()) {
PurchasingService.getUserData(UserDataRequest.newBuilder().setFetchLWAConsentStatus(true).build());
}
//...
}
If a customer provided their consent, the LWAConsentStatus
of the UserData
object has the status CONSENTED
. If a customer hasn't provided consent or if the consent token expired, LWAConsentStatus
has the status UNAVAILABLE
.
The following code shows how to handle the consent data received from the UserDataResponse
object.
@Override
public void onUserDataResponse( final UserDataResponse response) {
final UserDataResponse.RequestStatus status = response.getRequestStatus();
switch (status) {
case SUCCESSFUL:
if (LWAConsentStatus.CONSENTED.equals(response.getUserData().getLWAConsentStatus())) {
// lwaMager is implemented in a later section.
lwaManager.startAutoLoginWorkflow();
}
break ;
case FAILED:
case NOT_SUPPORTED:
// Fail gracefully.
break ;
}
}
If the customer provides consent, call the authorize()
method from LWA to retrieve the access token to fetch the customer's details from your server. For details on how to set up your server, see Get Customer Information to your Server. Then, create an account in your back-end system with the customer information.
The following code shows how to use the LWAManager
to enable automatic sign in for a customer who has provided consent.
//..
private RequestContext requestContext;
private Context context;
//..
LWAManager(RequestContext requestContext, Context context) {
this.requestContext = requestContext;
this.context = context;
requestContext.registerListener(new AuthorizeListener() {
//..
@Override
public void onSuccess(AuthorizeResult authorizeResult) {
signUpAccountWithAccessToken(authorizeResult.getAccessToken());
}
//..
});
}
public void startAutoSignupWorkflow() {
AuthorizationManager.authorize(
new AuthorizeRequest.Builder(requestContext)
.addScopes(ProfileScope.profile(), ProfileScope.postalCode())
.build()
);
}
private void signUpAccountWithAccessToken(final String accessToken) {
// Pass the accessToken to app's back-end API to get customer information for account creation.
// Details for backend API implementation can be found here:
// https://developer.amazon.com/docs/login-with-amazon/customer-profile-other-platforms-cbl-docs.html#get-customer-information-to-your-server
invokeAppBackendToCreateAccount(accessToken);
}
[Optional] If the customer doesn't provide consent, show the sign-in screen with a Login with Amazon button. The customer can then enter their credentials using the keyboard or use the Login with Amazon button to sign in to your app.
Flow diagram
The following diagram shows the code flow for Quick Subscribe with one-click account information sharing.
Best practices for account setup
Follow these best practices for setting up customer accounts.
- If
LWAConsentStatus
has the valueCONSENTED
in thegetUserData()
response, do the following:- Fetch the user information from the Login with Amazon server. Use this information to create a login account with a temporary password. Sign the customer in to the app without requesting a password reset or additional details from the customer.
- Later, ask the customer to reset the password through email.
- If
LWAConsentStatus
isUNAVAILABLE
, use the default app sign-up experience for the customer.
Step 8: Test Quick Subscribe with LAT
To test Quick Subscribe with Live App Testing (LAT), first configure Quick Subscribe for LAT in the Developer Console using the steps in Configure Quick Subscribe in the Developer Console. You can configure Quick Subscribe for LAT only, or configure it for both your live and LAT apps, as shown in the following image.
If you choose to configure Quick Subscribe for LAT only, you can later promote the configuration to your live app by selecting Actions > Promote to Live as shown in the following image.
If you configured Quick Subscribe for your LAT app differently than your live app, a TEST label appears in the quick subscription details for the LAT app as shown in the following image.
You can test the Quick Subscribe flow through the Amazon retail website or on a Fire device. When you start a live app test, you can send invitations to testers. Testers receive an email with a link to the Amazon website with the LAT version of the app.
Test Quick Subscribe on the website
From the LAT invitation email, select the Amazon website for your marketplace. On the app detail page, select the subscription option, which appears as a paid option for a subscription term, such as $20.00 monthly. Then, select a device to deliver to, and click Get App.
Test Quick Subscribe on the device
To get started with testing Quick Subscribe on the device, you can use the LAT invitation email or the device notification.
To test from the LAT invitation:
- Use the link in the invitation email to go to the app detail page on the Amazon website.
- Select the App Only option.
- In the Deliver to: drop-down menu, select Cloud Only.
- Click Get App.
- On a Fire TV device associated with the Amazon account, click the icon for Your Apps & Channels (the icon appears on the navigation bar as three squares and a plus sign).
- Find the LAT version of your app, which has a TEST banner on the app icon. You might need to click App Library to see the app.
- Select the app icon to open the app detail page on the device.
- Select Subscription Options and download the app.
To test from the notification:
After you send a LAT invite, the test devices associated with the tester email receive a notification. If you open the notification when it appears, you are taken to the LAT app detail page. This notification appears for 5-10 seconds. If you miss the notification when it first appears, you can click the settings icon (the gear icon) and select Notifications to see it. You can then read the notification and go to the app detail page. Select Subscription Options and download the app.
Important
- Testing Quick Subscribe through LAT isn't supported in the following cases:
- Using the App Only option on the website when you choose a specific device to deliver to.
- Using the App Only option on a device.
-
To test the app through LAT for a purpose other than Quick Subscribe, you can use the App Only option and select a specific device to deliver the app to.
-
Turn off accelerated subscriptions while testing Quick Subscribe.
-
To reset Quick Subscribe for a test account, go to the Developer Console to reset subscriptions for LAT. For details, see Reset in-app items for all testers in the LAT or Manage individual testers.
- If you want to accelerate the 30-day cancellation window to a 1-day window for testing, contact your Amazon representative.
Related topics
Last updated: Oct 02, 2024