Integrate OneSignal Web Push Notifications into your Vue.js application using either the onesignal-vue or @onesignal/onesignal-vue3 plugin. Learn how to install, configure, and customize service workers for seamless push delivery.
This guide explains how to integrate OneSignal push notifications into a Vue.js application. It covers both Vue 2 and Vue 3 using the official OneSignal Vue plugins, along with key setup considerations including service worker configuration and TypeScript support.
Make sure you install a plugin version compatible with your Vue environment.
Vue | OneSignal Plugin |
---|---|
2 | onesignal-vue |
3 | onesignal-vue3 |
Install via your preferred package manager:
Import the OneSignal service and initialize it in your root component. The init
function returns a promise that resolves when OneSignal is loaded.
Replace YOUR_APP_ID
with your OneSignal app ID found in Keys & IDs.
The OneSignal plugin automatically exposes a $OneSignal
global property accessible inside the application.
You can also leverage Vue’s Composition API via the useOneSignal()
hook that can be called from within setup
.
You can customize your initialization with additional init
parameters.
If you haven’t done so already, you will need to download the OneSignal Service Worker file to add to your site.
The OneSignalSDKWorker.js
file must be publicly accessible. You can put it in your public
directory, top-level root, or a subdirectory. However, if you are placing the file in a subdirectory and/or have another service worker for your site, then make sure to specify the path. See OneSignal Service Worker for details.
Option | Description |
---|---|
serviceWorkerParam | Scope controlled by the OneSignal worker. Recommendation: Use a custom sub-path (e.g., "/onesignal/" ). |
serviceWorkerPath | Path to your hosted OneSignal service worker file (e.g., "onesignal/OneSignalSDKWorker.js" ). Must be publicly accessible. |
Example:
/OneSignalSDKWorker.js
/onesignal/OneSignalSDKWorker.js
as set in the previous step.Visit the path in your browser to confirm it’s accessible.
If you used root:
If using the example path:
It should return valid JavaScript.
<React.StrictMode>
causing effects to run twice in development. To resolve it, remove <React.StrictMode>
from your root component during development.Strict mode only affects development—it does not impact production builds.
This guide helps you verify that your OneSignal SDK integration is working correctly by testing push notifications and subscription registration.
Launch your site on a test device.
Web push native permission prompt
Check your OneSignal dashboard
Check the OneSignal dashboard:
Dashboard showing subscription with 'Subscribed' status
Test subscriptions are helpful for testing a push notification before sending a message.
Add to Test Subscriptions.
In the dashboard, next to the subscription, click the Options (three dots) button and select Add to Test Subscriptions.
Adding a device to Test Subscriptions
Name your subscription.
Name the subscription so you can easily identify your device later in the Test Subscriptions tab.
Dashboard showing the 'Name your subscription' field
Create a test users segment.
Go to Audience > Segments > New Segment.
Name the segment.
Name the segment Test Users
(the name is important because it will be used later).
Add the Test Users filter and click Create Segment.
Creating a 'Test Users' segment with the Test Users filter
Get your App API Key and App ID.
In your OneSignal dashboard, go to Settings > Keys & IDs.
Update the provided code.
Replace YOUR_APP_API_KEY
and YOUR_APP_ID
in the code below with your actual keys. This code uses the Test Users
segment we created earlier.
Run the code.
Run the code in your terminal.
Check images and confirmed delivery.
If all setup steps were completed successfully, the test subscriptions should receive a notification.
Expanded push notification with image on Chrome macOS
Check for confirmed delivery.
In your dashboard, go to Delivery > Sent Messages, then click the message to view stats.
You should see the confirmed stat, meaning the device received the push.
Delivery stats showing confirmed delivery
If you’re on a Professional plan or higher, scroll to Audience Activity to see subscription-level confirmation:
Confirmed delivery at the device level in Audience Activity
Need help? Contact support@onesignal.com
with the following information:
.txt
fileWe’ll be happy to help!
Previously, we demonstrated how to create web push Subscriptions. Now we’ll expand to identifying Users across all their subscriptions (including push, email, and SMS) using the OneSignal SDK. We’ll cover External IDs, tags, multi-channel subscriptions, privacy, and event tracking to help you unify and engage users across platforms.
Use an External ID to identify users consistently across devices, email addresses, and phone numbers using your backend’s user identifier. This ensures your messaging stays unified across channels and 3rd party systems (especially important for Integrations).
Set the External ID with our SDK’s login
method each time they are identified by your app.
OneSignal generates unique read-only IDs for subscriptions (Subscription ID) and users (OneSignal ID).
As users download your app on different devices, subscribe to your website, and/or provide you email addresses and phone numbers outside of your app, new subscriptions will be created.
Setting the External ID via our SDK is highly recommended to identify users across all their subscriptions, regardless of how they are created.
Tags are key-value pairs of string data you can use to store user properties (like username
, role
, or preferences) and events (like purchase_date
, game_level
, or user interactions). Tags power advanced Message Personalization and Segmentation allowing for more advanced use cases.
Set tags with our SDK addTag
and addTags
methods as events occur in your app.
In this example, the user reached level 6 identifiable by the tag called current_level
set to a value of 6
.
A user profile in OneSignal with a tag called "current_level" set to "6"
We can create a segment of users that have a level of between 5 and 10, and use that to send targeted and personalized messages:
Segment editor showing a segment targeting users with a current_level value of greater than 4 and less than 10
Screenshot showing a push notification targeting the Level 5-10 segment with a personalized message
Earlier we saw how our SDK creates web push subscriptions to send push. You can also reach users through emails and SMS channels by creating the corresponding subscriptions.
addEmail
method to create email subscriptions.addSms
method to create SMS subscriptions.If the email address and/or phone number already exist in the OneSignal app, the SDK will add it to the existing user, it will not create duplicates.
You can view unified users via Audience > Users in the dashboard or with the View user API.
A user profile with push, email, and SMS subscriptions unified by External ID
Best practices for multi-channel communication
To control when OneSignal collects user data, use the SDK’s consent gating methods:
setConsentRequired(true)
: Prevents data collection until consent is given.setConsentGiven(true)
: Enables data collection once consent is granted.See our Privacy & security docs for more on:
Use SDK listeners to react to user actions and state changes.
The SDK provides several event listeners for you to hook into. See our SDK reference guide for more details.
Explore more capabilities to enhance your integration:
Make sure you’ve enabled all key features by reviewing the Web push setup guide.
For full details on available methods and configuration options, visit the Web SDK reference.
Need help?
Chat with our Support team or email support@onesignal.com
Please include:
We’re happy to help!
Integrate OneSignal Web Push Notifications into your Vue.js application using either the onesignal-vue or @onesignal/onesignal-vue3 plugin. Learn how to install, configure, and customize service workers for seamless push delivery.
This guide explains how to integrate OneSignal push notifications into a Vue.js application. It covers both Vue 2 and Vue 3 using the official OneSignal Vue plugins, along with key setup considerations including service worker configuration and TypeScript support.
Make sure you install a plugin version compatible with your Vue environment.
Vue | OneSignal Plugin |
---|---|
2 | onesignal-vue |
3 | onesignal-vue3 |
Install via your preferred package manager:
Import the OneSignal service and initialize it in your root component. The init
function returns a promise that resolves when OneSignal is loaded.
Replace YOUR_APP_ID
with your OneSignal app ID found in Keys & IDs.
The OneSignal plugin automatically exposes a $OneSignal
global property accessible inside the application.
You can also leverage Vue’s Composition API via the useOneSignal()
hook that can be called from within setup
.
You can customize your initialization with additional init
parameters.
If you haven’t done so already, you will need to download the OneSignal Service Worker file to add to your site.
The OneSignalSDKWorker.js
file must be publicly accessible. You can put it in your public
directory, top-level root, or a subdirectory. However, if you are placing the file in a subdirectory and/or have another service worker for your site, then make sure to specify the path. See OneSignal Service Worker for details.
Option | Description |
---|---|
serviceWorkerParam | Scope controlled by the OneSignal worker. Recommendation: Use a custom sub-path (e.g., "/onesignal/" ). |
serviceWorkerPath | Path to your hosted OneSignal service worker file (e.g., "onesignal/OneSignalSDKWorker.js" ). Must be publicly accessible. |
Example:
/OneSignalSDKWorker.js
/onesignal/OneSignalSDKWorker.js
as set in the previous step.Visit the path in your browser to confirm it’s accessible.
If you used root:
If using the example path:
It should return valid JavaScript.
<React.StrictMode>
causing effects to run twice in development. To resolve it, remove <React.StrictMode>
from your root component during development.Strict mode only affects development—it does not impact production builds.
This guide helps you verify that your OneSignal SDK integration is working correctly by testing push notifications and subscription registration.
Launch your site on a test device.
Web push native permission prompt
Check your OneSignal dashboard
Check the OneSignal dashboard:
Dashboard showing subscription with 'Subscribed' status
Test subscriptions are helpful for testing a push notification before sending a message.
Add to Test Subscriptions.
In the dashboard, next to the subscription, click the Options (three dots) button and select Add to Test Subscriptions.
Adding a device to Test Subscriptions
Name your subscription.
Name the subscription so you can easily identify your device later in the Test Subscriptions tab.
Dashboard showing the 'Name your subscription' field
Create a test users segment.
Go to Audience > Segments > New Segment.
Name the segment.
Name the segment Test Users
(the name is important because it will be used later).
Add the Test Users filter and click Create Segment.
Creating a 'Test Users' segment with the Test Users filter
Get your App API Key and App ID.
In your OneSignal dashboard, go to Settings > Keys & IDs.
Update the provided code.
Replace YOUR_APP_API_KEY
and YOUR_APP_ID
in the code below with your actual keys. This code uses the Test Users
segment we created earlier.
Run the code.
Run the code in your terminal.
Check images and confirmed delivery.
If all setup steps were completed successfully, the test subscriptions should receive a notification.
Expanded push notification with image on Chrome macOS
Check for confirmed delivery.
In your dashboard, go to Delivery > Sent Messages, then click the message to view stats.
You should see the confirmed stat, meaning the device received the push.
Delivery stats showing confirmed delivery
If you’re on a Professional plan or higher, scroll to Audience Activity to see subscription-level confirmation:
Confirmed delivery at the device level in Audience Activity
Need help? Contact support@onesignal.com
with the following information:
.txt
fileWe’ll be happy to help!
Previously, we demonstrated how to create web push Subscriptions. Now we’ll expand to identifying Users across all their subscriptions (including push, email, and SMS) using the OneSignal SDK. We’ll cover External IDs, tags, multi-channel subscriptions, privacy, and event tracking to help you unify and engage users across platforms.
Use an External ID to identify users consistently across devices, email addresses, and phone numbers using your backend’s user identifier. This ensures your messaging stays unified across channels and 3rd party systems (especially important for Integrations).
Set the External ID with our SDK’s login
method each time they are identified by your app.
OneSignal generates unique read-only IDs for subscriptions (Subscription ID) and users (OneSignal ID).
As users download your app on different devices, subscribe to your website, and/or provide you email addresses and phone numbers outside of your app, new subscriptions will be created.
Setting the External ID via our SDK is highly recommended to identify users across all their subscriptions, regardless of how they are created.
Tags are key-value pairs of string data you can use to store user properties (like username
, role
, or preferences) and events (like purchase_date
, game_level
, or user interactions). Tags power advanced Message Personalization and Segmentation allowing for more advanced use cases.
Set tags with our SDK addTag
and addTags
methods as events occur in your app.
In this example, the user reached level 6 identifiable by the tag called current_level
set to a value of 6
.
A user profile in OneSignal with a tag called "current_level" set to "6"
We can create a segment of users that have a level of between 5 and 10, and use that to send targeted and personalized messages:
Segment editor showing a segment targeting users with a current_level value of greater than 4 and less than 10
Screenshot showing a push notification targeting the Level 5-10 segment with a personalized message
Earlier we saw how our SDK creates web push subscriptions to send push. You can also reach users through emails and SMS channels by creating the corresponding subscriptions.
addEmail
method to create email subscriptions.addSms
method to create SMS subscriptions.If the email address and/or phone number already exist in the OneSignal app, the SDK will add it to the existing user, it will not create duplicates.
You can view unified users via Audience > Users in the dashboard or with the View user API.
A user profile with push, email, and SMS subscriptions unified by External ID
Best practices for multi-channel communication
To control when OneSignal collects user data, use the SDK’s consent gating methods:
setConsentRequired(true)
: Prevents data collection until consent is given.setConsentGiven(true)
: Enables data collection once consent is granted.See our Privacy & security docs for more on:
Use SDK listeners to react to user actions and state changes.
The SDK provides several event listeners for you to hook into. See our SDK reference guide for more details.
Explore more capabilities to enhance your integration:
Make sure you’ve enabled all key features by reviewing the Web push setup guide.
For full details on available methods and configuration options, visit the Web SDK reference.
Need help?
Chat with our Support team or email support@onesignal.com
Please include:
We’re happy to help!