Nexx360 Analytics Adapter: add analytics adapter

libraries/nexx360Utils/index.ts

@@ -8,6 +8,7 @@
 import { StorageManager } from '../../src/storageManager.js';
 import { BidRequest, ORTBImp, ORTBRequest, ORTBResponse } from '../../src/prebid.public.js';
 import { AdapterResponse, ServerResponse } from '../../src/adapters/bidderFactory.js';
+import { Nexx360ServerAuction } from './types.js';
 
 const OUTSTREAM_RENDERER_URL = 'https://acdn.adnxs.com/video/outstream/ANOutstreamVideo.js';
 
@@ -79,8 +80,8 @@
   width: number,
   height: number
 ) => (bidResponse: VideoBidResponse) => {
   bidResponse.renderer.push(() => {
     (window as any).ANOutstreamVideo.renderAd({
       sizes: [width, height],
       targetId: divId,
       adResponse: bidResponse.vastXml,
@@ -108,8 +109,8 @@
   { requestId, vastXml, divId, width, height }: CreateRenderPayload
 ): Renderer | undefined => {
   if (!vastXml) {
     logInfo('No VAST in bidResponse');
     return;
   }
   const installPayload = {
     id: requestId,
@@ -201,7 +202,7 @@
       response.renderer = renderer;
       response.divId = bid.ext.divId;
     } else {
       logInfo('Could not create renderer for outstream bid');
     }
   };
 
@@ -213,10 +214,38 @@
   return response as BidResponse;
 }
 
+// --- Server auction data extraction ---
+
+let lastServerAuctionData: Nexx360ServerAuction | null = null;
+
+function extractServerAuction(responseBody: any): void {
+  const serverAuction = deepAccess(responseBody, 'ext.serverAuction');
+  if (serverAuction && typeof serverAuction === 'object' && serverAuction.auctionId) {
+    lastServerAuctionData = serverAuction as Nexx360ServerAuction;
+  }
+}
+
+export function getLastServerAuctionData(): Nexx360ServerAuction | null {
+  return lastServerAuctionData;
+}
+
+export function clearLastServerAuctionData(): void {
+  lastServerAuctionData = null;
+}
+
 export const interpretResponse = (serverResponse: ServerResponse): AdapterResponse => {
   if (!serverResponse.body) return [];
   const respBody = serverResponse.body as ORTBResponse;
-  if (!respBody.seatbid || respBody.seatbid.length === 0) return [];
+
+  if (!respBody.seatbid || respBody.seatbid.length === 0) {
+    // No bid responses will be produced, so no analytics `bidResponse` will
+    // consume server-auction data. Clear it rather than let a stale value leak
+    // into a later, unrelated auction.
+    clearLastServerAuctionData();
+    return [];
+  }
+
+  extractServerAuction(respBody);
 
   const responses: BidResponse[] = [];
   for (let i = 0; i < respBody.seatbid.length; i++) {

libraries/nexx360Utils/types.ts

@@ -0,0 +1,48 @@
+/** Per-SSP bid attempt for a specific impression */
+export interface Nexx360SSPBid {
+  ssp: string;
+  status: 'bid' | 'noBid' | 'timeout' | 'error';
+  responseTimeMs?: number;
+  cpm?: number;
+  currency?: string;
+  size?: string;
+  dealId?: string;
+  bidId?: string;
+  error?: string;
+}
+
+/** Auction summary for a single impression */
+export interface Nexx360ImpressionAuction {
+  impId: string;
+  adUnitCode: string;
+  bids: Nexx360SSPBid[];
+  totalSsps: number;
+  bidsReceived: number;
+  timeouts: number;
+  errors: number;
+  auctionTimeMs: number;
+  winner?: {
+    ssp: string;
+    cpm: number;
+    currency: string;
+  };
+}
+
+/** Server-side auction data attached to Nexx360 OpenRTB response ext */
+export interface Nexx360ServerAuction {
+  auctionId: string;
+  timestamp: number;
+  impressions: Nexx360ImpressionAuction[];
+  totalImpressions: number;
+  totalSspsCalled: number;
+  totalBidsReceived: number;
+  totalTimeouts: number;
+  totalErrors: number;
+  auctionTimeMs: number;
+}
+
+/** Top-level Nexx360 response extension */
+export interface Nexx360ResponseExt {
+  cookies?: unknown[];
+  serverAuction?: Nexx360ServerAuction;
+}

metadata/modules.json

@@ -6532,6 +6532,11 @@
       "componentName": "mobkoi",
       "gvlid": null
     },
+    {
+      "componentType": "analytics",
+      "componentName": "nexx360",
+      "gvlid": null
+    },
     {
       "componentType": "analytics",
       "componentName": "nobid",

metadata/modules/nexx360AnalyticsAdapter.json

@@ -0,0 +1,12 @@
+{
+  "NOTICE": "do not edit - this file is autogenerated by `gulp update-metadata`",
+  "disclosures": {},
+  "purposes": {},
+  "components": [
+    {
+      "componentType": "analytics",
+      "componentName": "nexx360",
+      "gvlid": null
+    }
+  ]
+}

modules/nexx360AnalyticsAdapter.md

@@ -0,0 +1,80 @@
+# Overview
+
+Module Name: Nexx360 Analytics Adapter
+Module Type: Analytics Adapter
+Maintainer: tech@nexx360.io
+
+# Description
+
+The Nexx360 Analytics Adapter collects Prebid.js auction data and sends it to the Nexx360 analytics platform for monitoring and reporting. It tracks auction lifecycle events, bid requests, bid responses, wins, timeouts, and ad render events.
+
+# Registration
+
+The Nexx360 Analytics adapter requires a publisher ID from Nexx360. Please contact Nexx360 to obtain your publisher credentials.
+
+```javascript
+pbjs.enableAnalytics({
+  provider: 'nexx360',
+  options: {
+    publisherId: 'your-publisher-id',
+    endpoint: 'https://monitoring.nexx360.io'
+  }
+});
+```
+
+Sampling is applied server-side (by the Nexx360 collector), so the adapter sends
+all events and exposes no sampling option.
+
+# Analytics Options
+
+{: .table .table-bordered .table-striped }
+| Name | Scope | Description | Example | Type |
+|------|-------|-------------|---------|------|
+| publisherId | required | Your Nexx360 publisher identifier | `"pub-12345"` | string |
+| endpoint | optional | Analytics endpoint URL (defaults to `https://monitoring.nexx360.io`) | `"https://monitoring.nexx360.io"` | string |
+| abTestLabel | optional | A/B test variant label, attached to every event for slicing analytics by test arm | `"variantA"` | string |
+
+# Events Tracked
+
+The adapter tracks the following Prebid.js events:
+
+- **auctionInit** - When an auction starts
+- **bidRequested** - When bid requests are sent to bidders
+- **bidResponse** - When bid responses are received
+- **bidWon** - When a bid wins the auction
+- **bidTimeout** - When bidders timeout
+- **adRenderSucceeded** - When an ad renders successfully
+- **adRenderFailed** - When an ad fails to render
+
+# Example Configuration
+
+## Basic Setup
+
+```javascript
+pbjs.enableAnalytics({
+  provider: 'nexx360',
+  options: {
+    publisherId: 'your-publisher-id'
+  }
+});
+```
+
+## Production Setup
+
+```javascript
+pbjs.enableAnalytics({
+  provider: 'nexx360',
+  options: {
+    publisherId: 'your-publisher-id',
+    endpoint: 'https://monitoring.nexx360.io'
+  }
+});
+```
+
+# Build
+
+To include this analytics adapter in your Prebid.js build:
+
+```bash
+gulp build --modules=nexx360AnalyticsAdapter,...
+```