Beacons (Pixels)

Overview

BrightRoll 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 or retargeting.

Endpoint

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

Fields

The Beacon object contains the following fields:

Name Description Type Add
id ID of the beacon. integer N/A
name Name of the beacon. text Required
accountId Advertiser/account ID. Refer to Advertisers. integer Required
beaconType

Type of beacon.

  • CONVERSION
  • RETARGETING
text Required
ruleType

Rule type for this beacon.

  • EVENTS - Track when a specific event or action is triggered on your site.
  • DESTINSTION_URL - Track customer visits to specific pages. Specify values for destinationUrl and destinationUrlOperator fields.
text Required
conversion_default_value Estimated value of the conversion. See conversion_category. integer 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. (1) Required when beaconType is CONVERSION.

  • 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
  • VIEW_CONTENT
  • ADD_TO_WISHLIST
  • INITIATE_CHECKOUT
  • ADD_PAYMENT_INFO
text Required (1)
destinationUrl A conversion occurs when a customer visits a web page that matches this URL. (1) Required when ruleType is DESTINSTION_URL. text Required (1)
destinationUrlOperator

Rule operator for destinationUrl. (1) Required when ruleType is DESTINSTION_URL.

  • 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
text Required (1)
isActive (Read-Only) Indicates if the Beacon is active or inactive. boolean N/A
createdAt (Read-Only) Creation timestamp. datetime N/A
updatedAt (Read-Only) Last updated timestamp. datetime N/A
condition You can create as many standard or custom events as you like. Refer to condition object. (1) Required when ruleType is EVENTS. Required (1)  

condition object

The condition object contains the following fields:

Name Description Type Add
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.
text Required
operator

Rule operator when ruleType is EVENTS.

  • EQUALS
  • LESS_THAN
  • GREATER_THAN
  • CONTAINS
  • REGEX - Regular expression. Use for wildcard searches where conversions occur if the value field contains any text string.
text Required
value Value for the event type. text Required

Read Beacon (Single)

To retrieve data for a specific Beacon, make a GET call with the id parameter.

GET https://dspapi.admanagerplus.yahoo.com/traffic/beacons/{id}
Name Description Type Required?
id Beacon ID integer Y

The response will be the Beacon associated with the given ID.

Example Request

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

Example Response

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

Read Beacons (Filtered)

To retrieve a filtered list of Beacons for an account, make a GET call with the supported query parameters.

GET https://dspapi.admanagerplus.yahoo.com/traffic/beacons?accountId={accountId}&page={page}&limit={limit}&sort={sort}&dir={dir}&query={query}
Name Description Type Required?
accountId Account or Advertiser ID integer Y
page Page number integer N
limit Total number of items to return. Maximum allowed value is 100. integer N
sort Column to sort by text N
dir Sort direction. Valid values: asc, desc text N
query Search term. Use url encoding conventions (i.e. a space should be replaced with a + or %20). text N

The response will be a list of matching Beacons.

Example Request

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

Example Response

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

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.

Create Beacon (Standard Events)

To create a new Beacon with standard events, make a POST call with a payload body. The response will be the newly created Beacon.

Example Request

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

Example Payload

{
  "name": "event12",
  "accountId": 1264413,
  "beaconType": "CONVERSION",
  "ruleType": "EVENTS",
  "conversion_category": "SIGNUP",
  "conversion_default_value": 1.46,
  "condition": [
    {
      "key": "ACTION",
      "operator": "GREATER_THAN",
      "value": "5"
    },
    {
      "key": "LABEL",
      "operator": "LESS_THAN",
      "value": "4"
    }
  ]
}

Example Response

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

Create Beacon (Custom Events)

To create a new Beacon with custom events, make a POST call with a payload body. The response will be the newly created Beacon.

Example Request

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

Example Payload

{
  "name": "event12",
  "accountId": 1264413,
  "beaconType": "CONVERSION",
  "ruleType": "EVENTS",
  "conversion_category": "SIGNUP",
  "conversion_default_value": 1.16,
  "isActive": true,
  "condition": [
    {
      "key": "blue",
      "operator": "GREATER_THAN",
      "value": "5"
    },
    {
      "key": "red",
      "operator": "LESS_THAN",
      "value": "4"
    }
  ]
}

Example Response

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

Create Beacon (Destination URL)

To create a new Beacon with a rule for Destination URL matching, make a POST call with a payload body. The response will be the newly created Beacon.

Example Request

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

Example Payload

{
  "name": "dest_url_beacon",
  "accountId": 1264413,
  "beaconType": "RETARGETING",
  "ruleType": "DESTINSTION_URL",
  "destinationUrl": "blue.com",
  "destinationUrlOperator": "EQUALS"
}

Example Response

{
  "response": {
    "condition": [],
    "ruleType": "DESTINSTION_URL",
    "destinationUrl": "blue.com",
    "destinationUrlOperator": "EQUALS",
    "beaconType": "RETARGETING",
    "id": 6524938,
    "name": "dest_url_beacon",
    "accountId": 1264413,
    "updatedAt": "2017-06-28T00:44:33Z",
    "isActive": true
    "createdAt": "2017-06-28T00:44:33Z"
  },
  "errors": null,
  "timeStamp": "2017-06-28T00:44:34Z"
}

Delete Beacon

Beacon deletion is not supported by the API.