This guide helps you make sense of our new user model compared to the old player model and provides high-level guidance on migrating an existing app to the User Model.

​

User model

We’ve updated our core model from a device-centric system to a user-centric one. Previously, you managed relationships between devices and users by assigning an external_id to Player objects. This complexity made it difficult to unify devices into a concept of a user, limiting adoption of features like Journeys.

The new User Model lets you represent real users directly.

A User represents a unique person who engages with your product. Each user:

• Has an identity, either a system-generated OneSignal ID or one or more Identity Aliases
• May be identified via a key-value pair alias such as external_id, email, or a custom ID

  {
    "identity": {
      "ONESIGNAL_ID": "...",
      "LABEL": "ASSOCIATED ID"
    }
  }

User objects can be identified using any alias. For example:

• onesignal_id: auto-generated, read-only, reserved
• external_id: writable, auto-migrated, reserved
• Custom labels (e.g. facebook, email, user_id): fully customizable

Learn more: Users and Aliases & External ID

User objects also include:

• Properties like tags, language, and last_active
• One or more subscriptions, which represent how users engage (e.g. iOS push, web push, email)

{
  "properties": {
    "tags": {
      "KEY": "VALUE"
    },
    "country": "US",
    "first_active": 1673449251,
    "last_active": 1678126124
  },
  "identity": {
    "external_id": "example123",
    "onesignal_id": "ONESIGNAL_ID"
  },
  "subscriptions": [
    {
      "id": "SUBSCRIPTION_ID",
      "app_id": "APP_ID",
      "type": "Email",
      "token": "[email protected]",
      "enabled": true,
      "notification_types": -99,
      "session_time": 3670,
      "session_count": 129,
      "sdk": "",
      "device_model": "",
      "device_os": "",
      "rooted": false,
      "test_type": 0,
      "app_version": "",
      "net_type": 0,
      "carrier": "",
      "web_auth": "",
      "web_p256": ""
    }
  ]
}

​

Limitations

• The User Model is not backward-compatible with the Player Model.
• Migration is one-way: you can migrate from Player to User, but not vice versa.
• OneSignal merges devices by external_id during migration.
• Some integrations are not yet supported. See User Model Supported Integrations.

​

Migration

​

SDKs

​

REST API