Skip to content

Commit

Permalink
IntentIq ID & Analytics Modules: update documentation (prebid#5669)
Browse files Browse the repository at this point in the history 
* update documentation

* White space fixes

* Apply suggestions from code review

Co-authored-by: bretg <bgorsline@gmail.com>

* Add example and link to Universal ID configuration

---------

Co-authored-by: bretg <bgorsline@gmail.com>
  • Loading branch information
@DimaIntentIQ @bretg
DimaIntentIQ and bretg authored Nov 12, 2024
1 parent e48deef commit 8e8bd7e
Show file tree
Hide file tree
Showing 2 changed files with 88 additions and 12 deletions.
75 changes: 75 additions & 0 deletions dev-docs/analytics/intentiq.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -26,3 +26,78 @@ pbjs.enableAnalytics({
provider: 'iiqAnalytics'
});
```

### Manual Report Trigger with reportExternalWin

The reportExternalWin function allows for manual reporting, meaning that reports will not be sent automatically but only when triggered manually.

To enable this manual reporting functionality, you must set the manualWinReportEnabled parameter in Intent IQ Unified ID module configuration is true. Once enabled, reports can be manually triggered using the reportExternalWin function.

```js
pbjs.setConfig({
userSync: {
userIds: [{
name: "intentIqId",
params: {
partner: 123456, // valid partner id
browserBlackList: "chrome",
manualWinReportEnabled: true
}
}]
}
});
```

You can find more information and configuration examples in the [Intent IQ Universal ID module](https://docs.prebid.org/dev-docs/modules/userid-submodules/intentiq.html#configuration)

### Calling the reportExternalWin Function

To call the reportExternalWin function, you need to pass the partner_id parameter as shown in the example below:

```js
window.intentIqAnalyticsAdapter_[partner_id].reportExternalWin(reportData)
```

Example use with Partner ID = 123455

```js
window.intentIqAnalyticsAdapter_123455.reportExternalWin(reportData)
```

### Function Parameters

The reportExternalWin function takes an object containing auction win data. Below is an example of the object:

```js
var reportData = {
biddingPlatformId: 1, // Platform ID. The value 1 corresponds to PreBid.
partnerAuctionId: '[YOUR_AUCTION_ID_IF_EXISTS]', // Auction ID, if available.
bidderCode: 'xxxxxxxx', // Bidder code.
prebidAuctionId: '3d4xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx8e', // PreBid auction ID.
cpm: 1.5, // Cost per thousand impressions (CPM).
currency: 'USD', // Currency for the CPM value.
originalCpm: 1.5, // Original CPM value.
originalCurrency: 'USD', // Original currency.
status: 'rendered', // Auction status, e.g., 'rendered'.
placementId: 'div-1' // ID of the ad placement.
}
```

| Field | Data Type | Description | Example | Mandatory |
|--------------------|-----------|--------------------------------------------------------------------------------------------------------------------------------------------------|-------------------------------|-----------|
| biddingPlatformId | Integer | Specify the platform in which this ad impression was rendered – 1 – Prebid, 2 – Amazon, 3 – Google, 4 – Open RTB (including your local Prebid server) | 1 | Yes |
| partnerAuctionId | String | Use this when you are running multiple auction solutions across your assets and have a unified identifier for auctions | 3d44542d-xx-4662-xxxx-4xxxx3d8e | No |
| bidderCode | String | Specifies the name of the bidder that won the auction as reported by Prebid and all other bidding platforms | newAppnexus | Yes |
| prebidAuctionId | String | Specifies the identifier of the Prebid auction. Leave empty or undefined if Prebid is not the bidding platform | | |
| cpm | Decimal | Cost per mille of the impression as received from the demand-side auction (without modifications or reductions) | 5.62 | Yes |
| currency | String | Currency of the auction | USD | Yes |
| originalCpm | Decimal | Leave empty or undefined if Prebid is not the bidding platform | 5.5 | No |
| originalCurrency | String | Currency of the original auction | USD | No |
| status | String | Status of the impression. Leave empty or undefined if Prebid is not the bidding platform | rendered | No |
| placementId | String | Unique identifier of the ad unit on the webpage that showed this ad | div-1 | No |

To report the auction win, call the function as follows:

```js
window.intentIqAnalyticsAdapter_[partner_id].reportExternalWin(reportData)
```
25 changes: 13 additions & 12 deletions dev-docs/modules/userid-submodules/intentiq.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -30,17 +30,17 @@ We recommend including the Intent IQ Analytics adapter module for improved visib
Please find below list of parameters that could be used in configuring Intent IQ Universal ID module

{: .table .table-bordered .table-striped }

| Param under userSync.userIds[] | Scope | Type | Description | Example |
| ------------------------------ | -------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------- |
| name | Required | String | The name of this module: "intentIqId" | `"intentIqId"` |
| params | Required | Object | Details for IntentIqId initialization. | |
| params.partner | Required | Number | This is the partner ID value obtained from registering with IntentIQ. | `1177538` |
| params.pcid | Optional | String | This is the partner cookie ID, it is a dynamic value attached to the request. | `"g3hC52b"` |
| params.pai | Optional | String | This is the partner customer ID / advertiser ID, it is a dynamic value attached to the request. | `"advertiser1"` |
| params.callback | Required | Function | This is a callback which is trigered with data and AB group | `(data, group) => console.log({ data, group })` |
| params.timeoutInMillis | Optional | Number | This is the timeout in milliseconds, which defines the maximum duration before the callback is triggered. The default value is 500. | `450` |
| params.browserBlackList | Optional |  String | This is the name of a browser that can be added to a blacklist. | `"chrome"` |
| Param under userSync.userIds[] | Scope | Type | Description | Example |
| ------------------------------ | -------- |----------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-----------------------------------------------|
| name | Required | String | The name of this module: "intentIqId" | `"intentIqId"` |
| params | Required | Object | Details for IntentIqId initialization. | |
| params.partner | Required | Number | This is the partner ID value obtained from registering with IntentIQ. | `1177538` |
| params.pcid | Optional | String | This is the partner cookie ID, it is a dynamic value attached to the request. | `"g3hC52b"` |
| params.pai | Optional | String | This is the partner customer ID / advertiser ID, it is a dynamic value attached to the request. | `"advertiser1"` |
| params.callback | Required | Function | This is a callback which is trigered with data and AB group | `(data, group) => console.log({ data, group })` |
| params.timeoutInMillis | Optional | Number | This is the timeout in milliseconds, which defines the maximum duration before the callback is triggered. The default value is 500. | `450` |
| params.browserBlackList | Optional |  String | This is the name of a browser that can be added to a blacklist. | `"chrome"` |
| params.manualWinReportEnabled | Optional | Boolean | This variable determines whether the bidWon event is triggered automatically. If set to false, the event will occur automatically, and manual reporting with reportExternalWin will be disabled. If set to true, the event will not occur automatically, allowing manual reporting through reportExternalWin. The default value is false. | `true`|

### Configuration example

Expand All @@ -53,7 +53,8 @@ pbjs.setConfig({
partner: 123456, // valid partner id
timeoutInMillis: 500,
browserBlackList: "chrome",
callback: (data, group) => window.pbjs.requestBids()
callback: (data, group) => window.pbjs.requestBids(),
manualWinReportEnabled: true
},
storage: {
type: "html5",
Expand Down

0 comments on commit 8e8bd7e

Please sign in to comment.