Skip to main content

BidRoll - Getting Started ( Manual )

This is the manual guide for getting started with BidRoll if you're using WordPress you can follow the WordPress guide instead.

Implementing the BidRoll Library Manually

This guide provides concise steps for implementing the BidRoll library for on-page ads.

Prerequisites​

Requirements Gathering​

Initially we will need to confirm various details of your current ad experience.

Ad Inventory​

At Spiny we can define a generic set of ad inventory(with best practice configurations/attributes) that should account for all use cases but if you would like to have more granular control over this; we will need a comprehensive listing of your ad inventory which should include the following properties where possible. If you're unable to define all properties that is ok we can simply apply our default best practices configurations to fill in the gaps.

  • Ad Element ID ( if static )
    • Incremental base id if incremental
  • Ad Sizes ( per element )
  • Bidders ( if you've configured them )
    • Inclusive of whether the unit should run through Amazon's apstag
  • Lazy load and/or lazy load offset rules
  • Out of page
  • Static site-wide targeting key/values
  • (Ad Experience, discussed in next section) What page types this unit runs on
  • (Ad Experience, discussed in next section) What devices this unit runs on
  • Site Wide Prebid Settings
    • Timeouts
    • User Sync Settings
    • User IDs
    • Any other pertinent configuration properties
  • Site Wide Amazon Settings
    • Timeout
    • Publisher ID, if necessary

Page Types​

Next we will need to account for various details around the ad experience you have or would like to have on your site. To do this we will need to define page types for your site. Generally these can be referred to as designations for a specific user experience/layout on your site. Examples include article, slideshows, home, category, database, database-item and so forth. We will need a sample URL for both staging and production for each of these page types such that we can properly organize our processes and for staging environments verify changes to your ad stack.

Important

If you've already worked through this step via Orion you do not need to do it again for BidRoll. However and additional implementation step(code) is needed for BidRoll.

Ad Experience​

Once we have these page types defined we can begin the granular definition of your ad experience. With Spiny's BidRoll library we can granlularly omit ads based on various runtime conditions we call this feature ad filtering. The various conditions we have available at this time for filtering are:

  • Orion Context Values
  • Device Type ( Desktop / Mobile )
  • Page Type
  • Page Targeting
  • Unit Targeting
  • Window variable
  • Local Storage Value
  • Cookie Value
  • Body Class

Simply let us know what various ad units you would like to filter out based on each property and we can configure this. Multiple filter types can be configured for each ad unit as well.

Pleae provide any additional details around your existing ad related integrations such as on-page tags. This should be inclusive of any integrations not related to standard display ads.

Bundle Generation​

Our team will need to generate a bundle based on the various requirements gathered before proceeding. Once we have generated a bundle and provided the url you can begin the next step.

Implementation​

Below we begin to define initial on page code implementation steps. Ideally these steps will initially live on an exposed staging site such that our team can confirm the implementation is working as intended. If you do not have a staging site to work with and cannot create one please let us know as we can potentially synchronize and accomodate production verification such that there is minimal issue if any do arise.

Script Reference​

Our script/bundle for BidRoll is included in our Pandora mono-library as a component. Ensure you reference the JavaScript bundle URL provided to you. Use the appropriate bundle for your environment: stage for exposed staging environments and prod for production environments.

The format of the bundle URL is as follows:

https://cdn-ext.spiny.ai/lib/pa/<ENVIRONMENT>/<ORGANIZATION>/<SITE DESIGNATION>/<BUILD>/pandora.min.js

Additionally if leveraging Spiny Ad Styles you will need to add the stylesheet reference for Pandora.

https://cdn-ext.spiny.ai/lib/pa/<ENVIRONMENT>/<ORGANIZATION>/<SITE DESIGNATION>/<BUILD>/pandora.min.css

Explanation of path parts:

  • <ENVIRONMENT>: Use stage for staging and prod for production.
  • <ORGANIZATION> (Optional): The organization designation for nesting sites. If not provided, it will be nested under sovereign.
  • <SITE DESIGNATION>: Usually the primary portion of the host name for the site.
  • <BUILD>: Initial value is usually default, representing the baseline bundle for your site.

Reference Attributes​

Use the following HTML script tag to reference the Pandora bundle for your site. You can use async or defer attributes for better site performance. Exclude Pandora from any plugins that perform post processing and script concatenation.

<script src="<SCRIPT URL>"></script>

Additionally if you're leveraging Spiny Ad Styles you will simple reference the stylesheet as a normal stylesheet in the <head>

<link rel="stylesheet" href="<CSS URL>">

Bootstrap Code​

If you use async or defer attributes, there might be a delay before the BidRoll library is available for your site's implementation. To handle this, use the following code in the <head> section of your page to enable the BidRoll queue interface:

window.bidroll = window.bidroll || { queue: [] };
window.bidroll.queue = window.bidroll.queue || [];

Once the BidRoll queue interface is available, you can push callbacks onto the window.bidroll.queue array to use any BidRoll methods within that callback. Example:

window.bidroll.queue.push(function(){
  // Full API of BidRoll is available in this scope

  const cancelListener = bidroll.on("initialize", function(...eventData){
    // do something with event data
  });

  const implementationConfig = {};

  bidroll.init(implementationConfig);

  // AFTER ad elements are available.
  bidroll.refresh(["preconfigued-div-id-1","preconfigured-div-id-2"]);

  // Cancellation trigger logic
  cancelListener();
})

Alternatively, you can use the provided bootstrap script to wrap various BidRoll methods in window.bidroll.queue and add window.bidroll.queue to the page. Note: that this method does not guarantee return values.

(function(s,p,i,n,y){s[i]=s[i]||{queue:[]};for(var x=0;x<n.length;x++){var m=n[x];s[i][m]=s[i][m]||function(){var a=arguments;s[i].queue.push(function(){s[i][m].apply(s[i],a)})}}if(y){var e=p.createElement("script");e.type="text/javascript";e.async=true;e.src=y;var f=p.getElementsByTagName("script")[0];if(f){f.parentNode.insertBefore(e,f)}else{var d=p.getElementsByTagName("head")[0];if(d){d.appendChild(e)}}}})(window, document, "bidroll", ["init","refresh","setConfig","on", "setPageTargeting"], null);

You will notice in the bootstrap code and array of function names ["init","refresh","setConfig","on", "setPageTargeting"]. These functions will be made available immediately after the bootstrap code is executed allowing your site side implementation to call the BidRoll library as you see fit with these methods. This array of methods will change if you have additional integrations. Please keep this in mind when implementing those additional integrations.

Ad Unit Markup​

For BidRoll we leverage some dynamic capabilities around the styling and ad element attributes. The following guidelines need to be followed to ensure your ad element markup is properly processed by BidRoll.

Autoloading​

BidRoll includes a common autoloader module that will automatically scan the DOM upon certain function calls and call refresh on them without the need for an explicit designation.

If the markup rules above are followed you can simply render these elements as needed and run the bidroll.init(implementationConfig) method or bidroll.detectAndRefresh(explicitDesignations?)

These autoloader module processes only works for an initial refresh subsequent refreshes will require a designation passed into the bidroll.refresh(<DESIGNATIONS>) call.

During onboarding process please be sure to let the Spiny team know you would like to enable the autoload module.

Standard Ads:​

info

my-predefined-ad in this section and the following sections refers to the Spiny Ad Unit Designation/Code.

<div id="my-predefined-ad"></div>

Manual Incremental Ads:​

If you would like to manually handle incrementing your ad units you can do so like below.

<div data-inherit="my-predefined-ad" data-increment="<INCREMENT>"></div>

<INCREMENT> should be a number representing the increment.

Auto Incremental Ads ( Recommended ):​

Use this syntax if you would like BidRoll to automatically handle increment of ad units.

<div data-inherit="my-predefined-ad" data-ad-unit></div>

Styled Ad Wrappers​

If you would like to leverage Spiny's ad styles please be sure to let us know so we can include and configure this in your BidRoll setup. Previously discussed ad elements will be referred to in the following examples as <AD ELEMENT> and data-inherit/id representing the preconfigured ad unit code will be represented as <AD UNIT CODE>

Additionally below you will see the usage of desktop in the classes. If leveraging filters of ad units based on device be sure to include the desktop version of the classes below and replace desktop with mobile for mobile experiences. If the ad unit is present on both you can simply omit these classes.

Mobile / Desktop Designations

Below you will see references to <mobile/desktop> please replace these with mobile where the unit only runs on mobile viewports and desktop where the unit only runs on desktop viewports. This step is important for designating ads to have the appropriate styles on these viewports.

Standard/Incremental Ad Container Styles​
<div class="spiny-ai-br-container spiny-ai-br-<mobile/desktop> <AD UNIT CODE>">
  <AD ELEMENT>
</div>
Adhesion Ad Container Styles​
<div class="spiny-ai-br-adhesion <mobile/desktop>">
  <div class="spiny-ai-br-container spiny-ai-br-<mobile/desktop> <AD UNIT CODE>">
    <AD ELEMENT>
  </div>
</div>

One popular ad experience to ensure you're getting optimal ad revenue and viewability is a sticky sidebar. For convenience our ad styles provide several classes to further streamline adding this where needed.


<div class="spiny-ai-br-sidebar-outer">
  <div class="spiny-ai-br-sidebar-inner">
    <div class="spiny-ai-br-container spiny-ai-br-<mobile/desktop> <AD UNIT CODE>">
      <AD ELEMENT>
    </div>
    <!-- Mid-sidebar site components -->
    <div class="spiny-ai-br-container spiny-ai-br-<mobile/desktop> <AD UNIT CODE>">
      <AD ELEMENT>
    </div>
  </div>
</div>

Library Initialization​

For a manual integration, call the following code on page load. This sets/merges your runtime configuration and initializes all modules. It also triggers an initial page view event. You can read more about what configuration capability is available here.

const implementationConfig = {
    // ... Your custom runtime configuration for BidRoll,
    targeting: {
        ptype: 'article' // replace value with the agreed upon page type for this layout/user experience
    },
  firstPartyData: {
    user: {
      email: "john@doe.com" // Where possible pass the end user's email. This will be one-way encoded(sha256) and passed to identity partners to enhance bid requests
    }
  }
}

bidroll.init(implementationConfig);
Important

Only call bidroll.init(implementationRuntimeConfig) once per client-side runtime.

For subsequent client-side page views, where client-side JavaScript renders more content or more than one page worth of data on a single server-side call, use the following verbose call when the user begins to scroll the subsequent page into view:

bidroll.newPageView({...newImplementationRuntimeConfig, destroyActiveUnits: false });

destroyActiveUnits is only necessary for full client side page transitions such as in the case with React Router or a similar client side routing library.

Ensure that newPageView is called before the next refresh call.

Ad Refresh​

Refresh is responsible for triggering the ad calls on page. You should only call refresh for ad units after they have rendered to the page. There are several ways you can define ad units. You can find the documentation for refresh here.

bidroll.refresh(['leader_top', 'leader_bottom', 'mpu_top', 'mpu_middle']); // Replace ad unit designations with the appropriate designations for the refresh at runtime.

// Additionally if you follow the ad mark up you can call the following and BidRoll will autoamtically detect on page ads.

bidroll.detectAndRefresh(['mpu_top']); // Only pass in designations you wish to explicitly refresh

Verification​

Once the above steps have been completed let our team know and we can verify the implementation is operating as expected.