Understanding Real-Time Notifications
Real-Time Notifications (RTN) are server-to-server push notifications that provide comprehensive data about in-app purchases in real time. You can use this information to monitor purchase state changes associated with your customer’s in-app purchasable items.
- Overview of Real-Time Notifications
- Prerequisites
- Live App Testing for RTN
- Real-Time Notification Message Details
- FAQs
Overview of Real-Time Notifications
Amazon notifies developers about a user’s purchase state of in-app items via receipts. A receipt contains information about the IAP that developers define at the time of submitting an app along with order state. Currently, to get the latest receipt status, you need to follow a pull model by querying Amazon services by calling Receipt Verification Service (RVS) periodically.
With Real-Time Notifications, Amazon provides real-time server push notifications. Amazon’s RTN server sends a notification to your back-end server with information about your customer's purchase, which you can then verify with RVS.
Real-Time Notifications can be used in addition to the existing RVS infrastructure. The diagram below demonstrates how the RVS and RTN processes interact. See the step breakdown below for detailed information about the processes.
Steps 1-5: These steps follow the request flow mentioned in the Receipt Verification Service Overview.
Step 6: Amazon Real-Time Notifications (RTN) sends a notification message about the customer’s in-app purchase to your app server (the developer’s back-end server).
Step 7: The app server sends a request to RVS server for validation of the receipt and obtains all information related to the receipt.
Step 8: The RVS server confirms the receipt’s validity and returns information associated with the receipt.
The Real-Time Notification flow (Steps 6-8) does not wait on the completion of the RVS flow (Steps 1-5) to be triggered. Both flows can be triggered in parallel.
Prerequisites
Before you can use Real-Time Notifications, you need to make sure your environment is set up to receive the RTN responses. Ensure you have a secure back-end server that meets the following requirements:
- Your back-end server needs an HTTPS end point to receive RTN responses.
- The back-end server must be able to handle HTTPS POST request sent by Amazon.
- The back-end server must use valid SSL certificates from a trusted certificate provider.
Live App Testing for RTN
See the steps below to set up Live App Testing (LAT) for RTN.
- Execute an IAP purchase under Live App Testing.
- The Amazon server returns an RTN payload with the attribute
betaProductTransaction=true
.
Real-Time Notification Message Details
Real-Time Notifications are delivered via a JSON message to your HTTPS endpoint. Each notification contains the following JSON payload. You can find additional information in the Amazon Simple Notification Service (SNS) Developer Guide.
The Message
attribute Real-Time Notification contains an escaped JSON with the following fields.
Field | Data Type | Description | Example Response |
receiptId
|
String | Unique identifier for the purchase. Max string length 200 characters and can include alphanumeric values and punctuation | kyplB1fdRX1m6/GNAVW0l6jv9Nl1V/GemSopKBHM84w=
|
relatedReceipts
|
Map | Additional receipts that are associated with the notification sent | cancelledReceiptId (Unique identifier for the previously cancelled receipt for SUBSCRIPTION_MODIFIED_IMMEDIATE notification)
|
appUserId
|
String | Identifier representing a distinct Amazon customer for your Appstore app. Max string length 128 characters and can include alphanumeric values and punctuation | wE1EG1gsEZI9q9UnI5YoZ2OxeoVKPdR5bvPMqyKQq5Y=:1:11
|
notificationType
|
String | Notification type | See the Supported Notifications table in the next section for details and examples. |
appPackageName
|
String | App package name that identifies the app | com.myapp.sample.android
|
timestamp
|
Long Integer | Epoch time | 1402008634018 |
betaProductTransaction
|
Boolean | Indicates if the transaction is for Live App Testing product | true /false
|
Supported Notification Types
RTN messages contain information about or each type of in-app purchase (subscriptions, entitlements, and consumables). The tables below describe the notifications that are currently available.
Amazon might add or change notification types over time. You will be informed of new notification types as they are added. Amazon generally recommends that you ignore any notification types not applicable to you.
Notification Type | Description |
CONSUMABLE_CANCELLED | Consumable item was voluntarily or involuntarily cancelled. |
CONSUMABLE_PURCHASED | Consumable item was purchased. |
ENTITLEMENT_CANCELLED | Entitlement item was voluntarily or involuntarily cancelled. |
ENTITLEMENT_PURCHASED | Entitlement item was purchased. |
SUBSCRIPTION_PURCHASED | A subscription was purchased. |
SUBSCRIPTION_AUTO_RENEWAL_OFF | Auto-renew feature for subscription was turned off. |
SUBSCRIPTION_CANCELLED | A subscription was voluntarily or involuntarily cancelled. |
SUBSCRIPTION_EXPIRED | A subscription was expired. |
SUBSCRIPTION_SCHEDULED_TO_END | A subscription is scheduled to end because the auto-renew feature was turned off. Sent 10 days before for a customer’s monthly subscription is scheduled to end. Sent 30 days before a customer semi-annual/annual subscription is scheduled to end. |
SUBSCRIPTION_AUTO_RENEWAL_ON | Auto-renew feature for subscription was turned on. |
SUBSCRIPTION_RENEWED | An active subscription was renewed. |
SUBSCRIPTION_CONVERTED_FREE_TRIAL_TO_PAID | An active free trial subscription was converted to paid subscription. |
SUBSCRIPTION_IN_GRACE_PERIOD | A subscription has entered grace period (if enabled). |
SUBSCRIPTION_OUT_OF_GRACE_PERIOD | User fixes the payment issue/failure of the subscription which was previously in grace period. |
FAQs
Answers to Frequently Asked Questions (FAQs) about Real-Time Notifications.
- Q1. What is the format of Real-Time Notification messages?
- Real-Time Notifications are delivered in JSON messages to your specified HTTPS endpoint. See “Real-Time Notification Message Details“ above for more details.
- Q2. Will notifications be delivered in the exact order they were published?
-
The Amazon SNS service attempts to deliver messages from the publisher in the order they are published. However, network issues could potentially result in out-of-order messages at the HTTPS end point. It is recommended to check the timestamp attribute in the payload to check for out-of-order messages.
- Q3. What are the possible delivery mechanisms supported?
-
Currently, we support only HTTPS endpoint for delivering notifications. Please refer to the Amazon SNS documentation for the required steps to set up the HTTPS endpoint.
- Q4. What is the scope of origination of notification traffic?
-
AWS provides a list of Amazon IP addresses from which the traffic originates. Whenever there is a change in IP address space, AWS provides a mechanism to notify subscribers. Please refer to AWS IP address ranges documentation for the current list of IP address ranges.
- Q5. How can I test my HTTPS endpoint with the test transaction?
-
You can test your HTTPS endpoint with Live App Testing (LAT). See Live App Testing for RTN above for details.
- Q6. Do I need to call the RVS API for all the notification messages?
-
Yes, it is recommended to call the Receipt Verification Service (RVS) API to get the latest information about the receipt.
- Q7. What is the SLA associated with the notification message?
-
The Real-Time Notifications service does not offer an official latency SLA. However, most notifications should be published within a few seconds of the event occurrence.
- Q8. Can I create an allow list of Amazon IP address?
-
Yes, but this is optional. You can approve Amazon IP addresses so that Amazon can communicate with your servers. Check this list periodically for changes.
Last updated: May 22, 2024