Introduction

📘

About GAM

GAM or Google Ad Manager is a comprehensive ad management platform that enables publishers to manage, sell, and optimize both direct and programmatic ad inventory across web, mobile, and app environments.

📘

The GAM integration is in beta

The documentation and features are likely to change, and the product might contain bugs. Please report any issues and check back for updates.

👍

GAM online Documentation

You can find the full Google Ad Manager documentation here.

Retailers already using GAM can now also integrate with Retail Media Onsite Display by adding a custom JS standalone tag directly to their Line items. This custom tag connects to the Retail Media Delivery system, allowing access to existing Retail Media demand without having to implement new placements.

GAM Workflow

📘

A Google Ad Manager (GAM) Javascript Tag (GPT) is already available on the Retailer Website in this example. This documentation assumes the Retailer has already made an integration with GAM.

The GAM workflow follows these steps:

Step 1

Within the GAM Ad calls made via the GAM JavaScript Tag client side (GPT), the Retailer should be already passing relevant information (like search keywords, categories, retailer visitor ID, etc.) for the GAM Ad Server to select the relevant line-item server side.

Step 2

The retailer will upload Criteo JS Standalone Tag into their GAM Ad Server by creating a new line item for the selected placement to monetize via Criteo. GAM will collect server side all the relevant parameters needed for the Criteo Delivery to function properly (like search keywords, categories, retailer visitor ID, etc.).

GAM will inject into Criteo JS Tag, server side, all the relevant parameters via the substitution's macros inserted in the Criteo Tag (if in the GAM Ad call “search=laptop” then “%%PATTERN:search%% = laptop” for example so GAM will inject “laptop” as a search keyword, and so on for all other parameters).

Step 3

The Criteo JS Standalone tag is then served and triggered on the Retailer Website so that Criteo can receive the Ad request with all the relevant parameters replaced before.

Step 4

Criteo CMax/CYield delivery is called.

Step 5

The Criteo Delivery will return:

• Option A: an ad response and the rendering script. Criteo “rm.js” library will make sure to render the ad and to trigger the beacons.
• Option B: If Criteo had no ad to serve, the “rm.js” library will trigger a customizable JavaScript pass back to give GAM the opportunity to serve another ad.

Required data

GPT Configuration & Ad call

The example below demonstrates the modification of a Google Publisher Tag (GPT) that was auto-generated from the Ad Unit. Because the GPT is implemented as a JavaScript library, it is also possible for the Retailer to have a more advanced configuration for their GPTs.

GPT Configuration

In order to populate the Macros (see below), the Google Publisher Tag will need to be modified. The .setTargeting invocations in the example below show an example with hard-coded values. In practice, the rvid and kwd values would have to be populated dynamically.

<script async src="https://securepubads.g.doubleclick.net/tag/js/gpt.js"></script>
<script>
  window.googletag = window.googletag || {cmd: []};
  googletag.cmd.push(function() {
    googletag.defineSlot('/2729856/BEN_TEST', [1024, 768], 'div-gpt-ad-1720721740722-0').addService(googletag.pubads())
    .setTargeting("rvid","TUoQPO58Wkr1dIYn234Eao")               // RETAILER VISITOR ID = TUoQPO58Wkr1dIYn234Eao
    .setTargeting("pa","viewSearchResult_API_desktop")           // PAGE ID = viewSearchResult_API_desktop
    .setTargeting("pl","InGrid")                                 // PLACEMENT ID = InGrid
    .setTargeting("kwd","laptop")                                // KEYWORD = laptop
    googletag.pubads().enableSingleRequest();
    googletag.enableServices();
  });
</script>

<!-- /2729856/BEN_TEST -->
<div id='div-gpt-ad-1720721740722-0' style='min-width: 1024px; min-height: 768px;'>
  <script>
    googletag.cmd.push(function() { googletag.display('div-gpt-ad-1720721740722-0'); });
  </script>
</div>

Ad call

The above tag will generate a call to GAM looking like the following:

https://securepubads.g.doubleclick.net/gampad/ads?pvsid=1920534727927771&correlator=4328069051982008&eid=31086815%2C31089864%2C31090092%2C83321073&output=ldjh&gdfp_req=1&vrg=202501290101&ptt=17&impl=fifs&iu_parts=2729856%2CBEN_TEST&enc_prev_ius=%2F0%2F1&prev_iu_szs=1024x768&ifi=1&dids=div-gpt-ad-1720721740722-0&sfv=1-0-40&sc=1&abxe=1&dt=1738351792324&lmt=1738351756&adxs=8&adys=8&biw=757&bih=934&scr_x=0&scr_y=0&btvi=0&ucis=1&oid=2&u_his=1&u_h=1080&u_w=1920&u_ah=1055&u_aw=1920&u_cd=24&u_sd=1&u_tz=-300&dmc=8&bc=31&nvt=2&uach=WyJtYWNPUyIsIjE1LjIuMCIsImFybSIsIiIsIjEzMi4wLjY4MzQuMTExIixudWxsLDAsbnVsbCwiNjQiLFtbIk5vdCBBKEJyYW5kIiwiOC4wLjAuMCJdLFsiQ2hyb21pdW0iLCIxMzIuMC42ODM0LjExMSJdLFsiR29vZ2xlIENocm9tZSIsIjEzMi4wLjY4MzQuMTExIl1dLDBd&uas=3&url=file%3A%2F%2F%2FUsers%2Fb.chapuzet%2FDownloads%2Findex.html&vis=1&psz=741x918&msz=1024x768&fws=0&ohw=0&topics=9&tps=9&htps=10&nt=1&psd=WzE1LFtdLG51bGwsM10.&dlt=1738351784028&idt=8274&prev_scp=rvid%3DTUoQPO58Wkr1dIYn234Eao%26pa%3DviewSearchResult_API_desktop%26pl%3DInGrid%26kwd%3Dlaptop&adks=1933767165&frm=20&td=1&tan=2ceb47bf-5516-425e-93fb-3739f388a083&tdf=2

To be able to see those newly created parameter on your ad call, you must examine the request made to GAM:

• Reload the retailer’s page with Chrome Developer Tools open.
• Filter by “gam” in the Network tab.

On the “Payload” tab of this request, find the prev_scp (slot level) and/or cust_params (page level) query string parameters.

Those two parameters (prev_scp and/or cust_params) will carry all relevant parameters that our newly created standalone tag needs. Both cust_params (page level) and/or prev_scp (slot level) are going to be passed to the GAM Ad Server, and any information inside will be accessible via a macro.

Macros & mapping

As said previously, prev_scp and/or cust_params will be accessible by the GAM Ad Server and Criteo will need to get access to those parameters' server side via a few macros.

Let’s assume GPT is configured with the following targeting: (this step should be already implemented)(please refer to this page and this page for assistance).

    .setTargeting("rvid","TUoQPO58Wkr1dIYn234Eao")               // RETAILER VISITOR ID = TUoQPO58Wkr1dIYn234Eao
    .setTargeting("pa","viewSearchResult_API_desktop")           // PAGE ID = viewSearchResult_API_desktop
    .setTargeting("pl","InGrid")                                 // PLACEMENT ID = InGrid
    .setTargeting("kwd","laptop")                                // KEYWORD = laptop

In this example, parameters to the RM Delivery request are populated as follows:

• The retailer-visitor-id is being populated by a macro: %%PATTERN:rvid%% and will ultimately be replaced by the server by the value: TUoQPO58Wkr1dIYn234Eao.
• The page-id is being populated by a macro: %%PATTERN:pa%% (it can be hardcoded) and will ultimately be replaced by the server by the value: viewSearchResult_API_desktop.
• The placement-id is being populated by a macro: %%PATTERN:pl%% (it can be hardcoded) and will ultimately be replaced by the server by the value: InGrid.
• The context is being populated by a macro: %%PATTERN:kwd%% and will ultimately be replaced by the server by the value: laptop.
• %%CACHEBUSTER%% is just a macro that expands to a random number to prevent caching.

Criteo JS standalone tag

A new line item in GAM needs to be created to host and deliver the following tag. Configuring the line item in GAM is largely up to the Retailer.

A modified version of the following tag needs to be uploaded in your GAM Ad Server as a new third party creative within this line item:

Criteo Tag to copy and modify

<script async src="https://d.us.criteo.com/Delivery/ClientPaths/Library/rm.js?a=[TO_BE_REPLACED]"></script>
<script async src="https://d.us.criteo.com/delivery/v2/rmgam?criteo-partner-id=[TO_BE_REPLACED]&retailer-visitor-id=%%PATTERN:[TO_BE_REPLACED]%%&page-id=%%PATTERN:[TO_BE_REPLACED]%%&placement-id=%%PATTERN:[TO_BE_REPLACED]%%&context=%%PATTERN:[TO_BE_REPLACED]%%&cb=%%CACHEBUSTER%%"></script>

Before macros substitution example

<script async src="https://d.us.criteo.com/Delivery/ClientPaths/Library/rm.js?a=123456789"></script>
<script async src="https://d.us.criteo.com/delivery/v2/rmgam?criteo-partner-id=123456789&retailer-visitor-id=%%PATTERN:rvid%%&page-id=%%PATTERN:pa%%&placement-id=%%PATTERN:pl%%&context=%%PATTERN:kwd%%&cb=%%CACHEBUSTER%%"></script>

After macros substitution example

<script async src="https://d.us.criteo.com/Delivery/ClientPaths/Library/rm.js?a=123456789"></script>
<script async src="https://d.us.criteo.com/delivery/v2/rmgam?criteo-partner-id=123456789&retailer-visitor-id=TUoQPO58Wkr1dIYn234Eao&page-id=viewSearchResult_API_desktop&placement-id=InGrid&context=laptop&cb=8472058275657293"></script>