Freestar Standard Implementation

Last Modified on 04/11/2023 5:07 pm EDT

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

The standard implementation is meant to be for websites running on WordPress or other similar CMS frameworks. These tags are set to render as the DOM is loading. These tags can be used with WordPress plugins, as well as tag managers like Google Tag Manager or Ensighten. 

If you have an SPA (Single Page Application) site using React please refer to our React Implementation

If you have an SPA site using Angular, Vue or similar framework please refer to our Event-based Implementation.

The documentation provided is an example of what your code may look like. Please use the tags found in the Freestar Dashboard to ensure that your site-specific tags are used.

Overview of changes to implement Freestar

  1. Call Freestar's JavaScript in the head of the page.
  2. Place Freestar's tags where you would like to see ads throughout your site.
  3. Place the CMP CCPA and GDPR links on your site.
  4. Set up Freestar's Dynamic ads.txt redirect at least 2 days before your site goes live.

See the Head, Body and Ads.txt tabs of this document for more information on how to place this code on your page.

Additional considerations

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

  • Both the header and body tags are required for our code to work.
  • Do not place ad tags in the body using CSS to hide them.
  • Tags load asynchronously.
  • Tags are built on standard Google Publisher Tag practices.
  • 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.
  • For us to perform optimally, our code needs to be on the root page, allowing bidding partners access to a user's cookies and other identifiers.
  • If you are using a different URL for your test site where the root domain does not match the domain that Google approved for your site you will need to add an additional line of code to the head of your page. See the Test Page tab for more details.

Ad Code

Freestar Ad Code

Where to get your Freestar ad code

  • You can download your tags from the Freestar Dashboard. Your unique ad tags will be in a .txt file. You can open this file in any document or code editor. The file will be unique for each of your domains. The Freestar tags will replace your current provider's tags on page.

  • How to find your ad tags

    1. Login to the Freestar Dashboard.
    2. Select the 3 lines icon in the top left to open the left menu.
    3. Select Site Configuration in the left menu.
    4. Select the Ad Tags Tab at the top of the page.
    5. Select the type of tags based on your site architecture. This will download your tags.
      1. Default - Use this for standard HTML tags for a site that is not using Single Page Architecture (SPA).
      2. React - Use this for React tags using our React component for sites using Single Page Architecture (SPA).  Please use the React integration guide for these type of tags.
      3. Event-Based - Use this for Event-Based tags for sites using Single Page Architecture (SPA) that are not React like Angular or Vue. Please use the Event-Based integration guide for these type of tags.

Notes about your Freestar ad code

  • Inside the file you will see 2 comments:
    <!-- PLACE THIS SECTION INSIDE OF YOUR HEAD TAGS -->
<!-- PLACE THIS SECTION INSIDE OF YOUR BODY TAGS -->
    • These will mark the start of your head and your body tags. Use the Head and Body tabs in this document for more information on how to place this code on your pages.
  • If Freestar adjusts sizes on your tags, due to our code accounting for CLS, we may need to provide you new tags for implementation.
  • If you need additional tags please ask your Onboarding Specialist or Customer Service Manager.
  • If you receive an error message when pulling your tags, please try disabling your Ad Blocker. If the issue continues to persist, please ask your Onboarding Specialist or Customer Service Manager to send them along.

Head

Header Tags

Please add the entire header code with the tags found in the Freestar Dashboard. This will replace the head code you had with your previous provider.

  1. Open the file provided by Freestar from your Onboarding Specialist or Customer Service Manager.
  2. Inside the file look for the following comment at the top of the file
    <!-- PLACE THIS SECTION INSIDE OF YOUR HEAD TAGS -->
  3. Copy all lines from the comment above until you see the following comment.
    <!-- PLACE THIS SECTION INSIDE OF YOUR BODY TAGS -->
  4. Paste these lines inside the <head></head> tags of your website.
    1. If using WordPress or a similar CMS you may need to use a plugin to edit the head of your page.
  5. Follow the instructions on the Body tab of this document to place your tags.
  6. If you have not done so already follow the instructions on the Ads.txt tab of this document to place your ads.txt lines.

Below is a sample of what the code will look like. Please use the code provided by your Onboarding Specialist or Customer Service Manager and not the example below as there are site-specific changes.

Notice that the code also contains comments identifying the intention of our code. 

<script data-cfasync="false" type="text/javascript">
// Creates the freestar variable on the Window of the page. 
// If freestar is already declared it will use that current state. If not it will default to an empty object.
var freestar = freestar || {};

// sets the time of the execution of this code for reporting
freestar.hitTime = Date.now();

// creates the key queue  in the freestar object. This is used for queuing code that needs to execute
freestar.queue = freestar.queue || [];

// creates the key object config.
freestar.config = freestar.config || {};

// creates a key debug which is used for testing and, or staging
freestar.debug = window.location.search.indexOf('fsdebug') === -1 ?false : true;

// The body tags will push the ad slots into this array and they will be sent to the ad server
freestar.config.enabled_slots = [];

// Use callback on initial page load to ensure scripts are ready
// The newAdSlots method will then call the array to fetch the ads
freestar.initCallback = function () { 
   freestar.newAdSlots(freestar.config.enabled_slots);
}
</script>

// This script tag is specific to you as a publisher and is what loads our core technology script. 
//Do not add the line below to your site, instead use the code provided by your Onboarding Specialist or Customer Service Manager.
<script data-cfasync="false" src="https://a.pub.network/yoursite-com/pubfig.min.js" async></script>

Body

Body Tags

Please add the body tags from the tags found in the Freestar Dashboard. This will replace the ad tags you had with your previous provider. The body tags are more specific to the actual ads and sizes that will be called on the page. You should be able to just replace the code you used previously in their respective ad slots.

  1. Open the file provided by Freestar from the Freestar Dashboard.
  2. Inside the file look for the following comment below the head tags
    <!-- PLACE THIS SECTION INSIDE OF YOUR BODY TAGS -->
  3. Below the tag above you will see a list of your ad unit tags. Each tag consists of 6 lines (see full example below). Copy 1 tag at a time copying all 6 lines starting with the opening of the comment <!-- to the end of the div </div>.
  4. Paste these lines inside the <body></body> tags of your website. Where you would like the ad to appear. 
    1. If we gave you suggested placements for your tags please refer to the list provided. If you do not know where the tag should be placed please ask your Onboarding Specialist or Customer Service Manager.
    2. If using WordPress or a similar CMS you may need to use a plugin to insert the ads into your page.
  5. If you have not done so already follow the instructions on the Head tab of this document to place your head tags.
  6. If you have not done so already follow the instructions on the Ads.txt tab of this document to place your ads.txt lines.

Below is a sample of what one ad unit tag code will look like. Please use the code provided by your onboarding specialist and not the example below as there are site-specific changes. If you need additional tags, please let us know.

<!-- Tag ID: ad-slot-1 -->
<div align="center" data-freestar-ad="__300x250 __300x600" id="ad-slot-1">
   <script data-cfasync="false" type="text/javascript">
      freestar.config.enabled_slots.push({ placementName: "ad-slot-1", slotId: "ad-slot-1" });
   </script>
</div>

Notes

  • If you are using a WordPress plugin, these tags will work with most of them. Some examples include Ad Inserter Pro and Advanced Ads
  • If you need to repeat an ad unit on the same page please refer to our event-based documentation here. Refer to the "Reusing a Placement On the Same Page" section for more details.

CCPA & GDPR Links

CCPA & GDPR Links

Why do you need CCPA & GDPR links?

The CCPA & GDPR links are required for privacy regulations in California and for GDPR. CCPA is an opt-out regulation so there is no initial prompt. Users are required to hit a link/button that reads “Do Not Sell My Personal Information” to opt out in California. You are required to add a link to the footer of your website that gives users the ability to opt-out. GDPR is an opt-in regulation so a prompt is required. Users are required to consent to all the different ad partners on page to serve ads. You are required to add a link to the footer of your website that gives users the ability to change their permissions. 

If you are using Freestar's Quantcast CMP you will need to place this code on your page to ensure the links appear. Once the user clicks on the link(s) this will pop-up their options on the Quantcast CMP. 

If you are using your own CMP you will need to follow the instructions provided by your CMP provider to place your links. You'll also need to enable all IAB-approved vendors within your CMP.

Where should you place the CCPA & GDPR links?

Your CCPA & GDPR links should be placed in the footer of your page.

When should you add the CCPA & GDPR links?

The CCPA & GDPR links should be added when you are adding Freestar's code to your page. We recommend doing this on your test page so we can test to ensure that it is working as expected before going live. Even though the CCPA & GDPR protections are for California and the EEA we ask that you add the link for all users to ensure you remain compliant.

How to add the CCPA & GDPR links

Add the code below to the footer of your page.

<footer>
<a class="change-consent" onclick="window.__uspapi('displayUspUi');">Do Not Sell My Personal Information</a>
<a class="change-consent" onclick="window.__tcfapi('displayConsentUi', 2, function() {} );">Change Consent</a>
</footer>

Ads.txt

Ads.txt

Why we use Dynamic Ads.txt?

We utilize a dynamic ads.txt product so that you will always have the most up-to-date version of ads.txt. To add this you will need to create a redirect to a file on our servers. Using our Dynamic Ads.txt will remove the monthly task of you having to update manually.

When should your Ads.txt file be updated?

Your ads.txt lines should be updated on your root domain (https://yoursite.com/ads.txt) a minimum of 2 days before your expected launch date. Freestar's Google ads.txt line needs to be in place before you can test our code on your test environment or page. For best results, we recommend that you update to use our dynamic ads.txt with all of Freestar's lines during testing as we already added your current provider's lines.

How to find your dynamic ads.txt redirect URL

  1. Login to the Freestar Dashboard.
  2. Select the 3 lines icon in the top left to open the left menu.
  3. Select Site Configuration in the left menu.
  4. Next to the site that you would like to edit select the "View FS Ads.txt" button in the main section of the page.
  5. Copy the URL in your address bar.
  6. Follow the steps below in "How to set up Dynamic Ads.txt" to redirect your ads.txt from https://yoursite.com/ads.txt to the redirect URL you copied.

How to set up Dynamic Ads.txt

Find instructions in the Freestar Dashboard

  1. Login to the Freestar Dashboard.
  2. Select the 3 lines icon in the top left to open the left menu.
  3. Select Site Configuration in the left menu.
  4. At the bottom of the page, you will find instructions for the different methods for creating a redirect. Select the tab that is appropriate for your setup.

If you are unable to log in you can find the instructions on how to implement this here.

How to edit your custom Ads.txt lines when using Dynamic Ads.txt

For the lines that are specific to your site and outside Freestar's portfolio, you can either edit this in the Freestar Dashboard or ask your Onboarding Specialist or Customer Service Manager to add them to your custom file. 

To update in the Freestar Dashboard
Watch a demo of how this is done here.

  1. Login to the Freestar Dashboard.
  2. Select the 3 lines icon in the top left to open the left menu.
  3. Select Site Configuration in the left menu.
  4. Next to the site that you would like to edit select the "Edit Fs Ads.txt" button in the main section of the page.
  5. Add a new line to the top or bottom of your file.
    1.  Use # at the beginning of any comment lines.
      • Note: It is very important that you do not delete any of your existing lines without checking with your Freestar representative as some lines are very important and may cause ads to stop serving if removed.
  6. Select Save Ads.txt.

Testing

Creating a Test Page

Using the tags found in the Freestar Dashboard follow the instructions provided on the Head, Body and ads.txt tabs in this document to make the changes on your test environment or page.

Test page or environment set-up

  • We would prefer if a test environment can be provided so we can test several pages with different layouts before you go live. If this is not possible a test page is acceptable.
  • Use a test environment or 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.
  • We prefer that your test environment or page not have live traffic. This allows us the opportunity to test everything before you set it live.
  • Replace your current provider's tags on page with the Freestar tags.
  • Please do not place our code on any pages where you do not want ads to run or pages with no content like a Login page.
  • Do not push tags to production until Freestar gives the green light as we like to ensure everything is set up properly and we do not disturb user experience.

Code changes if using a different root domain for your test environment

  • If you are using a different URL for your test environment or page where the root domain does not match the domain that Google approved for your site you will need to add an additional line of code to the head of your page. Add the following line of code after enabled_slots and before initCallback.
    • Code to add (replace https://yoursite.com with the root domain we had approved with Google)
      • freestar.queue.push(function() { googletag.pubads().set("page_url", "https://yoursite.com"); });
    • Full Example:
<!-- Below is a link to a CSS file that accounts for Cumulative Layout Shift, a new Core Web Vitals subset that Google uses to help rank your site in search -->
<!-- The file is intended to eliminate the layout shifts that are seen when ads load into the page. If you don't want to use this, simply remove this file -->
<!-- To find out more about CLS, visit https://web.dev/vitals/ -->
<link rel="stylesheet" href="https://a.pub.network/core/pubfig/cls.css">
<script data-cfasync="false" type="text/javascript">
  var freestar = freestar || {};
  freestar.queue = freestar.queue || [];
  freestar.config = freestar.config || {};
  freestar.config.enabled_slots = [];

freestar.queue.push(function() { googletag.pubads().set("page_url", "https://yoursite.com"); });

freestar.initCallback = function () { (freestar.config.enabled_slots.length === 0) ? freestar.initCallbackCalled = false : freestar.newAdSlots(freestar.config.enabled_slots) }</script>
<script data-cfasync="false" src="https://a.pub.network/yoursite-com/pubfig.min.js" async></script>

Code changes if using subdomains with your own Quantcast CMP

  • If you are using a subdomain for your test environment, page or live site where your Quantcast Choice CMP was only set-up with the root domain you will need to edit the host line of code provided by Quantcast to allow ads to serve on all subdomains. This allows you to use the same code on each subdomain while telling Quancast to use the root domain.
    • If you did set up each subdomain in the Quantcast UI for your CMP you can skip this step, otherwise, follow the steps below.
    • Code to adjust (replace yoursite.com with the root domain you added in the Quantcast UI)
      • var host = "yoursite.com";
    • Full Example:
      • (function() {
  var host = "yoursite.com";
  var element = document.createElement('script');
  var firstScript = document.getElementsByTagName('script')[0];
  var url = 'https://quantcast.mgr.consensu.org'
    .concat('/choice/', '1_3qeSjJG-hKn', '/', host, '/choice.js')
  var uspTries = 0;
  var uspTriesLimit = 3;
  element.async = true;
  element.type = 'text/javascript';
  element.src = url;
  firstScript.parentNode.insertBefore(element, firstScript);

Code changes if you would like a 3rd party script to wait for Freestar's Quantcast CMP consent before loading

  • If you need to load a script after we receive consent from our Freestar Quantcast CMP you can use the Freestar Queue as this will only load if consent is given.
  • First, you will need to make sure the code is added after our Queue is initialized.
    • freestar.queue = freestar.queue || [];
  • Second, you will add the code to push information to our queue.
    • <script>freestar.queue.push(function() {
 });
</script>
  • Third, you will add your third party code inside our push function.
    • <script>freestar.queue.push(function() {
 //enter your code here
});
</script>

How to Test

  • To test that the ads are loading as expected you can use a URL parameter ?dfpkey=fsads to load our House Campaigns. This will allow you to see the ads filling the slots and to ensure you have placed the code in the correct locations.
    • Example
      • URL: https://yourtestdomain.com/?dfpkey=fsads
  • Double-check that you made all the required code replacements by using the search function in your browser's inspector to search for your previous provider to ensure they have been removed.

Ready for Freestar to Test

Once your test environment or page is ready for us to test please provide the URL(s) and any login credentials to your Onboarding Specialist or Customer Service Manager. Our team will run a series of tests to ensure everything is set up as expected and there is no conflicting code on your site. We will let you know if there are any issues or edits that need to be made.

Test Page Passes Testing

Once your test environment or page has passed testing we will then schedule a launch date with your team. Please do not launch without checking with our team first as we want you to be set up for success.

Related Articles

How would you rate this article?
Thank you for your feedback!
User Icon

Thank you for your feedback!

© 2022 Publisher First Inc. All rights reserved.