AppNexus Ad Server is a comprehensive hosted ad serving platform that streamlines your ad management, whether you deliver ads to websites, mobile webpages, mobile apps, games, or a combination.

Permutive is able to integrate with AppNexus to enable you to target your impressions to Permutive segments, while also creating segments in AppNexus based on impressions. Since Permutive updates in real-time, our integration enables you to target users from the very first time they arrive on-site.

This integration enables the following functionality:

This integration includes support for event collection. Our platform support matrix shows which events we are able to collect:

* Out-of-the-box, our AppNexus integration attempts to collect clicks on ad iframes. This may lead to inaccuracies in some cases, e.g. for rich media or video ads. Permutive offers more comprehensive solutions for ad click tracking if needed - talk to your CSM to find out more.

Setup - Web

On Web, we integrate directly with the AppNexus Seller Tag which will be running on your page. Our integration interacts with this tag to send Permutive targeting data to AppNexus as slot-level key-value pairs.

Prerequisites

• AppNexus Installation - You must already have the AppNexus Seller Tag installed on your site and configured to serve your advertising campaigns.
• AppNexus User - You must create an AppNexus user account for our integration can use. Please grant this account the "Network Observer" role, as Permutive will need permissions to manage your key-values and segments in AppNexus.
• API Access - You must have API access enabled on your AppNexus network. To get this enabled, please discuss this with your AppNexus account manager.

Enabling the Integration

You must enable this integration in the Permutive dashboard, if this has not already be done. In the Permutive dashboard, navigate to your project integrations page. Click Add Integration and select AppNexus Ad Server.

You will be asked to enter your AppNexus Username, Password and Member ID at this stage.

Optional configuration

The rest of the configuration is optional and can be left at default values. These setting are Expiration (minutes), Segment name prefix and Segment code prefix.
Expiration determines how long a user stays in a segment, the default is the AppNexus default of 180 days.
The segment name and code prefix make created segments distinctive in the AppNexus console, see the behind the scenes section for an example.

JavaScript Changes

You'll need to deploy a small piece of additional JavaScript on-site, alongside the Permutive tag, to enable a seamless integration with AppNexus. This JavaScript ensures that we are always able to target users with data collected on their previous pages views or browsing sessions. It also ensures that we collect all ad events, even if the events occur before Permutive has fully loaded.

window.apntag = window.apntag || {};
window.apntag.anq = window.apntag.anq || [];
window.__permutive = window.__permutive || {};
window.__permutive.appnexusEvents = window.__permutive.appnexusEvents || [];
['adRequested', 'adAvailable', 'adBadRequest', 'adLoaded', 'adNoBid', 'adError', 'adCollapse'].forEach(function (eventType) {
  window.apntag.anq.push(function() {
    window.apntag.onEvent(eventType, function (arg) {
      window.__permutive.appnexusEvents.push({
        eventType: eventType,
        arg: arg
      });
    });
  });
});
window.apntag.anq.push(function() {
  var original = window.apntag.defineTag;
  window.apntag.defineTag = function(arg) {
    original(arg);
    try {
      if (arg.targetId) {
        var kvs = window.localStorage.getItem('_papns');
        window.apntag.setKeywords(arg.targetId, { "permutive": kvs ? JSON.parse(kvs) : [] }, { overrideKeyValue: true });
      }
    } catch(e) { /* Ignore */ }
  }
});

Behind the Scenes

This section explains how Permutive integrates with AppNexus AdServer and is not required to enable and use the integration.

Enabling the Integration

When you enable the integration in the Permutive dashboard, we will create key with the name permutive in your AppNexus Key/Value targeting, if one does not already exist.

Creating Reactions

When you create new reactions in the Permutive dashboard, we will create a value under the permutive key in your AppNexus Key/Value targeting. In addition a segment is created in the AppNexus Segment Manager.

The properties of the AppNexus value and segment are determined by the Permutive segment and optional integration configuration.

To demonstrate this if a reaction were setup for the Permutive segment with name All Users and code 12345 then the AppNexus targeting value and segment would be created as follows (assuming default integration configuration):

Targeting value name: 12345
Targeting value label: All Users

Segment code: permutive_12345
Segment name: Permutive: All Users (12345)

Once Configured

While a user is in a Permutive segment with a configured reaction, ad requests to AppNexus will include the created key/value combination. The user will also enter the AppNexus segment as a result, which is handled by AppNexus internally.