Contact Support | System Status
Page Contents

    Receiving In-App Purchase Notifications

    In this topic, you will learn the requirements for implementing an endpoint to receive in-app purchase notifications.

    Overview

    Consider when an in-app purchase is done through a Brightcove Beacon app. The app communicates with one of the platform stores, like the Apple App Store, to complete the purchase. By default the supplier of the video content (and possibly other merchandise) purchased is not notified. It is necessary for the provider of the video content and/or merchandise to setup an endpoint so Brightcove Beacon can notify the provider a purchase was completed.

    For clarification, this example demonstrates the flow of the purchase to notification. The fictional company, Acme Symphony. has implemented an endpoint. A viewer using a Brightcove Beacon app on iOS makes a purchase. A high-level take on the workflow is as follows:

    • 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 sends tickets to the purchaser, and subscription purchase is reflected in Acme Symphony's store front.

    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 user, 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.

    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
      • Renewals
      • Cancellations
      • Pauses
      • Holds
      • Resumes
    • Enough information is provided in the notification so the seller's external system 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 within 5 min after receiving notification from source stores.

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

    Page last updated on 23 Sep 2021