App API learn more, tips & tricks

OVERVIEW

1. About the API

2. Tips and information for integration

2.1. Registration

2.1.1. Registration with MSN

2.1.2 Registration without MSN (deterministic PIN)

2.2 Display content in app

2.3 Shop transaction

2.3.1 Shop transactions – Liquid Barcodes integrates towards payment provider

2.3.2 Shop transactions – Customer integrates towards payment provider

2.4 Select preferred store(s)

2.5 Scan code to get reward

2.6 Rating

2.7 Store finder

2.8 Recruit a friend

2.9 Customer user groups

2.10 Edit user information

2.11 Push notification – register device

2.12 Share content / Send a gift

2.13 Receipts handling

3. Definitions

 

 

1. About the API

This is a web service where you can register a user and fetch all coupons that are available to the given user at any point in time. Hence, the app-API allows Liquid Barcodes to distribute coupons and other content to your app. Before coupons can be distributed to the user’s app, the user must be registered.

The API requires a unique and persistent ID to be created per user upon registration. This can be handled entirely by Liquid Barcodes, or, if you already have a registration service, the registration to Liquid Barcodes can be done in the background without involving the user. The registration process is described in detail in the API.

Liquid Barcodes will populate a record per user with information to display in the app. Liquid Barcodes will ensure that the data in the record at all times is correct, and will remove coupons when they expire, have been redeemed etc. This record is obtained through the API. The record primarily contains one or several coupons (referred to as coupon objects in the API specification). All coupon objects are structured in groups called sets. Each set should be displayed in its entirety in one designated space in the app. One app may contain one or several such spaces, depending on your requirements, with one corresponding set per space. There are many different types of coupon objects, but it is important to maintain a fallback handling of unknown coupon objects.

The API allows you to distribute many coupons to your app through Liquid Barcodes’ dashboard and automated couponing through campaign rules. Content can be distributed based on many different parameters, eg. lists, rules, region filters, segments.  Also, the API can receive coupons from the Coupon API – IssueRequest.

 

 

2. Tips and information:

2.1 Registration

2.1.1. Registration with MSN

  • Consent handling. The API supports two types of consents: Master consents and Non-master consents. Master consent is identified through the consent situation model parameter Name= ‘Master’. User should accept Master consent on registration. As a minimum, user should be presented with  the consent model title and link to Privacy policy text. Both texts are provided through the API.
  • Age restrictions. App is responsible for verifying user’s age, either by collecting date of birth or presenting user with active consent mechanism (eg. toggle button or check box) and MinimumAgeText. User registration cannot be completed if DateOfBirth < MinimumAge.
  • After age verification and consent accept, user receives SMS-PIN, types PIN and is logged in (optional flow: deterministic PIN without SMS PIN, see API).

(click image to enlarge)

 

  • Non-master consents provide options for granular consents that can be handled after the main registration process or on ‘My page’. We advice to present users with all granular consents on one page. Present consent model title and link to consent model description.

 

  • Consent updates: The API supports breaking and non-breaking changes. Breaking changes on Master consent will block the app from getting content until new consent has been accepted. Prompt user with updated consent version to restore app functionality. The app should check for, at regular intervals eg. daily, and warn user about non-breaking changes to Master consent and changes to Non-master consents. The API may provide change description for each consent update back to previous accepted consent version. Note that there may be several new versions and corresponding change log texts for one user.

 

  • User rights: the API provides basic account information and a link to advanced ‘My page’ solution. Make sure to link to this ‘My page’ solution to ensure full compliance with user rights. Expect the ‘My page’ link to be unique and dynamic for each user.

 

  • Texts can be provided as HTML converted from markdown.
  • Store the UserID locally, not in clear text.

 

2.1.2 Registration without MSN (deterministic PIN)

  • Simplified registration method for apps that already have a unique and persistent ID for each user. The app is responsible for collecting and maintaining valid consent.

 

2.2. Display content in app:

  • GET /content is the main function to access content via the App API
  • When sending a GET /content request, Liquid Barcodes reply with an array of content objects
  • The content objects are grouped in Sets
    • Each Set should be mapped to one specific location (room) in your app. Eg. place all content in the ‘Coupons’ Set in a room called ‘Coupons’.
    • You can have one or more dedicated rooms in the app for all content from Liquid Barcodes, the number of Sets can be configured to your needs.
  • Each content object contain all the image urls and text information required for displaying each item:
    • Build coupon images from elements. The app must handle images that are too small or too large (aspect ratio not optimal for current screen size)
    • There are two main content types: Coupon and HTML.
    • Have one logic to build coupon view based on the gross list of coupon items. This should also be fallback if unknown content is provided.
    • Make one logic for showing HTML content. Opens in app browser.
    • Test the in app browser for various HTML content (survey, games and web link)
    • Make sure that all Liquid Barcodes content rooms support Coupon and HTML content.
    • Display the coupons and html content in the order presented in the app feed. Do not filter content based on any properties.
    • Add a refresh button to allow the user to update content. As a minimum, this should force a refresh of all content for this coupon.
    • Update images based on HTML headers.
    • Make it possible to share coupons if the coupon is sharable (LB define shareable or not)
    • Make sure to use the coupon or html content according to its intention (e.g. the parameter BackUrl should be placed on the backside of the coupon)
  • Offline handling. Do not delete cache on device if in offline mode or no response from server. The app should work without connection (albeit with limited functionality).
  • Register push on every app opening. Test push when releasing new app versions.
  • If customer can give feedback from the app, this should be done using a form (mail not required). Remember to include information about the user, msn, device, os and app version
  • If recruiting function is implemented, make sure that there is an info image (hosted by LB) that can be updated without app update and pre-populate the SMS with the SMS-text received from LB

 

2.3 Shop transactions

2.3.1 Shop transactions – Liquid Barcodes integrates towards payment provider

  • Shop offers are items that have a defined price and that end users can purchase.
  • When buying a shop offer, one or multiple actions can be triggered in Liquid Barcodes system, such as issuing a coupon or topping up a gift card.
  • You create shop offers and related actions in Liquid Barcodes dashboard.
  • Each shop offer has a unique shop offer token that serves to define the shop offer and add security.
  • When content has been issued, the app shows the content using the method described above ‘Display content in app’.
  • To show receipts, use App API GET /receipts

 

2.3.2. Shop transactions – Customer integrates towards payment provider

  • Use this flow if you manage your own payment service (eg. your own points program or private label gift cards)
  • Shop offers are items that have a defined price and that end users can purchase.
  • When buying a shop offer, one or multiple actions can be triggered in Liquid Barcodes system, such as issuing a coupon or topping up a gift card.
  • You create shop offers and related actions in Liquid Barcodes dashboard.
  • Each shop offer has a unique shop offer token that serves to define the shop offer and add security.
  • The token has an outer and inner part. For processing the payment, you need to decrypt the outer part.
  • The inner part can only be decrypted by Liquid Barcodes and is used when issuing the related content.
  • When content has been issued, the app shows the content using the method described above ‘Display content in app’.
  • To show receipts, use App API GET /receipts

 

2.4 Select preferred store(s)

  • Use this flow to let users set their preferred store(s).

 

2.5 Scan code to get reward

  • The function allows app users to enter a code in the app to get reward, transfer stamps from paper loyalty card to app and many other functions.
  • In most use cases, the app should only send code to Liquid Barcodes back end. The issue of the correct reward is handled by Liquid Barcodes back end.

 

2.6 Rating

  • When implementing rating functionality in the app, you can choose between making one location in the app to show a dynamic list of all rating types and pending ratings (recommended), or you can make one specific location for each rating type.

 

2.7 Store finder

  • Liquid Barcodes can send a wide range of information per store to the app.
  • The app should have a user friendly way of displaying the information to the user.

 

2.8 Recruit a friend

 

2.9 Customer user groups

 

2.10 Edit user information

 

2.11 Push notification – register device

 

2.12 Share content / Send a gift

 

2.13 Receipts handling

 

 

3. Definitions:

Coupon: all offer types and mechanics, e.g. Offers, Hurry, Chicken, Share & care, Stamp cards, Image coupons etc.

HTML content (requires launching of in app browser): Survey, Games, Web link etc.

Shop offer: a content object that end users can buy. Purchasing these items will trigger issue of related content, eg. coupons or gift card balance top up.