Receiving In-App Purchase Notifications

In this topic, you will learn the requirements for implementing an endpoint to receive 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:

overview beacon in app purchase

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.

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).