❗️

Legacy Integration Only

This guide applies only to the legacy version of the OneSignal integration using device-based push targeting. For the updated integration using OneSignal's user-centric model, refer to OneSignal User Management which provides out of the box solutions to associate users with your backend.

Overview

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

• Alerting users of new messages or deliveries
• Re-engaging users based on past activity
• Sending promotional offers aligned with user preferences

This guide presents two ways to send personalized notifications under the legacy model:

Option 1: Manage User–Device Associations in Your Backend

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).

📘

Tip for testing

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.

Option 2: Use OneSignal External User IDs

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

Javascript

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

// Remove an External ID
median.onesignal.externalUserId.remove();

This method simplifies implementation, but offers less flexibility than managing Player IDs yourself. Learn more about External User IDs

Demo and Testing

You can test both methods using the OneSignal Developer Demo. Open it inside your app to inspect the median_onesignal_info() output and confirm external ID handling.

Related Guide: Programmatic Notifications

To send notifications based on backend events (e.g., order shipped, message received), refer to Programmatic Notifications.