Using the Entitlements option
What are entitlements?
Entitlements are a way to allow an external system to determine which content a specific user can have access to. In the world of magazines, this is most frequently used to allow print subscribers to automatically access the digital editions.
However, the entitlements solution in Twixl Publisher is flexible enough to implement use cases that go further than just allowing print subscribers to have access to the contents.
Here are some other examples of what is possible:
- Allow a user to register to access extra content
- After a user has registered, allow him to receive content specifically for him
- Allow a user to select a region when the app opens and get only the content for that specific region
- Require a user to enter a license key before he can access the content
- Require a user to accept a license agreement before he can access the content
- Define users and groups with access privileges for easy in-house distribution
Entitlements influence the list of issues that a user can see, download or purchase in the kiosk. It does not have an influence on the actual content of an issue itself.
Prerequisites
To use entitlements in your application, you will need:
- An App Store kiosk app (on iOS and/or Android)
- An account and an app on the Twixl Distribution Platform
How entitlements work
When you create an application that supports entitlements, there are several steps in the process to get this working.
Build settings in the Twixl Publisher OS X app
Enable entitlements in your app build. This is configured in the build settings under "App Store Kiosk - Entitlements". You will need to enter the following parameters:
- Entitlements URL: you'll find this in the Entitlements configuration window on the Twixl Distribution Platform
- Entitlements URL style: defines how the urls for the Entitlements Server are constructed. For more information, see Entitlements Server URLs.
- Require on startup: if enabled, you will need to be entitled before you can access the content in the app. In other words, this allows you to create a "restricted access" app.
- Toolbar Button Title: if you want a button to appear in the toolbar of the App Store Kiosk that can trigger the entitlements signin form, you can enter the title for the button here, e.g. "Already a subscriber?".
- You will also need to specify an info cell in the "App Store Kiosk - User Interface". More information on how to integrate this is available in our article "Customizing the App Store kiosk apps".
- The web page displayed in the info cell should contain a special hyperlink that triggers the entitlements signin form, or alternatively you could directly trigger the registration from the page:
tp-entitlements-signin://self
or
tp-entitlements-register://self
Twixl Distribution Platform Configuration
- Print Subscribers (for providing print subscribers free access to digital content - users can still see and purchase the different issues and also purchase a subscription through the App Store)
- User name & password (for a restriced access app, i.e. without a user name and password, users will not be able to access any content)
- Users & Groups: define access to your publications based on group access privileges - users belong to a group, publications can be visible in on or more groups.
- Access Key (can be used for providing extra content to anyone with a valid access key)
- Sections (allows you to have content for e.g. multiple languages, regions in a single app, but by requiring the users to select a language/region... they will only see the content relevant for them)
- Promo Code: allows readers to redeem a promo code and get an issue for free that normally needs to be purchased
- Custom Entitlements Server (connect via a web service to an external database - technical documentation available here)
Then, you can enter user details manually or use the Twixl Distribution Platform Admin API to automatically add, remove or update entitlement info.
Print Subscriber example
When users open the app, they will see a screen that looks like the one above.
When the user then taps the "Login As Print Subscriber" link, this will trigger the special url "tp-entitlements-signin://self", open up a modal dialog and show the output of the "signin_form" API call of the entitlements server.
Note that the user needs to be online for this to work.
In this example, a form is displayed that can be used for login/password authentication, but it's up to the publisher to decide which types of information are requested from the user.
Sign in Form
What is important is that the form submits its parameters using a GET request and that it includes the hidden form parameter called "do" which should be set to "signin". This is required so that the application can catch this and add extra parameters to this action.
<form method="GET"> <input type="hidden" name="do" value="signin" /> <input type="text" name="email" /> <input type="password" name="password" /> </form>
You can also use a hyperlink to do trigger the signin. You can specify the link as follows:
<a href="?do=signin®ion=UK">Select UK</a>
Submit form
When the user then submits the form or taps the link, the application will catch the "signin" request and will add the following extra parameters:
- app_id: the unique application identifier of the app (e.g. com.twixlmedia.myMagazine)
- app_version: the version number of the application (e.g. 1.0)
- udid: the unique Twixl identifier of the device (e.g. 3efad737b4d845ffa6ddc4d514b279e9).
Using these parameters, a POST request will be sent to the signin action on the Entitlements Server to verify the data. The signin action should return a JSON dictionary with one key in there called "token". This will be used in all subsequent calls to identify the user or device.
{"token": "248335453156"}
If something goes wrong or when e.g. the user is not known, an error should be returned. The output should be:
{"error": "Unknown subscriber."}
Sign in succeeded/error
Depending on the result of the signin action, the app will present a new web page, using either the "signin_succeeded" or "signin_error" action on the Entitlements Server. Both actions will receive an extra parameter in the query string:
signin_succeeded: token
This can be used to show e.g. the subscriber details.
signin_error: error
This can be used to show an error message to the user explaining why the signin failed.
If you don't want to show anything and just close the popup window or provide the user with a button to do so, you can use the following special link:
tp-close://self
Product Identifiers
Every time the application now reloads the contents of the store or when someone wants to purchase an issue, the Twixl Distribution Platform will perform the "entitlements" API call on the Entitlements Server. It will check which product_identifiers a user is entitled for and will allow free access to these issues if so.
Custom Entitlements Server
If you prefer to use your own entitlements server instead of using the built-in options, then refer to our separate article.