OneSignal Help & Documentation

Welcome to the OneSignal New IA developer hub. You'll find comprehensive guides and documentation to help you start working with OneSignal New IA as quickly as possible, as well as support if you get stuck. Let's jump right in!

Get Started    Discussions

Google Tag Manager

Adding OneSignal to your Website with Google Tag Manager

Google Tag Manager (GTM) is a free tool made by Google that allows you to integrate tags (snippets of code) into your site.

You can use GTM to add the OneSignal Web Push SDK directly into your site and even setup analytics.

This guide will show you how to setup OneSignal with GTM and add Subscription tracking.

Install OneSignal with Google Tag Manager

1. Setup your OneSignal App

Login to your OneSignal account and follow our OneSignal Web Push SDK Setup Guide.

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

Wordpress Users will not have to copy this code

2. Setup your Google Tag Manager Account

Login to your Google Tag Manager Account where you will see your home page.

2.1 Select "Admin" > "Install Google Tag Manager" and follow the directions for adding the code snippets to each page of your site's and tags if you have not done so already.

2.2 Once you added the code to your site, navigate back to your Workspace where you can select "New Tag" or on the left side "Tags" > "New"

3. Create your OneSignal Init Tag

On the New Tag Screen, name your tag and click "Tag Configuration"

3.1 Select "Custom HTML"

3.2 Paste the OneSignal Init code into the HTML field

3.3 Select "Advanced Settings" and set "Tag firing options" to Once per page

3.4 Click the "Triggering" box and select "All Pages"

3.5 Click "Save" at the top to save your tag

3.6 Back on your Workspace tab, you can "Publish" or "Submit" and "Publish"

👍

You're Done!

Next step: Send your first push notification via the OneSignal Dashboard


OneSignal Event Tracking with GA & GTM

If you have added GTM and OneSignal to your site, have successfully subscribed and have successfully sent yourself a notification, then you can go one step further and add analytics to your GTM.

This guide will use the OneSignal Web Push SDK methods for tracking subscriptions.

Subscription Tracking

Similar to our Google Analytics Subscription Tracking Guide you can use the OneSignal notificationPermissionChange event to detect when a user subscribes, blocks, or dismisses the native browser prompt on your site.

1. Setup the OneSignal Notification Permission Change Event

Select the OneSignal Init Tag you created above

If you have not created a OneSignal init tag, you can create a new Tag in Google Tag Manger

1.1 Add the dataLayer and OneSignal notificationPermissionChange event

Adding a dataLayer is recommended in Google's Tag Manager Support docs

Here is some example code:

<script>
  window.dataLayer = window.dataLayer || [];
  OneSignal.push(function() {
    // Occurs when the user's subscription changes to a new value.
    OneSignal.on('notificationPermissionChange', function(permissionChange) {
      var currentPermission = permissionChange.to;
      console.log('New permission state:', currentPermission);
      window.dataLayer.push({
        'event': 'permissionChangeEvent',
        'currentPermission': currentPermission
      });
   });
});
</script>

1.2 In "Advanced Settings", make sure "Tag firing options" is "Once per page" and "Triggering" is set to "All Pages"

See above step 3 for more details on "Advanced Settings" (step 3.3) and "Triggering" (step 3.4).

Your Tag should look similar to this:

1.3 Click "Save" at the top right

2. Create the Permission Change Event Trigger

In your Tag Manager Workspace, select Triggers > New

2.1 Name the trigger "permissionChangeEvent" and select "Custom Event"

2.2 Add the "Event name" as permissionChangeEvent and "This trigger fires on" "All Custom Events"

2.2 Save the trigger

3. (Optional) Setup a User-Defined Variable

This is for tracking the permission status in GA

3.1 In Workspace, select Variables. Under "User-Defined Variables", select "New"

3.2 Name the Variable currentPermission and for "Variable Configuration" select "Data Layer Variable"

3.3 Make the "Data Layer Variable Name" currentPermission

4. Setup the OneSignal Permission Change Tracking Tag

Back in Workspace, select Tags > New

Name this tag, OS Permission Change Tracking

4.1 Select "Google Analytics - Universal Analytics"

Track Type

Event

Category

OneSignal

Action

Prompt_Permission_Change

Value

{{currentPermission}}

Non-Interaction Hit

False

Google Analytics Settings

{{your_UA_Tracking_Numner}}

Tag firing options

Unlimited

4.2 For Triggering, select your permissionChangeEvent and "Save"

👍

All Done!

Return to your site. Clear your browser data to test your site as a first time user. Subscribe to your site and view the event in Google Analytics.

🚧

Troubleshooting

If experiencing any issues, try debugging with the Tag Manager's Preview and debug containers

FAQ

Why does OneSignal appear to be loaded synchronously?

GTM automatically adds all tags asynchronously and strips out async calls along with labels in HTML tags  That is why when you try adding "async" as shown in our setup code, it only appears as 
<script type="text/javascript" id="" src="https://cdn.onesignal.com/sdks/OneSignalSDK.js"></script>

The file that we load in this call here is very small and is designed to first check if the browser supports push, then if it does, our SDK adds 
<script src="https://cdn.onesignal.com/sdks/OneSignalPageSDKES6.js?v=150712" async=""></script> which is asynchronous and contains the bulk of our SDK.

Updated about a month ago


Google Tag Manager


Adding OneSignal to your Website with Google Tag Manager

Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.