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", { item_list_id: "related_products", item_list_name: "Related products", items: [ { item_id: "SKU_12345", item_name: "Stan and Friends Tee", affiliation: "Google Merchandise Store", coupon: "SUMMER_FUN", currency: "USD", discount: 2.22, index: 0, item_brand: "Google", item_category: "Apparel", item_category2: "Adult", item_category3: "Shirts", item_category4: "Crew", item_category5: "Short sleeve", item_list_id: "related_products", item_list_name: "Related Products", item_variant: "green", location_id: "L_12345", price: 9.99, quantity: 1 } ] }); or dataLayer.push({ ecommerce: null }); // Clear the previous ecommerce object. dataLayer.push({ event: "view_item", ecommerce: { items: [ { item_id: "SKU_12345", item_name: "Stan and Friends Tee", affiliation: "Google Merchandise Store", coupon: "SUMMER_FUN", currency: "USD", discount: 2.22, index: 0, item_brand: "Google", item_category: "Apparel", item_category2: "Adult", item_category3: "Shirts", item_category4: "Crew", item_category5: "Short sleeve", item_list_id: "related_products", item_list_name: "Related Products", item_variant: "green", location_id: "L_12345", price: 9.99, quantity: 1 } ] } }); depending on whether you use the DataLayer directly, or rely on gtag. ⚠️ 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 ecommerce object. dataLayer.push({ event: "view_item", news: { items: [ { item_id: "SKU_12345", item_name: "Stan and Friends Tee", index: 0, item_category: "News", item_category2: "Global", item_category3: "US", item_list_id: "related_articles", item_list_name: "Related Articles", location_id: "L_12345", author: "James McAllister" } ] } }); 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 request_id (click_on_recommendation) items[n].version select_item version (click_on_recommendation) items[n].user_group select_item user_group (click_on_recommendation) items[n].item_type Required in all events IF you have more than one item_type item_type An example modified select_item GA4 event would then look like this: dataLayer.push({ event: "select_item", ecommerce: { items: [ { item_id: "SKU_12345", item_type: "product", request_id: "1294bf", version: "Froomle_1", user_group: "froomle", item_name: "Stan and Friends Tee", affiliation: "Google Merchandise Store", coupon: "SUMMER_FUN", currency: "USD", discount: 2.22, index: 0, item_brand: "Google", item_category: "Apparel", item_category2: "Adult", item_category3: "Shirts", item_category4: "Crew", item_category5: "Short sleeve", item_list_id: "related_products", item_list_name: "Related Products", item_variant: "green", location_id: "L_12345", price: 9.99, quantity: 1 } ] } }); 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. The variable channel is used to identify which version of your website the user is seeing, e.g. "web" and "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. "category" or "item_detail" (please refer to your API context for the different page_types we expect). dataLayer.push({ 'channel': 'web', '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. Additionally, on product_detail pages, we recommend setting an additional variable, namely the context_item. This is the item_id of the item the user is visiting. If there is more than one type of item on your website, you should also provide context_item_type. dataLayer.push({ 'context_item': 'SKU_12345', 'context_item_type': 'product', }); 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. Ideally, optional fields are specified as well (when and where possible). 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. Both can be found in your API contract. 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 as listed in your API contract. 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: "SKU_12345", **item_type: "product", request_id: "1294bf", version: "Froomle_1", user_group: "froomle",** } ] } }); 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. 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 product 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 item_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.