Receive impression notifications

You can receive impression notifications whenever Google detects that your data segments were used in a winning bid in the Real-time Bidding auction, and resulted in an impression. Google recommends that you integrate with impression notifications to learn more about how your data segments are being used. Contact your account manager to enable impression notifications.

Configure your impression notification endpoint

You must create an HTTP endpoint and share its URL with Google to receive impression notifications. You can set the URL that impression notifications are sent to with one of the following options:

  1. Set the impression notification endpoint URL for each Real-time Curation callout.
    • You can dynamically set the URL used for impression notifications for each Real-time Curation callout you receive by populating the SegmentResponse.burl field.
    • For a given Real-time Curation callout, you must set the SegmentResponse.burl field to receive an impression notification for that callout. If the SegmentResponse.burl field isn't populated, no notification will be sent for that callout even if the SegmentResponse.burl field was set in earlier callouts.
  2. Set an account-level impression notification endpoint URL.
    • You can set an account-level impression notification endpoint URL for your account by contacting your account manager. This is ideal if your endpoint URL changes infrequently.
    • All Real-time Curation callouts will use the account-level impression notification URL you configure for your account, unless you override the account-level URL by setting the SegmentResponse.burl field for an individual Real-time Curation callout.

Parse an impression notification

The information sent in an impression notification depends on the configuration of your impression notification endpoint URL. Your endpoint URL can include query parameters and use macros to include additional context about how your data segments were used by the winning bid that resulted in an impression.

Understand how macros are expanded

If you configure your endpoint URL to contain one or more query parameters that are set to a macro, impression notifications sent to your endpoint will expand those macros, replacing the macros with their corresponding values.

For example, you could configure an impression notification endpoint URL to look like the following:

https://testendpoint.com/impressions?segmentReqId=${SR_ID}&segmentIds=${SEGMENT_IDS}

When receiving an impression notification, the macros would be replaced, causing the URL to look like the following:

https://testendpoint.com/impressions?segmentReqId=8Mbl39sMOX5yg1NZgS35ET&segmentIds=test-ds-1|test-ds-2

Learn about supported macros

The following are macros you can include in query parameters of the impression notification endpoint URL. These macros are replaced with values related to the winning bid that one or more of your data segments contributed towards.

Macro Description
${SR_ID} A unique string ID equivalent to the SegmentRequest.segment_request_id field for the corresponding Real-time Curation callout. This refers to the segment request that you responded to with one or more data segment IDs that contributed to the winning bid.
${SEGMENT_IDS} A list of string data segment IDs that contributed to the winning bid. Each item in the list is separated by the "|" character. For example, this could be expanded to a list of values such as: "segmentId1|segmentId2|segmentId3" Each data segment ID that populates the list refers to the resource ID of the corresponding curators.dataSegments resource in Marketplace API.
${AUCTION_PRICE} A string representing the winning price of the auction. The price is the cost of a single impression (CPI) expressed in micro-USD. For example, a Real-time Bidding bid of $5 USD CPM would result in the ${AUCTION_PRICE} macro expanding to 5000 micro-USD CPI in the Real-time Curation impression notification.
${DEAL_ID} ID of the deal or package that won the auction. This is a deal or package that targets one or more of your data segment IDs, which can be identified with the ${SEGMENT_IDS} macro.
${BUYER_SEAT_ID} The ID of the buyer seat that won the impression, as specified by the bidder in the winning bid. For example, buyer seats can be agencies or advertisers.

Next steps