Set a custom User ID and link it to multiple devices

To enable seamless, personalized communication across all platforms and devices, it is essential to assign a custom User ID to each user.

User ID is a unique identifier that is assigned to each user to maintain consistent user data across all their devices. This allows you to provide your audience with a seamless user experience across their devices.

For a detailed explanation of how User IDs work and how they relate to devices, see this guide.

By default, when your app is first launched, Pushwoosh creates a User ID equal to the device’s Hardware ID (HWID). This means each device is treated as a separate user. So if one person uses more than one device, like a phone and a tablet, Pushwoosh sees them as two separate users, and their data won’t be connected.

Setting a custom User ID lets you link all devices and contact methods under one profile. This provides several important benefits:

Pushwoosh charges based on the number of unique users in your database.

Learn more about Pushwoosh pricing

If you don’t set a custom User ID, each device counts as a separate user, even if they belong to the same person. For example, if one user uses both a mobile phone and a tablet, they may be counted as two users.

For a unified experience across push notifications, email, SMS, in-app, WhatsApp, and other channels, all user data must be linked under a single User ID.

By setting a custom User ID, you ensure that Pushwoosh recognizes all contact methods (devices, emails, phone numbers) as belonging to the same user, which is essential for consistent and personalized omnichannel campaigns.

Learn more about Omnichannel campaigns

A custom User ID allows Pushwoosh to maintain a complete, unified profile for each user. This profile includes:

• All devices and contact info linked to the same user
• Tags
• Event history and campaign participation
• Messages sent and opened

You can view and manage this data in User Explorer, helping you deliver more accurate targeting and better personalization.

Pushwoosh offers several methods to assign and manage UserIDs:

By default, when an app with Pushwoosh SDK is launched for the first time, it sets a device HWID as a User ID. However, you can set a custom user ID at various points depending on the app’s design and user flow. For this, use the setUserId method provided by the Pushwoosh SDK.

Here are some key moments when you can set or update a custom User ID:

• When the user registers in the app
• When the user logs in
• When the user makes a purchase or subscription
• When the user interacts with specific features, etc.

iOS example

[[Pushwoosh sharedInstance] setUserId:@"userId"];

Android example

Pushwoosh.getInstance().setUserId("testUser");

Web example

api.registerUser('user123');

When a user logs out, it’s recommended to reset their User ID to a default value using another setUserId call. When the user logs in again, update the User ID to the custom value specific to that user.

If the User ID changes (e.g., if one user logs out and another user logs in), call setUserId to update the User ID associated with that device. This ensures that the correct User ID is always linked to the device, allowing personalized notifications to be sent to the appropriate user.

Use the registerEmail or registerEmailUser API method to associate an external User ID with a specified email address.

Please note that registerEmailUser does not register an email address in your user base; it should be used only for assigning user IDs to email addresses that have been registered already by registerEmail request.

While primarily used to register a new device in Pushwoosh, this method can also set a User ID at the time of device registration.

If you pass a custom User ID in this call (for example, “userId”: “Alex”), it will be associated with the device. If no UserID is provided, the device will be associated with an anonymous User ID equal to the hardware ID (HWID)

To associate customer phone numbers with UserId using the /registerDevice method, please specify the phone number in the “hwid” parameter.

This API method allows you to associate an external User ID with a specified device or transfer a device between users while retaining device tags, for example when a user logs out and a new user logs in.

This method can be used before the device is registered or before obtaining the push token, for example, when you need to pre-register a user in Pushwoosh. Learn more