Beacon Targeting

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

Overview

Verizon Media 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 Verizon Media 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 Verizon Media 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 Verizon Media 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 Verizon Media 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 Verizon Media 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

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

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

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