This guide explains how to integrate OneSignal with your website using Google Tag Manager (GTM). It covers the OneSignal service worker setup, the updated initialization code, and introduces a new step to send user profile tags (attributes) to OneSignal.

Setup your OneSignal app

Follow our Web push setup docs. When prompted, note your App ID, which you will replace in the code below.

Copy & update the OneSignal initialization code

When you get to the step Add Code to Site click Copy Code.

Copy the code provided in your OneSignal dashboard.

You will need to make some adjustments to the code to work with Google Tag Manager as shown here:

<script src="https://cdn.onesignal.com/sdks/web/v16/OneSignalSDK.page.js" defer></script>
<script>
  window.OneSignalDeferred = window.OneSignalDeferred || [];
  // remove async
  OneSignalDeferred.push( function(OneSignal) {
    // remove await
    OneSignal.init({
      // replace with YOUR_APP_ID
      appId: "YOUR_APP_ID",
    })
    // Add event to track OneSignal initialization if desired
      .then(function() {
        dataLayer.push({ event: 'OneSignalInitialized' });
      }).catch(function(e) {
        console.error("OneSignal initialization failed:", e);
    });
  });
</script>

Setup Google Tag Manager

Login to your Google Tag Manager Account and setup a new tag called OneSignal Init.

The Tag Configuration/Tag Type should be Custom HTML.

Paste the OneSignal code into the HTML field.

Under Advanced Settings > Tag firing options select Once per page.

For Triggering select Initialization - All Pages.

Click Save at the top right to save your tag.

Back on your Workspace, you can Publish or Submit to deploy the changes.

Ensure that your container is installed on every page of the site you want OneSignal to load and the initialization tag is firing as expected.

Refer to Google Tag Manager Help if you need additional setup assistance.

Testing

Visit your website and you should be prompted to subscribe to push notifications based on the prompt settings you setup. See Web permission prompts for details.

Check your OneSignal Dashboard Audience > Subscriptions to see your Subscriptions. Find your subscription and set it as a Test subscriptions.

Then head over to Messages > New Push to send yourself a notification.

If running into issues, checkout the Web Push Troubleshooting Guide for common fixes.

Visit Web Push Tutorials for next steps or continue below for other GTM options.


Add data tags

This step sends custom User Data Tags (attributes) to OneSignal from GTM using the OneSignal.User.addTags method.

Use the following code snippet to set tags. Replace "TAG_1" and "VALUE_1" with your desired tag key and value:

<script>
window.OneSignalDeferred = window.OneSignalDeferred || [];
OneSignalDeferred.push(function(OneSignal) {
  OneSignal.User.addTags({
      "TAG_1": "VALUE_1"
  });
});
</script>

Publish the changes

After configuring the new tag and its trigger group, publish your container to deploy the new user tagging functionality.


Troubleshooting

Use GTM’s Preview and Debug Mode to ensure that both the initialization tag and the user profile tagging tag fire correctly.

Check the browser console for any OneSignal-related errors and review your OneSignal Dashboard for error notifications.

DataLayer Events: Confirm that the events (e.g., OneSignalInitialized) are pushed into the dataLayer as expected for further tracking in your analytics setup.

See Web SDK troubleshooting for more details.

With these updates, your website now uses the latest OneSignal initialization and sends custom user profile tags via GTM using the OneSignal.User.addTags method.

The added trigger group ensures that the tag fires only after OneSignal has initialized and when your chosen conditions are met.

For additional customization or advanced tracking, consult our Web SDK reference and Google Tag Manager documentation.

If you have any questions or run into issues, please refer to Web SDK troubleshooting or reach out to OneSignal support.