SDK Overview

TapPoint SDK makes it easy to take advantage of Bluetooth beacons, enabling you to focus on creating the best possible app experience for your users. Once integrated it enables your app to detect nearby beacons and trigger content specific to that beacon's location.

Let's explore how it works in conjunction with a use case. The owner of a department store would like to increase footfall into his store during off-peak times. As customer's walk past the store he would like to attract them in-store by delivering a 10% off trainers coupon. The basic integration process is as follows:

There are four key concepts to understanding how the TapPoint SDK works: beacons, TapPoint, Triggers and Payloads:

SDK Overview

What is a beacon?

A Bluetooth Low Energy (BLE) Beacon is a low power transmitter that can notify TapPoint SDK enabled apps about its presence. A beacon provides real-world proximity awareness to mobile devices which an app can use to perform an action.

There are currently two types of beacons we support, iBeacon (Apple) and Eddystone* (Google) beacons. An iBeacon transmits three pieces of information: a UUID that identifies the network that the beacon belongs to and major and minor values that identify an individual beacon within a network.

Similar to iBeacon, Eddystone beacons transmit UID information consisting of a namespace and instance. Where Eddystone differs is its ability to transmit telemetry data (TLM), which includes information on the beacons battery, temperature and other useful statistics. It also has the ability to transmit a URL. Beacons typically have a signal range of 40 meters. This range can be affected by water, metallic surfaces, walls or people.

Proxama's Proximity Network is a collection of beacons installed in public transport, shops and out-of-home media which can be used to run campaigns on.

* Eddystone caveat: Currently iOS devices can only detect Eddystone beacons while the host app is in the foreground. This limitation does not effect iBeacons, which have full background capability. Android devices have no limitation and support background detection of both Eddystone and iBeacon.

What is TapPoint?

TapPoint is a cloud-based platform which enables brands, retailers and location owners to create campaigns to run on their TapPoint SDK enabled apps. A campaign consists of a start and end date, a selection of beacons to trigger use cases and some context-specific campaign data which is to be delivered to your app upon interaction with a beacon.

In the use case above, a campaign owner would setup a campaign to run for 2 weeks on selected beacons which are in close proximity to the department store. They would setup the campaign data to contain a coupon ID and a message to be delivered to the app when a customer walks past a beacon.

What is a Trigger?

The functionality of the TapPoint SDK is driven by the use of Triggers. A Trigger links a physical beacon to a campaign and delivers campaign data to your app based on rules defined when setting up a campaign.

A Trigger is made up of "Proximity Rules" and "Campaign Data":

Trigger Overview

Proximity Rules

A Trigger contains a number of rules that must be satisfied before campaign data is delivered to the parent application:

Trigger Event Type

The Trigger beacon event type can be configured to deliver campaign data either on entering the range of a beacon, leaving the range of a beacon or both. This is useful when you want to provide a different experience in your application depending on the event. For example, to display a welcome message when the user enters a department store and a goodbye message when they leave.

Campaign Data

Upon matching the proximity rules TapPoint SDK will deliver the campaign data to the parent application. The application must then hook up functionality within the application to perform an action based on the campaign data exposed. Exposed data includes:

Triggers are created when you setup a campaign on TapPoint and need to be synced to your application before they are active. TapPoint SDK provides syncing APIs to make this easy. An application developer needs to implement a syncing strategy that ensures new campaign triggers are synced to the application before the campaign starts. Syncing of Triggers allows applications to interact with beacons in areas where Internet connectivity is limited (subway stations, festivals, stadia etc.)

What is a Payload?

A Payload is some campaign specific data that is delivered by TapPoint SDK to the parent application when entering or exiting the range of a beacon. The application needs to interpret the payload and perform an action based on the data.

Payload Overview

A Payload can be any valid JSON object; the contents of a Payload are completely defined by an application and can be unique for each Trigger. Payloads are added to Triggers when a new campaign is created.

{ "coupon_id": "112", "coupon_text": "10% off trainers" }

In our example use case, the payload consists of a coupon ID and some coupon text. When a customer walks in range of a beacon the TapPoint SDK delivers the coupon ID and coupon text to the parent application. Upon receiving this data it is up to the application to perform some action on it - if the application is closed show a notification using the offer text or if the app is open display the coupon ID to user ready for redemption.

We made a conscious design decision not to hijack your app UI - providing you the freedom and flexibility to create amazing consumer experiences that go beyond just showing a notification.