mag+ Subscription API - Adding Custom Access Control and Entitlements to Apps

mag+ access control and entitlements is a feature available to all mag+ apps through the Subscription API. When activated, it adds a login window to your app which can be used to authenticate subscribers or to gate content so that only specified users see it.

The login window connects to your user database or fulfillment system so you can authenticate users. The Subscription API allows you to return a list of mag+ Issues to the app and make them available for download to the logged in user. You can do integration, testing and launch with no further mag+ intervention.

This is a live feature, which means that you do not need to build and submit a new version of your app in order to use it.

Some use cases enabled by the mag+ Subscription API include:

  • Gate content for employees or clients so that they can only see particular documents
  • Let end users enter a code to unlock additional content
  • Let employees select a department to receive only the content appropriate for them
  • Sell a subscription from your own web site and have users log in via the app to retrieve that subscription
  • Entitle print subscribers to authenticate and get access to digital editions
  • Set content to expire and delete from a device at a preset time
  • Maintain control over login to your content and the authentication parameters

Architecture Overview

Components are divided so that the app publisher handles user management and entitlements, and the mag+ system handles fulfillment.

 The system components involved are:

  • Your branded mag+ app
  • The app publisher's "My Account" webview (this is the login window embedded in your app)
  • The mag+ Backend system
  • The app publisher's User Database or Fulfillment System
  • (optional) The app publisher's Web Storefront

In the "My Account" webview, the end user logs in to your authentication system through a webview you provide. This means the login is under your control and can be branded with your look and feel and consist of any criteria you choose.

Note: The webview is completely tied to your system. There is no mag+ login for end users.

Once the user is logged in, your User Database is queried for entitlements available to that user, i.e. a list of mag+ Issues the user has access to.

The image below illustrates the flow of information between the systems:

  1. Your mag+ app opens your embedded webview
  2. The webview queries your User Database
  3. The User Database returns a message to the webview
  4. The webview hands control back to your mag+ app
  5. Your mag+ app queries the mag+ Backend system
  6. The mag+ Backend system queries the User Database for available entitlements for the user
  7. The User Database returns what content should be served to the user
  8. The mag+ Backend system returns a list of available content to your mag+ app
Architecture Overview

What You Need to Provide

Embedded "My Account" webview

The "My Account" webview needs to be designed and implemented by your company according to technical requirements described in the mag+ Subscription API Integration Guide—you can contact support or your sales rep to receive this guide, but it is also available in the Subscription API area of the mag+ Publish portal. The webview can contain features like registration, login, forgotten password, my account page, and logout.

Note: When used with iOS, the Apple Review Guidelines prohibit linking to an external storefront from this view.

mag+ Backend API implementation

Your system needs to be able to receive and respond to API calls from your branded mag+ app. Refer to the mag+ Subscription API Integration Guide for details.

User/Entitlements database

You need a solution for end user account and entitlements management. If you do not have your own system, you can use a mag+ affiliate service called Appthenticate.

Note: mag+ cannot troubleshoot or support your custom server-side integration. If you are unable to configure your system to work with the mag+ Subscription API, we recommend using the Appthenticate service. 

Appthenticate: If you don't have an existing user/entitlement database or fulfillment system, you can use a mag+ affiliate service called Appthenticate (formerly Subs+). The service is a turnkey way to enable access control in your app. It provides a pre-built and customizable login window as well as a web-based backend for managing users and entitlements. You can manually enter users or upload a spreadsheet with hundreds or thousands of users. The service is managed by a mag+ partner and is an add-on to your standard license. To learn more, contact your mag+ sales rep or support. 

Error handling

In the following situations, the "My Account" button and webview will be disabled:

  • If an end user goes offline by not being connected to a network
  • If the URL defined in the mag+ Publish portal > Admin > Subscription API is incorrect
  • If the app publisher's User Database is offline
Note: End users who go offline will not lose existing entitlements they have downloaded, but they will not get new ones.

Features of the mag+ Subscription API

  • Expiring issues: In addition to granting access to mag+ Issues, the API provides a way for you to return an expiration date on a given entitlement. When a mag+ Issue expires, it is deleted from the end user's device and the entitlement is revoked, even if the user is offline at the time of expiration. You can modify or delete previously provided expiration dates.
  • Hidden Issues: The API allows you to mark specific mag+ Issues as only being available to users who are logged in to your system. These Issues will not appear in a subscription or available to purchase to users who are not logged in. To only display specific Issues to your logged-in users, mark the Issue in the mag+ Publish portal as "Entitled through Subscription API" in Issue Detail > Payment > Entitlement Category.
  • mag+ Publish portal reporting: An optional endpoint can alert your system whenever a new mag+ Issue is published in the mag+ Publish portal so that you may update your entitlements database automatically.
  • Download reporting: Another optional endpoint can alert your system whenever an end user successfully completes a download.
  • Promotional messaging:You can attach a popup message for end users with Yes/No action buttons. This popup is returned as part of the entitlement reply event and can alert the end user if, for example, their subscription has run out or to entice the end user to create an account.

How to Integrate the mag+ Subscription API

The mag+ Subscription API is configured in the mag+ Publish portal > Admin tab.

Note: You must contact your sales rep or mag+ support to activate the Subscription API feature in the Admin tab. Once activated, you can access the menu in the mag+ Publish portal and gain access to the technical specification (see image below). If your fulfillment provider is CDS, please inform your sales rep, as there are unique settings that apply to you. If you are not a CDS customer, you can ignore those fields in the Subscription API settings.
How to Integrate the Mag+ Subscription API

1. Contact your sales rep or mag+ support to activate the Subscription API feature in the mag+ Publish portal.

2. Build the API endpoints in your system and in your "My Account" webview.

3. Enter your API endpoints and "My Account" URL in the mag+ Publish portal > Admin > Subscription API screen.

Enter your API endpoints and "My Account" URL in the Mag+ Publish portal > Admin > Subscription API screen.

4. Test your API endpoints with the mag+ Lint Test.

Test your API endpoints with the Mag+ Lint Test.

You can access the Lint Test in the mag+ Publish portal under the Subscription API header.

5. Test your integration with Subscription API test devices.

Test your integration with Subscription API test devices.
Note: Enabling "Test devices only" will disable the standard mag+ functionality of Test Devices and enable the Subscription API for these devices. Test Devices are set in the mag+ Publish portal > Devices tab. Subscription API Test Devices will no longer have access to all published mag+ Issues and instead be routed through the Subscription API system.

6. When satisfied with testing, enable the Subscription API for all devices.

When satisfied with testing, enable the Subscription API for all devices.

7. Build and distribute your app.

Note: You do not need to contact mag+ to make your custom Subscription API integration live.


Article is closed for comments.
Powered by Zendesk