How To Integrate OneSignal Cordova Plugin?

Ever struggled to manage push notifications consistently across iOS and Android in a single hybrid app? If you’ve faced delays, inconsistent delivery, or platform-specific setup issues, you may want to consider integrating OneSignal with Cordova.

OneSignal offers a unified approach to sending and managing notifications across multiple platforms. The Cordova plugin directly connects this service with Cordova apps, allowing developers to implement push notifications without writing separate native code for each platform.
Installing OneSignal Cordova
To start using OneSignal in your Cordova project, the first step is to add the required platforms and install the plugin. Cordova supports multiple environments, but it is best to confirm that your setup includes at least the Android or iOS platform before proceeding.

You can add them with the following commands:

cordova platform add android
cordova platform add ios

Once your project has the platforms configured, install the OneSignal Cordova plugin using:

cordova plugin add onesignal-cordova-plugin --save

This command downloads the plugin and saves it to your project configuration so it remains linked even after rebuilding. After installation, you must connect your app to OneSignal using your unique App ID.

Pro Tip: For newer Cordova CLI versions, use @onesignal/cordova-plugin instead of the legacy onesignal-cordova-plugin.

Open your project’s main JavaScript file, typically located at www/js/index.js, and replace the placeholder value with your OneSignal App ID.

When everything is set, you can build and run your project:

cordova run android
cordova run ios

These commands build the application and deploy it to a connected device or emulator. Always test on a real device because push notifications may not function properly on simulators.
Initialization and Configuration
Once the plugin is installed, the next step is to initialize OneSignal when your Cordova app starts. This is done inside the deviceready event, which ensures the Cordova environment is fully loaded before running any plugin code.

You can add the following snippet inside your www/js/index.js file:

document.addEventListener('deviceready', function () {
    OneSignal.setAppId("YOUR_ONESIGNAL_APP_ID");

    OneSignal.setNotificationOpenedHandler(function (notification) {
        console.log("Notification opened:", notification);
    });

    OneSignal.promptForPushNotificationsWithUserResponse(function (accepted) {
        console.log("Permission accepted:", accepted);
    });
});

This script performs three key actions:

Registers your App ID: Links your Cordova project to your OneSignal account.
Defines an event handler: Detects when a user opens a notification and allows you to respond, such as navigating to a specific page.
Requests permission: Prompts users to allow notifications on their device.

Note: If you’re using OneSignal SDK version 2.x or earlier, replace setAppId() with OneSignal.init(appId, options, notificationOpenedCallback);

Each method must run only after the device is ready. Running them too early will result in the plugin not being recognized. It is also a good practice to test this configuration on both Android and iOS devices to verify that permissions and notifications behave as expected.
Using Core OneSignal Cordova Plugin Features
After initialization, the OneSignal Cordova Plugin gives you access to several useful methods for managing notifications and user data. These methods help you retrieve device information, organize users, and customize how messages are sent and received.

To get the current device state, which includes details like the user ID and subscription status, use:

OneSignal.getDeviceState(function (state) {
    console.log("User ID:", state.userId);
    console.log("Push Enabled:", state.isPushEnabled);
});

This information is essential when linking users to your backend or verifying if notifications are active on a device. You can also segment users based on custom attributes using tags. Tags let you target notifications to specific groups. For example:

OneSignal.sendTags({ role: "admin", plan: "premium" });

Here, users with these tags can later receive tailored notifications. To update or remove a specific tag, use:

OneSignal.deleteTag("role");

When your app manages user accounts, you can associate a user’s internal ID with their OneSignal profile for better tracking:

OneSignal.setExternalUserId("USER_12345");

If the user logs out, clear this ID to prevent data mismatch:

OneSignal.removeExternalUserId();

Wrapping Up
Integrating OneSignal with Cordova is a simple way to add reliable push notifications without maintaining separate native codebases. With a few setup commands and clear initialization steps, you can manage users, track engagement, and send targeted notifications directly from OneSignal’s dashboard.

Before publishing, always test on both platforms and confirm that permissions and device states are configured correctly. Once everything is working, OneSignal takes care of the delivery so you can focus on building better user experiences.