React Integration

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 React implementation is meant to be for websites running Single Page Applications (SPA) using React. 

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

If you have a regular HTML site please refer to our Standard Implementation.

The documentation provided is an example of what your code may look like. Please use the tags provided by your Onboarding Specialist or Customer Service Manager to ensure that your site-specific tags are used.

Overview of changes to implement Freestar's Component

  1. Install the React Component.
  2. Create your code using the Component Code provided on the Component Tab and the site-specific information provided in your tag file.
  3. PR your changes to Master.
  4. Once approved, merge your branch to master.
  5. Switch to the master branch and run the build.
  6. Publish the package using np.
  7. Set up Freestar's Dynamic ads.txt redirect at least 2 days before your site goes live.

See the Component 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:

  • 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.
  • In order 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 additional 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

  • Your Onboarding Specialist or Customer Service Manager will provide your unique ad tags as a .txt file. You can open this file in any document or code editor. The file will be unique for each of your domains.
  • Inside the file you will see pieces of information:
    • Variable: eg. const publisher = 'yoursite-com'
    • Placement Names: eg. placementName = "yoursite_leaderboard_atf"
      • There will be a different placementName for each ad unit created in Freestar's system.
  • These will give you the name of your site variable and the placement tags that will be used with the component. Use the Component tab in this document for the Component code and more information on how to place this code on your pages.
  • If you need additional tags please ask your Onboarding Specialist or Customer Service Manager.

Component

Component

To create the component you will need the tags provided by your Onboarding Specialist or Customer Service Manager. This will replace the code you had with your previous provider.

  1. Install the React Component.
    npm install --save @freestar/pubfig-adslot-react-component
  2. Create your code using the Component Code provided below and the site-specific information provided in your tag file.
    1. Open the site-specific tag file provided by Freestar from your Onboarding Specialist or Customer Service Manager.
    2. Inside the file look for the following at the top of the file (where yoursite-com represents your domain in the Freestar system) and copy the variable value.
      1. const publisher = 'yoursite-com'
    3. Paste the value over the placeholder 'publisherName' in the Component Code provided below.
      1. const publisher = 'publisherName'
    4. Inside the file look for the placement name (where yoursite represents your domain in the Freestar system) and copy the value.
      1. placementName = "yoursite_leaderboard_atf"
    5. Paste the value over the placeholder 'PublisherName_970x250_728x90_320x50' in the Component Code provided below.
      1. const placementName = 'PublisherName_970x250_728x90_320x50'
    6. Repeat d-e for each Placement being used on page.
  3. PR your changes to Master.
  4. Once approved, merge your branch to master.
  5. Switch to the master branch and run the build.
    1.  npm run build
  6. Publish the package using np. 
    1. np major|minor|patch
  7. If you have not done so already follow the instructions on the Ads.txt tab of this document to place your ads.txt lines.

Please use the code provided by your Onboarding Specialist or Customer Service Manager for your site-specific changes.

Component Code

import React, { Component } from 'react'

import FreestarAdSlot from '@freestar/pubfig-adslot-react-component'

import './demo.css'

class Demo extends Component {
  render() {
    const placementName = 'PublisherName_970x250_728x90_320x50'
    const slotId = 'in_content_ad_1'
    const publisher = 'publisherName'
    const targeting = { key1: 'value1', key2: 'value2' }
    const { adRefresh } = this.state

    return (
      <div>
        <FreestarAdSlot
          publisher={publisher}
          placementName={placementName}
          slotId={slotId}
          targeting={targeting}
          channel='custom_channel'
          classList={['m-30', 'p-15', 'b-thin-red']}
          onNewAdSlotsHook={(placementName) => console.log('creating ad', placementName)}
          onDeleteAdSlotsHook={(placementName) => console.log('destroying ad', placementName)}
          onAdRefreshHook={(placementName) => console.log('refreshing ad', placementName)}
        />
        <button onClick={this.onAdRefresh}>Trigger Refresh</button>
      </div>
    )
  }
}

export default Demo

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.

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 provided by your Onboarding Specialist or Customer Service Manager follow the instructions provided on the Component and ads.txt tabs in this document to make the changes on your test environment or page.

Test page set-up

  • 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.

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 to the head of your page.
    • Code to add (replace https://yoursite.com with the root domain we had approved with Google)
      • var freestar = freestar || {};
        freestar.queue = freestar.queue || [];
        freestar.queue.push(function () {
            googletag.pubads().set('page_url', 'https://yoursite.com');
        });

Code changes if using subdomains with Quantcast's 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 Quantcast 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);

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 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 searching for your previous provider in our code.

Ready for Freestar to Test

Once your test environment or page is ready for us to test please provide the URL 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.

Props

Props

publisher A required string of the publisher, which will be provided by Freestar.

placementName A required string of the ad unit placement, which will be provided by Freestar.

slotId An optional string to specify the element id of the containing div around the adslot. Defaults to the placement.

targeting An optional object of key/value pairs for targeting.

channel An optional string of a custom channel to use.

classList An optional array of strings representing any additional classes that should be applied to the wrapper dom element of the ad slot.

adRefresh An optional number bound to the ad refresh. Increment this value to trigger a refresh of the ad slot. Please consult your Freestar support team for more information.

onNewAdSlotsHook An optional event hook that returns the placementName when the component mounts and an ad is requested.

onDeleteAdSlotsHook An optional event hook that returns the placementName when the component unmounts.

onAdRefreshHook An optional event hook that returns the placementName when the component refreshes an ad.

integrity An optional attribute that when passed enables SRI for our pubfig library. The component will use this value for the integrity attribute when loading pubfig

Advanced

Advanced Implementation

API Methods

  • Key-Values
    • FreestarAdSlot.setPageTargeting Proxy for the GPT setTargeting call to set page level targeting. See Freestar documentation here.
    • FreestarAdSlot.clearPageTargeting Proxy for the GRP clearTargeting call to clear page level targeting. See Freestar documentation here.
  • Pageviews
    • FreestarAdSlot.trackPageView Proxy for the freestar.trackPageview() method.
      • Freestar collects data values such as URL location which is then used in various tables. In order to properly track data sites that are using Single Page Applications (SPAs), or sites with slideshows/carousels that change urls/url parameters these new actions must be taken by the publisher to assure the accuracy of the collected data. When the location and/or URL is updated the lifecycle of the DOM and/or Window does not reload the pubfig.js script. In order to address this the publisher must invoke the freestar.trackPageview() method. This will ensure that the new url is stored and used throughout the data collection for that page or view. See instructions for more details.

Queuing Freestar Ad Placements

  • If you would like to allow the Freestar library to preload but need to hold off on ad delivery until business logic has completed please follow the instructions here

For more details please see our GitHub:

https://github.com/freestarcapital/pubfig-adslot-react-component