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

Overview of changes to implement Freestar

  1. Call Freestar's JavaScript library in the head of the page.
  2. Place Freestar'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 Freestar 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 Freestar. This is because they share the GPT library. A call for one GAM may impact the one you are using with Freestar, and can impact ad serving and cause reporting discrepancies. 
  • We do not support the use of Google Tag Manager (GTM) to serve Freestar'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.

For industry insights and information about our product offerings, check out our blog!

Want to see our products in action? For a demo, fill out a form here.

Ad Code

Freestar Ad Code

Where to get your Freestar ad code

  1. Log in to Freestar's analyzable 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 Freestar, 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

Freestar 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

Freestar 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

Freestar 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 Freestar's Ad Manager account, you can only use Freestar's Amazon account (if approved). Freestar 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 analyzable UI. See the Ad Code tab for where to get your code.

Freestar - Freestar 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 analyzable UI. See the Ad Code tab for where to get your code.

  1. Take your Freestar 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 Freestar'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 Freestar 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 Freestar the testing domain so we can whitelist it in our system. Be sure to add our ads.txt to the testing domain as well. 
    • Note: We are unable to test ad serving when the testing domain is not owned by the Publisher. This is a limitation of Google as they will not serve any ads if the domain is not approved in their MCM. We can add all owned domains but cannot add a shared domain that is owned by a third party.
  • Replace all programmatic ads with Freestar's and place the ads in the same positions you plan on using with Freestar 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 Freestar 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 Freestar'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 Freestar 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.

Freestar will automatically add our Confiant to scan all of Freestar'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 Freestar 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 Freestar representative for the workaround code.
TealiumAd latencyFreestar 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 Freestar.
Cloudflare Rocket LoaderRocket loader caches our JavaScript causing your site to have outdated scripts.Add data-cfasync="false" to all Freestar 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 Freestar JavaScript file into the "Never minify the following JS files" where <SITE_NAME> is your Freestar 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 Freestar'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 Freestar'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 Freestar's ads. See the next step for ways to see if Freestar is working.
    • If no, double-check that you added all three (3) lines of Freestar'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 Freestar'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 Freestar received the request and responded (it does not necessarily mean that it filled).

Common Issues

Common Issues

Code issues

Freestar's JavaScript library doesn't start loading

  • Double-check that you are calling the correct JavaScript file name as given by Freestar. 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 Freestar'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 Freestar'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

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

When using Freestar's ad units, ensure that you are only using the data-ad-name of tags provided by Freestar. 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.