Server-side tracking with Google Tag Manager (GTM server container)

What is server-side tracking with Google Tag Manager?

Raptor tracking records how visitors interact with your website, such as which products they view, add to the basket and purchase. Raptor uses this data to give each visitor more relevant product recommendations.

With server-side Google Tag Manager (sGTM), your website sends its events to your own tagging server, which then forwards them to Raptor. No Raptor script is loaded in the visitor's browser. Raptor provides a ready-made tag template for server containers in the GTM Community Template Gallery, and this article walks you through the setup step by step.

Prerequisites

• A server-side GTM container that is up and running. See Google's server-side tagging overview
• A Google tag or GA4 setup on your website that sends its data to the server container.
• Your Raptor Customer ID, which you can find in the Raptor Control Panel.
• A cookie consent solution on your website. Raptor tags must only fire after the visitor has given consent.
• A basic understanding of GTM: tags, triggers, variables and clients.

Key terms

Server container: A GTM container that runs on your own tagging server instead of in the visitor's browser. It receives events from your website and forwards them to tools such as Raptor.

Client: The part of the server container that receives incoming requests and turns them into event data. The built-in GA4 client is usually all you need.

Event data: The information in each incoming event, such as the event name (view_item, add_to_cart, purchase) and the products involved (items). The Raptor tags read their values from the event data.

Parameters (p1, p2, p3 ...): Raptor receives every event as a set of numbered parameters. What each parameter contains is specific to your account and is listed on the Implementing tracking page in the Raptor Control Panel.

How it works

1. Your website sends events to the server container, usually through the Google tag or GA4 tag in your web container.
2. A client in the server container, usually the built-in GA4 client, receives each event and turns it into event data.
3. Raptor Event Tracking tags read the event data and send the events directly from the server to Raptor. You create one tag for each type of event.

How to add the Raptor template to your server container

1. Open your server container in GTM.
2. Select Templates in the left-hand menu.
3. Under Tag Templates, click Search Gallery.
4. Search for "Raptor".
5. Select Raptor Event Tracking and click Add to Workspace.

The template is now listed under Tag Templates.

How to make sure your website sends events to the server container

1. In your web container, set up the Google tag to send data to your tagging server (the server_container_url setting). See Google's guide 
2. Make sure your website sends the GA4 e-commerce events, such as view_item, add_to_cart, remove_from_cart, view_cart and purchase, including their items. Most e-commerce platforms do this out of the box. If yours does not, your web developer can add it. See Google's GA4 e-commerce documentation
3. In your server container, check under Clients that a client receives the events. The built-in GA4 client is usually already there.

Inspect the incoming event data

1. Click Preview in the server container.
2. Open your website in another tab and browse to a product page.
3. Select an event in the left-hand list and open the Event Data tab.
   
   

A product view looks like this:

{
    event_name: 'view_item',
    page_location: 'https://www.example.com/products/macbook-pro',
    currency: 'DKK',
    items: [
        {
            item_id: '12345',
            item_name: 'Apple Macbook Pro',
            item_brand: 'Apple',
            item_category: 'Laptops',
            item_variant: 'Gray',
            price: 12995,
            quantity: 1
        }
    ]
}

To use a value in a Raptor tag, create a variable of the type Event Data with the path to the value as its Key Path, for example items.0.item_id for the product ID above.

How to set up a page view tag

Start with a page view tag. It is the simplest event and confirms that the connection from your server container to Raptor works.

1. Select Tags in the left-hand menu and click New.
2. Click Tag Configuration and select Raptor Event Tracking.
3. Enter your Customer ID in Raptor Customer Id.
4. Under Event Type, select Page View (pageview).
5. Under Triggering, create a Custom trigger that fires when Event Name equals page_view.
6. Name the tag, for example "Raptor - Pageview".
7. Click Save.

Verify the setup

1. Click Preview in the server container, then open your website so that it sends events to the server container.
2. Accept cookies on your website.
3. In the server container's Preview, select the page_view event and check that "Raptor - Pageview" is listed under Tags Fired.
4. Open the Request tab and check that a request to t.raptorsmartadvisor.com is listed under Outgoing HTTP Requests.
5. Open the Live Tracking Stream in the Raptor Control Panel (Data Management > Live Tracking Stream). "pageview" events now appear.

How to create an event tag

Create one event tag for each type of visitor action you want to track. The example below sets up a product view ("visit") event. All other events follow the same pattern.

1. Select Tags in the left-hand menu and click New.
2. Click Tag Configuration and select Raptor Event Tracking.
3. Enter your Customer ID in Raptor Customer Id.
4. Under Event Type, select Product Detail (visit).
5. Under Product Datalayer, select where the tag finds the product information (see Choose the source of the product information below).
6. Under Parameter Mapping, map your values to Raptor parameters (see Map values to Raptor parameters below).
7. Under Triggering, create a Custom trigger that fires when Event Name equals view_item. As with the page view tag, it must only fire after cookie consent has been given.
8. Name the tag. We recommend "Raptor" followed by the event, for example "Raptor - Visit".
9. Click Save.
   
   

Event types

Choose the source of the product information

• Option A: Product object (recommended). Create an Event Data variable with the Key Path items.0 (the first product in the list) and call it, for example, "Event Data - first item". Select it in Product Detail Object. You can then refer to each value by its field name, such as item_id or price.
• Option B: Individual variables. Leave Product Detail Object empty and create one Event Data variable per value instead, for example "Event Data - item name" with the Key Path items.0.item_name.

Map values to Raptor parameters

The standard Raptor events and their parameters are described in Tracking Events & Parameters Reference.

The parameter setup for your own account, including which value belongs in which parameter for each event, is in the Raptor Control Panel under Data Management > Implementing tracking.

In the tag, click Add Parameter under Parameter Mapping once for each parameter listed for the event. Each row has three fields:

Test the event

1. Click Preview in the server container and open a product page on your website.
2. Select the view_item event and check that "Raptor - Visit" is listed under Tags Fired.
3. Under Outgoing HTTP Requests, check the request to t.raptorsmartadvisor.com. It shows the parameters that were sent, for example p1=visit&p2=12345.
4. Open the Live Tracking Stream and check that a "visit" event appears. Compare its values with the event data to make sure every parameter is mapped correctly.

Values sent automatically

Besides the mapped parameters, the tag sends these values with every event. You do not need to set them up.

Purchase events

When you select Purchase (buy), the Product Detail Object field is replaced by Purchased Products Array.

1. Create an Event Data variable with the Key Path items, which holds all products in the order.
2. Select it in Purchased Products Array.
3. Under Parameter Mapping, map each parameter by field name, for example item_id, price and quantity.
4. Under Triggering, create a Custom trigger that fires when Event Name equals purchase.

The tag sends a separate "buy" event to Raptor for each product in the order.

Calculate subtotal

When Calculate subtotal is selected, the tag calculates the subtotal of each product (price × quantity) and sends it to Raptor.

The parameters for price, quantity and subtotal are set under Custom Parameter Mapping. The defaults are:

• Item Price Parameter Number: 12
• Quantity Parameter Number: 13
• Subtotal Parameter Number: 5

Price and quantity must also be mapped under Parameter Mapping, as the subtotal is calculated from the mapped values. Only change these numbers if the buy event on the Implementing tracking page lists different parameters.

Empty the stored basket after the purchase

Keep Empty the stored basket after the purchase selected. Once an order is completed, the basket on your website is empty, and this setting empties the basket stored by the tag as well.

Basket events

Raptor needs the complete basket content with every basket event, not only the product that was added or removed. GA4 basket events such as add_to_cart usually only contain the product that changed, so the tag can keep track of the basket for you.

Under Basket Content Source, select one of two options:

• Stored by the tag in a cookie in the visitor's browser (recommended): The tag stores the basket in a first-party cookie (rsaBasket), updates it with every basket event and sends the complete basket to Raptor as a comma-separated list of product IDs.
• Provided in the event data: Your website already sends the complete list of basket products with every basket event. Map it to the basket content parameter (usually p10) under Parameter Mapping, like any other value. The product IDs must be a comma-separated list, for example 1234,4567,3456.
  
  

Settings when the tag stores the basket

Recommended setup

Create one tag per basket action:

Set basket

Set basket replaces the stored basket with the complete list of products from the event data and sends the updated basket to Raptor. Use it wherever your website sends the full basket, for example view_cart on the basket page or begin_checkout. This keeps the stored basket in sync, even if the basket changed in ways the other basket tags did not register.

{
    event_name: 'view_cart',
    items: [
        { item_id: '1234', item_name: 'T-shirt', quantity: 2 },
        { item_id: '4567', item_name: 'Cap', quantity: 1 }
    ]
}

With Basket Product List set to the Event Data variable items and Product ID Field Name set to item_id, the stored basket is replaced with 2 units of product 1234 and 1 unit of product 4567. Raptor receives the basket content 1234,4567.

How the stored basket changes

The tag keeps track of quantities so it knows when a product has been removed completely. Only product IDs are sent to Raptor.

Raptor module clicks

When a visitor clicks a product in a Raptor recommendation module, Raptor needs to know which module was clicked. This is what makes it possible to measure how your recommendation modules perform.

1. Make sure your website sends the module name with the event, for example as raptor_module on the GA4 select_item event.
2. In the server container, create an Event Data variable with the Key Path raptor_module.
3. Create a tag with the event type Raptor Module Click (itemclick).
4. Select the variable in Raptor Module Clicked.
5. Map the product ID and other values under Parameter Mapping, for example with the Event Data variable items.0.item_id.

gtag('event', 'select_item', {
    raptor_module: 'GetSimilarItems',
    items: [{ item_id: '12345', item_name: 'Apple Macbook Pro' }]
});

Identifying visitors

When a visitor identifies themselves, for example by logging in or subscribing to the newsletter, you can send their email address or another unique ID to Raptor. This lets Raptor recognise the visitor later, for example when they click a link in one of your marketing emails, and improves their personal recommendations.

1. Send the ID from your website as an extra parameter on the event, for example raptor_user_id on the GA4 login event:
   
   

   gtag('event', 'login', {
       raptor_user_id: 'visitor@example.com'
   });

   
   
   
2. In the server container, create an Event Data variable with the Key Path raptor_user_id.
3. Create a tag with the event type Set Email Marketing ID (setuser) and select the variable in Email Marketing ID.
4. Under Triggering, create a Custom trigger that fires when Event Name equals login (and any other events that carry the ID). It must only fire after cookie consent has been given.
5. Name the tag, for example "Raptor - Set Email Marketing ID", and click Save.
   
   

The tag encodes the ID, stores it in the rsaRuid cookie and sends it to Raptor. All later events from the visitor include it as well. The ID is encoded in the same way as in the client-side setup, so the same visitor is recognised in both. If the variable is empty, the tag does nothing.

Cookies used by the tag

Default Settings (collapsed by default) contains two settings:

• Eventtype Parameter Number (default 1): The parameter for the event type. Only change it if the Implementing tracking page lists a different parameter.
• Use HttpOnly Cookies (default selected): Stops JavaScript on your website from reading the Raptor cookies. Keep it selected unless your website needs to read them, for example to use the cookie ID in other Raptor integrations.

Next step: test your setup

Once your tags are set up, follow Testing of Tracking Implementation to make sure every event reaches Raptor with the right values before you go live.