Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

IntentIq ID & Analytics Modules: update documentation #5669

Merged
merged 7 commits into from
Nov 12, 2024
Merged

IntentIq ID & Analytics Modules: update documentation #5669

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
7 commits
Select commit Hold shift + click to select a range
88358f3
update documentation
DimaIntentIQ Oct 23, 2024
6d2c1f8
White space fixes
DimaIntentIQ Oct 24, 2024
9039a52
Merge branch 'master' into master
DimaIntentIQ Oct 31, 2024
f8034a9
Merge branch 'master' into master
DimaIntentIQ Nov 5, 2024
6a024f2
Apply suggestions from code review
DimaIntentIQ Nov 8, 2024
4e18140
Merge branch 'prebid:master' into master
DimaIntentIQ Nov 8, 2024
1bbd163
Add example and link to Universal ID configuration
DimaIntentIQ Nov 8, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
75 changes: 75 additions & 0 deletions dev-docs/analytics/intentiq.md
View file
Open in desktop
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.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Where is this manual thing set? Looks like it may be in the usersync config? It would clearer with an example here.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Hi @bretg, the document has been updated to include a code example.


```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
Open in desktop
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