This guide is to help you make sense of our new user model with our old player model and provide high-level guidance on migrating an existing app to User Model.

User Model

We have updated our core model from a device-centric model, which requires you to manage the relationships between devices and your users. We added an optional external_id property to Player objects, enabling you to tie those devices to a single user. Due to the complexity required to unify Players into some notion of a user, many of you couldn't take advantage of our new Journeys product, which operates on the concept of a user. Our new model, User Model, now lets you think of your users as users. Just as you'd expect 😄

You can logically think of a User as any unique person engaged with your website, service, or application. All User entities have Identity; all instances of this type can be uniquely identified via OneSignal ID, generated upon creation, or Identity Alias.

An Identity Alias is a label and an associated identifier expressed as a key-value pair.

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

User objects can be identified using any Identity Alias.More details can be found here: Users. In fact, onesignal_id is implemented as an Identity Alias with a couple of special properties:

• Read-only.
• Autogenerated by OneSignal.
• The label onesignal_id is reserved.

A second special-case alias exists for External ID. external_id is implemented as an Identity Alias:

• Writeable.
• OneSignal automatically sets External ID for apps that implemented External User ID when migrating from Player Model.
• The label external_id is reserved.

Our Identity Alias system allows you to find your users using whichever ID you use in your system. For example, suppose you use a Facebook ID to reference users in your system; you can leverage Aliases to use that identity on OneSignal. To accomplish this, you add an Alias to your user objects setting the Alias Label to facebook and the Alias ID to the Facebook ID of your user. More details can be found here: Aliases & External ID.

User objects also contain other writeable properties inherent to a user profile, such as last active status, language, and Data Tags.

Finally, users have Subscriptions. Subscriptions represent how users engage with your website or app, whether it's push notifications via iOS, chrome, or email. Available properties on a subscription depend on the subscription type. More details can be found here: Subscriptions.

The following snippet is what a User object may look like when fetched from our API.

{
  "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 and Player models are incompatible, so you must update your websites and apps to our latest SDKs supporting the new User Model.

All new apps will use the User Model. It is impossible to migrate from User Model; however, migrating to User Model from the old Player Model is fine. When migrating from Player Model, OneSignal automatically merges devices by External ID (previously External User ID).

Additionally, some Integrations (User Model Supported Integrations), Backend SDKs and Identity Verification are not supported for this Release but will be in the future. Documentation will be updated once these items are supported.

Migration

1. Unify users via External ID
2. Ship an updated app and site with our latest SDKs
3. Update your app's backend a) To the latest backend SDK -- b) To call new User Model APIs

1. Unify via External ID

You must inform us which devices belong to which users. Set the External ID with Frontend SDKs login method or set the external_id property through our API or CSV upload.

• Create user API
• Update user API
• Create alias (by subscription) API
• Import Email Addresses CSV
• Import Phone Numbers CSV

2. Ship an updated app and site with our latest SDKs

Update your apps and websites to the latest SDK version that supports User Model.

If you're upgrading a current app, please follow one of the platform-specific migration guides:

• Web 16.0 Upgrade Guide
• Android Native 5.0 Upgrade Guide
• iOS Native 5.0 Upgrade Guide
• Unity 5.0 Upgrade Guide
• Cordova 5.0 Upgrade Guide
• .NET 5.0 Upgrade Guide
• Flutter 5.0 Upgrade Guide
• React-Native 5.0 Upgrade Guide

Please review the SDKs section below for a complete list of platform versions supporting the User Model.

3a. Update your app's backend to use the latest backend SDK

Update your app's backend code to use the latest SDK that supports User Model. The upgrade process is very straightforward, update to the latest SDK; your code will continue to work as User Model only adds new APIs to maintain backward compatibility with apps that still use Player Model. To use User Model functionality, call one of the new User Model API functions.

For a complete list of backend SDKs, see the Backend Server section.

3b. Update your backend to call new User Model APIs

Review your app's backend code to ensure it doesn't call deprecated APIs. If your backed code calls any deprecated APIs, you must update those APIs to the new corresponding User Model APIs. For a complete list of deprecated APIs, see the correspondingly named section.

SDKs

Frontend SDKs now have a unified API where functionality is grouped into namespaces. Please refer to the developer references for API details:

• Mobile SDKs
• Web SDK

Native

Web

Cross-Platform

Backend server

REST API

If you’re not already using one of our backend server SDKs to interact with our REST API, consider migrating to one of our many new SDKs supporting the User Model. If you cannot use one of our backend server SDKs to interact with our REST API, you must change how you call them.

Deprecated APIs

The following APIs have been deprecated. The table below shows which API to migrate to for similar functionality.

New APIs

User Model brings several new APIs for managing your users and their subscriptions.

User

Subscription

Bug Reporting

Please report any bugs or issues you encounter by opening an issue in the repository for the SDK(s) your application uses. You can also share feedback or ask questions via our Developer Community on Discord.

Known Issues

Common items to watch out for with migration.

Data Tag Migration

Users with multiple versions of your app may experience issues with mismatched tags as follows

Player Model

Tags were set at the Subscription-level (Player ID).

• Device1 (iPhone) Subscription1 | External_ID = 1 | Using SDK version 4 or less (Web SDK 15 or less) has tags set:
  • Tag 1 = 1
  • Tag A = A
• Device2 (Android) Subscription2 | External_ID = 1 | Using SDK version 4 or less (Web SDK 15 or less) has tags set:
  • Tag 2 = 2
  • Tag A = B

User Model

Tags are set at the User level, but previously set tags are still available.

Device2: Subscription2 upgrades to SDK 5 (Web SDK 16)

• Calls OneSignal.addTags method to set Tag 3 = 3
• Subscription2 now has tags:
  • Tag 3 = 3
  • Tag 2 = 2
  • Tag A = B
• Device1: Subscription1 still on SDK 4
  • Subscription1 now has tags:
    • Tag 3 = 3
    • Tag 1 = 1
    • Tag A = A
• External_ID=1 has access tags:
  • Tag 3 = 3
  • Tag 2 = 2
  • Tag 1 = 1 (Potential problem if this tag is outdated)
  • Tag A = A & B (Problem! 🙀) This user can be associated with segments and Journeys targeting Tag A = A or Tag A = B
• Current workaround:
  • Create a new tag scheme for User Model. Remove old and unused tags. Update tags you wish to continue using in User Model.
  • Use the Importing User Attributes or Tags CSV to update tags on all External IDs to the same value.
  • Use the Update user API to update tags on all External IDs to the same value.
  • Delete tags on “older” subscriptions.
• Considerations:
  • Hard coded tags and users that never update but continue to use the app may continue to see mismatched tags.
  • OneSignal is looking to provide other solutions. Contact [email protected] if you need assistance.