User model & migration guide

Learn how to migrate from OneSignal’s device-centric model to the new user-centric APIs and SDKs for more personalized, multi-channel engagement.

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:

• Users
• Subscriptions
• Mobile SDK reference
• Web SDK reference

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.

Player vs. User Model

---

Key concepts

Users

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:

   • SDK login(externalId)
   • API: Create User, Update User
   • CSV: Import

   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:

   • Apple Phased Rollout
   • Google Play Staged Rollout

   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

Mobile SDKs

Platform	SDK	Migration Guide
Android	v5+	Guide
iOS	v5+	Guide
Unity	v5+	Guide
Flutter	v5+	Guide
React Native	v5+	Guide
.NET MAUI	v5+	Guide

For a map of old player model methods to new user model methods, see Mobile SDK mapping.

---

API reference

Player Model (Deprecated)

Old API	Replacement
Add Device	Create User or Create Subscription
Edit Device	Update User or Update Subscription
Delete Player	Delete User or Delete Subscription

---

Next steps

• 📘 See our Users and Subscriptions documentation
• 🛠️ Update SDKs and test in staging before going live
• 💬 Need help? Contact [e-mail]

You’re now ready to build personalized, multi-channel messaging experiences powered by the new User Model!

---