Login

Learning & Support

Documentation

Integrating a Custom Entitlements Server

Twixl Support Team Updated: - Created :

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

    ABOUT THE API INFORMATION:

    This documentation is only available for Twixl subscriptions with an Entitlements Pack. For  more info about our Packs, see our Specs & Pricing.

    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.

    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:

    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: 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.6. 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.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>

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

    4.10. force re-login of the user

    When the /entitlements call returns a token __token_expired__, it will force the app to clear the token, thus requiring the user to login again.

    Note that this feature requires the Twixl app to be built with version 15+.

    Was this article helpful?

    0 out of 0 found this helpful