How to Trigger Facebook CAPI When User Interacts With an iframe Using GTM and Deviate Tracking
In some cases, Google Tag Manager and its triggers can’t track specific sequences of events, or very specific instances of events such as clicking inside of an iframe on a webpage. The solution is to use a data layer event alongside Deviate Tracking’s tag.
Prerequisites
Make sure GTM is installed
Before adding CAPI Facebook Tracking to a website or web application, Google Tag Manager (GTM) must first be installed. Ensure that GTM has already been installed. Or, install GTM onto any website or web application using <this walkthrough.>
Setup Deviate Tracking Variables
Follow best practices and configure the necessary Deviate Tracking variables in GTM before continuing installation by using <this quick tutorial.> This will save time and reduce mistakes.
Tip:
Javascript can be used to trigger a custom event in GTM programmatically. By inserting the javascript event below, it is possible to track custom event triggers, such as form validations. Or, server-sent events such as sign ups or other dynamic server responses:
| <script>dataLayer.push({‘event’: ‘eventname’});</script> |
In order to correctly trigger this data layer event, two tags are needed to be created; 1) The tag that will track the iframe and 2) the Deviate Tracking tag template. Each of these tags will then have its corresponding triggers configured. Follow the steps below to install and configure these tags properly.
1a. Creating a Tag to track the iFrame
First, navigate to Tags in the left-hand side menu of the GTM Workspace. Click the ‘New’ button to open the Tag settings. Next, click within the Tag Configuration and select the ‘Custom HTML’ tag.
[Choosing the Custom HTML tag type within the Tag configuration settings of GTM]
Next, paste the following HTML code into the text box:
| <script> focus(); var listener = addEventListener(‘blur’, function() { if(document.activeElement === document.getElementById(‘playframe’)) { dataLayer.push({‘event’: ‘eventname’}); } removeEventListener(listener); }); </script> |
Within the HTML code, find document.getElementById, and replace it with a DOM selector that identifies the iframe. The iframe’s DOM selector can be identified using the Inspect Element tool of most browsers. Mozilla Developer Resources has a helpful article on locating DOM selector elements.
Follow the next steps to help find the DOM selector in order to replace the HTML portion from above. First, right click on the iframe in the browser and select Inspect Element.
[Right-clicking on the iframe in Safari to Inspect Element]
Next, locate its HTML identifier, either as a class or element ID. Both the classname or ID will be found as an HTML attribute. The iframe’s classname and ID are identified below as an example:
Element classes are indicated by the HTML element attribute, class=“classname”
[Identifying the Element’s class name in the Element Inspector]
If the iframe is being indicated by its html element class attribute, then replace the HTML portion above with document.querySelector(‘classname’).
Element IDs are indicated by the HTML element attribute, id=“idname”
[Identifying the Element ID in the Element Inspector]
If the iframe is being indicated by its html element ID attribute, then replace the HTML portion with document.getElementById(‘idname’)
Lastly, select ‘Once per page’ for the Tag Firing Options.
[Configuring a GTM Tag to track an iframe using Javascript]
1b. Creating a Trigger for Tag Above (Custom HTML Tag)
Tracking an Event on All Pages
Once the trigger has been configured, navigate to Tags in the left-hand side menu. Click the ‘New’ button to open the Tag settings. Next, click within the Tag Configuration and select Page View.
[Trigger configuration for firing a tag on All Page Views in Google Tag Manager]]
Tracking an Event on Specific Pages
To track this event only on certain pages specified, configure this trigger to fire on ‘Some Page Views.’ Set the first dropdown from ‘Click Text’ to ‘Page URL’ or ‘Page Path’ to configure the Trigger to fire on certain pages only.
Copy the URL of the page(s) with the iframe to track. Either the entire page’s URL or just the page’s path is required to configure the Trigger to fire. The page path is anything after the domain (e.g. .com, .edu, .org) including the forward slash that follows. If any parameters other than the page path is needed, use Page URL. If just the page path, use the Page Path variable.
Example: https://domain.com/game/play
- Page URL: domain.com/game/play
- Page Path: /game/play
Now, set the condition to ‘Contains’ and paste the URL or Page Path in the third drop down.
2a. Creating a Trigger (Deviate Tracking Event Tag)
Create a Trigger in GTM so that the Deviate Tracking tag can fire accordingly. Navigate to Triggers in the left-hand side menu. Click ‘New’ to start configuring the Trigger.
[Image of ‘New’ button in the Trigger section of Workspace]
Scroll to the Other category of Trigger options and select ‘Custom Event.’ In the Event name field, set the event name to match the eventname from the code snippet in the first tip:
| <script>dataLayer.push({‘event’: ‘eventname’});</script> |
The event name can be anything as long as it matches the code snippet as well. Lastly, set this Trigger to fire on ‘All Custom Events’
[Custom Event named ‘eventname’ configured as a trigger in GTM]
2b. Creating the Deviate Tracking Tag
Once the trigger has been configured, navigate to Tags in the left-hand side menu. Click the ‘New’ button to open the Tag settings. Next, click within the Tag Configuration and search the Community Template Gallery for ‘Deviate Tracking’ to find and select the Facebook Conversions API (CAPI) by Deviate Tracking tag.
Set the four Built in Variables that have already been pre-configured; Deviate Tracking Email, Deviate Tracking Key, Facebook Token, Facebook Pixel ID.
Now, Set the Event Type to an appropriate FBQ Standard Event Type to match the intent of the Trigger. For example, ViewContent. You can reference FBQ Standard Event types on Facebook/Meta’s Standard Events Reference guide using this link.
Now, set the Trigger as the one that was just created to track ‘eventname.’
[Configuring the Deviate Tracking tag to a Custom HTML event ‘eventname’]
Test and then publish
Before publishing the GTM Container, test that the Tag is firing accordingly on the correct pages using Preview Mode in GTM.
Tips:
Preventing double firing
Within the Tag configuration settings, selecting the Tag to fire Once Per Page may prevent double firing. In Tag configuration settings, choose Advanced Settings > Tag Firing Options > select Once Per Page.
[Image of selecting the Tag to fire One Per Page within the Deviate Tracking Tag Configuration]
Deviate Tracking PageView tag is configured on the same page
The webpage with the tracked iframe should have the Deviate Tracking Pageview Tag installed and firing as well. Follow this quick start guide to check or install the PageView tag from Deviate Tacking.
Test in Preview Mode (GTM)
Always test in Preview Mode before publishing and to check if the Triggers and Tags are firing properly on the correct pages. Most debugging can be resolved in Preview Mode inside GTM. <Here’s a tutorial to walkthrough using Preview Mode in Google Tag Manager>.
Use Test events mode in facebook events manager
Alternatively, test events using the Test Events Tool in Facebook’s Events Manager if Facebook Pixel is installed on the website or web application in use. <Here is a helpful walkthrough on testing with the Test Event Tool.>
Please note: Make sure that test mode is off in the production environment. To do this, open the Tag configuration and under the ‘User Data Parameters’ is a checkbox asking to ‘Send as a Test Event?’ Ensure that this is unchecked when real data is being tracked. This option should only be enabled when Preview mode is being used in GTM.
[Setting the Tag to send data as a Test Event]
