# Middleware

Marfeel offers a set of Providers that can be used to enhance the behavior of your site. They can be used to integrate with different metrics and analytics platforms or add custom functionality via Widgets.

These providers usually require a set of parameters for them to work correctly. Some of these parameters don't change and can be configured in the corresponding JSON file in the Media Group.

Other parameters are more dynamic, and cannot be defined in the corresponding JSON file. This could be things like:

An Ad Server attribute that needs to be extracted from the page's HTML.
Values that change per user session or depending on what page the user is on. This could be things like document.referrer or the URL for a video.

This is where Middleware comes into play, they are small functions that you can connect with your provider to extract the data you need from a page and pass it on to your Provider.

Middleware works the same way for all types of Providers, so when you've gotten familiar with them you will be able to use them for all kinds of Providers.

# Recognizing a Middleware

When working with a Media Group, you can find the Middleware under the path example.com/marfeelName/src/middlewares. Inside the middlewares folder, the Middleware is grouped under different folders to avoid naming conflicts.

For example, a site with Middleware for the Youtube Playlist Widget Provider, Doubleclick Ad Server Provider, Adsense Ad AdServer Provider and for Google Analytics Provider can have a file structure like this:

example.com/
└── index/
    └── src/
        └── fixtures/
        │   └── some-news-article.html
        │
        └── middlewares/
            └── widgets/
                └── youtube-playlist/
                    ├── on-browser.ts
                    ├── on-browser.test.ts
                    ├── on-extraction.ts
                    └── on-extraction.test.ts
            └── inventory/
                ├── dfpUrlTargeting/
                │   ├── on-browser.ts
                │   ├── on-browser.test.ts
                │   ├── on-extraction.ts
                │   └── on-extraction.test.ts
                └── adSenseTargeting/
                    ├── on-extraction.ts
                    └── on-extraction.test.ts
            └── analytics/
                └── ugaCustomEvents/
                    ├── on-browser.ts
                    ├── on-browser.test.ts
                    ├── on-extraction.ts
                    └── on-extraction.test.ts

To cover a wide variety of use cases, Middleware provides multiple hooks that you can use to extract the data you need. These hooks are defined as TypeScript functions which enforce that the correct data is returned.

TIP

If you are unfamiliar with TypeScript, TypeScript in 5 minutes (opens new window) provides a good introduction.

# Middleware Prerequisites

Mediagroup Compatibility

Middleware is only available for Media Groups with XP as a Library.

First of all, you will need to enable Middleware in the Media Group by setting the feature flag invokeMiddleware to true.

{
    "features": {
        "useMarfeelXPAsALibrary": true,
        "invokeMiddleware": true
    }
}

Then you will need to install the type definitions for Middleware which makes the TypeScript compiler aware of the different Middleware hooks.

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

You will also have to make sure that the Provider you are writing the Middleware for is installed in the Media Group.

npm i @marfeel/widget-providers-youtube-playlist

TIP

To validate these packages are installed, check the package.json file at the root of the Media Group repository.

# Middleware Hooks

The two available hooks for data extraction using middleware are:

# OnExtraction

Use the OnExtraction hook when you need to extract values from the original HTML of a page.

# OnBrowser

Use the OnBrowser hook is used when you need to retrieve a value from the Window (opens new window) object of the page that varies every time the page is opened. Eg. To retrieve information about the page referrer.

# Connect Middleware to a Provider

A Middleware is always used in combination with an analytic, widget or ad server provider. The integration between them is accomplished by adding the middleware field to your Provider configuration in either analytics.json, widgets.json or inventory.json.

// analytics.json

{
  "googleanalytics": [
    {
      "vars": {
        "account": "UA-383432-5"
      },
      "triggers": {
        "__extends": "marfeel/index/resources/analytics/triggers/googleanalytics/pageview.json"
      },
      "middleware": "ugaCustomEvents"
    }
  ]
}

// widgets.json

{
  "widgets": [
    {
      "type": "provider",
      "id": "youtube-playlist",
      "name": "youtube-playlist",
      "selector": ".video_playlist",
      "middleware": "youtube-playlist",
      "parameters": {
        "videoSrc": "",
        "videos": []
      }
    }
  ]
}

// inventory.json

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

TIP

The parameters are mandatory in the youtube playlist widget.json object. However, the attribute will get replaced by the right values after the middleware execution.

WARNING

Each Provider can be linked to only one Middleware. Each Middleware though can use several hooks.

# Known issues

No open known issues right now.

# Learn More

Check out the following articles for hands-on guides that will help you work with Middleware:

← Providers OnExtraction hook →