Integrating a Custom Entitlements Server

For some customers, the built-in entitlement scenario’s don’t always offer exactly what they are looking for… others require a connection to an external data source. In those cases, a custom entitlement server can be an alternative.

The implementation and deployment of a custom entitlement server is something that can be offered by Twixl or by Twixl’s solution partners, and is based on the technical information below.

If you are looking for the Twixl dev team to implement a custom entitlement server, then please provide us a much details as possible about the project via this form.

1. Prerequisites

To use a Custom Entitlements Server in your app, you will need:

An App Store app for iOS and/or Android.
An account and app on the Twixl platform.
An external web application that implements the Entitlements API.

2. Terminology

There is some specific terminology you need to be familiar with before using entitlements:

Entitlements Server: the external web application that implementes the Entitlements API.
Token: a unique identifier for the user on the entitlements server. This can e.g. be a print subscriber number, a region, ... This token will be used to verify which content a user has access to.
Device UDID: in a Twixl app, a device is identified by a unique identifier that stays the same, even when you reinstall the application on the same device. This can be used to track a specific device. Note that this information remains completely anonymous.

3. Configuration

First of all, make sure you have done the necessary configuration on the Twixl platform, as described in the Entitlements documentation.

4. API

4.1. Sample implementations

You can download example implementations of an Entitlements Server SDK in the following server-side programming languages:

ASP.NET
Java
PHP

4.2. Syntax and payload

More info about the syntax and the payload can be found in the API documentation on the Twixl platform.

4.3. Entitlements Server URLs

Depending on the server side implementation of the Entitlements Server, there are two different ways the URLS can be constructed. This can be configured on the Twixl platform!

4.4. URL Styles

The first style is passing the action in the query string parameter called “do”. This can be done by selecting the following url style in the build settings.

https://<url>?do=signin_form&amp;app_id=test</url>

Click to copy

This will generate URLs in the following style:

https://<url>?do=<action>&amp;param=value</action></url>

Click to copy

If you prefer the action to be a part of the url itself, you can choose the following url style in the build settings:

https://<url>/signin_form?app_id=test</url>

Click to copy

This will generate URLs in the following style.

https://<url>/<action>?param=value</action></url>

Click to copy

IMPORTANT NOTE:

For security reasons it is obviously a requirement to use the https protocol for your connections. Note that this requires that you have a secure SSL certificate installed on your web server.

4.5. signin_form

HTTP method: GET / POST
POST Parameters: None
Description: This API call shows the signin page. Using this page, you can e.g. ask users for their print subscribers credentials or allow them to choose e.g. a region from a list of regions. When you use a link to trigger the signin action, you can specify the link as follows:

<a href="?do=signin&amp;region=uk">Select UK</a>

Click to copy

When you use a form, there are a few things you need to take into account:

If the signin_form is fetched by the browser client it should contain method POST, otherwise it should use GET. The reason for this is that the mobile apps need to 'hijack' the signin call (and they will convert it to POST) but the browser client needs to send the credentials by POST to make it secure.
The browser client will fetch the signin_form with a ref=browserclient parameter. Check for this parameter to return a form with a POST method.
The form should call the action signin (using a hidden form field).

The example HTML code for a form can be:

<form method="GET">
    <input type="hidden" name="do" value="signin">
    <input type="text" name="email">
    <input type="password" name="password">
</form>

Click to copy

When the user clicks the link or submit the form, the application will intercept the URL and parse the query string. It will then add the following parameters to the dictionary of keys and values:

app_id: the unique application identifier of the app (e.g. com.twixlmedia.myfancyapp)
app_version: the version number of the application (e.g. 1.0)
udid: the unique Twixl identifier of the device (e.g. 3efad737b4d845ffa6ddc4d484b279e9).

HTTP method: POST
POST Parameters:
- app_id: the unique application identifier of the app (e.g. com.twixlmedia.myfancyapp)
- app_version: the version number of the application (e.g. 1.0)
- udid: the unique Twixl identifier of the device (e.g. 3efad737b4d845ffa6ddc4d514b279e9).
- all parameters from the signin_form action.
Description:
- This is the call that will check if the user is entitled or not. If the user is entitled, it should generate a so-called “entitlement token”. This is a unique ID identifying the user and will be used by Twixl Publisher to identify the user for all other entitlement requests.
- The signin call should always return JSON data. There are two results that are possible, depending on the result.
- If the user is entitled, the following JSON structure should be returned:

{"token": "the entitlement token"}

Click to copy

If the entitlement fails, the following JSON structure should be returned:

{"error": "a message explaining why the user is not entitled"}

Click to copy

4.7. signin_succeeded

HTTP method: POST
POST Parameters:
- token: The token that was returned in the signin action.
Description: This is the view that is shown when the signin returned a valid token (which means that the user is entitled). You can either show an HTML page with more details based on the token passed as a query string parameter. If you want to provide a link that allows the user to close the popup window, you need to use the following URL:

<a href="tp-close://self">Close Me</a>

Click to copy

If you want to automatically close the popup when the signin succeeds, you can also perform an HTTP redirect to the tp-close URL:

header('Location: tp-close://self')

Click to copy

4.8. signin_error

HTTP method: POST
POST Parameters:
- error: The error that was returned in the signin action.
Description: This action is executed when the signin action returns an error message. This can be used to e.g. indicate that the user is not known or not entitled. The actual error message will be passed as a query string parameter.

4.9. entitlements

HTTP method: POST
POST Parameters:
- requested_identifier: the product identifier of the requested issue (will only be filled in when the user does a purchase. It will be empty when the user requests the contents of the kiosk).
- app_issues: the list of issues defined for the app encoded as a json string
- app_id: the unique application identifier of the app (e.g. com.twixlmedia.AvantGand)
- app_version: the version number of the application (e.g. 1.0)
- token: the token that was returned in the signin action
- product_identifiers: a json string containing the list of product identifiers the application is about to show.
Description: This action is called every time the application wants to show the list of issues or when a user tries to purchase an issue. The post request will contain a parameter called “product_identifiers” which is a JSON string containing the list of product identifiers the application is about to show. To convert these to a real list, you need to parse the JSON string. In PHP, this can be done using the json_decode function:

$product_identifiers = json_decode($_POST['product_identifiers']);

Click to copy

The result of the entitlements call should be a JSON structure with the following content:

{
    "token":"my-entitlement-token",
    "entitled_products":
        [
            "com.myapp.product1",
            "com.myapp.product2"
        ],
    "mode":"hide_unentitled"
}

Click to copy

The parameter entitled_products should contain the list of issue identifiers to which the user is entitled.

The parameter mode defines how the Twixl Distribution Platform will interpret the results:

purchase_unentitled: make all the products to which you are entitled free if you didn’t get them for free yet
hide_unentitled: hides all the items to which you are not entitled from the app

In this call, you should also make sure you properly handle the case where the "token" is empty. This basically means that the user is not entitled.

Help

Documentation

1. Prerequisites

2. Terminology

3. Configuration

4. API

4.1. Sample implementations

4.2. Syntax and payload

4.3. Entitlements Server URLs

4.4. URL Styles

4.5. signin_form

4.7. signin_succeeded

4.8. signin_error

4.9. entitlements

Sign in

Don’t have an account yet?

Help

Documentation