We’re here to help

Integrating a Custom Entitlements Server

Follow

1. Prerequisites

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

  • An App Store kiosk app for iOS and/or Android.
  • An account and app on the Twixl Distribution 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 Publisher 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

Configuration

First of all, make sure you have done the necessary configuration in the Twixl Publisher builder app, and on the Twixl Distribution 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. 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 in the Build Settings under “App Store Kiosk - Entitlements”.

Entitlements Server URLs

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

http://<url>?do=signin_form&app_id=test

This will generate URLs in the following style:

http://<url>?do=<action>&param=value

 

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

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

This will generate URLs in the following style.

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

Important note:

While we do support the use of 'standard' http, for security reasons it is obviously recommended 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.4. signin_form

HTTP method: 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&region=uk">Select UK</a>

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

  • All form parameters should be passed as GET parameters
  • 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>

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.AvantGand)
  • app_version: the version number of the application (e.g. 1.0)
  • udid: the unique Twixl identifier of the device (e.g. 3efad737b4d845ffa6ddc4d484b279e9).

4.5. signin

HTTP method: POST

POST Parameters

  • 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)
  • 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"}

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

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

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

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')

4.7. 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.8. 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_indentifiers = json_decode($_POST['product_indentifiers']);

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"
}

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.

Was this article helpful?
0 out of 0 found this helpful

Comments

0 comments

Please sign in to leave a comment.