NAV

Introduction

Welcome to the OpenAds Developer Docs.

For live support, visit our Discord or email support@openads.ai

Installation

<script async='' defer='' crossorigin='anonymous' src='https://js.stratos.blue/stratos.js'></script>

<script>
  window.stratosSettings = {
    publisherId: 'abcdef123456789', // your publisher ID goes here
  };

  window.stratos = window.stratos || { queue: [] };
  window.stratos.queue.push(function() {
    console.log('Stratos initialized!')
  });
</script>

Add this HTML snippet to the header of every page for OpenAds to track prompts, serve ads, and measure ad performance.

If concerned about race conditions with loading, best practice is to push commands into the stratos.queue Array, per the example.

All window.stratos SDK commands sent to the queue will execute in the order they were received after the stratos tag has finished loading.

Configuration

Declare initial settings

window.stratosSettings = {
  publisherId: 'loremipsum',
  logsEnabled: false,
  testMode: false,
  disableInitialLoad: true,
  collapseEmptySlots: true,
  enableRefresh: false,
  refreshSettings: { refreshTrigger: 'automatic', refreshRate: 30, requireViewable: true, viewableTimeThreshold: 10 },
  forceSafeFrame: false,
  safeFrameConfig: { allowOverlayExpansion: Boolean, allowPushExpansion: Boolean, sandbox: Boolean }
}

window.stratosSettings

Object for configuration options; define this before using other functions.

Authorize the integration by setting your publisherId, and include additional configuration options as desired.

Only publisherId is required.

Parameter Scope Type Description
publisherId Required String Required. Unique key identifying your OpenAds account. The "stratos" variable name avoids ad blockers that block "openADS"
logsEnabled Optional Boolean Toggle debugging logs to the console
testMode Optional Boolean Toggle debugging mode, where only 100% fill rate demo ads will be served.
disableInitialLoad Optional Boolean When true: does not immediately request ads for defined slots; ads will only be served upon a call to window.stratos.trackPrompt().
collapseEmptySlots Optional Boolean When true: collpases slot divs so they don't take up layout space on the page whne there is no ad to display.
enableRefresh Optional Boolean Toggle ad refresh upon subsequent trackPrompt responses
refreshSettings Optional Object Reserved/Unimplemented. Detailed control settings for ad refresh functionality.
forceSafeFrame Optional Boolean Reserved/Unimplemented. Sets whether this ad slot should load into a SafeFrame. Overridden by slot-level settings.
safeFrameConfig Optional Object Reserved/Unimplemented. Sets the page-level SafeFrame configuration (settings at the ad slot level override page-level settings).

Ad slots

Define ad slots

window.stratos.defineSlot({
  adUnitCode: "example-ad-unit",
  sizes: [[300, 250], [300, 600]],
  mediaTypes: ['display', 'native'],
  enableRefresh: true,
  refreshSettings: { refreshTrigger: 'automatic', refreshRate: 30, requireViewable: true, viewableTimeThreshold: 10 },
  forceSafeFrame: false,
  safeFrameConfig: { allowOverlayExpansion: false, allowPushExpansion: false, sandbox: true },
  adTemplate: `
    <style>@import url(https://fonts.googleapis.com/css2?family=Poppins:wght@400;500;700&display=swap);</style>
    <div class="sponsored-post" style="background-color: #f3e77a; border-radius: 18px; padding: 12px 17px;">
      <div class="content" style="font-size: 18px; font-family: 'Poppins', sans-serif;">
        <div>
          <div class="thumbnail" style="display: inline-block; vertical-align: middle; background-image: url('##hb_native_icon##'); width: 50px; height: 50px; background-size: contain; background-repeat: no-repeat;"></div>
          <div style="display: inline-block; vertical-align: middle; width: calc(100% - 70px); margin-left: 5px; font-weight: 500;">
            <a href="##hb_native_linkurl##" target="_blank" style="text-decoration: none; color: black">##hb_native_title##</a>
          </div>
        </div>
        <p style="margin: 0px; font-weight: 500">##hb_native_body##</p>
        <div class="attribution" style="background-color: rgb(210, 198, 100); color: #766f2b; padding: 10px 15px; margin: 15px 0 5px 0; border-radius: 18px; font-size:12px; font-weight:500; display: inline-block; line-height: 26px">##hb_native_brand##</div>
      </div>
    </div>`
});

window.stratos.defineSlot(params)

Define the container(s) for where on your site you want ads to appear, their sizing, and details of rendering

Parameter Scope Type Description
adUnitCode Required String Element ID for the container div where the ad should be loaded.
sizes Required Array[Number, Number] Supported width and height configurations for the ad slot. Use [1, 1] for native.
mediaTypes Required Array[String] One or more supported media types for this ad request. Values are 'banner', 'native', and 'chat'.
enableRefresh Optional Boolean When true: subsequent invocations to window.stratos.trackPrompt() will request new ads, and render them if there is a valid ad to serve.
refreshSettings Optional Object Reserved/Unimplemented. Detailed control settings for ad refresh functionality.
forceSafeFrame Optional Boolean Reserved/Unimplemented. Sets whether this ad slot should load into a SafeFrame. Overrides page-level settings.
safeFrameConfig Optional Object Reserved/Unimplemented. Sets the slot-level SafeFrame configuration (settings at the ad slot level override page-level settings).
adTemplate Optional HTML Template String HTML rendering template for native ads.

Track user prompt

Use this code to save your prompts to OpenAds for analytics, as well as trigger loading ads if valid slots have been defined and your account has been set up to support ad rendering.

window.stratos.trackPrompt(yourPromptGoesHere);