Beacons
  • 8 Minutes to read

    Beacons


      Article summary

      Overview

      Yahoo DSP supports Yahoo 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

      /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, refer to Advertisers.

      integer

      Required

      Optional

      pixelId

      Specifies the parent Pixel ID.

      To learn more, refer to 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.

      • APP_URL: Track conversions in apps. Specify values for appUrl, appLocale and mobileMeasurementPartner fields.

      string

      Required

      Optional

      conversion_default_value

      Estimated value of the conversion. Refer to conversion_category.

      integer

      Optional

      Optional

      conversion_category

      (Optional) 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, favorite 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.

      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

      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.

      Required when ruleType is EVENTS.

      array

      Required [3]

      Optional

      appUrl

      The URL of the app. It should be Google app URL if targeting Android devices and Apple store app URL if targeting IOS devices.

      Example values: https://play.google.com/store/apps/details?id=com.espn.score_center&hl=en_US, https://apps.apple.com/pe/app/instagram/id389801252

      Required when ruleType is APP_URL.

      string

      Optional [4]

      Optional [4]

      appLocale

      The region (country) of the Google play store or Apple app store where the app is uploaded.

      Allowed values:

      • de-de: Germany

      • el-gr: Greece

      • en-au: Australia

      • en-ca: Canada

      • en-gb: United Kingdom

      • en-hk: Hong Kong

      • en-in: India

      • en-nz: New Zealand

      • en-ph: Philippines

      • en-sg: Singapore

      • en-us: United States

      • en-za: South Africa

      • es-ar: Argentina

      • es-cl: Chile

      • es-co: Colombia

      • es-cr: Costa Rica

      • es-es: Spain

      • es-mx: Mexico

      • es-pe: Peru

      • es-pr: Puerto Rico

      • es-us: United States (Spanish)

      • fr-ca: Canada (French)

      • fr-ch: Switzerland

      • fr-fr: France

      • id-id: Indonesia

      • it-it: Italy

      • ja-jp: Japan

      • ko-kr: South Korea

      • ms-my: Malaysia

      • pt-br: Brazil

      • sv-se: Sweden

      • th-th: Thailand

      • vi-vn: Vietnam

      • zh-cn: China

      • zh-tw: Taiwan

      Required when ruleType is APP_URL.

      string

      Optional [5]

      Optional [5]

      appId

      The app ID is generated based on the appUrl and appLocale provided. Identifier representing mobile app in Google/Apple store.

      Example values: com.espn.score_center, 389801252

      string

      N/A

      N/A

      mobileMeasurementPartner

      Mobile measurement partner that provides conversions data for your mobile campaign.

      Allowed values:

      • KOCHAVA: Kochava

      • APPSFLYER: Appsflyer

      • ADJUST: Adjust

      • SINGULAR: Singular

      Required when ruleType is APP_URL.

      string

      Optional [6]

      Optional [6]

      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.

      • APP_ID - Identifier representing app in Google/Apple store.

      • MOBILE_MEASUREMENT_PARTNER - Mobile measurement partner that provides conversions data for your mobile campaign.

      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.

      Required when ruleType is EVENTS.

      string

      Required [7]

      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"
            }
          ],
          "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 descending 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",
            "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,
            "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"
            }
          ],
          "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"
            }
          ],
          "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": [],
          "createdAt": "2017-06-28T00:44:33Z",
          "updatedAt": "2017-06-28T00:44:33Z"
        },
        "errors": null,
        "timeStamp": "2017-06-28T00:44:34Z"
      }

      Create Beacon (App URL)

      Create a new beacon with APP 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": "app_url_beacon",
        "accountId": "1356341",
        "conversion_category": "APP_INSTALLATIONS",
        "conversion_default_value": 20,
        "condition": [
         {
           "key": "ACTION",
           "operator": "EQUALS",
           "value": "5"
         }
        ],
        "ruleType": "APP_URL",
        "appUrl": "https://apps.apple.com/us/app/colorsnap-visualizer-iphone/id316256242&locale=en-us",
        "appLocale": "en-us",
        "mobileMeasurementPartner": "SINGULAR",
      }

      Example Response

      {
        "errors": null,
        "response": {
          "accountId": 1356341,
          "appId": "316256242",
          "appLocale": "en-us",
          "appUrl": "https://apps.apple.com/us/app/colorsnap-visualizer-iphone/id316256242&locale=en-us",
          "condition": [
            {
              "key": "ACTION",
              "operator": "EQUALS",
              "value": "5"
            },
            {
              "key": "APP_ID",
              "operator": "EQUALS",
              "value": "316256242"
            },
            {
              "key": "MOBILE_MEASUREMENT_PARTNER",
              "operator": "EQUALS",
              "value": "apsalar"
            }
          ],
          "conversion_category": "APP_INSTALLATIONS",
          "conversion_default_value": 20.0,
          "createdAt": "Sun Oct 18 01:32:04 PDT 2020",
          "id": 1018,
          "mobileMeasurementPartner": "SINGULAR",
          "name": "app_url_beacon",
          "pixelId": 10065562,
          "ruleType": "APP_URL",
          "updatedAt": "Sun Oct 18 01:32:04 PDT 2020"
        },
        "errors": null,
        "timeStamp": "2020-10-18T08:32:04.712Z"
      }

      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.

      Get Beacon Instrumentation Code

      Get instrumentation code for a beacon. The response object contains the following fields:

      Field

      Description

      Data Type

      urlSecureMultiple

      Javascript instrumentation code for the parent pixel

      string

      urlSecureSingle

      Instrumentation code for the parent pixel as an Image tag

      string

      customEventScript

      Javascript instrumentation code for this beacon

      string

      GET /traffic/beacons/{id}/i13n

      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/1005/i13n

      Example Response

      {
        "response": {
          "beaconId": 1005,
          "pixelId": 10065562,
          "urlSecureMultiple": "<script type=\"application/javascript\">(function(w,d,t,r,u){w[u]=w[u]||[];w[u].push({'projectId':'10000','properties':{'pixelId':'10065562'}});var s=d.createElement(t);s.src=r;s.async=true;s.onload=s.onreadystatechange=function(){var y,rs=this.readyState,c=w[u];if(rs&&rs!=\"complete\"&&rs!=\"loaded\"){return}try{y=YAHOO.ywa.I13N.fireBeacon;w[u]=[];w[u].push=function(p){y([p])};y(c)}catch(e){}};var scr=d.getElementsByTagName(t)[0],par=scr.parentNode;par.insertBefore(s,scr)})(window,document,\"script\",\"https://s.yimg.com/wi/ytc.js\",\"dotq\");</script>",
          "urlSecureSingle": "<img src=\"https://sp.analytics.yahoo.com/spp.pl?a=10000&.yp=10065562\"/>",
          "customEventScript": "<script type=\"application/javascript\">\nwindow.dotq = window.dotq || [];\nwindow.dotq.push(\n{\n'projectId': '10000',\n'properties': {\n'pixelId': '10065562',\n'qstrings': {\n'et': 'custom'\n}\n} } ); </script>"
        },
        "errors": null,
        "timeStamp": "2021-03-06T02:16:27.035Z"
      }


      Was this article helpful?