Single Page Applications (SPA)

Sovrn Ad Management implementation on Single Page Application (SPA) based websites

1.      To begin, insert the properSpecialOps code into the header, before the header bidding script:

var properSpecialOps = properSpecialOps || {};
properSpecialOps['spa_settings'] = {
    enabled: true,
    prefetch: true,
    gallery_id: 'gallery_1',
    gallery_base_url: 'https://gallery.com/for/things/'
}

Below are the parameters and a short description for each:

Property Data Type Description
enabled boolean Enables SPA logic
prefetch boolean Prefetch ads for next page. Only use on gallery pages where layout will stay the same, as prefetch will send out two auctions on the first page
gallery_id string Unique id for gallery. Stays the same throughout gallery. We only show prefetched ads for pages in the same gallery
gallery_base_url string URL to use when sending bid requests for prefetching. Should stay the same throughout gallery pages. Can help URL request/display mismatch
*Optional - only for use when ad layout will remain exactly the same from page to page

2.      Next, insert the header bidding script and ad units as described in basic implementation.

Dynamically loading new pages

  1. Update the page URL (if needed)
  2. Update properSpecialOps.['spa_settings'] accordingly if the gallery_id or gallery_url are changing. (Primarily used for gallery style pages where the layout stays the same between pages.)
  3. Load new page
    1. Delete/destroy slots from previous page
      1. Use function properDeleteSlot(slot_name); to delete slots that will not be on the new page.
      2. Use properDestroyDfpSlot(slot_name); for slots that will be on the next page, but the div will be removed and reinserted into the DOM.
      3. No action needed for slots that will remain in the DOM from the previous page
    2. Insert any new ad unit divs or divs that have been destroyed from the previous page and will be re-inserted
    3. Call properSpaNewPage(); to count a new pageview, run a new auction, build new ad units, and reload ad units from previous page

      Note, if new ad units are added to the page after properSpaNewPage is called, the function properBuildSlots(); can be called to build new slots without counting a new pageview or refreshing existing slots.
       

Additional Functions for Single Page Applications

properSpaNewPage();

This function should be called when a new page is loaded in a Single Page App. This function should not be called on the initial page load.

When used, properSpaNewPage will rebuild the page object in the ad-project code and record a new page-view.

It will refresh ad slots that are persisting to the next page while also building new slots that have been added to the DOM. The page URL needs to be updated in the address bar before calling this function so that the earnings are recorded correctly.

properBuildSlots();

This function allows the ad-project code to know that the layout of the page has changed. It runs a check to see if more slots have been added, or if they need to be dynamically added by the ad-project code.

This function doesn't refresh the current slots on the page, but it will build and display new slots. Additionally, this function won’t record a new page-view.

A good use case for this is on an infinite scroll page where new content is appended to the page as the user scrolls. Once the new content is added to the page you then need to call properBuildSlots() to let the ad-project code know SMS needs to both check for new slots and then display them.

properDeleteSlot(slot_name);

This function can be used to destroy the ad slot object on the page. Should be used when a slot is being removed from the DOM and will not be on the next page.

properDestroyDfpSlot(slot_name);

This function destroys the GPT slot reference but keeps the slot object in our code. This should be used if a slot will be on the next page but the div will be removed and re-inserted into the DOM. GPT slot will need to be re-defined and will be handled by our code.