Skip to main content

BidRoll - Getting Started ( WordPress )

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

Implementing the BidRoll Library WordPress

This guide provides concise steps for implementing the BidRoll library for on-page ads. Using our WordPress integration certain steps are much more abbreviated as our integration with WordPress allows our libraries to have a server side component and our team can manage more aspects of the integration.

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​

Spiny's WordPress plugin will handle rendering the script to the page. A member of the Spiny team will ensure the appropriate bundle URL is configured.

Reference Attributes​

Since the script itself will be rendered by the Spiny WordPress plugin if you have a preference of load(async or defer) attribute you would like to apply simply let our team know and we will make the appropriate configuration change to the WordPress plugin.

Bootstrap Code​

The Spiny WordPress plugin will render the necessary bootstrap code for BidRoll to perform normal operations. If you do leverage additional methods that don't seem to be working as expected in your implementation please let our team know and we can make the appropriate updates to your plugin code.

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>

Page Type​

For WordPress if you're leveraging the various aspects of the WordPress ecosystem as their default setup certain page types such as articles, categories, authors, tags, and the home page types will be automatically handled by our WordPress plugin. However if you have custom pages that you would like to track as separate page types or have replaced one of the previously mentioned page types with a custom 'page' you will need to call bidroll.setPageTargeting({ptype: "<PAGE TYPE>"}) to set the appropriate page type.

Initialization​

For a WordPress integrations we enable our autoload functionality out of the box. The WordPress plugin will setup all the necessary data to ensure BidRoll gets all the necessary data. Our autoload feature will automatically call the following code in the page footer. You can read more about the configuration here.

Important

If you're using "pages" or non-standard WordPress pages for content items/user experiences you will need to tell BidRoll the page type prior to initialization. To do this your site side code should call bidroll.setConfig("targeting.ptype", "article"); except replace "article" with the appropriate agreed upon page type.

bidroll.init(window.spiny.bidroll.initData);

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

Refresh​

In addition to automatically initializing, BidRoll's autoload functionality will call bidroll.detectAndRefresh() in the site footer. This allows all necessary ad elements to render and then be detected by BidRoll automatically for refresh. So the initial refresh is handled for you given the ad unit elements follow the specification above in this guide. Subsequent refreshes will need to be called manually. See the documentation for refresh here.