Median.co HomeDeveloper Portal
Documentation

User Management

Suggest Edits

📘

Send personalized push notifications to your users using OneSignal's user management functionality and logging in the current user using an identifier such as email address or account number. For advanced use cases you can target a specific device using `subscription.id`.

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 the following strategy to send personalized push notifications to specific users using OneSignal.

Associate a user within your app as a OneSignal user

OneSignal's latest SDKs employ a user-centric model wherein a unique user interacting with your website/app will be a unique internal OneSignal ID. If the user exists in OneSignal the existing OneSignal ID will be assigned otherwise a new ID will be generated. The OneSignal ID is guaranteed to remain the same across multiple installs and installs across multiple devices as long as you assign the same user the same identifier (e.g email/phone/account number) by "logging in" the user to OneSignal with the median.onesignal.login() method. This strategy provides ease of use as OneSignal tracks all devices belonging to a single user and you can simply target users instead of targeting devices (and manually associating devices to users).

Refer to OneSignal's documentation on user management.

👍

Legacy Support

If you previously used OneSignal's External User ID functionality you can implement the new login method using the same external user id for seamless migration to the user-centric model. If you still have older versions of your app in use you will need to check the current app version using Device Info and call the corresponding median.onesignal.login() or median.onesignal.externalUserId.set() method depending on app version.

Login the OneSignal SDK

Add JavaScript to your website, such as a login success page, to login to the OneSignal with a user identifier. You can use email, phone number, account number, etc. This identifier is used by OneSignal to associate the user and device and will update the active internal OneSignal ID to the unique OneSignal ID for that user.

↔️Median JavaScript Bridge

To login a user to the OneSignal SDK: 

median.onesignal.login("[email protected]");

You can then logout the user when a user logs out in your application so they no longer receive personalized targeted push notifications.

median.onesignal.logout();

Legacy Support - External User ID

If you are migrating from the OneSignal legacy device-centric SDK versions you can use OneSignal's External User ID functionality. Make sure you set the external ID on every app start instead of login so users who are upgrading your app can have this set prior to updating to your new app.

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

↔️Median JavaScript Bridge

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

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

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

median.onesignal.externalUserId.remove();

Retrieve the OneSignal identifiers and save in your database

In some cases you may need to access the active internal oneSignalId, externalId, or subscription.id identifiers which are all available through the OneSignal Info methods.

/* Login Page Sample Code */

async function loginUserAndPostOSId() {
  await median.onesignal.login("[email protected]");

  const osInfo = await median.onesignal.info();

  $.ajax({
    url: updateUserRecord,
    type: "POST",
    data: {
      yourAppUserId: userId,
      oneSignalUserId: osInfo.oneSignalId, // user-specific and will change after login
      oneSignalExternalId:  osInfo.externalId, // will be the same as userId
      oneSignalSubscriptionId:  osInfo.subscription.id // device-specific will not change after login
    },
    contentType: "application/json"
  });
}

👍

Developer Demo

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

Targeting devices and logged out users

If you need to target devices before you have identified and logged in a user or need maximum flexibility and more granular control over a user's devices you can use the subscription.id to target a specific device. The subscription.id, available in OneSignal Info, is unique to each device and will not change if you later login a user on the device. However, this id is not guaranteed to be same across reinstalls of the app. You can send this id to your backend per the example above and use it as part of your messaging strategy.

Targeting groups of users

While subscription.id is recommended for targeting individual devices if you are looking to target groups of devices/users you can use Data Tags. For example, if a logged out (or logged in) user selects they are an employee in your New York City office you can programatically tag them as NYO and target that tag via push messaging.

Programmatic Notifications

One of the most common use cases for personalized push is to send notifications programmatically based on transactions or backend 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 for implementation details.

Updated 5 months ago

Next Steps