Custom user ID

Batch can automatically tie several push tokens from different OS' to a single user ID. This allows you to use the Custom Data API. This is also useful if you are planning to use the Transactional API and don't want to manage devices' tokens on your side.

Custom user IDs

This custom user identifier can be:

  • The unique ID you are using in your login system.
  • A stable ID used in your data store (e.g. Firebase, etc).
  • Any stable information that can help you to identify a user (e.g. hashed email address, etc).

Pushing a custom ID will send a notifcation to every installation with that ID set. That means that one user might get a push on multiple devices at a time.

Setting up a custom user ID

The API is pretty straightforward:

var userProfile:BatchUserProfile = Batch.getUserProfile();

userProfile.setCustomID("john.doe"); // Set to `null` if you want to remove the Custom ID.

You should remove the Custom ID anytime the identified user logs out.

Custom IDs are case and whitespace sensitive. If you want to avoid potential issues, you may want to lowercase and trim the Custom ID string.

Make sure the identifier is unique, otherwise users might get pushes that are not meant for them. You should never associate a custom ID to more than one user.

Choosing a unique identifier

If you're wondering how to use the identifier in your app, we've covered a few use cases:

Login system

If you have a login system, you probably have a unique user ID associated to the user's account.
Simply set this ID as your custom ID, and don't forget to reset it (by setting it to null) when the user logs out.

While emails are an appropriate custom ID, we suggest to hash them before setting them as your custom ID, for privacy reasons.

PaaS datastore

Your datastore probably has a stable ID associated to your installation. You just need to make sure it is unique between installations, and you are easily able to retreive it from your backend code.

Specific backend and database

Anything that can identify a user uniquely will work. Emails, phone numbers, etc...
We suggest you hash this information before setting id, and use the same hash on your backend.

Otherwise, you will need to create a stable identifier for your app installation and send it to your backend. The most common way to do that is to generate a RFC4122 UUID.

Resetting the custom data

When a user logs out, you may want to clear the custom data. It's pretty easy, just set the values to null:

var userProfile:BatchUserProfile = Batch.getUserProfile();