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

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

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.

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

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.