Google Tag Manager Integration Guidelines Google Tag Manager, or GTM, is a free tool that enables you to track users across your website and communicate this tracking data to different downstream data analytics products, f.e. Google Analytics, Google Ads, Facebook and of course: Froomle. Integrating events using the Froomle GTM template will require the participation of your GTM administrator, and potentially your front-end and/or back-end developer to make changes to your DataLayer. We strongly recommend using the Google Tag Manager template if you have a pre-existing Tag Manager installation and follow the GA4 Events standard. ⚠️ If you do not yet have a pre-existing Tag Manager installation or you do but don’t follow the GA4 Events standard, be advised that this integration will require significant involvement of your web development team. Prerequisites for a smooth implementation If you have a previous GTM implementation, we assume it is implemented as recommended in their Developer Guide. We expect you to have a DataLayer that contains all the information you wish to pass to Google Tag Manager. We assume you are using the Data Layer version 2. We use the GA4 standard for tracking events in your Data Layer. As many of you have already implemented a Data Layer following this standard, Froomle will piggy-back onto their events, thereby limiting the additional effort required from your web development team. 💪 Tracking Froomle events with GTM Step 0: Import Froomle Google Tag Manager Template Below you find the latest version of the Froomle Media Template. Froomle Media Template. To use it, open the “Workspace” you wish to add Froomle tracking to on tagmanager.google.com. In the bottom right of the left navigation bar, you will find “Templates”. Click “New”, which will open up the Template Editor. Use the breadcrumbs menu in the top right of the page and select “Import”. Now, add the Froomle Media Template file you downloaded. After doing so, you should see the following info populated in the Template Editor Window Click the “Save” button at the top, the Froomle template is now ready for use. Step 1: Google Analytics 4 (Data Layer) Events Before we get started configuring GTM, we first need to identify what exactly needs to be configured in the Data Layer. 👀 Every GA4 event will have a counterpart as a Froomle Event. GA4 Events in your Data Layer Froomle’s GTM Template works best when you are already using the GA4 Events standard combined with a Data Layer. We made it so that every GA4 Data Layer/gtag event has a logical Froomle counterpart, both as a tag and Froomle event. Specifically, we use the following GA4 Events GA4 Event Needed for view_item detail_pageview view_item_list impression select_item click_on_recommendation add_to_cart add_to_cart remove_from_cart remove_from_cart purchase purchase add_to_wishlist item_interaction share item_interaction Please check the Event section in our documentation for an overview of Froomle events required to power your modules. ⚠️ You may notice that Froomle’s page_visit and checkpoint do not have a GA4 counterpart, this will be cleared up in later sections. If you already implement the required GA4 events in your Data Layer: Great! If you don’t, please read the Google documentation carefully and identify whether an equivalent event is available in your Data Layer. A typical GA4 event looks like this: gtag("event", "view_item", { items: [ { item_id: "item_id_123", item_type: "article" } ] }); or dataLayer.push({ ecommerce: null }); // Clear the previous ecommerce object. dataLayer.push({ event: "view_item", ecommerce: { items: [ { item_id: "item_id_123", item_type: "article" } ] } }); depending on whether you use the DataLayer directly, or rely on gtag. It could be that your events contain more fields than shown above. This is not a problem, Froomle selects only the necessary information from e.g. the items array and ignores the rest. To avoid confusion, we only focus on the fields relevant to Froomle on this page. ⚠️ The GA4 Event Examples are heavily e-commerce inspired. Don’t let this discourage you to use them for media and news purposes. A similar example for news could look something like this: dataLayer.push({ news: null }); // Clear the previous news object. dataLayer.push({ event: "view_item", news: { items: [ { item_id: "item_id_123", item_type: "article" } ] } }); Froomle requires you add some additional variables to your GA4 events. GA4 Variables Required in GA4 Event Fieldname in Froomle Documentation items[n].request_id select_item, view_item_list request_id, can be retrieved from recommendation response (click_on_recommendation,impression) items[n].user_group select_item, view_item_list user_group, can be retrieved from recommendation response (click_on_recommendation, impression) items[n].item_list_name select_item, view_item_list list_name, can be retrieved from recommendation response (click_on_recommendation, impression) items[n].item_type Required in all events action_item_type (e.g. (detail_pageview) An example modified select_item GA4 event would then look like this: dataLayer.push({ event: "select_item", ecommerce: { items: [ { item_id: "item_id_123", item_type: "article", request_id: "78945", user_group: "froomle", item_list_name: "continue_reading", // needs to match the list_name used in the recommendation response } ] } }); Page-scope Variables in your Data Layer Lastly, Froomle needs two Data Layer variables to be set on every page, as in this example. These are variables that are not necessarily tied to your users' interactions with your website, but instead give you some "context" on the page. Froomle expects two page-scope variables to always be present: channel and page_type. More information on these variables and the allowed values can be found on Step 2: Understanding the Froomle platform. The variable channel is used to identify which version of your website the user is seeing, e.g. "www-mobile". It is important to make this distinction when analyzing user behavior: different channels lead to different user experiences. The variable page_type is used to identify what kind of page the user is currently on, e.g. "home". dataLayer.push({ 'channel': 'www-mobile', 'page_type': 'home', }); If variables with this meaning, but with a different name, are already present, these can be used in the User-Defined Variables you configure in the next section. Step 2: Set variables 👀 Here you will create a User-Defined Variable for all fields required for the tags in the Froomle GTM template. To successfully send any event to Froomle, at least all required fields need to be specified. Generally speaking, to add a variable you need to complete the following steps. Navigate to the "variables" tab in your Google Tag Manager Container (tagmanager.google.com) Under "User-Defined Variables" click "New". image::gtm/GTM_4.png[] Click on the "Variable Configuration" box. You will see the "Choose variable type" popup. Constant Variables To be able to connect to Froomle’s Events API, you will need to specify a subdomain and environment. These will be communicated to you by your account manager. It is best to declare these as “User-Defined Variables” of type “Constant”, so that you can refer to them in all your tags. An example is shown below ℹ️ Use the values of subdomain and environment communicated to you by your account manager. Items Array First, we create a ”User-Defined Variable” of type “Data Layer Variable” named “items”. If you are using the GA4 (Ecommerce) standard as in this example. dataLayer.push({ event: "select_item", ecommerce: { items: [ { item_id: "item_id_123", item_type: "article", request_id: "1294bf", user_group: "froomle", item_list_name: "list_name_used_in_recommendation_request" } ] } }); Your configuration will look like this, where you refer to the variable ecommerce.items as defined in your Data Layer. Froomle will parse the fields it requires out of the items array in your GA4 event automatically. (As a reminder of what your items array looks like, check out the Data Layer example right above.) 1st Party Cookies Second, we create two User-Defined Variables for our user identifiers: device_id and login_id. Most often, both will be configured as a 1st Party Cookie. See Users for more information about how Froomle uses these user identifiers. Data Layer Variables Finally, we create a separate “User-Defined Variable” of type “Data Layer Variable” for all fields required by Froomle events that are not a part of the GA4 items array. When you’re done, your User-Defined Variables Overview will look something like this Step 3: Create triggers 👀 Here, you will create a Trigger for every Tag (= Froomle Event) you are required to configure. Next, we need to create triggers. These triggers will later be assigned to the matching tag. Triggers can be set to fire when Data Layer events are pushed onto the Data Layer by using a “Custom Event” Trigger Type. For Event name, use the name of the GA4 event pushed onto the DataLayer, and select trigger on “All custom events”. Below you find an example trigger configuration for the detail_pageview tag: All Froomle Events that can be triggered from GA4 Events are found in the table below. GA4 Event Needed for view_item detail_pageview view_item_list impression select_item click_on_recommendation add_to_cart add_to_cart remove_from_cart remove_from_cart purchase purchase add_to_wishlist item_interaction If you already have existing triggers for these GA4 Events, you do not need to define Froomle-specific triggers but can refer to these in your Froomle tags. You will note that some Froomle events do not have a GA4 counterpart, f.e. page_visit and checkpoint. For the page_visit event, we recommend the following Trigger configuration in which you exclude the page_type that matches your article detail page (as we receive a detail_pageview on this page). For checkpoint events we recommend you add your own checkpoint Data Layer event and use this as a trigger: Step 4: Create tags 👀 Here, you will create a GTM tag for every Froomle event you are required to configure. Now that your Data Layer, your variables and triggers are set up, adding tags is a piece of cake! When creating a new tag, choose the Froomle template under the header "Custom" in the right navigation bar. Then proceed to configure the tag Choose the correct Froomle event_type in the drop-down. For every field link it to the appropriate “User-Defined Variable”. Next add the appropriate "Trigger" to the event under "Triggering". Step 5: Does everything work like it should? Don’t forget to save and publish your changes. You can now check that everything is working using the Google Tag Manager preview mode. After connecting and doing the action which should trigger an event (for example, go to an article_detail page), check that the appropriate trigger was fired and that all variables are filled with the right value.) Afterwards, also go to the Developer console in the browser pop-up of your website (opened by Google Tag Manager Preview). In the console tab you should see two events: Froomle: Script Loaded Successfully API called successfully FAQ/Troubleshooting I don’t see "Script loaded successfully" in my Developer Console! 😱 First navigate to the network tab in your developer tools. Next, type "froomle" in the search bar at the top. Make sure to check the "preserve log" tickbox. Then refresh the page. If no Javascript snippet with Froomle in the name was loaded, it is likely there are no tags being triggered on this page. Check Tag Assistent to troubleshoot. I don’t see "API called successfully" in my Developer Console! 😱 If you don’t see "API called successfully" you should see an error message instead. If it is a 500 error message, contact support@froomle.com for resolution. A 400 message indicates that the event body was not in the right format or missing required fields. Please check that the information is passed correctly in the Data Layer and that the tag is set up correctly.