Sortable 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 Sortable's Google Ad Manager account. Sortable provides tags that will call Sortable's Google Ad Manager without using GPT tags. 

Overview of changes to implement Sortable

  1. Call Sortable's JavaScript library in the head of the page.
  2. Place Sortable's tags where you would like to see ads throughout your site. See our recommended placements for details.

Additional considerations

There are a few additional considerations that may need to be captured as we proceed with the integration:

  • 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.
  • 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) to serve Sortable's JavaScript or ad tags, as this can impact ad serving and cause 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.
  • See the Conflicting Code tab for other code conflicts that might occur and how to work around them.

Ad Code

Sortable Ad Code

Where to get your Sortable ad code

  1. Log in to Sortable Analytics using the username and password provided.
  2. From the left menu select Site Settings > Ad Tags.
  3. If you have more than one (1) domain with Sortable, use the Select a Site section at the top to select your domain. The available ad units are visible in the table.
  4. Copy the ad unit's tags:
    • To get a single tag (use one of the following): 
      • Select the copy icon for the row of the ad unit to copy the code.
      • Select the name of the tag to view and copy a single tag.
    • To get all tags (use one of the following): 
      • Select Copy all in the top right.
      • Select Download all in the top right. 
  5. See the Test Page tab for instructions on how to add your code on-page.

Notes: 

  • Ignore the interstitial and anchor ad units as these will be added to the page for you.
  • Depending on what you are doing with the ad unit and what code you already have on-page, you may need to edit the code from the default provided. The different options are listed on the Tag Options and Conflicting Code tabs. Make sure to read these in their entirety before adding the code to your page.

Refresh

Sortable automatically adds refresh to your ads starting at a 50% test to ensure it works well for your site. Ads are refreshed after they have been viewed for at least one (1) second and loaded for at least 30 seconds. If the test passes, we scale up to 100%. If not, we adjust your test as necessary until we see positive results.

Anchors

Sortable automatically adds anchors to your page on mobile and desktop. These are fixed to the bottom of the viewport and include a close button.

Interstitials

Sortable automatically adds interstitials to your page on all device types. These are displayed between the first and second page, when a user selects in-site navigation. It will only ever load one (1) time per user per hour and includes a close button.

Tag Options

Tag Options

Sticky

Sticky ad units are ad units that stick to the top of the viewport when a user scrolls, allowing the ad unit to have higher viewability, helping increase CPMs. To make an ad unit stick to the top of the page, use the data-ad-sticky attribute with our ad tags. We recommend you use it on one (1) side rail ad, typically on the bottom side rail. This can only be used on one (1) ad unit per page.

To use: 

  1. Add data-ad-sticky="sidebar 60px" to the ad div.
  2. Adjust "60px" to the distance from the top of the page where the ad should stick.

Example:

<div class="ad-tag" data-ad-name="sidebar_sticky" data-ad-sticky="sidebar 60px"></div>

Amazon

Amazon

When using Sortable's Ad Manager account, you can only use Sortable's Amazon account (if approved). Sortable adds the code required for Amazon.

Code Example

Code Example

In the example we link to below, you will see <SITE_NAME> and ad_unit_name. Once we finish the backend set-up for your site, you will be able to see your ad unit names and JavaScript URL to replace these placeholders. They can be found in the Sortable Analytics UI. See the Ad Code tab for where to get your code.

Sortable - Sortable Ad Server - Integration Example.txt

See our ad units and placement for the list of ad units and sizes with suggested placements.

Test page

Creating a test page

How to place your code

In the examples below, you will see <SITE_NAME> and ad_unit_name. Once we finish the backend set-up for your site, you will be able to see your ad unit names and JavaScript URL to replace these placeholders. They can be found in the Sortable Analytics UI. See the Ad Code tab for where to get your code.

  1. Take your Sortable JavaScript line #2 and place it in the <head></head> of the page.
    Example: <script async="async" src="//tags-cdn.deployads.com/a/<SITE_NAME>.js"></script>
  2. To ensure that our responsive tags work on your pages, check that you have the viewport initial-scale tag in the <head></head> of the page. This may already be included in your pages, so only add it if it's missing.
    Example: <meta name="viewport" content="initial-scale=1" />
  3. Take all three (3) lines of the ad tag including the ad div, JavaScript, and Sortable's push function, and place them where you would like the ad to appear within your code. Keep in mind the ad unit names and suggested placements (see the Ad units & Placement tab for more details).
    Example:
    <div class="ad-tag" data-ad-name="ad_unit_name"></div>
    <script src="//tags-cdn.deployads.com/a/<SITE_NAME>.js" async ></script>
    <script>(deployads = window.deployads || []).push({});</script>

What makes a good test page?

When you are making your test page for the Sortable team to review, ensure it has the following:

  • The domain of the test page matches the domain you are onboarding. If the testing domain does not match, give Sortable the testing domain so we can whitelist it in our system.
  • Replace all programmatic ads with Sortable's and place the ads in the same positions you plan on using with Sortable on the whole test page. 
  • Remove your previous provider's code from the test page.
  • Use a test page with the same code as a regular page on your site, using all the same plugins and third-party scripts (except your previous provider's) so we can check for code conflicts.
  • If needed, apply any of the required workarounds from the Conflicting Code tab to your test page.
  • Double-check that you made all the required code replacements by using the search function in your browser's inspector.
  • We prefer that your test page not have live traffic going to the page. This allows us the opportunity to test everything before you set it live. 
  • Send Sortable your testing URL as soon as it is ready. It may take our team a few days to test depending on the complexity of your code.

Ad Units & Placement

Ad Units and Placement

We suggest using multi-sized units whenever possible to increase competition, CPMs, and revenue. Below are the default ad units and their suggested placements. 

Header

This unit should appear at the top of your site pages on Desktop and Tablet, and at least halfway down your first viewport on mobile.

Suggested sizes:

  • Desktop: 970x250, 970x90, 728x90, 728x15, 468x60, 1x1, 1x2
  • Tablet: 728x90, 728x15, 468x60, 300x250, 336x280, 320x50, 300x50, 320x100, 1x1, 1x2
  • Mobile: 300x250, 336x280, 320x50, 300x50, 320x100, 1x1, 1x2

Anchors

These units are automatically added to your site with Sortable's code.

Suggested sizes:

  • Desktop: 728x90, 1x1, 1x2
  • Mobile: 320x50, 1x1, 1x2

Side Rails/Side Bar

These units should appear in your side rails on desktop and larger tablets. 

On mobile, if your side rails appear, remove the ads or lazy load them. They often appear below the site content and would have very low viewability.

Suggested sizes:

  • Desktop: 300x600, 300x250, 160x600, 120x600, 336x280, 1x1, 1x2
  • Tablet: 300x600, 300x250, 160x600, 120x600, 336x280, 1x1, 1x2
  • Mobile: Do not display or lazy load

In-article/In-content

These units should appear inside the content of your page.

Suggested sizes:

  • Desktop: 970x250, 970x90, 728x90, 728x15, 468x60, 300x250, 320x50, 1x1, 1x2
  • Tablet: 728x90, 728x15, 468x60, 300x250, 320x50, 1x1, 1x2
  • Mobile: 300x250, 336x280, 320x50, 300x50, 320x100, 1x1, 1x2

Below-article/Below-content

These units typically have very low viewability as they are below site content. If you wish to keep ads below the content, they need to be lazy-loaded to improve viewability.

Talk to your Sortable representative for lazy load instructions and to have the below-content ad units created for your site.

Conflicting Code

Conflicting Code

See the list below for known code conflicts that can be solved with a workaround. 

For a list of code conflicts that do not have a workaround, see the list in the additional considerations in the Introduction tab.

Sortable will automatically add our Confiant to scan all of Sortable's demand partner seats. If you have your own demand partner seats where you would like to apply your own Confiant scanning, speak to your Sortable representative for other options.

WhatIssue it causesHow to work around the issue
MarfeelSortable's automatic anchors do not appear on-pageUse a hard-coded anchor instead. Ask your Sortable representative for the workaround code.
TealiumAd latencySortable needs to see this on a test page to see if we can provide guidance.
RebelMouse  CMSThey use the same "ad-tag" class that Sortable uses. This conflicts with our code as we try to insert an ad into that div.No ad widgets should be used on a RebelMouse site using Sortable.
Cloudflare Rocket LoaderRocket loader caches our JavaScript causing your site to have outdated scripts.Add data-cfasync="false" to all Sortable script tags.
Example:
<script data-cfasync="false" src="//tags-cdn.deployads.com/a/snapsort.com.js" async ></script>
W3 Total CacheW3 Total Cache caches our JavaScript causing your site to have outdated scripts.
  1. In WordPress: Go to Performance > Minify > Advanced
  2. Enter the URL to your Sortable JavaScript file into the "Never minify the following JS files" where <SITE_NAME> is your Sortable JavaScript file name:
    tags-cdn.deployads.com/a/<SITE_NAME>.js
  3. Select Save all settings. If you already added the JavaScript file before doing this, Save Settings and Purge Caches.
AutoptimizeAutoptimize will cache our JavaScript causing your site to have outdated scripts.Add <!--noptimize--> around all script tags with Sortable's code.
Example:
<!--noptimize--><script src="//tags-cdn.deployads.com/a/snapsort.com.js" async ></script><!--/noptimize-->
Theia Post SliderDefault settings for this theme in WordPress automatically refreshes ads. Since these refresh calls are not using Sortable's version of refresh, we are not notified when the refresh occurs.On the Advanced tab of the Theia Post Slider plugin, uncheck the box next to Refresh ads when navigating to another side to disable it (in the Ad behavior section).
Confiant DFP WrapperWe don't support integrating Confiant through a DFP wrapper. 

Debugging

Debugging

While you are making your test pages, there are a number of indicators to tell if your code is working with Sortable's.

  1. Look at the webpage and see if an ad is filling the slot. 
    • If yes, this means ad code is working, but not necessarily loading Sortable's ads. See the next step for ways to see if Sortable is working.
    • If no, double-check that you added all three (3) lines of Sortable's tags with every ad unit, and added any applicable conflicting code workarounds needed for your site. If the code is correct, proceed to the next checks to see if you can see any issues.
  2. Using your browser inspector (we recommend using Chrome):
    1. In network: Search for deployads. Make sure the JavaScript file name for your site has a status of 200. This means the JavaScript file called matches a file enabled in Sortable's system.
    2. In elements: Look for the data-google-query-id on the ad div. This means that GAM received the request and responded (it does not necessarily mean that it filled).
    3. In elements: Look for the data-ad-imp on the ad div. This means that Sortable received the request and responded (it does not necessarily mean that it filled).

Common Issues

Common Issues

Code issues

Sortable's JavaScript library doesn't start loading

  • Double-check that you are calling the correct JavaScript file name as given by Sortable. This usually matches your website's domain, however, sometimes it does not always match.
  • Ensure that there are two forward slashes at the beginning. For example, //tags-cdn.deployads.com/a/snapsort.com.js

Ads aren't loading correctly

There can be many issues that are causing ads to not load correctly, but here are the most common:

  • Ensure that you added all three (3) lines of Sortable's tags with every ad unit mentioned in this document.
  • If using a plugin to lazyload your ads, ensure your ads in the first 1–2 viewports load with page load, and load the remaining ads after the user scrolls.

Defining the correct unit

When using Sortable's ad units, ensure that you are only using the data-ad-name of tags provided by Sortable. If not, the ad unit will default and won't use the best size of ad unit.

Reporting issues

Sortable is reporting ad units as “default” when there are no units named “default”

When using Sortable's ad units, ensure that you are only using the data-ad-name of tags provided by Sortable. If not, the ad unit will be listed as default in reporting and will be grouped together with any other units that have incorrect names.