Connecting Your App

A developer guide for integrating your mobile app with the UbiQuity API to enable push notifications.

To send push notifications through UbiQuity, your mobile app needs to be integrated with the UbiQuity API. This involves adding API calls to your app code and ensuring your app is set up to receive push notifications.

This page is intended for developers integrating a mobile app with UbiQuity.

---

Overview

Your developers will need to:

1. Add API calls that register the device with UbiQuity each time the app is opened

2. Ensure the app is set up to display push notifications when they arrive

Once your app has been set up and registered with UbiQuity, you will be able to send push notifications to users who have the app installed.

For API reference documentation, see the UbiQuity API docs under /push.

---

Recommended API calls

Each time your app is opened, call:

POST /push/apps/{appID}/registrations/{deviceToken}

Calling this on every app open ensures the device is registered even if a previous call failed.

If the app is uninstalled, call the API to unregister the device from UbiQuity.

Linking to a database contact

The registration endpoint includes an optional referenceID parameter. This is the GUID of a UbiQuity database contact. Linking a device registration to a database contact unlocks the full segmentation and personalisation capabilities of UbiQuity — you can filter and target push notifications using all the data available against that contact, including results from mailouts, TXT messages, surveys, and events.

If you register a device without linking it to a database contact, you can still send push notifications, but segmentation and merge field personalisation will be limited.

Optional data fields

You can also pass optional fields data1, data2, and data3 when registering a device (for example, a name or email address). These make it easier to identify registered devices in UbiQuity, which would otherwise appear as a list of IDs.

Transactional data

You can pass data about how the app is being used via UbiQuity Transactional Tables. This lets you store relational information against a database contact — for example, recording when a specific feature is used — and then filter and segment on that data when sending notifications.

---

Device tokens

Device tokens are used to uniquely identify each device within UbiQuity. A stable device token should be maintained for each device to prevent the same device being registered multiple times.

Platform	Recommended approach
iOS	Use identifierForVendor or a custom ID generated with NSUUID. Store the ID in Keychain to prevent it changing if the app is uninstalled and reinstalled.
Android	Use ANDROID_ID.

---

Push tokens

To send push notifications to a device, the device must first register with Apple or Google's servers. Those servers return a secure token that is used to route notifications to that device. UbiQuity refers to this as the push token.

Each platform uses a different name for this token:

Platform	Name
iOS	Device Token
Android	Registration ID

Note that push tokens can change. This is why UbiQuity uses your own device token (described above) as the stable identifier for each device, rather than relying on the push token.