Publisher Ad Server – Integration Example

Select from the tabs below to view the indicated information. Read and follow all of the instructions to ensure that your integration goes smoothly.

Introduction

Introduction & Overview

This document guides you through an example for implementing Sortable’s solution for publishers using their own Google Ad Manager account. Sortable provides replacement functions for some of GPT’s standard calls. Sortable’s calls ensure we protect critical GPT functions and safely manage the timing of header partners and communication between Sortable and GPT. After the demand partners have responded with bids, Sortable then calls GPT from our JavaScript library, and sets key-value targets on the ad calls.

If you do not already have GPT on-page, we recommend using Google's ad unit and GPT documentation to create your ad units and establish the GPT code you would like to use. The remainder of Sortable's instructions speaks to the Sortable replacements required for the standard GPT set-up.

Overview of changes to regular GPT to implement Sortable

  1. Initialize Sortable's JavaScript library in the head of the page.
  2. Replace the following GPT calls with Sortable's calls:
    1. disableInitialLoad
    2. enableServices
    3. display
    4. refresh
    5. destroySlots
  3. If using your own Amazon account, follow the Amazon integration instructions.

Additional considerations

As we proceed with the integration, there are a few additional considerations you may need to capture.

  • If you already use a header bidder wrapper solution, disable it when Sortable is called. This ensures that header bidders are only called by one platform.
  • While Sortable's stack is compatible with GPT's enableLazyLoad, we do not fully support it. See our article on using GPT's enableLazyLoad for more details.
  • We do not support the use of code from multiple GAMs on the same page as Sortable. This is because they share the GPT library. A call for one GAM may impact the one you are using with Sortable, and can impact ad serving and cause reporting discrepancies.
  • We do not support the use of Google Tag Manager (GTM) for ad serving as this can cause delays and reporting discrepancies.
  • We do not support the use of Single Page Applications (SPA).
  • We cannot whitelist IP addresses; instead set up the testing IP on a test domain so that we can whitelist.
  • Let Sortable know if you are using roadblocking in GAM so that we can ensure that your roadblock(s) still serve as expected.
  • Special ad units are exempt from Sortable's line items and are not used with Sortable.
  • Sortable's line items cannot win below any unified pricing rules set in your GAM, as they are using the Price Priority type. Ensure your pricing rules are set appropriately for your inventory.
  • See the best practices tab for any other code conflicts that might occur and how to work around them.

Initialize Sortable's library

Initialize Sortable's library

Call Sortable's JavaScript and initialize Sortable’s deployads in the head of the page before defineSlots or enableServices. In the examples, you will see "<SITE_NAME>"; once we finish the backend set-up for your site we will provide you with the correct JavaScript URL to replace this placeholder. 

There are two (2) ways to load the library:

  1. Use Script calls outside an existing ad library.
  2. Use JavaScript inside an existing ad library file.

Use Script calls outside an existing ad library

Find the regular GPT in your code and replace it with the Sortable GPT.

Regular GPT

<script async="async" src="https://securepubads.g.doubleclick.net/tag/js/gpt.js"></script>
<script>var googletag = googletag || {};
googletag.cmd = googletag.cmd || [];

// Proceed with GPT slot definitions and set targeting
</script>

Sortable GPT

<script async="async" src="https://securepubads.g.doubleclick.net/tag/js/gpt.js"></script>
<script async="async" src="//tags-cdn.deployads.com/a/<SITE_NAME>.js"></script>
 
<script>var googletag = googletag || {};
googletag.cmd = googletag.cmd || [];

// Initialize the deployads array
window.deployads = window.deployads || [];

// Proceed with GPT slot definitions and set targeting
</script>

Use JavaScript inside an existing ad library file

Find the regular GPT in your code and replace it with the Sortable GPT.

Regular GPT

// Load the GPT library

(function() {

    var gads = document.createElement("script");

    gads.async = true;

    gads.type = "text/javascript";

    var useSSL = "https:" == document.location.protocol;

    gads.src = (useSSL ? "https:" : "http:") + "//securepubads.g.doubleclick.net/tag/js/gpt.js";

    var node =document.getElementsByTagName("script")[0];

    node.parentNode.insertBefore(gads, node);

})();var googletag = googletag || {};

googletag.cmd = googletag.cmd || [];

Sortable GPT

// Load the GPT library

(function() {

    var gads = document.createElement("script");

    gads.async = true;

    gads.type = "text/javascript";

    var useSSL = "https:" == document.location.protocol;

    gads.src = (useSSL ? "https:" : "http:") + "//securepubads.g.doubleclick.net/tag/js/gpt.js";

    var node =document.getElementsByTagName("script")[0];

    node.parentNode.insertBefore(gads, node);

})();

// Load Sortable's library
(function () {

      var st = document.createElement("script");

      st.async = true;

      st.type = "text/javascript";

      var useSSL = "https:" == document.location.protocol;

      st.src = (useSSL ? "https:" : "http:") + "//tags-cdn.deployads.com/a/<SITE_NAME>.js";

      var node = document.getElementsByTagName("script")[0];

      node.parentNode.insertBefore(st, node);

})();

var googletag = googletag || {};

googletag.cmd = googletag.cmd || [];

// Initialize the deployads array for asynchronous use

window.deployads = window.deployads || [];

disableInitialLoad

disableInitialLoad

Replace all googletag disableInitialLoad calls with Sortable’s pubadsDisableInitialLoad calls. This function helps Sortable support publishers using disableInitialLoad, and refresh to fire ad calls. This call should be in the head of the page inside the googletag.cmd.push, and called before the service is enabled (enableServices). This should only be called once per page. There should be an accompanying refresh call to load ads when using disableInitialLoad, using either a global or slot-specific refresh.

Find the regular GPT in your code and replace it with the Sortable GPT.

Regular GPT

googletag.pubads().disableInitialLoad();

Sortable GPT

deployads.push(function () { deployads.gpt.pubadsDisableInitialLoad(); });

enableServices

enableServices

Replace all googletag enableServices calls with Sortable’s enableServices calls. This function allows Sortable to enable all GPT services after the header bidding auction and set key value targets on the ad calls. This call should be in the head of the page inside the Google Command Queue and called after page-level settings like disableInitialLoad, enableSingleRequest, and collapseEmptyDivs. This should only be called once per page.

Find the regular GPT in your code and replace it with the Sortable GPT.

Regular GPT

googletag.enableServices();

Sortable GPT

deployads.push(function () { deployads.gpt.enableServices(); });

display

display

Replace all googletag display calls with Sortable's display calls. This function allows Sortable to fire the ad calls after setting the header bidding key-value targets. This call should be inside the Google Command Queue and called after the corresponding defineSlot and must have a matching div. This should be called once for each div id included in the defineSlot(s). All ad units defined must be displayed or this may cause a reporting discrepancy.

Find the regular GPT in your code and replace it with the Sortable GPT.

Regular GPT

googletag.display("div-gpt-ad-1111-0");

Sortable GPT

deployads.push(function() { deployads.gpt.display("div-gpt-ad-1111-0"); });

refresh

refresh

Replace all googletag refresh calls with Sortable’s refresh calls. This function ensures we fetch new bids and set header bidder key value targets ahead of dynamically-refreshed or lazy-loaded ad calls. 

There are two (2) different uses of refresh.

  1. Refresh all ad slots on page:
    • Use to load all ads on page when using disableInitialLoad.
    • Use to refresh all ads on a time interval or event-based action. We do not recommend this type of refresh, instead, we suggest using viewability-based refresh which Sortable can add to the page for you.
  2. Refresh individual ad slots:
    • Use to load individual ads on page when using disableInitialLoad. This is commonly used for lazyloading ads.
    • Use to refresh individual ads on a time interval or event-based action. We do not recommend this type of refresh, instead, we suggest using viewability-based refresh which Sortable can add to the page for you.

The refresh call could be in the body or head of the page (depending on the use case) and should be inside the Google Command Queue. Find more information on GPT's refresh here.

Find the regular GPT in your code and replace it with the Sortable GPT.


Refresh all ad slots on page

Find the regular GPT in your code and replace with the Sortable GPT.

Regular GPT

googletag.pubads().refresh();

Sortable GPT

deployads.push(function () { deployads.gpt.pubadsRefresh(); });

Refresh individual ad slots

Find the regular GPT in your code and replace with the Sortable GPT.

Regular GPT

googletag.pubads().refresh(opt_slots);

Where opt_slots is an array containing the variables used to store the defineSlot of the ad slot you would like to refresh.

Sortable GPT

deployads.push(function () { deployads.gpt.pubadsRefresh(opt_slots); });

Where opt_slots is an array containing the variables used to store the defineSlot of the ad slot you would like to refresh.

destroySlots

destroySlots

Replace all googletag destroySlots calls with Sortable’s destroySlots calls. This function allows us to receive information about cleared slots so we do not attempt to auction or set targets on slots that have been removed.

There are two (2) different uses of destroySlots.

  1. Destroy all ad slots on page:
    • Use to destroy all ads on page when a specific action has occurred. Generally used in Single Page Applications (SPA) when switching from one page to another. Note, Sortable does not currently support SPA.
    • Use to destroy all ads on an event-based action. 
  2. Destroy individual ad slots:
    • Use to destroy individual ads on-page. Commonly used when lazyloading ads on long-form pages to remove ads that have already been viewed.
    • Use to destroy individual ads on an event-based action.

The destroySlots call should be called when the ad slot is no longer available and should be inside the Google Command Queue. Find more information on GPT's destroySlots here.


Destroy all ad slots on page

Find the regular GPT in your code and replace it with the Sortable GPT.

Regular GPT

googletag.destroySlots();

Sortable GPT

deployads.push(function () { deployads.gpt.destroySlots(); });

Destroy individual ad slots

Find the regular GPT in your code and replace it with the Sortable GPT.

Regular GPT

googletag.destroySlots(opt_slots);

Where opt_slots is an array containing the variables used to store the defineSlot of the ad slot you would like to destroy.

Sortable GPT

deployads.push(function () { deployads.gpt.destroySlots(opt_slots); });

Where opt_slots is an array containing the variables used to store the defineSlot of the ad slot you would like to destroy.

Amazon

Amazon

When using your own Google Ad Manager account, you can either use Sortable's Amazon account (if approved and your GAM Currency is USD) or use your own account. If you are using Sortable's Amazon account, Sortable will add the code required for Amazon. If you are using your own Amazon account, you need to add and maintain the Amazon code on-page and follow the integration steps below. 

How it works

Since Amazon is not a header bidder, they are run outside the header bidding auction. Instead, 

  1. They run first, before Sortable and GAM.
  2. Amazon calls Sortable.
  3. Sortable holds our header bidding auction.
  4. Then Sortable sends all key-value pairs to GAM where GAM chooses the winning line item and creative to serve. 

How to integrate

To integrate your Amazon seat with Sortable, use Amazon's instructions to integrate Amazon with Googletag while using Sortable's replacements for enableServices, disableInitialLoad, refresh, and display.

Code Example

Code Example

The following is an example of GPT code with the Sortable replacements including all the required head and body calls. 

Sortable - Publisher Ad Server - Integration Example.txt

See Publisher Ad Server – Best Practices for suggested ad sizes for each type of ad placement.

Best Practices

Best Practices

Read Publisher Ad Server – Best Practices for the following topics:

  • Creating a test page
  • Suggested unit sizes
  • Conflicting Code

Common Issues

Common Issues

Publisher Ad Server – Common Integration Issues and Debugging