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:
- Applicable to Google Play only:
- 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.
JSON payload specifications
The JSON payload that is sent to the external store end point can include following fields:
|notification_type||String||Always||new, renew, cancel, pause, hold, resume||
|✝︎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
|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