Combining entitlements with the info cell of a kiosk app

Pieter Claerhout 29-04-2014 How-To

We often get the request from customers to combine entitlements with the info cell in a multi-issue app. Today, we are going to show you an example of how you can use entitlements data in your info cell.

The basic idea is that we want to be able to show 3 different info cells, based on different criteria:
  • One view if the user is offline (has no network access)
  • One view if the user is online and not entitled
  • One view if the user is online and entitled
To get this working, we need to do this in different steps. Let's go over them one by one.

Step 1 - Enable entitlements in the build settings

The first step is that we need to enable entitlements in our build settings. To do so, open the Twixl Publisher mac app, go to the build settings and select the panel called "App Store Kiosk - Entitlements". You will be presented with the following screen: Entitlements in the build settings In this example, we did not enter a "Toolbar button title" as we will use the info cell for this instead.

Step 2 - Add the infoCell.html file

Once we have configured the entitlements url and settings, we will also add a custom html file with the info cell. To do this, in the build settings, you select the panel called "App Store Kiosk - User Interface". Then click on the button "Show WebResources" at the bottom which will take you to the folder containing the web resources for our build setting. WebResources in the buld settings In this folder, we need to create a file called "infoCell.html" (case-sensitive). You can download the sample files from here. Place the 3 files in the WebResources folder.

Also change the option "Info cell height" to 150 px in the build settings. This will create an area with a height of 150 px in which the info cell will be shown.

Step 3 - Run the application

The next step is to create an app and run it on our device. You can create an iPad development or ad-hoc build or a Android test build. Install the app on the device and run it.

The first time you run the app, you should see a screen that is similar to: iOS-Simulator-Screen-shot-29-Apr-2014-11_06_49 As you are not entitled the first time you install the app, you will see that the info cell shows a message that you don't have an entitlement token and offers you the option to login. We are using the entitlement scenario of print subscribers.

When you hit the login button, it will trigger the entitlements signin form which allows you to sign in. iOS-Simulator-Screen-shot-29-Apr-2014-11_07_03 Enter your print subscriber credentials and login. The reader app will now refresh the kiosk interface after you are logged in and will also reload the info cell. At that point, the info cell will show you that you are entitled, it will also show the entitlement token and allow you to log out.

iOS-Simulator-Screen-shot-29-Apr-2014-11_07_08 If you don't have a network connection, the info cell will show that you are offline.

Step 4 - How does this work?

To understand how this works, you first need to understand the concept of an "entitlement token". We you sign in using entitlements, the entitlements server will return you a unique token identifying your entitlement. This token is used to communicate with the entitlements server to find out what you are entitled to. This token is called the "entitlement token".

The info cell gets a reference to this token via the url using a parameter called "token". This means that the info cell is loaded using the following url:

file://WebResources/infoCell.html?token=my-entitlements-token
This is the information we can use to find out if you are entitled or not.

If we look at the code in the infoCell.html file, the following script contains the core logic;

We first use the property called "navigator.onLine" to figure out if the user has a network connection or not. If the user has a network connection, we use the TMParameter.get function (which is a custom function created by Twixl media) to extract the entitlement token from the url. If we have a token, we can show the div with the id "online-entitled", otherwise, we show the div with the id "online-not-entitled".

In these divs, we are using some special Twixl Publisher links to trigger actions in the app:

log in
This triggers the entitlements signin form. To log out, we can use the following code:

log out
Logging out basically means that we are clearing the entitlements token.

If your entitlements server also supports the register option, you can use the following link to trigger the register form

log out
As you can see, with a little bit of JavaScript knowledge, you can make great combinations between entitlements and the info cell.

Download sample files

You can download the sample files for this from:

InfoCellAndEntitlemens_2014-04-29

As always, contact support in you need help.

Tweet this article: Combining entitlements with the info cell of a kiosk app

Share this post to your network.

Download the free trial of Twixl Publisher

Start using Twixl Publisher immediately, preview the result on your own device, share your creations with a colleague or client, get started!
Need any help? Visit our documentation site.

Download the trial Check out the documentation today

× Free trial/download