Learn how to use custom aliases in OneSignal to identify and track users across different platforms and devices using your own unique identifiers. Aliases help unify user data across multiple sources and are essential for integrations, user data management, and transactional messaging.
onesignal_id
to identify users. This ID only stays consistent across Subscriptions if they have the same external_id
.Custom aliases do not link Subscriptions together—they rely on the external_id
to work correctly. Without it, aliases won’t associate with the same user across devices or platforms.key : value
pair where:
alias_label
(key) is a consistent, static identifier across all users (e.g., facebook_id
, firebase_id
, crm_user_id
).alias_id
(value) is the specific user’s ID for that label (e.g., facebook_id: 3453443
, firebase_id: test3555
).OneSignal.login(externalId)
to associate the user record.
OneSignal.User.addAlias(label, id)
to add a single alias, or OneSignal.User.addAliases({ label1: id1, label2: id2 })
to set multiple.
OneSignal.logout()
to remove the external ID and any associated aliases for that device or session.
external_id
before assigning any aliases.crm_user_id
, legacy_user_id
) to avoid confusion across teams.logout()
to clean up aliases on device sign-out or user switch events.