Microsoft Monetize

Microsoft Monetize (Ad Server)

Microsoft Monetize (formerly Xandr, AppNexus) is a comprehensive ad serving platform that enables publishers to manage and monetize their advertising inventory with advanced targeting and reporting capabilities.

Setup

Troubleshooting

Overview

Microsoft Monetize (formerly Xandr, AppNexus) is Microsoft’s ad serving platform that provides publishers with tools to manage, deliver, and optimize advertising campaigns. Our integration with Microsoft Monetize enables you to activate Permutive cohorts for real-time targeting and collect comprehensive ad performance data for insights and optimization. This integration is both a Source and Destination:

Source: Permutive collects ad impression and click events from Microsoft Monetize.
Destination: Permutive activates your cohorts in Microsoft Monetize using targeting key-value pairs.

Use cases include:

Target your advertising campaigns in real-time with rich Permutive cohorts using Microsoft Monetize’s ad server.
Track ad impressions and clicks in Permutive for insights, retargeting, or modeling.
(Advanced) Log-Level Data: Ingest comprehensive ad event data from Microsoft Monetize Log-Level Data Feeds for enhanced reporting and mobile support.

Environment Compatibility

Environment	Supported	Notes
Web		Full support with AppNexus Seller Tag
iOS		Supported via Permutive SDK add-on
Android		Supported via Permutive SDK add-on
CTV		Supported via Permutive CTV SDKs
API Direct		For environments where SDK deployment is not possible

Prerequisites

Member ID - You must provide your Microsoft Monetize Member ID, which can be found in your Microsoft Monetize dashboard.
User Credentials - You must create a Microsoft Monetize user account for Permutive with appropriate permissions. We recommend using an account with the following permissions:
- View and edit key-values
- Create and manage targeting keys
- Access to inventory settings
AppNexus Seller Tag - For Web integration, you must already have the AppNexus Seller Tag installed on your site and configured to serve your advertising campaigns.

Show Advanced: Log-Level Data Feeds

Log-Level Data Prerequisites

For comprehensive ad event tracking including mobile support and line item IDs, Permutive can ingest Microsoft Monetize Log-Level Data Feeds.

You must have access to Microsoft Monetize’s Log-Level Data Feeds feature.
You must be able to configure log export to a Permutive-provided GCS bucket.
You must provide your Microsoft Monetize Member ID (this must match the member ID writing to the GCS bucket).

Setup

Primary Setup Steps
Web
iOS
Android
API Direct

Enable in Permutive Dashboard

You must enable the Microsoft Monetize (Ad Server) integration in the Permutive dashboard. In the Permutive dashboard, navigate to your workspace’s integrations page. Click Add Integration and select Microsoft Monetize (Ad Server).You will be asked to provide:

Your Microsoft Monetize Member ID
Microsoft Monetize username and password (for API access)

Verify Key-Values in Microsoft Monetize

In your Microsoft Monetize dashboard, navigate to Inventory => Key-Values and search for permutive. You should find that a targeting key has been created for permutive. If you cannot find the targeting key, please reach out to Permutive Support.

Verify Setup

In the Permutive Dashboard, navigate to one of your cohorts. Check that the Microsoft Monetize (Ad Server) activation sync is visible. You can try toggling this to On. After doing this, in your Microsoft Monetize dashboard you should see a new targeting value created under the permutive targeting key, with the value corresponding to your cohort’s ID. This verifies your integration setup is successful.

Show Advanced: Log-Level Data Feeds

Log-Level Data Setup

Enable Log Ingestion in Permutive Dashboard

Enable the Microsoft Monetize Log-Level Data integration in your Permutive Dashboard. You will need to specify:

Your Microsoft Monetize Member ID
Whether to ingest clicks
Whether to ingest impressions

When enabled, Permutive will create a GCS bucket permutive-xandr-logs-<member_id> for your log files.

Configure Log Export in Microsoft Monetize

In your Microsoft Monetize account, configure your Log-Level Data Feeds to export to the Permutive-provided GCS bucket.

Verify Setup

Check back after 24 hours. You should see new events (XandrLogAdImpression and XandrLogAdClick) on the Events page in your Permutive Dashboard with line item IDs included.

Log-Level Data integration requires the standard Microsoft Monetize (Ad Server) integration (for event collection) to be enabled first.

Deploy Microsoft Monetize-specific JavaScript

You’ll need to deploy additional JavaScript on-site, alongside the standard Permutive tag. This script ensures that we are always able to target users with cohort membership data from their previous page views or browsing sessions, and that we collect all ad events even if they occur before Permutive has fully loaded.We recommend deploying this script immediately above the Permutive tag:

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 */
    }
  };
});

In many cases, this step will have been carried out as part of your initial Permutive deployment.

Integrate Permutive with Microsoft Monetize on Android

You’ll need to integrate the Permutive Android SDK with your Microsoft Monetize (Xandr) ad requests to enable cohort targeting in-app.Alongside our Android SDK, you must add our Xandr/AppNexus add-on dependency to your Gradle build:

implementation("com.permutive.android:appnexus:1.7.0")

implementation "com.permutive.android:appnexus:1.7.0"

Our Android SDK then provides methods to automatically add Permutive targeting to your Xandr ads and track impressions:

// For AdViews - add Permutive targeting
banner.addPermutiveTargeting(permutive)
banner.loadAd()

// For NativeAdRequests - add Permutive targeting
nativeAd.addPermutiveTargeting(permutive)

// For impression tracking - without existing listener
banner.setPermutiveAdListener(permutive)

// For impression tracking - with existing listener
banner.setPermutiveAdListener(
    permutive,
    object : AdListener {
        // ... your listener methods
    }
)

// For AdViews - add Permutive targeting
banner.addPermutiveTargeting(permutive);
banner.loadAd();

// For NativeAdRequests - add Permutive targeting
nativeAd.addPermutiveTargeting(permutive);

// For impression tracking
banner.setPermutiveAdListener(permutive);

If you are already using an AdListener, pass it as the optional second parameter to setPermutiveAdListener to avoid conflicts with Permutive impression tracking.

Cohort Activation via API Direct

In environments where it is not possible to deploy a Permutive SDK, you can use Permutive’s CCS (Custom Cohort Segmentation) API for event tracking and segmentation instead.Access to this API requires customer-specific authorization. You will need a dedicated API key from Permutive.

How it Works

The CCS API can be used to:

Track events for a specific user (optional)
Retrieve cohort IDs for activation

The events array in the request is optional. If you only need to retrieve cohort memberships without tracking a new event, you can pass an empty array.

Example Request:

curl --request POST \
     --url 'https://api.permutive.app/ccs/v1/segmentation?activations=true&synchronous-validation=false&k=PERMUTIVE_API_KEY' \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data '
{
  "alias": {
    "tag": "user_id",
    "id": "12345"
  },
  "events": [
    {
      "name": "Pageview",
      "time": "2025-10-02T09:40:43.179Z",
      "properties": {}
    }
  ]
}
'

The API accepts a user identity passed in the alias object. Permutive then either links this identity to an existing Permutive user ID or creates a new Permutive user ID if the identity hasn’t been seen before.For cross-environment segmentation and targeting, the identity provided should be consistent with identities used in your other environments (web, app).Example Response:

{
  "user_id": "2008c38f-dece-4570-976d-87593ed001c3",
  "cohorts": ["12345", "23456", "34567"],
  "activations": {
    "appnexus_adserver": ["12345"]
  }
}

The API response includes cohort IDs for Microsoft Monetize activation under the appnexus_adserver key within the activations object. These can then be passed to Microsoft Monetize as key-values for targeting.Important Notes:

Replace PERMUTIVE_API_KEY with your actual Permutive API key
The activations=true query parameter is required to receive activation data in the response

Data Types

With your Microsoft Monetize (Ad Server) integration setup, you’ll see the following additional event types collected in Permutive:

AppNexusAdImpression

Tracks ad impression events from the AppNexus Seller Tag on web. Based on Microsoft Monetize’s ad event callbacks.

string

Unique identifier for the ad auction.

number

The Advertiser ID for this impression.

number

The Line Item ID for this impression (only available with Log-Level Data integration).

number

The Campaign ID for this impression.

number

The Creative ID for this impression.

string

The ad tag/placement identifier.

AppNexusAdClick

Tracks ad click events from the AppNexus Seller Tag on web.

string

Unique identifier for the ad auction.

number

The Advertiser ID for this click.

number

The Campaign ID for this click.

number

The Creative ID for this click.

string

The ad tag/placement identifier.

Show Advanced: Log-Level Data Events

Log-Level Data Event Types

XandrLogAdImpression

Tracks comprehensive ad impression data from Microsoft Monetize Log-Level Data Feeds. Includes line item IDs and supports mobile platforms.

string

Unique identifier for the ad auction, linking to edge SDK events.

number

The Advertiser ID for this impression.

number

The Line Item ID for this impression, enabling detailed campaign reporting.

number

The Campaign ID for this impression.

number

The Creative ID for this impression.

number

Your Microsoft Monetize Member ID.

XandrLogAdClick

Tracks comprehensive ad click data from Microsoft Monetize Log-Level Data Feeds, including clicks from mobile apps.

string

Unique identifier for the ad auction, linking to edge SDK events.

number

The Advertiser ID for this click.

number

The Line Item ID for this click.

number

The Campaign ID for this click.

number

The Creative ID for this click.

number

Your Microsoft Monetize Member ID.

Log-Level Data events are linked to edge SDK events via the auction_id field, allowing Permutive to enrich log data with user IDs and session context.

Troubleshooting

Unable to enable Microsoft Monetize (Ad Server) integration in Permutive Dashboard

If you see an error when enabling the Microsoft Monetize (Ad Server) integration, check that you have provided valid Microsoft Monetize credentials with the correct permissions. The user account must have permissions to view and edit key-values and access inventory settings. Verify your Member ID is correct.

The `permutive` targeting key was not created

Double check that the Microsoft Monetize user credentials provided to Permutive have the correct permissions to create and manage targeting keys. The user must have access to the inventory section and permissions to edit key-values. If you have reached Microsoft Monetize’s limit of targeting keys, you may need to remove an old/inactive key first.

Cohorts not appearing as targeting values in Microsoft Monetize

First, verify the cohort is toggled On for Microsoft Monetize (Ad Server) activation in the Permutive Dashboard. Then check in your Microsoft Monetize dashboard under Inventory => Key-Values that the cohort ID appears as a value under the permutive targeting key. If the value is missing, try toggling the cohort activation off and on again, and contact Permutive Support if the issue persists.

Log-Level Data events not appearing

Verify that you have enabled both the standard Microsoft Monetize (Ad Server) integration (for event collection) and the Log-Level Data integration. Check that your Microsoft Monetize Log-Level Data Feeds are correctly configured to export to the Permutive-provided GCS bucket. Allow 24 hours for initial data to appear. If events still don’t appear, verify your Member ID matches in both the dashboard configuration and the service account writing to the GCS bucket.

Missing line item IDs in events

Line item IDs are only available when using the Log-Level Data integration. Standard edge SDK events (AppNexusAdImpression and AppNexusAdClick) do not include line item IDs due to limitations of the AppNexus Seller Tag API. To get line item IDs, you must enable the Log-Level Data Feeds integration.

Changelog

June 2025

Enhanced support for activating cohorts via Microsoft Monetize (Ad Server) with improved targeting key management

November 2019

Initial release of Microsoft Monetize (Ad Server) (formerly Xandr AdServer, AppNexus) integration with cohort activation and event collection

For detailed changelog information, visit our Changelog.

Integrations

Identity

Contextual

Advertising

Marketing

Data Collaboration

Video

Social Media

Survey

Microsoft Monetize