Richie Ads HTML5 SDK

Overview

Richie SDK enables dynamic ad delivery and analytics for web applications. It is designed for easy integration into modern HTML5 sites, providing ad container management, event-driven API, and analytics reporting. This guide covers the basics for getting started.

Getting Started

1. Include the SDK

Add the Richie SDK script to your HTML page:

<script src="https://js.richie.fi/sdk/richie.sdk.js" type="text/javascript"></script>

2. Initialize the SDK

Call richie.init with your application ID. Optionally, you can specify a custom API base hostname. If not provided, it defaults to relative paths, and proxies should be used to forward those requests to Richie endpoints.

// Basic initialization (uses relative paths for API requests)
richie.init('com.example.site');
 
// With absolute API base hostname
richie.init('com.example.site', false, { baseHostname: 'https://data.richie.app' });

3. Listen for SDK Events

Richie SDK uses an event-driven API. Register listeners for key events:

richie.addEventListener('ready', function() {
  // SDK is initialized and ready
});
 
richie.addEventListener('error', function(err) {
  // Handle errors
});

Displaying Ads

Show an Ad in a Slot

Use nextFlightForSlotWithIdentifier to fetch the next available ad container for a given slot and add it to your page:

const adContainer = richie.nextFlightForSlotWithIdentifier('ad-slot-1');
if (adContainer) {
  document.getElementById('article-slot').replaceChildren(adContainer);
  richie.adBecameVisible(adContainer); // Notify SDK that ad is visible
}

Whether an ad is returned depends on slot intervals and limits. The API returns null if no ad is available. If the interval is 0, the API will return an ad on every call (unless slot or flight limits are reached). If the interval is greater than zero, the API will return an ad only if the specified interval has passed since the last ad was returned.

The returned ad container is a DOM element, which should be added to the document.

When the ad becomes visible on screen, call richie.adBecameVisible(adContainer).

Remove or Dismiss an Ad

richie.adWasDismissed(adContainer); // Notify SDK that ad was dismissed
richie.removeAd(adContainer);        // Remove ad container from DOM

Or, as a shortcut to dismiss and remove the ad:

richie.closeAd(adContainer);

Use richie.adBecameVisible(adContainer) when an ad comes onscreen.
Use richie.adWasDismissed(adContainer) when an ad is hidden or removed.

Example Integration

Fully working example that requests an ad once the SDK is ready and shows it in a predefined slot. Note: The target app ID/slot needs to have interval 0, so you get an ad every time.

<!doctype html>
<html lang="en">
  <head>
    <script src="https://js.richie.fi/sdk/richie.sdk-dev.js" type="text/javascript"></script>
    <style>
      #ad-slot-1 {
        width: 600px;
        height: 300px;
        margin: auto;
      }
    </style>
  </head>
  <body>
    <div id="ad-slot-1"></div>
    <script>
      function showArticleAd() {
        const adContainer = richie.nextFlightForSlotWithIdentifier('ad-slot-1');
        if (adContainer) {
          const adSlot = document.getElementById('ad-slot-1');
          // Check if there is currently an ad visible and remove it
          const currentAd = richie.currentAdContainer();
          if (currentAd) {
            richie.closeAd(currentAd); // Shortcut to dismiss and close
          }
          // Replace the slot's content with the new ad container
          adSlot.replaceChildren(adContainer);
          richie.adBecameVisible(adContainer); // Notify SDK that ad is visible
          return adContainer;
        } else {
          console.log('No ads available');
        }
      }
      richie.addEventListener('ready', function () {
        console.log('Richie SDK is ready');
        showArticleAd();
      });
      richie.init('richie-webtest', false, { baseHostname: 'https://data.richie.app' });
    </script>
  </body>
</html>

Supported Events

ready: SDK initialized and ad list fetched
adWasRemoved: Ad container was removed
error: Error occurred
adClose: Ad close button clicked
shouldOpenUrl: User clicked an ad link
analytics: Analytics event (only in preview mode)

Notes

Only one ad container can be active at a time. Remove the previous ad before displaying a new one. This limitation may be lifted in future versions.
Some API methods and features may change in future releases.
For advanced usage, refer to the full API documentation (coming soon).

Overview

Getting Started

1. Include the SDK

Add the Richie SDK script to your HTML page:

<script src="https://js.richie.fi/sdk/richie.sdk.js" type="text/javascript"></script>

2. Initialize the SDK

// Basic initialization (uses relative paths for API requests)
richie.init('com.example.site');
 
// With absolute API base hostname
richie.init('com.example.site', false, { baseHostname: 'https://data.richie.app' });

3. Listen for SDK Events

Richie SDK uses an event-driven API. Register listeners for key events:

richie.addEventListener('ready', function() {
  // SDK is initialized and ready
});
 
richie.addEventListener('error', function(err) {
  // Handle errors
});

Displaying Ads

Show an Ad in a Slot

Use nextFlightForSlotWithIdentifier to fetch the next available ad container for a given slot and add it to your page:

const adContainer = richie.nextFlightForSlotWithIdentifier('ad-slot-1');
if (adContainer) {
  document.getElementById('article-slot').replaceChildren(adContainer);
  richie.adBecameVisible(adContainer); // Notify SDK that ad is visible
}

The returned ad container is a DOM element, which should be added to the document.

When the ad becomes visible on screen, call richie.adBecameVisible(adContainer).

Remove or Dismiss an Ad

richie.adWasDismissed(adContainer); // Notify SDK that ad was dismissed
richie.removeAd(adContainer);        // Remove ad container from DOM

Or, as a shortcut to dismiss and remove the ad:

richie.closeAd(adContainer);

Use richie.adBecameVisible(adContainer) when an ad comes onscreen.
Use richie.adWasDismissed(adContainer) when an ad is hidden or removed.

Example Integration

Fully working example that requests an ad once the SDK is ready and shows it in a predefined slot. Note: The target app ID/slot needs to have interval 0, so you get an ad every time.

<!doctype html>
<html lang="en">
  <head>
    <script src="https://js.richie.fi/sdk/richie.sdk-dev.js" type="text/javascript"></script>
    <style>
      #ad-slot-1 {
        width: 600px;
        height: 300px;
        margin: auto;
      }
    </style>
  </head>
  <body>
    <div id="ad-slot-1"></div>
    <script>
      function showArticleAd() {
        const adContainer = richie.nextFlightForSlotWithIdentifier('ad-slot-1');
        if (adContainer) {
          const adSlot = document.getElementById('ad-slot-1');
          // Check if there is currently an ad visible and remove it
          const currentAd = richie.currentAdContainer();
          if (currentAd) {
            richie.closeAd(currentAd); // Shortcut to dismiss and close
          }
          // Replace the slot's content with the new ad container
          adSlot.replaceChildren(adContainer);
          richie.adBecameVisible(adContainer); // Notify SDK that ad is visible
          return adContainer;
        } else {
          console.log('No ads available');
        }
      }
      richie.addEventListener('ready', function () {
        console.log('Richie SDK is ready');
        showArticleAd();
      });
      richie.init('richie-webtest', false, { baseHostname: 'https://data.richie.app' });
    </script>
  </body>
</html>

Supported Events

ready: SDK initialized and ad list fetched
adWasRemoved: Ad container was removed
error: Error occurred
adClose: Ad close button clicked
shouldOpenUrl: User clicked an ad link
analytics: Analytics event (only in preview mode)

Notes

Only one ad container can be active at a time. Remove the previous ad before displaying a new one. This limitation may be lifted in future versions.
Some API methods and features may change in future releases.
For advanced usage, refer to the full API documentation (coming soon).

Richie Ads HTML5 SDK

Overview

Getting Started

1. Include the SDK

2. Initialize the SDK

3. Listen for SDK Events

Displaying Ads

Show an Ad in a Slot

Remove or Dismiss an Ad

User Actions & Analytics

Example Integration

Supported Events

Notes

Richie Ads HTML5 SDK

Overview

Getting Started

1. Include the SDK

2. Initialize the SDK

3. Listen for SDK Events

Displaying Ads

Show an Ad in a Slot

Remove or Dismiss an Ad

User Actions & Analytics

Example Integration

Supported Events

Notes