Integration requirements

Before you begin your integration, download the Integration Steps and QA Checklist, which is useful to have on hand as you plan your Subscribe with Google integration project. The checklist comes with a detailed breakdown of all the SwG components and tasks to reference throughout your SwG integration process.

Overview

The SwG integration process consists of the following components, each a SwG system requirement. In certain scenarios, a publisher might not need to use a particular component. Such cases are detailed in the component description.

  1. Google Play developer account: The publisher must create a Google Play developer account, upload an application, and enable the application for billing. The publisher must publish the application in production, or use an existing production application.
  2. Publication Configuration: Publisher must work with Google technical solutions representatives to set up certain points of configuration. These items include urls for required API endpoints, logo/branding assets, SKU details, privacy policy URL, and such other pieces of information that Google requires to set up the integration. This configuration must be done per integrated publication.
  3. Page markup: Publisher must add structured data to all article pages. This data comprises a publication id (corresponding to the id in the Publication Configuration) and an entitlement label. These data must be on all article pages, including AMP documents.
  4. SwG.js client integration: Publisher must integrate the Google javascript client into their publication website. The Publisher must include swg.js client library on all article pages where a paywall may be triggered, including articles that are part of a server-side paywall implementation, and must call the SwG.js getEntitlements function and handle the response from that function appropriately.

    To the extent that the publisher creates AMP versions of its pages and these AMP pages potentially trigger paywalls, the AMP pages must be configured for AMP-subscriptions-google, so that SwG user entitlements will be respected.

  5. Google News: If the publisher gates access to content it presents in the Google News product, it must update its Google News configuration to make it SwG-compatible, meaning that the SKUs it sells there will work on its O&O products and that subscriptions it may sell elsewhere--either via its own purchase flow or via a SwG purchase flow--can be recognized and honored on Google News. To the extent that the publisher wishes to use AMP documents in the context of Google News, it must configure these documents to use AMP-subscriptions-google so that user entitlements will be recognized properly.

  6. Android integration: To the extent that the publisher is selling divergent sets of SKU on Android vs web, or in the case that the publisher has multiple apps for the same publication, the publisher must update its Android applications to check for the subscription purchase, and also call the Subscribe with Google Publication API and grant access appropriately.
  7. Google Sign-in: The Publisher must include a Google Sign-in option on all login pages for web, iOS applications, and Android Applications.

    This Google Sign-in implementation must check the Subscribe with Google Publication API to ensure that if the Google Account has a linked entitlement with the publisher already, the account is associated with the user’s existing account at the publisher’s site. On the Publisher’s website, If the Subscribe with Google Publication API indicates that the user has an entitlement the Publisher is unaware of, the Publisher will appropriately grant access for known users, and launch a Deferred Account Creation Flow if the user is unknown.

    If a publisher web or mobile application product provides an entirely free experience and does not gate access with a paywall, Google Sign-in is not required. Additionally, in the unusual case where a publisher does not maintain a user management system (i.e., the publisher relies completely on Subscribe with Google for managing user transactions), no Google Sign-in integration is necessary (or possible).

  8. Post Purchase Account Creation Handler: Publishers must create accounts for users following a purchase.

    On the web, a publisher must be able to pass back swg.js subscription events and entitlement data to the Publisher infrastructure. For purchases made on Google News and via Android in-app-billing, the publisher must make use of the Deferred Account Creation flow on their website via swg.js when those users visit.

    For AMP purchases, if a publisher is implementing a buy flow on AMP, the publisher must subscribe to Play Cloud Pub/Sub events within the Publisher infrastructure.

    The Publisher must use the purchase data from subscription events to request user profile and subscription data from Google’s Subscription Status API. Subsequent to getting that data, the Account Management API must either:

    1. Create an account with the user profile information provided by Google and associate the subscription with that account, or
    2. Append the Google user profile and subscription data to an existing user account at the Publisher’s site.

    In the circumstance where a publisher does not maintain a user management system (i.e., the publisher relies completely on Subscribe with Google for managing user transactions), no post-purchase Account Creation would be necessary (or possible).

  9. OAuth account link page: The Publisher must create an OAuth login page to facilitate the following process:

    1. authentication of Publisher’s existing users
    2. checking of user entitlements,
    3. Creation of a user access token
    4. Redirecting and passing the access token back to the referring page

    In the circumstance where a publisher does not maintain a user management system (i.e., the publisher relies completely on Subscribe with Google for managing user transactions), no OAuth account link page would be necessary (or possible).

  10. Entitlements API: The Publisher must create an entitlements API that accepts an access token create via the Publishers OAuth account link flow, and responds with a user’s entitlements. These entitlements are represented as a set of labels to which the user has access and, optionally, a text descriptor of the product the user purchased.

    In the circumstance where a publisher does not maintain a user management system (i.e., the publisher relies completely on Subscribe with Google for managing user transactions), no Entitlements API would be necessary (or possible).

  11. Auto-login Prompt: If the Google Entitlements API returns a user entitlement that is known to the publisher, but the user is not currently logged in to publisher systems, we strongly encourage the publisher to automatically log the user in to the account on the publisher site. The publisher may use the swg.js Auto-Login functions to alert the user to this event or to prompt the user to consent to the log-in action before performing it.
  12. iOS Integration: If the publisher has paywalled content associated with a Subscribe with Google SKU in an iOS app, following the use of Google Sign-in, the publisher must check their backend for entitlements, and if none found, call the Subscribe with Google Publication API to check for entitlements, and grant access if any are found.
  13. Save Subscriptions: At the end of any purchase flows not going through Subscribe with Google, the publisher must integrate Save Subscription functionality to allow users the option of linking to their Google account.