@frontity/smart-adserver

Smart Adserver is an ad serving network and they provide an API for displaying the ads which is described here.

The @frontity/smart-adserver package will load a third-party Smart Adserver library which adds certain properties on the global window object. Then you as the developer can render the exposed <SmartAd> component, which will use those properties to make the "ad call" (which are basically API calls to the Smart Adserver).

In response, the Smart Adserver dynamically loads some code which will modify the DOM to insert the ad in the place that the <SmartAd> component was rendered.

The package has 3 main components:

• The "Root" component. It includes the <Head> that loads the Smart Adserver library. When the user adds the @frontity/smart-adserver to their frontity.settings.js file, this library will be loaded automatically.
• The SmartAd component. This component is exposed in libraries.fills.SmartAdserver.SmartAd. The users can just use this component directly to display ads by passing it relevant props. The component takes care of calling the Smart Adserver API and injecting the ad into the DOM in the relevant place
• Ability to specify the ads in fills in the frontity.settings.js file. Ads can be placed in specific slots in a theme by using that approach.

Table of Contents⁠#

• Installation
• Settings
  • Object properties
    • The props property
• Examples
• Usage
  • Using the Slot & Fill pattern
  • Using the Ad component directly

Installation⁠#

The package can be installed like:

npm i @frontity/smart-adserver

Settings⁠#

This package can be included in your frontity.settings.js file as one of the packages that will be part of your Frontity project.

The namespace for this package is smartAdserver. To use the Slot and Fill pattern with this package we should add a settings object to state.fills under the smartAdserver namespace.

Each fill in the smartAdserver namespace is an object which should be assigned to an arbitrarily named key. The structure should be as follows:

export default {
  packages: [
    {
      name: "@frontity/smart-adserver",
      state: {
        fills: {
          smartAdserver: {
            arbitrary_fill_name: {
              // Object properties
            },
          },
        },
      },
    },
  ],
};

Object properties⁠#

To define a SmartAd using the Slot & Fills pattern we use the standard FilL properties

The props property⁠#

An object with props that will be passed to the <Slot> component.

Examples⁠#

module.exports = {
  packages: [
    ...,
    {
      name: "@frontity/smart-adserver",
      state: {
        // Global settings.
        smartAdserver: {
          networkId: 620,
          subdomain: "www8",
        },
        fills: {
          smartAdserver: {
            // This ad is using the 'std' call: https://support.smartadserver.com/s/article/Tagging-guide
            stdAd: {
              slot: "header",
              library: "smartAdserver.SmartAd",
              props: {
                callType: "std",
                siteId: 103409,
                pageId: 659846,
                formatId: 14968,
                tagId: "below-header-14968", // The id of the container where we render the ad.
                minHeight: 100, // In px, optional.
              },
            },
            // This ad is using the 'iframe' call: https://support.smartadserver.com/s/article/Tagging-guide
            iframeAd: {
              slot: "content",
              library: "smartAdserver.SmartAd",
              props: {
                siteId: 103409,
                pageId: 659846,
                formatId: 14968,
                tagId: "below-content-14968",
                width: 300, // Should be specified if callType === 'iframe'.
                height: 600, // Should also be specified if callType === 'iframe'.
              },
            },
          },
        },
      },
    },
  ],
};

Usage⁠#

Using the Slot & Fill pattern⁠#

The recommended usage of this component is using the Slot and Fill pattern. The configuration of the fill(s) is done in the state.fills.smartAdserver namespace in frontity.settings.js as explained above.

With this configuration we can then insert the Slots representing the Ads in any React component.

import { Slot, ... } from "frontity";

const MyComponent = () => {

  return (
    <>
      ...
      <Slot name="header" />
      ...
      <Slot name="content" />
      ...
    </>
  );
};

...

export default MyComponent;

Using the Ad component directly⁠#

Alternatively, since the Ad component is exposed in libraries, you can get the SmartAd component from libraries and render it wherever you wish.

const MyComponent = ({ libraries, ...props }) => {
  const MySmartAd = libraries.fills.smartAdserver.SmartAd;
  const {siteId, pageId, formatId} = props
    return (
      <MySmartAd
        callType="std"
        siteId={siteId}
        pageId={pageId}
        formatId={formatId}
        tagId="test-smartad"
        css={css`
          border: 5px solid dotted;
        `}
      />
    );
};

export connect(MyComponent);