Receiving In-App Purchase Notifications

Overview

It is necessary for the provider of the video content and/or merchandise to setup an endpoint so Brightcove Beacon can notify the provider that a purchase is completed. When an in-app purchase is made through a Brightcove Beacon app, the app communicates with one of the platform stores, like the Apple App Store, to complete the purchase. Defined endpoints will receive a notification of this transaction.

Let's look at an example that demonstrates the flow from purchase to notification. The fictional company, Acme Symphony, has implemented an endpoint. A viewer using a Brightcove Beacon app on iOS makes a purchase. Here is the high-level workflow:

A viewer purchases a subscription for access to videos of past symphonies, and tickets for the upcoming summer season of live concerts.
The Beacon app completes the purchase through the Apple App Store.
The Beacon app notifies Beacon of the purchase.
The Beacon entitlement subsystem grants the viewer access to all video assets in the purchased subscription.
A notification is sent to Acme Symphony's endpoint.
Acme Symphony knows of the purchase and is able to trigger additional workflows like sending tickets to the purchaser.

The rest of the document clarifies the technical implementation and provides specifics for implementing your endpoint.

How notifications are implemented

Here is a high-level diagram of the process:

Clarification details for the diagram:

Amazon Simple Notification Service (Amazon SNS) is a managed service that provides message delivery from publishers to subscribers. For full details see Amazon's SNS Developer Guide.
After the notification is received by you, the Brightcove Beacon customer, the actions will vary. In the example, since tickets were purchased, the tickets would need to be sent. So once the notification is received, your business rules will determine what must occur.
The endpoint implementation approach is entirely your decision. The decision will most likely be guided by backend technologies used and skills of your software engineers.
The dashed line from the platform stores directly to the Brightcove Beacon backend is for other notifications, like renewals.

Notification usage guidelines

The following specify usage guidelines for notifications:

Notifications of in-app purchases from following stores is supported:
- Apple App Store (iOS and AppleTV)
- Google Play (Android and Android TV)
- Roku Channel Store
- Amazon Appstore (FireTV)
- Stripe (Web and Samsung TV)
Beacon will report all purchase related events, including the following actions on subscriptions:
- New
- Renewal
- Cancellation
- Applicable to Google Play only:
  - Pause
  - Hold
  - Resume
Enough information is provided in the notification so the external store is able to apply entitlements and/or prevent purchases of the same asset (subscription) if already purchased through Beacon or native stores.
Purchase events are delivered to external stores after receiving notification from source stores. This typically happens in under 5 minutes (usually within seconds).

API endpoint specifications

After successfully processing a subscription in the Beacon system, Beacon will deliver an SNS topic message to a configured API endpoint specific for a particular customer.

Following are the requirements for the external end point:

The API endpoint must be compatible with AWS SNS integration. See Amazon's Fanout to HTTP/S endpoints document for more details. This document contains a link to an implementation of an endpoint that processes Amazon SNS HTTP POST requests, written as a Java servlet.
The API endpoint must be open to range of IP addresses used by AWS - see AWS IP address ranges.
The API endpoint will go through a subscription confirmation step. See Amazon's Confirm the subscription document for more details.
The API endpoint will need to unescape the JSON in the message field of the notification. See Amazon's Parsing message formats document for more details.
The API endpoint must verify the signature and provenance of the message. See Amazon's Verifying the signatures of Amazon SNS messages document for more details.

To be able to recover from errors, it is possible to re-send all purchases for a user (filtering any non active notifications). The store's external API endpoint is responsible for re-processing all messages, even if those were previously consumed.

Notes:

It is possible to generate an infinite loop of notifications. For instance, Beacon sends the IAP notification to the end point, the receiver creates a user and sends a create entitlement message to Beacon, which in turn sends an IAP notification to the receiver, and an infinite loop is started. When implementing your endpoint you must be sure not to allow this to happen.
SNS queues do not have a retention period. We have a 3x 20s retry policy and then the message is moved to a dead letter queue. The dead-letter queue has a retention period of 14 days. However, the customer can force the sync either via beacon admin UI or via the API.
Brightcove can provide a file you can use to force the sync for all users, or you can use the API directly.

JSON payload specifications

The JSON payload that is sent to the external store end point can include following fields:

Name	Type	Required	Possible Values	Notes
notification_type	String	Always	new, renew, cancel, pause, hold, resume	new - Issued for a new subscription renew - Used to renew an existing subscription (extend the subscription^✝︎) cancel - Cancel an existing purchase hold - Subscription was put on hold due to non payment pause - Subscription is paused by user resume - Subscription transition from hold or pause to continue
^✝︎This is not always true for Apple. Apple uses renew to indicate a cancellation of future renewal. Apple also uses a cancel to indicate and immediate cancellation of the subscription. See Apple's notification_type documentation for full details.
external_user_id	String	Always		This is the id that is commonly used by Beacon and the external store to identify the user
transaction_id	String	Always		Unique identifier for the transaction. When a cancellation is done, this ID should be used to cancel the subscription or individual purchase. When a subscription is renewed, resumed, paused or put on hold, this ID is used to find the specific subscription that is affected.
start_date	integer	Yes with the exception of cancellation notifications		The date when the purchase is in effect and entitlements to user should start
end_date	integer	Required for these notification types: new, renew, cancel and resume		The date when the purchase is no longer in effect and entitlements to the user should end. For cancellation requests, the `end_date` defines when the user loses access to the content.
original_store	String	Always	Apple Store, Google Play, Amazon Store, Stripe, Roku Store, Evergent, Beacon Store	The original store where the purchase was done
sku	String	Always		Identifies the item that was purchased. This is the identifier used in the source store.
package_name	String	Always		The name of the SVOD or TVOD package in Brightcove Beacon
notification_date	integer	Always		Timestamp of dispatching the event from Beacon to the external store system
cancellation_date	integer	Required when notification type is cancel		Used for a cancel request and specifies the Timestamp of when the user/store cancelled the subscription
trial_end_date	integer	Optional (applicable only to new subscriptions)		If present, means that there is a trial. For new subscriptions it is possible that a trial end date is same as `end_date` (use case where stores sends one notification for trial and a second one for when the real subscription starts).