Welcome to the User Model SDK Migration Guide (v16) 👋

Intro

In this release, we are making a significant shift from a device-centered model to a user-centered model. This means that instead of identifying devices, we now focus on identifying individual users. This update is part of a larger effort to shift towards a user-oriented omni-channel messaging system.

To facilitate this change, the externalId approach for identifying users is being replaced by the login and logout methods. In addition, the SDK now makes use of namespaces such as User, Notifications, and Slidedown to better separate code.

This guide will walk you through these and other important changes in the version 16 update.

Overview

Under the new model, the concept of a "player" is being updated to include three new concepts: users, subscriptions, and aliases.

Users

Users own subscriptions and are identified by aliases which are used to point to users using different alias schemes.

Subscriptions

Subscriptions refer to the way in which a user can receive various communication methods offered by OneSignal, including push notifications, SMS, and email.

Aliases

Aliases are identifiers that point to users and are made up of an alias label and id. Users can have multiple aliases. Consider the need to identify a user with your own application's unique identifier as well as identifiers from other integrated applications.

The SDK will use external_id as the default alias label for the public OneSignal.login("1234") method.

Alias Example:

"aliases": [
  {
    "label": "external_id",
    "id": "1234"
  },
  {
    "label": "my_alias",
    "id": "5678"
  }
]

// WebSDK-specific example
{
  external_id: "1234",
  my_alias: "5678"
}

Guide

1. Setup Changes

Use the new script import on both your pages and your Service Worker file (OneSignalSDKWorker.js).

Script

Find and replace the following on all your pages.

From:

<script src="https://cdn.onesignal.com/sdks/OneSignalSDK.js" async/>

To:

<script src="https://cdn.onesignal.com/sdks/web/v16/OneSignalSDK.page.js" defer></script>

Service Worker

Open your OneSignalSDKWorker.js and update the following line.

From:

importScripts('https://cdn.onesignal.com/sdks/OneSignalSDKWorker.js');

To:

importScripts("https://cdn.onesignal.com/sdks/web/v16/OneSignalSDK.sw.js");

Another option is to download the new service worker file file, overwriting your existing one.

2. OneSignal Usages

Replace all OneSignal.push occurrences with OneSignalDeferred.push. Push a callback with the OneSignal object as an argument.

From:

window.OneSignal = window.OneSignal || [];
OneSignal.push(function() {
    OneSignal.init({});
});

To:

window.OneSignalDeferred = window.OneSignalDeferred || [];
OneSignalDeferred.push(async function(OneSignal) {
    await OneSignal.init({});
});

3. External User ID

Update any usages of OneSignal.setExternalId to OneSignal.login or OneSignal.logout From:

OneSignal.setExternalId("myId");

To:

OneSignal.login("myId");

Use OneSignal.logout(); instead anywhere you have OneSignal.setExternalId(""); or are setting it to null.

4. Custom Setup Changes

If you have customized the OneSignal setup update the following in your code.

ServiceWorker Config

If you have customized the OneSignal Service Worker

OneSignal.SERVICE_WORKER_PARAM = { scope: "/myCustomScope" };
OneSignal.SERVICE_WORKER_PATH = "/myPath/OneSignalSDKWorker.js";

Change to this:

await OneSignal.init({
    // ... keep other pre-existing params, such as appId
    serviceWorkerParam: { scope: "/myCustomScope" },
    serviceWorkerPath: "/myPath/OneSignalSDKWorker.js"
});

`script.onLoad`

Uncommon setup, if you have script.onLoad on OneSignalSDK.js you must replace this with the new OneSignalDeferred instead noted above.

5. API Changes

Update your code to use the new API. The following namespaces are on the OneSignal object.

User Namespace

Example:

OneSignal.User.addAlias("my_alias", "1234");

All user functions are synchronous.

Property/Function	Description	Argument List
`addAlias()`	Adds a new alias for the current user.	`label: string, id: string`
`addAliases()`	Adds multiple aliases for the current user.	`aliases: { [key: string]: string }`
`removeAlias()`	Removes an alias for the current user.	`label: string`
`removeAliases()`	Removes multiple aliases for the current user.	`labels: string[]`
`addEmail()`	Adds an email address for the current user.	`email: string`
`removeEmail()`	Removes an email address for the current user.	`email: string`
`addSms()`	Adds an SMS number for the current user.	`smsNumber: string`
`removeSms()`	Removes an SMS number for the current user.	`smsNumber: string`
`addTag()`	Adds a tag for the current user.	`key: string, value: string`
`addTags()`	Adds multiple tags for the current user.	`tags: { [key: string]: string }`
`removeTag()`	Removes a tag for the current user.	`key: string`
`removeTags()`	Removes multiple tags for the current user.	`keys: string[]`
`getTags()`	Returns the local tags on the current user.
`onesignalId`	Returns the local OneSignal Id for the current user.
`externalId`	Returns the local external Id for the current user.
`addEventListener()`	Adds an event listener for the `change` event.	- `event` ("change") - `listener` ((change: UserChangeEvent) => void)
`removeEventListener()`	Removes an event listener for the `change` event.	- `event` ("change") - `listener` ((change: UserChangeEvent) => void)

Notifications Namespace

Example:

await OneSignal.Notifications.requestPermission();

Sync/Async	Property/Function	Description	Argument List
`async`	`setDefaultUrl()`	Sets the default URL for notifications.	`url` (string)
`async`	`setDefaultTitle()`	Sets the default title for notifications.	`title` (string)
`sync`	`isPushSupported()`	Returns true if the current browser supports web push.
`async`	`requestPermission()`	Requests push notifications permission via the native browser prompt.
	`permission`	Returns true if your site has permission to display notifications.
	`permissionNative`	Returns browser's native notification permission status; `"default"`(end-user has not accept or decided yet), `"granted"`, or `"denied"`.
`sync`	`addEventListener()`	Adds an event listener for the following events: - `click` - `foregroundWillDisplay` - `dismiss` - `permissionPromptDisplay` - `permissionChange`* * argument type: bool	- `<event>` (string) - `(arg: <type>) => {}` (callback)
`sync`	`removeEventListener()`	Removes the event listener.	`() => {}` (the event listener you want to remove)

Slidedown Namespace

Example:

await OneSignal.Slidedown.promptPush();

Sync/Async	Function Name	Description	Argument List
`async`	`promptPush`	Displays the notification permission prompt.	`options` (AutoPromptOptions)
`async`	`promptPushCategories`	Displays the notification permission prompt for notification categories.	`options` (AutoPromptOptions)
`async`	`promptSms`	Displays the SMS subscription prompt.	`options` (AutoPromptOptions)
`async`	`promptEmail`	Displays the email subscription prompt.	`options` (AutoPromptOptions)
`async`	`promptSmsAndEmail`	Displays the SMS and email subscription prompts.	`options` (AutoPromptOptions)
`sync`	`addEventListener`	Adds an event listener for the `slidedownShown` event.	- `event` ("slidedownShown"), - `listener` ((wasShown: boolean) => void)
`sync`	`removeEventListener`	Removes an event listener for the `slidedownShown` event.	- `event` ("slidedownShown") - `listener` ((wasShown: boolean) => void)

Push Subscription Namespace

Example:

OneSignal.User.PushSubscription.optIn();

Sync/Async	Property/Function	Description	Argument List
	`id`	Gets the current user's ID.
	`token`	Gets the current user's push notification token.
	`optedIn`	Gets a boolean value indicating whether the current user is subscribed to push notifications.
`async`	`optIn()`	Subscribes the current user to push notifications.
`async`	`optOut()`	Unsubscribes the current user from push notifications.
`sync`	`addEventListener()`	Adds an event listener for the `change` event.	- `event` ("change") - `listener` ((change: SubscriptionChangeEvent) => void)
`sync`	`removeEventListener()`	Removes an event listener for the `change` event.	- `event` ("change") - `listener` ((change: SubscriptionChangeEvent) => void)

Debug Namespace

Example:

OneSignal.Debug.setLogLevel(“trace”);

Function Name	Description	Argument List
`setLogLevel`	Turns on logging with the given log level.	`setLogLevel: string` - `"trace"` - `"debug"` - `"info"` - `"warn"` - `"error"`

Limitations

April 2023

Version 16 (beta)

Please test thoroughly prior to production use.

Any User namespace calls must be invoked after initialization (async). Example: OneSignal.User.addTag("tag", "2");
HTTP environments are not supported.
AMP environments are not supported.
Identity verification is not functional.

January 2023

Version 16 (alpha)

It is recommended this version is used only in development and staging envrionments.

Switching between users via login() and logout() is unsafe. Please stick to single user testing.
Any User namespace calls must be invoked after initialization (async). Example: OneSignal.User.addTag("tag", "2");
Aliases will be available in a future release,
HTTP environments are not supported.
AMP environments are not supported.
Identity verification is not functional.
Outcomes are not functional.

Glossary

OneSignal user

(noun) lowercase

A user of the OneSignal service.

user

(noun) lowercase

An end-user of an application using the OneSignal service. They may or may not have a subscription.

user ID

(noun) lowercase

A OneSignal-provisioned unique identifier for Users (User.onesignal_id).

user external ID

(noun) lowercase

A customer-provisioned unique identifier for Users (User.external_id).

user alias

(noun) lowercase

A customer provisioned key-value pair used to uniquely identify a User.

subscription

(noun) lowercase

An established communication channel between an App and its User, such as a push-subscribed device, email address, or SMS-subscribed phone number.

subscription ID

(noun) lowercase

A OneSignal-provisioned unique identifier for a single subscription.

notification

(noun) lowercase

A unidirectional outbound communication message from an App to one or more Users via their Subscriptions.

notification ID

(noun) lowercase

A OneSignal-provisioned unique identifier for Notifications (Notification.id).

notification external ID

(noun) lowercase

A customer-provisioned unique identifier for Notifications (Notification.external_id).

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

MIGRATION_GUIDE.md

MIGRATION_GUIDE.md

Welcome to the User Model SDK Migration Guide (v16) 👋

Intro

Overview

Users

Subscriptions

Aliases

Guide

1. Setup Changes

Script

Service Worker

2. OneSignal Usages

3. External User ID

4. Custom Setup Changes

ServiceWorker Config

`script.onLoad`

5. API Changes

User Namespace

Notifications Namespace

Slidedown Namespace

Push Subscription Namespace

Debug Namespace

Limitations

April 2023

Version 16 (beta)

January 2023

Version 16 (alpha)

Glossary

Files

MIGRATION_GUIDE.md

Latest commit

History

MIGRATION_GUIDE.md

File metadata and controls

Welcome to the User Model SDK Migration Guide (v16) 👋

Intro

Overview

Users

Subscriptions

Aliases

Guide

1. Setup Changes

Script

Service Worker

2. OneSignal Usages

3. External User ID

4. Custom Setup Changes

ServiceWorker Config

script.onLoad

5. API Changes

User Namespace

Notifications Namespace

Slidedown Namespace

Push Subscription Namespace

Debug Namespace

Limitations

April 2023

Version 16 (beta)

January 2023

Version 16 (alpha)

Glossary

`script.onLoad`