Marfeel Docs

# Ad server providers

Ad server providers are the Marfeel standard for both custom and core ad server extensions.

Learn how to create a provider in the specific guide.

# Find an ad server provider

Ad server providers are published in the Marfeel releases repository (opens new window) and can be found by looking for adserver-providers-* packages. Their source code is usually stored in its own repository, e.g. Marfeel/Taboola (opens new window) or Marfeel/MGID (opens new window).

# Mandatory files

Providers must contain several files in addition to their Javascript implementation:

# Package setup

  • package.json contains the package configuration and the information required to publish the ad server.
  • README.md contains a short description of the ad server and instructions on how to use, debug and publish it.

# Ad server implementation and unit tests

  • src/index.js is the entry point of the Javascript implementation.
  • src/index.test.js contains unit tests for the entry point.

# Schema and schema tests

  • schema/index.json contains the JSON schema used to validate the ad server on inventory.json.
  • schema/test/valid/index.test.json contains a valid test for the ad server JSON schema.
  • schema/test/wrong/index.test.json contains a wrong test for the ad server JSON schema.

# Provider Extractor

  • extractor/index.ts extractor code that Alfred will use to detect this ad server provider on a tenant page.
  • extractor/index.test.ts contains unit tests for the extractor code.

# Available Scripts

NPM Script Ad Server Providers CLI Action
npm run build npx adserver-providers build Builds the adserver
npm run build:dev npx adserver-providers build:dev Builds the adserver in dev mode
npm run test npx adserver-providers test Runs unit tests with jest
npm run test:watch npx adserver-providers test:watch Runs unit tests in watch mode
npm run lint npx adserver-providers lint Runs the linter
npm run start npx adserver-providers start Builds and runs playground

Some advanced actions can only be run using adserver-providers:

  • scaffolding
  • only acid-test
  • etc.

See next section for more details.

# Ad Server providers CLI

There is a @marfeel/adserver-providers-cli (opens new window) command-line tool defined as a dependency of every ad server provider. It exposes an adserver-providers binary that can be used to build, debug and test ad servers.

WARNING

  • Some CLI commands require npx to be executed. It is an npm runner for Node.js executables and is pre-bundled with npm since version 5.2.0, so it should be available on most of the environments. Check npx official documentation (opens new window) for more information.
  • All the commands must be executed from the root directory of the ad server.
  • scaffold generates a preview version of all the mandatory files inside the current directory.
npm run scaffold
  • build generates a production-ready bundle from the source code. It creates at least two files inside the dist folder, one for legacy browsers and another one ES2015 compliant.
npx adserver-providers build

npx adserver-providers lint
  • test runs the unit tests defined in src/*.test.js files.
npx adserver-providers test
  • test:watch runs the unit tests in watch mode.
npx adserver-providers test:watch

  • acid-test runs a suite of integration tests to check if the provider fits the minimum requirements to be published. Those tests are common for all the ad servers and check the following:

    • Mandatory files are present
    • Mandatory methods are present and return proper values
    • Performance (bundle weight and execution time must be under a threshold)
    • DOM is not modified during the execution
npx adserver-providers acid-test
  • acid-test:watch runs the acid tests in watch mode.
npx adserver-providers acid-test:watch
  • test:all runs both unit and acid tests
npx adserver-providers test:all
  • playground:start builds and serves a web tool to test the ad server in your local environment. It provides a visual interface to test different setups without having to integrate the ad server into a tenant.
npx adserver-providers playground:start
  • playground:build is like playground:start but, instead of serving the tool using a local web server, it generates a static bundle that can be shared, opened or installed anywhere. The resulting files can be found in the playground-dist folder.
npx adserver-providers playground:build

# How to use an ad server provider

Check the in-depth explanation of when to use an ad server provider, and how.

← Legacy ad servers →