The KIOSK app turns any smartphone or tablet into a powerful redemption scanner device. This app is mainly designed for users of our cloud-based platform for non-payment Mobile Wallet solutions. Merchants benefit from KIOSK by simplifying the process of redeeming and managing loyalty cards, coupons, tickets, and gift cards using a smartphone or tablet at the point of sale, without the need of expensive integration of scanning software.

Using KIOSK you can:

  • Automatically discount scanned passes from Pass Inventory
  • Detect whether a code is valid and confirm its authenticity
  • Recognize if the code has already been used
  • Add or subtract loyalty points after each scan
  • Confirm and issue available rewards for each customer
  • Customize your reward rules
  • Set your language preferences (English or Spanish)

This scanner supports the following formats: QR Code, PDF 147, Aztec, and Code 128. Authentication is handled in a simple and easy way, and is compatible with the Mobile Wallet ID Cards.

Global Overview

The KIOSK app is a Barcode Scanner. It works on Android and iPhone as a regular app with no special requirements. However, the app is able to recognize special Mobile Engagement barcodes to provide enhanced features, including authentication and rules execution. Users of the KIOSK app can login and logout easily, and can scan loyalty cards or consume coupons without having to integrate a POS system to our platform.


Rules are collections of actions and views that represent the lifecycle of a campaign from the point of view of an individual. For this reason the rules cover not only the process of using and consuming the passes, but the initialization, mapping, redemption, and update processes for each customer that participates in the campaign.

During the description of these rules we are going to use a simple demo: a loyalty program for a Coffee House where users that download the pass start with 0 points, and once they receive 4 points they can redeem a Free Donut as reward, at which point they are returned back to 0 points.

Rules are composed of 5 main elements:

Init Rules

The Init Rules are executed whenever a new user downloads a pass that uses this set of rules. For example, in our Coffee House loyalty program we initialize the user's points to 0. In a different scenario we may issue an on-boarding reward for new users that join the program.

Mapping Rules

The Mapping Rules are also executed when a new user downloads the pass. These rules specify the mapping between Pass fields and data fields in the user's record. In our example, if our pass has a variable field with name Points and we want that field to show the value of the points field in our segmentation list, this is the place to define that rule.

Load Rules

These are the rules executed every time a user record is loaded from the Backend DB. These rules simply parse whatever information is received from the backend, make any REST API calls to external platforms to load additional information, and prepare everything for processing and display.

Scan Rules

The Scan Rules are executed when the operator scans a pass using the KIOSK app, after the Load Rules have been executed. These rules render the UI that the operator will see inside the KIOSK app. In our example, this rule would render the button to increase or subtract the user's points. If our loyalty program allows the user to receive a reward after obtaining 4 points, this rule would include the validation to check if the user has 4 points, and the instructions to render the redeem option in the KIOSK app for the operator to use.

Execute Rules

These are the rules that are executed after the operator decides to apply one of the options presented by the Scan Rules. In the Coffee House example, if the operator pressed the button to add one point, these rules would increase the user's points in the DB. If the operator selected to issue a reward, the reward would be issued, and the points are updated back to 0.

As you can see from the below diagram, the first two rules (Init Rules and Mapping Rules) are part of the pass and user data initialization flow:

The Last three rules (Load Rules, Scan Rules and Execute Rules) are part of the KIOSK app flow when the user presents the pass to an operator:


Authentication with the KIOSK app is performed using an Authentication String that can be encoded as a QR Code or a clickable URL for convenience. The KIOSK app detects the digitally signed format and executes the authentication process without additional user intervention. If the user scans the same QR Code again he's automatically logged out. The digitally signed code lives in the mobile app memory, so the user must log back in if the app is closed, force closed, or the device is restarted.

The Authentication String uses the following format:


The tokens in the authentication string are:

  • KIOSKAUTH: Mandatory prefix indicating that the code is an Authentication String.
  • USER_NAME: Name of the user for which this Authentication String was created. This is the user name that is going to be registered in the backend logs and analytics platform when transactions are made using the KIOSK app.
  • WORKSPACE_ID: The ID of the workspace in the Mobile Engagement platform for which this user is authorized.
  • TIMESTAMP: The timestamp indicating the moment in which this Authentication String starts being valid. This value is the number of milliseconds since January 1, 1970, 00:00:00 GMT.
  • VALIDITY_PERIOD: The number of seconds during which this this Authentication String is valid.
  • LIST_ID: An optional Subscription List ID to be used as store for Authorized User information.
  • PADDING: Secure random padding.
  • SIGNATURE: The secure SHA256 signature of the whole Authentication String using the workspace's private key. More information here.

The Authentication String structure guarantees that an user will only have access to the platform during the authorized period, and will only have access to the provided workspace. The signature is used for authorization and tampering prevention.

For example, assuming that the private key for the workspace with ID 434 is AbAbAbAbAbAbAbAbAbAb, the operator can generate the following Authentication String to authorize the user testuser for 5 minutes (600 seconds) starting on January 17, 2018 5:23:29.506 PM GMT (1516209809506 milliseconds since January 1, 1970, 00:00:00 GMT), using the List ID 1342:


This Authentication String can be used in multiple ways in connection with the KIOSK app. We describe the two main ways below:

QR Code Authentication

The Authentication String can be encoded as a QR regular Code:

Once the user scans the code with the app he will be informed that the login process was successful. The KIOSK app will now display the user name in the top left corner while the session is valid:


If the same code is scanned again or the session expire,, the user will be informed that the session has been terminated:


URL Authentication

The Authentication String can also be delivered as a custom URL to users of the KIOSK app. To do so, it must be delivered using the kiosk:// URL schema:


This URL can then be delivered to the operator using any available channel (email, web, or SMS). Once the user clicks the URL the KIOSK app will be opened and the Authentication String will be processed. Using the same Authentication String as the previous example, we can deliver an authentication URL to a mobile phone that will trigger the whole process:


Upon clicking that link the KIOSK app will be automatically opened and the auth process will be executed:


The user is now authorized to use the platform for 600 seconds (5 minutes) starting from the date stored in the timestamp field.

The LIST_ID parameter can be used to implement more fine grained authentication schemes, including on-demand request of Authentication Strings for authorized users, and manual expiration of user access.

Rules Example

As mentioned above, we will build the Coffee House rules as an example. We are only going to cover the On-Demand use case, where there's no user information in the platform an the user needs to register, either by using a form or connecting with Facebook. Other use-cases where the database has been pre-populated with the customer's information are supported, and will just skip the initial part of capturing and storing the user's data.

This example assumes that the following wallet template has already been created:

As you can see there are 4 variable fields in this template: Name, Last Name, Points, and the barcode. The Mappings Rule will include a default mapping that maps the barcode to the code field in the subscription list. This means that our Mappings Rule needs to have 3 mappings for the 3 remaining variable fields.

Following the flow from the diagrams above, when the user clicks on the link to download the pass and all the validations are made, the Init Rules will be executed. In the Coffee House demo these rules should just initialize the user's Points to 0:

JsonObject user = getUserRecord();
user.addProperty("points", 0);

Once the user has clicked the link, the Init Rule has been executed, and the user record has been stored, the Mapping Rule is executed to let the pass know which fields in the segmentation list should be used to fill the variable fields in the pass. In this case we have 3 variable fields (apart from the barcode), so the Mapping Rule will have to create 3 mappings:

mappings.put("Points", "points");
mappings.put("Name", "first_name");
mappings.put("Last Name", "last_name");

The pass is delivered to the mobile device after this rule is executed. The user will see the pass with all the fields from the Mapping Rules, including the fields that were initialized in the Initialization Rules:


In this example, when the user visits the Coffee House and presents the pass, an employee will use the KIOSK app to scan the barcode. The KIOSK app will perform the authentication as described in the Authentication section of this document and if everything is ok the Load Rule and Scan Rule will be executed in succession. These rules will load the user data from the platform and display the scan view:


If the KIOSK operator decides to add points to the user's account he clicks on the +1 button in that screen, and after a validation the points are added:



If the Execute Rules include sending a push notification to the user he will receive an update with the new information which will be available in he Wallet app: