Using your own security or subscription system

It is a common requirement to integrate with an existing third party subscription system in order to allow existing users or subscribers to access paid for or restricted content. There are numerous examples of Pugpig powered apps that do this. 

If you are submitting your app to a store, always ensure you understand what commercial restrictions may be placed on your app. iTunes, for example, will NOT let you link to a subscription site to acquire new subscribers - you will only be able to let existing subscribers log in. Other ecosystems are more flexible and will allow links to your subscription store front.

Note: If you are thinking about offering digital and print bundles for the first time, ensure you understand tax or VAT implications. This is particularly true in the United Kingdom.

The Pugpig clients support two different models for access. If you use access based security, then active subscribers will get access to all issues, including all back issues. If you use issue based security, then existing users will only have access to certain issues. This might be single issues bought via your subscription systems, or the issues that were released only while the user was a subscriber.

If your app is allowing access via a combination of In App Purchases and your own subscription system it will query the authorisation providers in the order they were added. The first provider that claims to support the product will be used to complete the purchase. If none of them respond, the last provider added will be used. This is why we recommend adding specialized providers like iTunes single item purchases first (which allow for the purchase of a specific product) and general providers (like iTunes subscription purchases) last.

Note: At present, the Pugpig clients support only access based security using subscriptions from Apple, Google, Amazon, Windows and Blackberry. Issue based security for these stores is achievable via single issue in-app purchases.

Third Party Subscription System Technical Checklist

If you are planning to integrate your subscription system, there are a few questions you should answer before you start. Here is a suggested started point.

• If someone buys a subscription (or single issue) via the subscription store front, the API should immediately grant access to that user, at least for the current issue or an issue which might be released shortly afterwards. Users get upset if they buy something then do not have access to the content.
• Does the API hide any complexities around print only, digital only and bundle subscriptions. Ideally we want to be able to say “Does user X have access to Y” and not deal with any business rules around checking multiple entitlements based on internal structures.
• Is the API public facing so that devices (such as a tablet over 3G) could talk to it, or is it IP restricted?
• Are there any methods that shouldn’t be exposed to the world (in particular those that write to database)
• Can we use HTTPS to communicate with the system?
• What load can the API handle. As Newsstand apps generate large spikes of traffic, it is important to load test these spikes? We recommend using http://www.blitz.io/ or something similar.
• You need to ensure you can get a set of test users that cover all possible subscriber states.
• What is the charging model? If you’re paying based on number of requests to the system, that could affect the integration approach. If you’re paying per user or paying a fixed price, the integration approach will not affect your costs.

What is the service level agreement? Some systems are down for routine maintenance fairly often. In this case, we recommend the Pugpig Authentication Proxy approach and implementing a fail-open. This means that if the back end systems are down, the security will allow people access rather than presenting an error.

Getting the Sign In Form right

At some point in your application, your user will be presented with a form into which they enter details that identify them as an existing subscriber. It is enormously important that you create a form that users understand, and that can actually work technically. There is a balance between keeping it as simple as possible, while providing enough information so users get it correct. Remember to also consider this form on smaller screens such as the iPhone. There is less space, and you do not want form field to be obscured when the keyboard is visible.

Questions you should ask yourself include:

• Will the users know where to find the information they’re asking for?
• If a user has lost details, can they retrieve them via a self-service web site you have?
• Will all users have the details you’re asking for (for example print only and digital only subscribers)?
• Will the subscription system API actually allow a credentials check using the information you’re asking for?
• If you have a support line or email address, will they be able to test/troubleshoot problems that users might be having?
• If print subscribers need to read details from a print label, will there be confusion between characters that look very similar (O or 0 or I and l and 1 or example

There are three different approaches you can take for the integrations, which are outlined below. In all cases, the responses should NEVER be cached and it is the server's responsibility to ensure that the correct caching headers are returned to enforce this.

Implement the Pugpig Security API

The Pugpig Reader apps (from version 2.0 upwards) include an out of the box Authorisation Provider that supports the Pugpig Security API out of the box. If you choose to follow this approach, you will not need to change the reader apps as they already understand the API format. This is the recommended approach if you can modify the subscription system API.

See Third party subscriptions with KGPugpigAuthorisation

Implement a Pugpig Subscription Proxy

This is the recommended approach if you have an existing subscription system that has a mature API that you cannot change. The idea is that you create something that implements the Pugpig Security API, but simply forwards all requests to the existing system. The advantage of this approach is that the back end system and the Pugpig clients do not need to be changed. However, it will slightly increase the latency when doing a request as they all need to pass through the proxy before hitting the origin system. This approach is also good if a) the existing system is not designed to be public facing or b) the existing system is down for maintenance quite often, where you can “fail open”.

Customise your app to use your API

This approach involves changing your application by creating your own Authorisation Provider that communicates directly with your API. If you support multiple clients (for example Android, iOS, Windows and Web), we recommend the proxy approach over this approach as you’ll need to customise each of the apps separately.

See Writing a custom authorisation provider

Using multiple subscription systems

In some cases, you may need to check multiple systems when a user logs in. This may be because, for example, your different country subscribers use completely different systems. Or you may have two different instances of the same systems. If this is the case, there are three options:

• If you’re using the same supplier and they are using different instances, complain to your supplier. A modern subscription system should be able to make their back end implementation invisible from the API perspective
• Implement a Subscription Proxy that checks multiple back end systems making it invisible to the app
• Use multiple Authorisation Providers in the reader app, chained together. 

Expected Load On Subscription Systems

In an architecture that has a large number of users, considering the load on the server is always important. While the content can normally be cached, the subscription checks will always be dynamic so particular care should be taken when load testing these. This section gives you an idea of how much traffic will hit the subscription system. In order to convert this to real numbers, you will need to have an idea of the number of subscribers via that system AND the frequency of publishing editions.

• Sign In: This is usually called once per user, and normally when they log in. The highest usage for this method is normally when the app is first released, so many existing subscribers log in at the same time.
• Verify Subscription: This is called every time a user that has logged into the subscription system opens an app AND every time a background download is initiated for one of these users. Peak load for this call is after a new issue is published, particularly if you are initiating background downloads.
• Edition Credentials: This is called every time a user that has logged into the subscription system user explicitly downloads an edition OR every time a background download is initiated for one of these users for an edition they do not already have. Peak load for this call is after a new issue is published, particularly if you are initiating background downloads

It is important to remember that Newsstand downloads will happen to all logged in users, even if they are no longer active users of your app.

Known Issue: As of version 2.1 of the Pugpig Core Libraries, the apps will send both a verify subscription and an edition credentials request on a background/Newsstand download. As this is the peak time for server load, we are looking into a way to halve this and only call Edition Credentials.