OneSignal has migrated from a device-centric (Player ID) model to a user-centric model built around the concept of a unified user. This guide explains the new model, how it differs from the old approach, and how to migrate your app safely and successfully.
This guide is for customers who have been using OneSignal for a long time on versions 2, 3, or 4 of our Mobile SDKs or v15 of our Web SDK.If you are a new customer or have already migrated to version 5 of our Mobile SDKs or v16 of our Web SDK, you can skip this guide and go to:
User Model multi-channel illustration

Multi-channel messaging with the User Model

​
What is the User Model?

The User Model lets you target actual users across all the messaging channels they subscribe to (mobile push, web push, email, SMS, and in-app) rather than targeting individual devices. Each User:
  • Has one or more Identity Aliases (e.g. external_id, custom alias)
  • Can have multiple Subscriptions, one for each channel or device
  • Includes metadata like tags, language, and activity history
This model simplifies audience targeting, supports personalized multi-channel messaging, and unlocks advanced features like Journeys, User-Level Analytics, and Real-Time Identity Resolution.
Diagram showing difference between Player and User Models

Player vs. User Model

​
Key concepts

A User represents a real person. You can identify a user using system-generated or custom aliases.
  • onesignal_id: Auto-generated by OneSignal
  • external_id: Set via SDK login() or the API (reserved alias)
  • Custom Aliases: e.g. user_id, email, facebook, etc.
Learn more: Users

​
Benefits of migrating

  • Unified Identity: One user across all devices and channels
  • Advanced Messaging: Power features like Journeys, in-app login tracking, and lifecycle campaigns
  • Clean Segmentation: Group users by tags, subscription status, channel engagement, and more
  • Simplified API: Fewer endpoints, more consistent data model

​
Migration steps

The User Model is not backwards compatible. Migration is one-way from Player Model to User Model.Before migrating:
  • Thoroughly test with a staging environment
  • Migrate only after all SDKs and backend services are updated
1

Unify users with external_id

Use identity aliases to link existing player records into unified users.Options:OneSignal will auto-merge subscriptions under the same External ID.
2

Update your OneSignal SDKs

All OneSignal mobile SDKs v5+ and web SDK v16+ support the User Model.Roll out SDK updates using phased deployment strategies to minimize risk:See SDK support table below.
3

Update your backend to use the new User APIs

Replace deprecated Player Model API calls with the new User Model equivalents.Use our API Reference and tables below to map old endpoints to new ones.

​
SDK support & migration guides

PlatformSDKMigration Guide
Androidv5+Guide
iOSv5+Guide
Unityv5+Guide
Flutterv5+Guide
React Nativev5+Guide
.NET MAUIv5+Guide
For a map of old player model methods to new user model methods, see Mobile SDK mapping.

​
API reference

​
Next steps

  • 📘 See our Users and Subscriptions documentation
  • 🛠️ Update SDKs and test in staging before going live
  • 💬 Need help? Contact support@onesignal.com
You’re now ready to build personalized, multi-channel messaging experiences powered by the new User Model!