Beacon Targeting¶

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

Overview¶

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

The pixel 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 Verizon Media. This information can then be used by Verizon Media to track conversions, retarget users in real time or collect user data for custom audience creation. As a convenience, the 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 Yahoo 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`

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 Yahoo 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 Yahoo 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. `true` - remove all targeted beacons. `false` - (Default Value) do not remove targeted beacons.	`boolean`

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 Yahoo 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¶

Field	Description	Data Type
`id`	Specifies the segment ID.	`integer`
`name`	Specifies the beacon name.	`string`
`recency`	Specifies the lookback window (in days) that Yahoo 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:

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.

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

Parameter

Source

Description

Data Type

Required

id

path

Specifies the line ID.

integer

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

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

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.

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.	`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

Parameter

Source

Description

Data Type

Required

id

path

Specifies the line ID.

integer

beacons

body

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

object

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

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.

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

Parameter

Source

Description

Data Type

Required

id

path

Specifies the ID of line targeting the beacons.

integer

beacons

body

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

object

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

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.

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

Parameter

Source

Description

Data Type

Required

id

path

Specifies the ID of line targeting the beacons.

``integer`

beacons

body

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

object

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