Smart Adserver

Description

This package will ease the integration of a Frontity site with Smart Adserver, letting you to configuring it in frontity.settings.js, adding there your client info and the fills for your ads in order to make them appear in a specific slot (see Slot and Fill).

General settings would be in the state, under the smartAdserver namespace.

Specific ad settings would be in the definition of each fill.

Also, you would be able to get the Ad component from libraries and render it in any place.

UserStories

As a Frontity user
I want to install and configure the Smart Adserver package
so that I can show ads from Smart Adserver in a site, without coding.

As a Frontity user
I want to create fills (see Slot and Fill) with ad components
so that I can show ads in specific slots of a Frontity theme.

As a Frontity user
I want to use the Ad component directly
so that I can show ads in my own theme without using fills.

The next two user stores are going to be developed in a different FD:

As a Frontity user
I want to show ads in SSR
so that a visitor would see ads without having to wait ot React to do the CSR.

As a Frontity user
I want to lazyload ads
so that I can show ads without harming visitors experience.

Possible solution

Initial proposed solution (click to open)

Any ad package should expose the Ad component in libraries, under its specific namespace (in this case smartAdserver), or following the rules decided on Slot and Fill.

Apart from that, the implementation of each package would be limited to the specific Ad component and the integration with the ad provider.

Ads should work on SSR, so the way to render them should be using the Script component or something like that. The same for setup tags.

Examples

  • Add an ad above the first post of any archive.
  • Add ads in the middle of a post’s content, below the header, above the footer, etc.

References

  1. Guide explaining how to use the Smart AdServer API to create ad tags: https://support.smartadserver.com/s/article/Tagging-guide
  2. Related Smart AdServer documentation: https://support.smartadserver.com/s/categorylist?category=Ad_calls_and_ad_tags
  3. The implemetation of this component in our old framework (link)
  4. Functions used in the previous component, rendered as strings inside <script> tags (link)

Possible implementation

Possible implementation

:warning: In this proposal wasn’t included how to implement the lazy-load feature.

Installation

The package would be named @frontity/smart-adserver. This would be the way to install it:

npm i @frontity/smart-adserver

This how to configure it in frontity.settings.js:

module.exports = {
  packages: [
    "@frontity/mars-theme",
    "@frontity/tiny-router",
    "@frontity/wp-source",
    {
      name: "@frontity/smart-adserver",
      state: {
        // Global settings.
        smartAdserver: {
          networkId: 620,
          subdomain: "www8"
        }
        // Fills with ads.
        fills: {
          smartads1: {
            slot: "Below Header",
            library: "SmartAd",
            props: {,
              siteId: 103409
              pageId: 659846,
              formatId: 14968,
              tagId: "below-header-14968",
              width: 300,
              height: 600
            }
          },
          smartads2: {
            slot: "Below Content",
            library: "SmartAd",
            props: {
              siteId: 103409
              pageId: 659846,
              formatId: 14968,
              tagId: "below-content-14968",
              width: 300,
              height: 600
            }
          }
        }
      }
    }
  ]
}

Settings

All the following settings are required:

state.smartAdserver.networkId

The network id assigned to this client (e.g. 620). Used in the Root component to setup the Smart Adserver library. Required.

state.smartAdserver.subdomain

The subdomain assigned to this client (e.g. www8). Used in the Root component to setup the Smart Adserver library.

Roots

roots.smartAdserver

The component that loads and sets up the Smart Adserver libraries. It should use networkId and subdomain from state.smartAdserver.

import React from "react";
import { Head, connect } from "frontity";

const SmartAdserver = ({ state }) => {
  const { networkId, subdomain } = state.smartAdserver;

  React.useEffect(() => {
    window.sas = window.sas || { cmd: [] };
    window.sas.cmd.push(function () {
      window.sas.setup({
        networkid: networkId,
        domain: `//${subdomain}.smartadserver.com`,
        async: true,
      });
    });
  }, []);

  return (
    <Head>
      <script
        src={`//ced.sascdn.com/tag/${networkId}/smart.js`}
        async
      />
    </Head>
  );
};

export default connect(SmartAdserver);

Libraries

libraries.fills.SmartAd

Component that renders an ad. It would receive the following properties, defined for each ad in state.fills:

  • siteId (number): identifies the website on Smart Adserver.
  • pageId (number): identifies the page on a website.
  • formatId (number): identifies the format (medium rectangle, skyscraper, etc.).
  • tagId (string): id for the <div> container, just to know where to render it.

    :bulb: This prop was generated like this (in the old implementation).

  • target (string, optional): used to pass keywords and key=value pairs.

    :bulb: This value was got from entities in the past (see this).

  • width (number): value in pixels.
  • height (number): value in pixels.

This could be the implementation:

import React from "react";
import { css } from "frontity";

const SmartAd = ({
  siteId,
  pageId,
  formatId,
  tagId,
  target,
  width,
  height,
}) => {
  React.useEffect(() => {
    const sas = window.sas || (window.sas = { cmd: [] });
    sas.cmd.push(function () {
      sas.call("std", {
        siteId,
        pageId,
        formatId,
        target,
        width,
        height,
        tagId,
      });
    });
  }, []);

  return (
    <div
      id={tagId}
      css={css`
        width: ${width}px;
        height: ${height}px;
      `}
    />
  );
};

export default SmartAd;

Issues

  • Settings and Root component
  • SmartAd component

Awesome work @david.

For what I see in their site and twitter, it seems like they consider smart ad and server as three different words:

If that’s the case, I would use the namespace SmartAdServer and the package name @frontity/smart-ad-server instead. What do you think?

Also, could you please add links to their documentation?

I chose the same name they use in their homepage, but I have no problem changing it.

  • Smart Adserver | The Most Powerful Adserving and RTB Platform

I’ll add the links in the References section.

You’re right. It looks like they use both indistinctly so keep it as it is. Sorry about that.

I’ve edited the implementation proposal to replace the <Script> component by React.useEffect hooks.