Beacon Targeting

This article describes resources that enable you to read and define beacon targeting.

Overview

Oath Ad Platforms DSP supports Yahoo’s Dot tag pixels, which offer a universal, cross-platform tracking tag. Use a single pixel to record many different types of events for conversion tracking.

The Dot tag is a standard code snippet that when placed on an advertiser’s web page can be used to send site interaction information about the advertiser’s users to Yahoo. This information can then be used by Yahoo to track conversions, retarget users in real time or collect user data for custom audience creation. As a convenience, the Yahoo tag can also support inclusion of third-party pixels.

To learn more, see Beacon Targeting.

Endpoint

/traffic/lines/{id}/targeting
  • A GET request enables you to view beacons targeted by the specified line.
  • A POST request enables you to target beacons with the specified line.

Resources

Targeting Object

The targeting resource is the standard Oath Ad Platforms DSP resource for targeting consumers based on their profiles, behaviors, and ad content.

This resource comprises multiple fields that enable you to specify line targeting across many types of targets including the SEGMENT, EXCHANGES, and BEACONS target types.

To target beacons, you need only be concerned with the following BEACONS targeting type-specific fields:

Field Definition Data Type
beacons

Specifies the beacons added, edited, and removed from line targeting.

To learn more, see Beacons Object.

array

Note

For a complete list of targeting resource fields, see Targeting Object.

Beacons Object

The beacons payload object enables you to Add/Update Beacon Targets, Update Beacon Targets, Remove Beacon Targets, or Clear All Beacon Targets targeted by a line.

Field Definition Data Type
added

Specifies an array of Beacon objects to add to line targeting. Each beacon object contains the following required fields:

  • entityId - Specifies the ID of the beacon to be targeted.
  • excluded - Indicates if the added beacons are to be excluded from line targeting.
    • If true, exclude from targeting.
    • If false, include in targeting.
  • recency - The lookback window (in days) that Oath Ad Platforms DSP should use to determine if a pixel fire occurred.
  • frequency - The number of times a beacon must fire for a particular user, for that user to be included in or excluded from the audience.
array
edited

Specifies an array of Beacon objects to edit. Each Beacon object the following required fields:

  • entityId - Specifies the ID of the beacon to update.
  • excluded - Indicates if the updated ID is to be excluded from targeting.
    • If true, do not target the specified beacon.
    • If false, target the specified beacon.
  • recency - Defines the lookback window (in days) that Oath Ad Platforms DSP should use to determine if a pixel fire occurred.
  • frequency - Specifies the number of times beacon must fire for a consumer for that consumer to be targeted or excluded from targeting.
array
removed Specifies an array of Beacon IDs to be removed from line targeting. array
clearAll

Indicates if all existing beacons should be removed.

  • If true, remove all targeted beacons.
  • If false, do not remove targeted beacons. (Default Value)
boolean

Beacons Included Object

Table 131 Beacons Included Object
Field Description Data Type
id Specifies the segment ID. integer
name Specifies the beacon name. string
recency Specifies the lookback window (in days) that Oath Ad Platforms DSP uses to determine if a pixel fire occurred. integer
frequency Specifies the number of times a pixel must fire for a particular consumer before that consumer is included in the audience. integer

Beacons Excluded Object

Table 132 Beacons Included Object
Field Description Data Type
id Specifies the segment ID. integer
name Specifies the beacon name. string
recency Specifies the lookback window (in days) that Oath Ad Platforms DSP uses to determine if a pixel fire occurred. integer
frequency Specifies the number of times a pixel must fire for a particular consumer before that consumer is excluded from the audience. integer

Read Beacons

Returns a list of beacons that can be targeted by the specified line. Beacons may be filtered based on a specified query.

GET /traffic/targeting/pixels?lineId={lineId}&query={query}

The resource accepts two parameters:

Table 133 GET targeting pixels
Parameter Source Description Data Type Required?
lineId query Specifies the line ID. integer Y
query query Specifies the search term. string N

Example Request

GET /traffic/targeting/pixels?lineId=365277&query=test

Use URL encoding conventions (i.e. a space should be replaced with a + or %20). Provide a partial search string or leave it empty to get all results.

Example Response

The response contains the following fields of interest:

Name Description
id Unique ID of the pixel. This value can be used to target the beacon.
name Pixel name.
createdAt (Read-Only) Creation timestamp.
type

Type of pixel.

  • CONVERSION
  • RETARGETING

Add/Update Beacon Targets

Adds or updates the beacons targeted for a line.

POST /traffic/lines/{id}/targeting

Parameters

The line ID is specified in the path of the endpoint. All other parameters are specified in the body of the application/json payload.

Table 134 Add Beacon Targets Parameters
Parameter Source Description Data Type Required?
id path Specifies the line ID. integer Y
beacons body

Specifies the beacons to add, update, or remove from line targeting. To learn more, see Beacons Object.

To include new beacons for inclusion in or exclusion from line targeting, specify an added array of Beacon objects.

array Y
types body

Specifies an array of targeting types.

To target beacons, the BEACONS targeting type must be enabled.

To learn more, see Targeting Types.

object Y

Example Request

The line ID is specified in the path of the resource endpoint:

POST traffic/lines/365277/targeting/

All other parameters are specified in the body of the application/json payload.

{
  "beacons": {
    "added": [
      {
        "excluded": false,
        "entityId": 6436593,
        "recency": 30,
        "frequency": 7
      },
      {
        "excluded": true,
        "entityId": 6434432,
        "recency": 50,
        "frequency": 1
      }
    ]
  },
  "types": [
    {
      "name": "BEACONS",
      "isTargeted": true
    }
  ]
}

Example Response

{
  "response": [
    {
      "id": "6508331",
      "name": "test dot broker conversion rule",
      "createdAt": "2016-07-19T21:44:35Z",
      "type": "CONVERSION"
    },
    {
      "id": "6508393",
      "name": "test dot broker retargeting",
      "createdAt": "2016-07-28T06:13:38Z",
      "type": "RETARGETING"
    }
  ],
  "errors": null,
  "timeStamp": "2018-01-05T02:23:02Z"
}

Update Beacon Targets

Updates the beacons targeted by a line.

POST /traffic/lines/{id}/targeting

Parameters

All parameters are specified in the body of the application/json payload.

Table 135 Update Target Beacons
Parameter Source Description Data Type Required?
id query Specifies the line ID. integer Y
beacons body Specifies the beacons to add, update, or remove from line targeting. To learn more, see Beacons Object. object Y
types body

Specifies the targeting types to enable or modify.

To target beacons, the BEACONS targeting type must be enabled. To learn more, see Targeting Types.

object Y

Example Request

{
  "id": 365277,
  "beacons": {
    "edited": [
      {
        "excluded": false,
        "entityId": 6436593,
        "recency": 55,
        "frequency": 2
      }
    ]
  },
  "types": [
    {
      "name": "BEACONS",
      "isTargeted": true
    }
  ]
}

Remove Beacon Targets

Removes the specified beacons from targeting.

POST /traffic/lines/{id}/targeting

The line ID is specified in the path of the URL. The beacon IDs are specified in the body of the application/json.

Parameters

All parameters are specified in the body of the application/json payload.

Table 136 Remove Target Beacons Parameters
Parameter Source Description Data Type Required?
id path Specifies the ID of line targeting the beacons. integer Y
beacons body Specifies the beacons to add, update, or remove from line targeting. To learn more, see Beacons Object. object Y
types body

Specifies the targeting types to enable or modify.

To target beacons, the BEACONS targeting type must be enabled. To learn more, see Targeting Types.

object Y

Example Request

{
  "id": 365277,
  "beacons": {
    "removed": [
      6436593
    ]
  },
  "types": [
    {
      "name": "BEACONS",
      "isTargeted": true
    }
  ]
}

Example Response

{
  "response": [
    {
      "id": "6508331",
      "name": "test dot broker conversion rule",
      "createdAt": "2016-07-19T21:44:35Z",
      "type": "CONVERSION"
    },
    {
      "id": "6508393",
      "name": "test dot broker retargeting",
      "createdAt": "2016-07-28T06:13:38Z",
      "type": "RETARGETING"
    }
  ],
  "errors": null,
  "timeStamp": "2018-01-05T02:23:02Z"
}

Clear All Beacon Targets

Clears all beacons currently targeted by the specified line.

POST /traffic/lines/{id}/targeting

The line ID is specified in the path of the URL.

Parameters

All parameters are specified in the body of the application/json payload.

Table 137 Clear All Target Beacon Parameters
Parameter Source Description Data Type Required?
id path Specifies the ID of line targeting the beacons. ``integer` Y
beacons body Specifies the beacons to add, update, or remove from line targeting. To learn more, see Beacons Object. object Y
types body

Specifies the targeting types to enable or modify.

To target beacons, the BEACONS targeting type must be enabled. To learn more, see Targeting Types.

object Y