Integrating entitlements in a kiosk infoCell
This article will show you an example of how you can use entitlements data in the info cell of your App Store kiosk app.
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
Below are the different steps to get this working.
1. Enable entitlements in the build settings
The first step is to enable entitlements in the build settings of your app.
Open the Twixl Publisher application, go to the build settings and select the section called "App Store Kiosk - Entitlements". You will be presented with the screen below - in this example, we did not enter a "Toolbar button title" as we will use the info cell for that purpose instead.
2. Add the infoCell.html file
Once you have configured the Entitlements URL, you will need to add a custom html file for the info cell. To do this, select the "App Store Kiosk - User Interface" panel in the build settings, then click "Show WebResources" at the bottom. This will take you to the folder containing the web resources for that build setting.
In this folder, create a file called "infoCell.html" (case-sensitive). You can also download a sample (place the 3 files in the WebResources folder).
Also make sure to set the "Info cell height" to e.g. 150 px in the build settings. This will create an area with a height of 150 px in which the info cell will be displayed.
3. Run the app
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 the one below:
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 to login. We are using the entitlement scenario of "print subscribers" in this case.
When you hit the login button, it will trigger the entitlements signin form that allows you to sign in.
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.
If you don't have a network connection, the info cell will show that you are offline.
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:
<script type="text/javascript" charset="utf-8">
// Hide all the blocks
$('.block').hide();
$('#token').html('no token');
// Check if the user has a network connection
if (navigator.onLine) {
// Get the token from the url parameters
var token = TMParameter.get('token');
// Check if we have a token
if (token && token != '') {
// Show the token
$('#token').html(token);
// We have token, user is entitled
$('#online-entitled').show();
} else {
// We don't have a token, user is not entitled
$('#online-not-entitled').show();
}
} else {
// User is offline, show the offline message
$('#offline').show();
}
</script>
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:
<a href="tp-entitlements-signin://self">log in</a>
This triggers the entitlements signin form. To log out, we can use the following code:
<a href="tp-entitlements-clear-token://self">log out</a>
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.
<a href="tp-entitlements-register://self">log out</a>
As you can see, with a little bit of JavaScript knowledge, you can make great combinations between entitlements and the info cell.