# Connecting Your App

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.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.ubiquity.co.nz/documentation/channels/push/connecting-your-app.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.