InsurAds Rtd Provider: initial release

integrationExamples/gpt/insurads.html

@@ -5,7 +5,7 @@
     <script async src="https://securepubads.g.doubleclick.net/tag/js/gpt.js"></script>
     <script>
         var FAILSAFE_TIMEOUT = 5300;
-        var PREBID_TIMEOUT = 2000;
+        var PREBID_TIMEOUT = 5000;
 
         var adUnits = [{
             code: 'div-gpt-ad-1460505748561-0',
@@ -41,6 +41,17 @@
             pbjs.setConfig({
                 enableTIDs: true,
                 debug: true, // use only for testing, remove in production
+                // Uncomment the following to test InsurAds real-time data integration with your adapter
+                // realTimeData: {
+                //     auctionDelay: 1000,
+                //     dataProviders: [{
+                //         name: 'insuradsRtd',
+                //         waitForIt: true,
+                //         params: {
+                //             publicId: 'ALIYJZJD'
+                //         }
+                //     }]
+                // }
             });
 
             // You can set up gzip compression like so, and the adapter will use this setting when sending bid requests
@@ -51,10 +62,10 @@
             //     }
             // });
 
-            
+
             pbjs.bidderSettings = {
                 insurads: {
-                    storageAllowed : true
+                    storageAllowed: true
                 }
             }
 

modules/.submodules.json

@@ -98,6 +98,7 @@
       "hadronRtdProvider",
       "humansecurityRtdProvider",
       "iasRtdProvider",
+      "insuradsRtdProvider",
       "imRtdProvider",
       "intersectionRtdProvider",
       "jwplayerRtdProvider",

modules/insuradsBidAdapter.ts

@@ -4,7 +4,7 @@ import { AdapterRequest, BidderSpec, registerBidder } from '../src/adapters/bidd
 import { BANNER, NATIVE, VIDEO } from '../src/mediaTypes.js';
 import { ortbConverter } from '../libraries/ortbConverter/converter.js'
 
-import { interpretResponse, enrichImp, enrichRequest, getAmxId, getLocalStorageFunctionGenerator, getUserSyncs } from '../libraries/nexx360Utils/index.js';
+import { interpretResponse as nexxInterpretResponse, enrichImp, enrichRequest, getAmxId, getLocalStorageFunctionGenerator, getUserSyncs } from '../libraries/nexx360Utils/index.js';
 import { getBoundingClientRect } from '../libraries/boundingClientRect/boundingClientRect.js';
 import { BidRequest, ClientBidderRequest } from '../src/adapterManager.js';
 import { ORTBImp, ORTBRequest } from '../src/prebid.public.js';
@@ -36,11 +36,12 @@ type InsurAdsBidParams = RequireAtLeastOne<{
   allBids?: boolean;
   customId?: string;
   bidders?: Record<string, unknown>;
+  rtdData?: Record<string, unknown>;
 }, "tagId" | "placement">;
 
 declare module '../src/adUnits' {
   interface BidderParams {
-    ['nexx360']: InsurAdsBidParams;
+    ['insurads']: InsurAdsBidParams;
   }
 }
 
@@ -82,6 +83,11 @@ const converter = ortbConverter({
       deepSetValue(imp, 'ext.dimensions.cssMaxW', slotEl.style?.maxWidth);
       deepSetValue(imp, 'ext.dimensions.cssMaxH', slotEl.style?.maxHeight);
     }
+    if (bidRequest.params.rtdData) {
+      deepSetValue(imp, 'ext.rtdData', bidRequest.params.rtdData);
+      delete bidRequest.params.rtdData;
+    }
+
     deepSetValue(imp, 'ext.nexx360', bidRequest.params);
     deepSetValue(imp, 'ext.nexx360.divId', divId);
     if (bidRequest.params.adUnitPath) deepSetValue(imp, 'ext.adUnitPath', bidRequest.params.adUnitPath);
@@ -96,6 +102,24 @@ const converter = ortbConverter({
   },
 });
 
+function getRtdTargetingFromRequest(request: AdapterRequest): Record<string, string> {
+  const targeting: Record<string, string> = {};
+  const imps = request?.data?.imp;
+  if (!Array.isArray(imps)) return targeting;
+
+  for (const imp of imps) {
+    const rtdData = imp?.ext?.rtdData;
+    if (!rtdData || typeof rtdData !== 'object') continue;
+
+    for (const [key, value] of Object.entries(rtdData)) {
+      if (value === null || value === undefined) continue;
+      targeting[key] = String(value);
+    }
+  }
+
+  return targeting;
+}
+
 const isBidRequestValid = (bid: BidRequest<typeof BIDDER_CODE>): boolean => {
   if (bid.params.adUnitName && (typeof bid.params.adUnitName !== 'string' || bid.params.adUnitName === '')) {
     logError('bid.params.adUnitName needs to be a string');
@@ -136,14 +160,33 @@ const buildRequests = (
   return adapterRequest;
 }
 
+const interpretResponse = (serverResponse, request) => {
+  const responses: any[] = nexxInterpretResponse(serverResponse) as any;
+  const rtdTargeting = getRtdTargetingFromRequest(request);
+
+  if (!rtdTargeting || Object.keys(rtdTargeting).length === 0) {
+    return responses;
+  }
+
+  return responses.map((bidResponse) => {
+    return {
+      ...bidResponse,
+      adserverTargeting: {
+        ...(bidResponse?.adserverTargeting || {}),
+        ...rtdTargeting,
+      }
+    };
+  });
+};
+
 export const spec: BidderSpec<typeof BIDDER_CODE> = {
   code: BIDDER_CODE,
   gvlid: GVLID,
   supportedMediaTypes: [BANNER, VIDEO, NATIVE],
   isBidRequestValid,
   buildRequests,
   interpretResponse,
-  getUserSyncs,
+  getUserSyncs
 };
 
 registerBidder(spec);

modules/insuradsRtdProvider.md

@@ -0,0 +1,61 @@
+## InsurAds Real-time Data Submodule
+
+The [InsurAds](https://insurads.com) real-time data module in Prebid enables publishers to leverage
+contextual targeting and audience segmentation capabilities. This module provides real-time
+key-value targeting data that seamlessly integrates into your existing Prebid deployment,
+helping you maximize your advertising strategies.
+
+## Building Prebid with InsurAds Support
+
+Compile the InsurAds RTD module into your Prebid build:
+
+`gulp serve --modules=rtdModule,insuradsBidAdapter,insuradsRtdProvider`
+
+Please visit https://insurads.com/ for more information.
+
+```javascript
+pbjs.setConfig({
+    ...
+    realTimeData: {
+        auctionDelay: 1000,
+        dataProviders: [{
+            name: 'insuradsRtd',
+            waitForIt: true,
+            params: {
+                publicId: 'YOUR_PUBLIC_ID',
+                timeout: 1000
+            }
+        }]
+    }
+    ...
+});
+```
+
+### Parameter Descriptions for the InsurAds Configuration Section
+
+| Name              | Type    | Description                                                               | Notes                    |
+|:------------------|:--------|:--------------------------------------------------------------------------|:-------------------------|
+| name              | String  | Real time data module name                                                | Always 'insuradsRtd'     |
+| waitForIt         | Boolean | When true, delays the auction until this provider calls back (bounded by `auctionDelay` / `params.timeout`) | Optional. Defaults to false |
+| params            | Object  |                                                                           |                          |
+| params.publicId   | String  | This is the Public ID value obtained from InsurAds                        | Required                 |
+| params.timeout    | Number  | Max time (ms) to wait for the InsurAds API response before continuing the auction without enrichment | Optional. Defaults to 1000 |
+
+## Testing
+
+To view an example of InsurAds RTD provider:
+
+`gulp serve --modules=rtdModule,insuradsBidAdapter,insuradsRtdProvider`
+
+and then point your browser at:
+
+`http://localhost:9999/integrationExamples/gpt/insurads.html`
+
+## How It Works
+
+The InsurAds RTD provider:
+
+1. Fetches contextual targeting data from the InsurAds API using your `publicId`
+2. Stores the returned key-values internally
+3. Enriches bid requests for the `insurads` bidder by attaching the key-values onto `bid.params.rtdData`
+4. Leaves other bidders unchanged

modules/insuradsRtdProvider.ts

@@ -0,0 +1,126 @@
+import { submodule } from '../src/hook.js';
+import { logInfo } from '../src/utils.js'
+import { fetch } from '../src/ajax.js';
+import type { RtdProviderSpec } from './rtdModule/spec.ts';
+
+/**
+ * @typedef {import('../modules/rtdModule/index.js').RtdSubmodule} RtdSubmodule
+ */
+
+const SERVER_IP = 'https://services.insurads.com';
+const MODULE_NAME = 'insuradsRtd';
+const ENDPOINT = `${SERVER_IP}/core/init/prebid`;
+const LOG_PREFIX = 'insurads Rtd: ';
+const GVLID = 596;
+
+// Internal state to store keyValues
+let keyValues = {};
+let apiCallPromise = Promise.resolve();
+
+declare module './rtdModule/spec.ts' {
+  interface ProviderConfig {
+    insuradsRtd: {
+      params: {
+        publicId: string;
+        timeout?: number;
+      };
+    };
+  }
+}
+
+export const insuradsRtdProvider: RtdProviderSpec<'insuradsRtd'> = {
+  name: MODULE_NAME,
+  gvlid: GVLID,
+  init: (config, userConsent) => {
+    const publicId = config?.params?.publicId;
+
+    if (typeof publicId !== 'string' || publicId.trim().length === 0) {
+      logInfo(LOG_PREFIX + 'publicId is required and must be a non-empty string');
+      return false;
+    }
+
+    // Reset keyValues to avoid stale values after failed/empty response
+    keyValues = {};
+
+    // Start fetch immediately without blocking init
+    apiCallPromise = makeApiCall(publicId);
+
+    logInfo(LOG_PREFIX + 'submodule init', config, userConsent);
+    return true;
+  },
+  getBidRequestData: (reqBidsConfigObj, callback, config, userConsent) => {
+    logInfo(LOG_PREFIX + 'submodule getBidRequestData', reqBidsConfigObj, config, userConsent);
+
+    // Wait for API call to complete before enriching bid requests
+    const timeout = config?.params?.timeout || 1000; // Default 1 second timeout
+    const timeoutPromise = new Promise((resolve) => setTimeout(resolve, timeout));
+
+    Promise.race([apiCallPromise, timeoutPromise])
+      .then(() => {
+        // Enrich bid requests with RTD data for insurads bidder
+        if (keyValues && Object.keys(keyValues).length > 0) {
+          reqBidsConfigObj.adUnits.forEach(adUnit => {
+            adUnit.bids.forEach(bid => {
+              if (bid.bidder === 'insurads') {
+                // Add RTD data to bid params so it can be accessed by the adapter
+                bid.params = bid.params || {};
+
+                (bid.params as any).rtdData = keyValues;
+                logInfo(LOG_PREFIX + 'Enriched bid request for insurads', (bid.params as any).rtdData);
+              }
+            });
+          });
+        } else {
+          logInfo(LOG_PREFIX + 'No keyValues available for bid enrichment');
+        }
+
+        callback();
+      })
+      .catch((_e) => {
+        logInfo(LOG_PREFIX + 'Error waiting for API call');
+        callback();
+      });
+  },
+};
+
+async function makeApiCall(publicId: string) {
+  const currentUrl = encodeURIComponent(location.href);
+
+  try {
+    const response = await fetch(`${ENDPOINT}/${publicId}?url=${currentUrl}`, {
+      method: 'GET',
+      headers: {
+        'Content-Type': 'application/json'
+      }
+    });
+    if (!response.ok) {
+      keyValues = {};
+      logInfo(LOG_PREFIX + `Network error: ${response.status} ${response.statusText}, cleared cached values`);
+      return;
+    }
+    if (response.status === 204) {
+      keyValues = {};
+      logInfo(LOG_PREFIX + '204 No Content received, cleared cached values');
+      return;
+    }
+
+    const data = await response.json();
+    if (data && data.keyValues) {
+      keyValues = data.keyValues;
+      logInfo(LOG_PREFIX + 'Received keyValues from endpoint', data.keyValues);
+    } else {
+      keyValues = {};
+      logInfo(LOG_PREFIX + 'No keyValues in response, cleared cached values');
+    }
+  } catch (_e) {
+    keyValues = {};
+    logInfo(LOG_PREFIX + 'API call failed, cleared cached keyValues');
+  }
+}
+
+function beforeInit() {
+  // take actions to get data as soon as possible
+  submodule('realTimeData', insuradsRtdProvider);
+}
+
+beforeInit();