2. Terminology

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

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

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

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:

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:

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: