Guides
DashboardPricingLoginSign-up for free

User IDs

Assign your own user IDs to integrate WonderPush with your systems

Suggest Edits

You can assign your own user IDs to installations in WonderPush. This allows you to target users by user ID and lets you tightly integrate WonderPush with your systems.

Assigning your own user IDs

Assigning your own user IDs depends on the platform (adapt THIS_USER_ID) with your own user ID:

window.WonderPush = window.WonderPush || [];
WonderPush.push(['setUserId', "THIS_USER_ID"]);

WonderPush.setUserId("THIS_USER_ID")

[WonderPush setUserId:@"THIS_USER_ID"];

WonderPush.setUserId("THIS_USER_ID");

WonderPush.setUserId("THIS_USER_ID");

You only need to specify the userId once: it persists until next time you specify a userId or null.

Removing a user ID

User IDS can be disassociated from the current device Installation id using the Wonderpush SDK unsetUserId method. It is recommended to call this method when the user logs out of your app or website.

window.WonderPush = window.WonderPush || [];
WonderPush.push(['unsetUserId']);

WonderPush.setUserId(null);

[WonderPush setUserId:nil];

WonderPush.setUserId(nil)

When to change the user ID

You can change the current user ID:

  • when anonymous users log into your app / website, user ID goes from null to something,
  • when a user logs out of your app / website, user ID goes back to null,
  • when a user directly switches from one account to another, we encourage you to directly set the user ID to the new value without unsetting it in between, if this matches your UI flow.

You do not have to set the user ID everytime your application starts, WonderPush remembers the last used ID; but if it's easier for you, feel free to.

Changing the user ID is akin to loading a new profile

When the user ID changes, a new separate installation is used, it is also created if it's the first time a given user ID is used on a given device. This means that all the tags, properties and events you've sent before changing the user ID will not be attached to the new installation. This ensures that data doesn't get mixed up between different user accounts. The push token is also moved from the old to the new installation, meaning the old installation is no longer pushable.

If you would like to keep all or some tags or properties, you can choose one of the following strategies:

  • change the user ID; then set all tags and properties according to your own external source of truth.
  • get all tags and properties of the current profile; then change the user ID; then set the tags and properties on the new profile

Getting all the current tags is done using WonderPush.getTags(). Getting all the current properties is done using WonderPush.getProperties().

Adding multiple tags at once is done by giving an array of tags to WonderPush.addTag() (WonderPush.addTags() on iOS). Setting multiple properties at once is done by giving an object to WonderPush.putProperties().

You might want to pay attention to the existing tags and properties if you want to avoid leftovers. You can remove all tags using WonderPush.removeAllTags(). You can remove all properties by calling assigning null to every existing property.

Targeting users with the API

You can use the targetUserIds parameter of the Send notifications API call to target one or more users.

# Sending a notificaton to 2 users: userID1 and userID2 
# Replace YOUR_ACCESS_TOKEN with your Management API access token
curl -XPOST https://management-api.wonderpush.com/v1/deliveries?accessToken=YOUR_ACCESS_TOKEN \
    -H 'Content-Type: application/json' \
    --data-binary '{
        notification: {"alert":{"text":"test"}},
        targetUserIds: ["userID1","userID2"]
    }'

// Sending a notificaton to 2 users: userID1 and userID2
// Adapt WONDERPUSH_ACCESS_TOKEN, WONDERPUSH_APPLICATION_ID
$client = new \WonderPush\WonderPush(WONDERPUSH_ACCESS_TOKEN, WONDERPUSH_APPLICATION_ID);
$client->deliveries()->create(array(
    'notification' => array(
      'alert' => array(
        'text' => 'test',
      ),
    ),
    'targetUserIds' => ['userID1','userID2'],
  ));

Targeting users via the online dashboard

To target one or more users from the target tab of the notification edition interface, setup a criterion of type User id is equal to.

Using the Management API to enrich users

The user objects are meant to bear additional properties to help you further segment your audience.

You can use the Management API PATCH /v1/users/someUserId endpoint to add new properties to a user:

curl -XPATCH https://management-api.wonderpush.com/v1/users/someUserId?accessToken=YOUR_ACCESS_TOKEN \
    -H 'Content-Type: application/json' \
    --data-binary '{
        "custom": {
            "string_subscribedPlan": "premium"
        }
    }'

You can then segment your users in the dashboard using the criterion of type User property (string):

This will select every installations whose associated user has the value premium in the string_subscribedPlan property.

Integration with Brevo

It is important to use a common identifier between your existing contacts in Brevo and the User ID given to the WonderPush SDK. Failing that you will end up with a new group of contacts that are subscribed to push notifications but inherit none of the contact attributes you have carefully built over time.

Avoid switching back and forth between kind of values in the WonderPush User ID, because although each installation could end up attached to the same contact, as far as WonderPush is concerned we are switching from a profile to another.

You have a few options to achieve a good integration, depending on your use of Brevo.

Option 1: You are using email for your existing contacts

Use the same email value as the WonderPush User ID.

Option 2: You are using an external identifier in Brevo, using the ext_id field in the Brevo API or EXT_ID contact attribute

Use the same external identifier value as the WonderPush User ID.

Option 3: You are only using SMS or WhatsApp numbers for your contacts, and not email

Use the same phone number value as the WonderPush User ID, using the international format consisting of a +, the country code and the rest of the numbers, without spaces, hyphens, parenthesis, etc.

Examples: The French number 01 22 33 44 55 would become +33122334455 (note that after the country prefix the initial 0 has disappeared). The Californian number (650) 123-4567 would become +16501234567.

Option 4: You are not using external identifiers in Brevo and do not wish to use the email or SMS or WhatsApp numbers in the WonderPush SDK

Use the new external identifier you want to use as WonderPush User ID.

Upgrade all your API calls to Brevo API to include the ext_id along with the other identifiers you currently use.

Then, go over all your existing contacts and add the new external identifier you want to use so that all contacts now have an external identifier.

The goal is to make a bridge between identifiers belonging to the same individual. If you enter a different identifier from the one entered in Brevo, no match will be possible.

Use the API calls in the next section to help you out.

Brevo API calls to create bridged between identifiers

To assign an External ID to an existing contact via their (numeric) Contact ID:

PUT https://api.brevo.com/v3/contacts/{contactId}

{
  "email": "xxxxxxxx",
  "ext_id": "yyyyyyyy"
}

To assign an External ID to an existing contact via their email address:

PUT https://api.brevo.com/v3/contacts/{email}?identifierType=email_id

{
  "ext_id": "yyyyyyyy"
}

To assign an External ID to an existing contact via their email address, or create the contact if it does not exist:

POST https://api.brevo.com/v3/contacts

{
  "email": "xxxxxxxx",
  "ext_id": "yyyyyyyy",
  "updateEnabled": true
}

Brevo documentation :

Updated 9 days ago