Real-Time Developer Notifications (RTDN)

Aptoide Connect’s Real-Time Developer Notifications (RTDN) allows developers to receive instant updates about specific events related to purchases for either Non-Consumables or Subscriptions type of products. It also notifies about Voided Purchases which can affect Consumables, Non-Consumables and Subscriptions.
With RTDNs, you can stay informed about your customers Purchases and respond in real-time to any change made to the Purchase.

Overview

Aptoide Connect’s RTDN service notifies the developers with the following notification types:

One Time Product (Non-Consumable) Purchase Notification: Notification sent when an Non-Consumable product type Purchase is successful.
Subscription Purchase Notification: Notification sent when a Subscription suffers a change in it's state. Take a look in this section to see the states of the Lifecycle of a SUBSCRIPTION.
Voided Purchase Notification: Notification sent when a purchase has been Voided.

These notifications provide essential details about the event, enabling you to update your records or take necessary actions.

With this, you can improve your application with the following points aimed to the User Experience:

Instant Updates: Real-time notifications keep users informed about subscription changes (e.g., renewals or cancellations) as soon as they occur.
Enhanced Trust: With up-to-date subscription information, users can rely on the service for accurate billing and subscription status, boosting confidence in the platform.
Seamless User Experience: Up-to-date backend data ensures users receive the most current subscription details, avoiding confusion or outdated information.
Backend Synchronization: For developers, keeping the backend updated ensures accurate and timely data delivery through RTDNs, preventing issues like delays or inconsistencies in subscription management.

Setting Up RTDNs API

To start receiving RTDNs, developers must register a callback URL. This URL is where Aptoide Connect's service will send the events.

1. Register your Callback URL

To register your callback URL for RTDNs, access the Webhooks page in Aptoide Connect.

Fig. 1 - Webhooks page to register RTDN URL

Once in this page, you will be able to add new URLs using the Add button and you will be able to select the type of Notifications you wish to receive.

There are 2 types products for RTDNs you can receive:

Subscriptions: This option will trigger Aptoide Connect's service to send notifications related to the Subscriptions type of Products.
InApp: This option will trigger Aptoide Connect's service to send notifications related to the InApp type of Products.

2. Manage your Callback URL

Once registered the URL for the RTDNs, you will be able to manage it with the following options:

Notification Payload

The notification payload you will receive comes encoded in a data parameter with the base64-encoded scheme.

{
  "message": {
    "attributes": {
      "key": "value"
    },
    "data": "eyJ2ZXJzaW9uIjogIlN0cmluZyIsICJwYWNrYWdlTmFtZSI6ICJTdHJpbmciLCAiZXZlbnRUaW1lTWlsbGlzIjogIkxvbmciLCAib25lVGltZVByb2R1Y3ROb3RpZmljYXRpb24iOiAiT25lVGltZVByb2R1Y3ROb3RpZmljYXRpb24iLCAic3Vic2NyaXB0aW9uTm90aWZpY2F0aW9uIjogIlN1YnNjcmlwdGlvbk5vdGlmaWNhdGlvbiIsICJ2b2lkZWRQdXJjaGFzZU5vdGlmaWNhdGlvbiI6ICJWb2lkZWRQdXJjaGFzZU5vdGlmaWNhdGlvbiJ9",
    "messageId": "123456789012"
  }
}

After decoding the data parameter, the payload you will find is the following JSON scheme:

{
  "version": String,
  "packageName": String,
  "eventTimeMillis": Long,
  "oneTimeProductNotification": OneTimeProductNotification,
  "subscriptionNotification": SubscriptionNotification,
  "voidedPurchaseNotification": VoidedPurchaseNotification
}

The parameters in this payload are described as the following:

Name	Type	Description
version	String	Version of the Payload received.
packageName	String	Package name of the Application to which the Notification corresponds.
eventTimeMillis	Long	Timestamp of the occurrence of this event.
oneTimeProductNotification	OneTimeProductNotification (nullable)	When this parameter is present, it means the notification is related to a state change in a Non-Consumable Product Purchase. This parameter is mutually exclusive with `subscriptionNotification` and `voidedPurchaseNotification`.
subscriptionNotification	SubscriptionNotification (nullable)	When this parameter is present, it means the notification is related to a state change in a Subscription Purchase. This parameter is mutually exclusive with `oneTimeProductNotification` and `voidedPurchaseNotification`.
voidedPurchaseNotification	VoidedPurchaseNotification (nullable)	When this parameter is present, it means the notification is related to a Purchase that has been Voided. This parameter is mutually exclusive with `oneTimeProductNotification` and `subscriptionNotification`.

Check what is the possible payload that each of the notification types can produce.

Handling Notifications

When an event occurs, our service will send an HTTP POST request to the registered callback URL with the notification payload in JSON format.
Implement the following practices to handle these notifications effectively:

Respond with a 200 OK Status Code:
- Ensure your server responds to the notification with a 200 OK HTTP status code to confirm receipt.
- Include a message such as "Event received successfully" in the response body to acknowledge the event.
Example response:
```
{
  "message": "Event received successfully"
}
```

Best Practices for Handling Notifications

Respond Quickly: Respond to the notification endpoint with a 200 OK HTTP status code as an acknowledgment. This ensures that the notification was received successfully.
Error Handling: If your server is unavailable or returns an error, our service will retry the notification delivery multiple times with exponential back-off.

FAQ

How can I test my callback URL?

Use the Sandbox testing mechanism to make a Purchase and receive the event of that Purchase.

What happens if my server is down?

If your server is unavailable, our service will retry sending the notification several times using a back-off algorithm.