🚧

This documentation is only to be used for the Legacy Version of the OneSignal integration. For the newer V5 version which supports OneSignal's user-centric data model please see OneSignal User Management.

📘

Send personalized push notifications to your users by maintaining a list of device IDs associated with each user within your database, or use OneSignal's external user ID functionality and a user identifier, such as email address or account number.

There are many use cases for sending push notifications to specific users, either individually or as part of a group.

• Alert notification when an event occurs such as message receipt or package delivery.
• Re-engagement notification based on user's prior app activity.
• Promotion notification based on user's product preferences.
• etc.

We recommend two alternate strategies to send personalized push notifications using OneSignal.

1 - Associate Users and Devices within your backend/database

You can associate your app users and their devices via the OneSignal Player Id (oneSignalUserId) and then send push notifications to specific devices.

Obtain the OneSignal Player Id / oneSignalUserId via your app, typically after a successful sign-in, and record within your database by adding to an array of devices for that user. This strategy provides full control so you can send notifications to specific devices, remove devices after a user has not logged in on a device for some time, or even allow multiple user accounts to be logged into your app concurrently from the same device.

Refer to OneSignal's documentation on Player Id

There are two methods to associate users and device OneSignal Player Id. The first uses JavaScript on your website to obtain the device player id, the second uses an API endpoint on your server to POST the same data.

1a - Obtain oneSignalInfo via JavaScript on your website

Add JavaScript to your website, such as a login success page, to retrieve the oneSignalInfo object including including the OneSignal Player ID which is available as oneSignalUserId.

Refer to our documentation on OneSignal Info for JavaScript examples.

Note that on iOS the oneSignalUserId will not be set if the user has declined the consent to opt out of push notifications.

/* Login Page Sample Code */
var gn_oneSignalUserId;

function median_onesignal_info(oneSignalInfo){
  gn_OneSignalUserId = oneSignalInfo.oneSignalUserId;
}

function yourLoginFunction(){
  if(gn_OneSignalUserId){
    $.ajax({
      url: updateUserRecord,
      type: "POST",
      data: {
        yourAppUserId: userId,
        oneSignalUserId = gn_OneSignalUserId
      },
      contentType: "application/json"
    });
  }
}

1b - POST to API endpoint from the native app

Define an API endpoint URL which the app will send a POST request to that includes the user's push token and OneSignal Player Id. The POST request will include any session cookies and complete HTTP headers. These can be used in your back-end to identify the user and match a user account.

The POST request is sent:

1. When the app registers with OneSignal and push tokens are initially created.
2. When a page that matches the URL defined is loaded in the app (e.g. a login success page).

📘

Testing Tips

We strongly recommend specifying .* or All Pages for testing until you have verified you can receive a POST. This will POST the data on all URLs within your app. If you still do not receive the POST verify your endpoint by testing with a tool like cURL or Postman.

2 - Use External User Ids on the OneSignal platform

An alternative to the OneSignal Player Id discussed above is to use OneSignal's External User Id methods to set and remove an external id (such as account number or email address) on the corresponding device record within the OneSignal platform. The benefit of this method is OneSignal manages the relationship between user and device, and you do not need to use your own database. However, the functionality is more limited.

↔️Median JavaScript Bridge

To set an external user id within your app, e.g. after login:

Javascript

median.onesignal.externalUserId.set({
   externalId: STRING // e.g. [email protected]
});

To remove an external user id within your app, e.g. after logout:

Javascript

median.onesignal.externalUserId.remove();

For more information on this strategy refer to OneSignal's documentation on External User Ids

Demo

The results of the median_onesignal_info() function and the OneSignal external user ID functions can be tested on our demo site. Open this page within your app to view and test: https://median.dev/onesignal/

Programmatic Notifications

One of the most common use cases for personalized push is to send notifications programmatically based on events. For instance if a message is sent from one user to another user. Or if an order is delivered. Refer to our documentation on Programmatic Notifications.