Parse the SegmentRequest

  • In Real-time Curation, Google sends a JSON SegmentRequest to your curation endpoint with impression signals.

  • Your endpoint must use gzip encoding for sending and receiving SegmentRequests.

  • You can configure your endpoint to receive either contextual signals or secure signals, which impacts the SegmentRequest content and eligible inventory.

  • Contextual signals provide information about the publisher, device, and user to help determine data segments.

  • Secure signals are publisher data that is obfuscated before being sent in the SegmentRequest.

In Real-time Curation, Google sends a JSON SegmentRequest to your curation endpoint to provide signals describing one or more impressions, letting you determine applicable data segments for each of them. This guide covers developing curation logic that handles the SegmentRequest.

Use gzip encoding

Google uses gzip encoding when sending a SegmentRequest to your endpoint. Your endpoint must be capable of receiving and responding with gzip encoding.

Curation with contextual signal or audience signal endpoints

When you create a Real-time Curation endpoint, you must select whether to receive contextual signals or audience signals. The signals you select impact how segment requests sent to your endpoint are populated, how much inventory produces segment requests sent to your endpoint, and the curation logic used in your integration.

Use contextual signals

Contextual signals include information about the publisher, device, and user that describe the origin of the impression. The following list describes the available signals:

  • SegmentRequest.site: Describes the website rendering the impression, such as the site's URL. Only one of SegmentRequest.site and SegmentRequest.app can be populated in a SegmentRequest.
  • SegmentRequest.app: Describes the app rendering the impression, such as the app's platform-specific application identifier. Only one of SegmentRequest.site and SegmentRequest.app can be populated in a SegmentRequest.
  • SegmentRequest.pub: Describes the publisher of the media rendering the impression; for example, the publisher's ID.
  • SegmentRequest.user: Describes user choices about how their personal data can be processed; for example, with the TCF consent string.
  • SegmentRequest.device: Describes information about the device, such as the device's geographical location at metro-level precision.

You can use contextual signals to implement curation logic that can determine applicable data segments to return in the SegmentResponse.

Use audience signals

Audience signals include user or device identifiers, as well as secure signals. Secure signals are data created by the publisher that they have chosen to share with one or more partners. They are obfuscated before being shared with Google in the ad request, and in Real-time Curation appear in their obfuscated form in SegmentRequest.user.eids.uids.id.

If your endpoint is configured to use audience signals, your endpoint only receives segment requests for the inventory of publishers that have chosen to share secure signals with your curation account. Consequently, there are fewer total impressions eligible to be sent to audience signal endpoints in comparison to contextual signal endpoints.

Your endpoint's curation logic must interpret the audience signals and determine applicable data segments to return in the SegmentResponse.

SegmentRequest examples

Contextual signal Real-time Curation endpoint

{
  "site":{
    "page":"https://dfpgpt.appspot.com/smd/"
  },
  "pub":{
    "id":"pub-1234567890987654"
  },
  "device":{
    "geo":{
      "country":"US",
        "metro":"501"
      }
  }
}

Audience signal Real-time Curation endpoint

{
  "device":{
    "ifa":"OMITTED_IFA"
  },
  "user": {
    "eids" : [ {
      "source": "pubcid.org",
      "uids":[
        { "id" :"OMITTED_SECURE_SIGNAL" }
      ]
    }],
    "buyeruid": "OMITTED_BUYERUID",
    "id": "OMITTED_ID"
  }
}

Next steps