Beacons

Overview

Verizon Media DSP supports Verizon Media’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.

Endpoint

https://dspapi.admanagerplus.yahoo.com/traffic/beacons

Resources

Beacon

The Beacon object contains the following fields:

Field

Description

Data Type

Create

Update

id

Specifies the beacon ID.

integer

N/A

Required

name

Specifies the beacon name.

string

Required

Optional

accountId

Specifies the advertiser ID.

To learn more, see Advertisers.

integer

Required

Optional

pixelId

Specifies the parent Pixel ID.

To learn more, see Pixels.

integer

Required

Optional

ruleType

Specifies the rule type for this beacon. Valid choices include:

  • EVENTS: Track when a specific event or action is triggered on your site.

  • DESTINATION_URL: Track customer visits to specific pages. Specify values for destinationUrl and destinationUrlOperator fields.

string

Required

Optional

conversion_default_value

Estimated value of the conversion. See conversion_category.

integer

Optional

Optional

conversion_category

Optionally set up a conversion category to automatically categorize data about a particular conversion activity and track your profits for that activity. Later, you can use the data to estimate your return on ad spend (ROAS). Set conversion_default_value to 1 to count the number of events or set an estimated average dollar value that each event is worth to your organization for ROAS calculations. Valid choices include:

  • CONVERSION

  • SIGNUP - A user creates an account on your site, or signs up for a newsletter or royalty program.

  • LEAD - A potential customer engages with your site by browsing products, favoriting items, or adding items to a wish list.

  • ADD_TO_CART - A user adds one or more items to a shopping cart.

  • APP_INSTALLATIONS - A user installs an app on your site. The app installation may lead to further sales on tokens, or present other sales opportunities.

  • OTHERS - A user performs another activity that is not covered by any of the categories.

  • PURCHASE - A user presses the Buy button on your site.

  • IN_APP_EVENT - A user performs an action within an app (AchievedLevel, ActivatedApp, AddedPaymentInfo, AddedToCart, AddedToWishlist, CompletedRegistration, CompletedTutorial, InitiatedCheckout, Purchased, Rated, Searched, Lead, SignUp, SpentCredits, or UnlockedAchievement).

  • VIEW_CONTENT - A user views content on your site.

  • ADD_TO_WISHLIST - A user adds a product to their wishlist.

  • INITIATE_CHECKOUT - A user initiates the checkout process for a product purchase.

  • ADD_PAYMENT_INFO - A user adds a credit card or other payment information to their account settings.

string

Required

Optional

destinationUrl

A conversion occurs when a customer visits a web page that matches this URL.

1

Required when ruleType is DESTINATION_URL.

string

Required 1

Optional

destinationUrlOperator

Rule operator for destinationUrl. Valid choices include:

  • EQUALS - For a conversion to occur, supply the full exact URL including the http/https protocol.

  • CONTAINS - For a conversion to occur, supply any part of the URL.

  • REGEX - Regular expression. Use for wildcard searches where conversions occur on any site within a domain or several domains.

  • BEGINS_WITH

2

Required when ruleType is DESTINATION_URL.

string

Required 2

Optional

conditions

You can create as many standard or custom events as you like. Refer to conditions object.

3

Required when ruleType is EVENTS.

array

Required 3

Optional

isActive

A read-only field that specifies the beacon status (Active/Inactive).

boolean

N/A

N/A

createdAt

A read-only field that specifies when the beacon was created.

string

N/A

N/A

updatedAt

A read-only field that specifies when the beacon was updated.

string

N/A

N/A

Conditions Object

The conditions object contains the following fields:

Field

Description

Data Type

Create

Update

key

Event type. Can be one of the standard types defined below or a custom key name.

  • CATEGORY - The object you want to track, such as clothes, electronics, or furniture.

  • ACTION - The type of action the user takes with the category object, such as clicking a button.

  • LABEL - A label for the event details. For example, add an item to a shopping cart, place an order, make a request, or download a file.

  • VALUE - A numeric value associated with the goal. For example, the number 10.

string

Required

Optional

operator

Rule operator. Allowed values:

  • EQUALS

  • LESS_THAN

  • GREATER_THAN

  • CONTAINS

  • REGEX - Regular expression. Use for wildcard searches where conversions occur if the value field contains any text string.

4

Required when ruleType is EVENTS.

string

Required 4

Optional

value

Value for the event type.

string

Required

Optional

Read Beacon

Read a specific beacon.

GET /traffic/beacons/{id}

Parameters

Parameter

Parameter Type

Description

Data Type

Required

id

path

Specifies the beacon ID.

integer

Y

Example Request URL

GET https://dspapi.admanagerplus.yahoo.com/traffic/beacons/6525079

Example Response

{
  "response": {
    "id": 6525079,
    "name": "event12",
    "accountId": 1356341,
    "pixelId": 10123456,
    "ruleType": "EVENTS",
    "conversion_category": "SIGNUP",
    "conversion_default_value": 1.46,
    "conditions": [
      {
        "key": "ACTION",
        "operator": "GREATER_THAN",
        "value": "5"
      },
      {
        "key": "LABEL",
        "operator": "LESS_THAN",
        "value": "4"
      }
    ],
    "isActive": true,
    "createdAt": "2017-06-28T23:34:50Z",
    "updatedAt": "2017-06-28T23:34:50Z"
  },
  "errors": null,
  "timeStamp": "2017-06-28T23:38:42Z"
}

Read Beacons

Read a filtered list of beacons.

GET /traffic/beacons?accountId={accountId}&query={query}&page={page}&limit={limit}&sort={sort}&dir={dir}

Parameters

Parameter

Parameter Type

Description

Data Type

Required

accountId

query

Specifies the advertiser ID.

integer

Y

query

query

Specifies the search term.

Use URL encoding conventions (i.e. a space should be replaced with a + or %20).

string

N

page

query

Specifies the page number.

integer

N

limit

query

Specifies the total number of items to return. Maximum allowed value is 100.

integer

N

sort

query

Specifies the column to sort by.

string

N

dir

query

Specifies the sort direction. Allowed values:

  • ASC: data is sorted in ascending order.

  • DESC: data is sorted in decending order.

string

N

Example Request URL

GET https://dspapi.admanagerplus.yahoo.com/traffic/beacons?accountId=1356341&query=event&limit=2

Example Response

{
  "response": [
    {
      "id": 6525028,
      "name": "event12",
      "accountId": 1356341,
      "pixelId": 10123456,
      "ruleType": "DESTINATION_URL",
      "conversion_default_value": 1.46,
      "conversion_category": "SIGNUP",
      "isActive": true,
      "createdAt": "2017-06-28T17:28:52Z",
      "updatedAt": "2017-06-28T19:20:03Z"
    },
    {
      "id": 6525032,
      "name": "event12",
      "accountId": 1356341,
      "pixelId": 10123456,
      "ruleType": "EVENTS",
      "conversion_category": "PURCHASE",
      "conversion_default_value": 1.46,
      "isActive": false,
      "createdAt": "2017-06-28T19:28:43Z",
      "updatedAt": "2017-06-28T19:30:22Z"
    }
  ],
  "errors": null,
  "timeStamp": "2017-06-29T01:37:17Z"
}

Create Beacon (Standard Events)

Create a new beacon with standard events rule.

POST /traffic/beacons

Example Request URL

POST https://dspapi.admanagerplus.yahoo.com/traffic/beacons

Example Request Body

{
  "name": "event12",
  "accountId": 1356341,
  "pixelId": 10123456,
  "ruleType": "EVENTS",
  "conversion_category": "SIGNUP",
  "conversion_default_value": 1.46,
  "conditions": [
    {
      "key": "ACTION",
      "operator": "GREATER_THAN",
      "value": "5"
    },
    {
      "key": "LABEL",
      "operator": "LESS_THAN",
      "value": "4"
    }
  ]
}

Example Response

{
  "response": {
    "id": 6525079,
    "name": "event12",
    "accountId": 1356341,
    "pixelId": 10123456,
    "conversion_default_value": 1.46,
    "conversion_category": "SIGNUP",
    "ruleType": "EVENTS",
    "conditions": [
      {
        "key": "ACTION",
        "operator": "GREATER_THAN",
        "value": "5"
      },
      {
        "key": "LABEL",
        "operator": "LESS_THAN",
        "value": "4"
      }
    ],
    "isActive": true,
    "createdAt": "2017-06-28T23:34:50Z",
    "updatedAt": "2017-06-28T23:34:50Z"
  },
  "errors": null,
  "timeStamp": "2017-06-28T23:34:51Z"
}

Create Beacon (Custom Events)

Create a new beacon with custom events rule.

POST /traffic/beacons

Parameters

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

Example Request URL

POST https://dspapi.admanagerplus.yahoo.com/traffic/beacons

Example Request Body

{
  "name": "event12",
  "accountId": 1356341,
  "pixelId": 10123456,
  "ruleType": "EVENTS",
  "conversion_category": "SIGNUP",
  "conversion_default_value": 1.16,
  "conditions": [
    {
      "key": "blue",
      "operator": "GREATER_THAN",
      "value": "5"
    },
    {
      "key": "red",
      "operator": "LESS_THAN",
      "value": "4"
    }
  ]
}

Example Response

{
  "response": {
    "id": 6525181,
    "name": "event12",
    "accountId": 1356341,
    "pixelId": 10123456,
    "conversion_default_value": 1.16,
    "conversion_category": "SIGNUP",
    "ruleType": "EVENTS",
    "conditions": [
      {
        "key": "blue",
        "operator": "GREATER_THAN",
        "value": "5"
      },
      {
        "key": "red",
        "operator": "LESS_THAN",
        "value": "4"
      }
    ],
    "isActive": true,
    "createdAt": "2017-06-29T02:49:29Z",
    "updatedAt": "2017-06-29T02:49:29Z"
  },
  "errors": null,
  "timeStamp": "2017-06-29T02:49:30Z"
}

Create Beacon (Destination URL)

Create a new beacon with destination URL rule.

POST /traffic/beacons

Parameters

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

Example Request URL

POST https://dspapi.admanagerplus.yahoo.com/traffic/beacons

Example Request Body

{
  "name": "dest_url_beacon",
  "accountId": 1356341,
  "pixelId": 10123456,
  "ruleType": "DESTINATION_URL",
  "destinationUrl": "blue.com",
  "destinationUrlOperator": "EQUALS",
  "conversion_category": "SIGNUP",
  "conversion_default_value": 1.16
}

Example Response

{
  "response": {
    "id": 6524938,
    "name": "dest_url_beacon",
    "accountId": 1356341,
    "pixelId": 10123456,
    "conversion_category": "SIGNUP",
    "conversion_default_value": 1.16,
    "ruleType": "DESTINATION_URL",
    "destinationUrl": "blue.com",
    "destinationUrlOperator": "EQUALS",
    "conditions": [],
    "isActive": true,
    "createdAt": "2017-06-28T00:44:33Z",
    "updatedAt": "2017-06-28T00:44:33Z"
  },
  "errors": null,
  "timeStamp": "2017-06-28T00:44:34Z"
}

Update Beacon

Beacon update is not supported because any pixels which have been counted would be invalidated. It is recommended to simply create a new beacon instead.

Delete Beacon

The DSP Traffic API does not support deletion of beacons.