Write an OnBrowser Middleware for Doubleclick Ad Server

This article explains the steps to implement an OnBrowser Middleware for Doubleclick Ad Server Provider.

Doubleclick Ad Server Provider

Doubleclick Ad Server has different properties available at its schema (opens new window) and one of them is the json.targeting property. For this example, we want to add a targeting with the current referrer page.

The referrer can be obtained through the window object of the browser, so that's why we have chosen an OnBrowser Middleware.

OnBrowser Middleware Implementation guide

Our objective is to send this information to the Ad Server in an object that can be merged with the one defined at the inventory. So, it has to partially match with the Config object of Doubleclick (opens new window). In this case, the object will be something like this:

{
    json: {
        targeting: {
            referrer: "https://www.google.com"
        }
    }
}

Set up

First, create the src/middlewares/inventory/dfpTargetingReferrer/on-browser.ts file with the implementation, and the src/middlewares/inventory/dfpTargetingReferrer/on-browser.test.ts file with the test.

Then, install:

• Middleware types package

npm i --save-dev @marfeel/middlewares-types

• and Doubleclick Adserver Provider package (unless it's already installed)

npm i @marfeel/adserver-providers-doubleclick

Create a test

We recommend using a test-driven approach so, let's create the tests first.

You can check the How to create tests for Middleware article to see in detail how to create a test for an onBrowser middleware.

We will need to mock up the window object, since it is the input parameter of the onBrowser hook. And then, we will verify that the result of clling the onBrowser is an object like the one we are looking for.

//on-browser.test.ts

import { createMock} from 'ts-auto-mock'
import { onBrowser } from './on-browser';

describe('Doubleclick', () => {
    describe('OnBrowser', () => {
        test('returns the referrer in targeting', async() => {
            const window = createMock<Window>({
                document: {
                    referrer: 'https://google.com/'
                },
                location: {
                    href: 'https://marfeel.com/docs/'
                }
            });

            const result = await onBrowser({window});

            expect(result).toEqual({
                json: {
                    targeting: {
                        referrer: 'https://google.com'
                    }
                }
            });
        });
    });
});

Middleware Implementation

Once the test is ready, you need to obtain the referrer on the page. To do so, first access the Document (opens new window) object in Window (opens new window) and then access its referrer property.

    const referrer = window.document.referrer;

After obtaining the referrer, you need the onBrowser hook to return the result as an object partially matching the Doubleclick Config type.

//on-browser.ts
import { Config } from '@marfeel/adserver-providers-doubleclick';
import { onBrowserFunction } from '@marfeel/middlewares-types';

export const onBrowser: onBrowserFunction<Partial<Config>> = async({ window }): Promise<Partial<Config> | undefined> => {
    return {
        json: {
            targeting:{
                referrer: window.document.referrer
            }
        }
    };
}; 

Now, it's time to run npm test and validate the tests are passing.

Connect the pieces

1. Add the invokeMiddleware flag to the features.json and set it to true.

//features.json
{
  "features": {
    "invokeMiddleware": true
  }
}

2. Add the middleware to the Ad Server on inventory.json. It should be always at the top level of the Ad Server Config and its name has to be the same name you used to create the middleware folder.

//inventory.json
{
    "placements": {
        "bottom_details_1": {
            "adServer": "dfp"
        }
    },
    "adServers": {
        "dfp": {
            "type" : "doubleclick",
            "slot" : "/123456/test.com",
            "middleware": "dfpTargetingReferrer"
        }
    }
}

Now you can test the middleware with a tenant in your local environment or with a Preview Branch and check if the DFP calls are done with that targeting.

WARNING

If you are replacing a Custom Adserver for an OnBrowser Middleware, remember to remove all the old Custom Adserver files and their references.