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.

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.

📘

Google Tag Manager Help

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.

📘

Troubleshooting

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

If stuck, feel free to contact [email protected] for assistance.

👍

You're Done!

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>

Create a Trigger Group for Firing the Tag

To ensure the tag fires under the proper conditions, configure a Trigger Group that combines:

• Trigger 1: A Custom Event trigger that fires on the event OneSignalInitialized (ensuring OneSignal has been initialized).
• Trigger 2: The additional trigger you want to use (for example, a page view or a custom user event).

To create the Trigger Group:

1. In your GTM Workspace, go to Triggers and click New.
2. Select Trigger Group as the trigger type.
3. Name the trigger group (e.g., "OS Tag – Initialized & Custom Trigger").
4. Under Configure Trigger Group, add the following triggers:
   1. Custom Event Trigger:
      1. Choose Custom Event as the trigger type.
      2. Set the event name to OneSignalInitialized.
   2. Additional Trigger:
      1. Select the trigger that meets your criteria (e.g., All Pages, or a custom trigger such as after user login).
5. Save the Trigger Group.

Create the GTM Tag for Adding User Profile Tags

1. In your GTM Workspace, click New Tag.
2. Set the Tag Configuration to Custom HTML and paste the code snippet from Step 5.1.
3. Under Advanced Settings > Tag firing options, select Once per page (or adjust based on your needs).
4. For Triggering, select the Trigger Group you created in Step 5.2.
5. Save the tag.

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.

👍

Complete!

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.