Decision Ads API (Advanced)

Overview

The Quickstart was just the beginning! Using the ad you created in the Quickstart, let's test out some additional features.

Custom Event Tracking

Use this to track special click events like 'likes', 'shares', etc. Basically, you'll request a special URL, Kevel will provide one in the response, and you place it where the click event happens. More info here.

  1. Make sure you've done the Decision API Quickstart and have created a Test Campaign/Flight/Ad. Make sure it's active and has no targeting.

  2. In the Decision API request, include eventIDs of 20 and 21. In Kevel reporting, these are titled "Like" and "Share" respectively, although technically the URL can be fired wherever it is placed.

Custom Events

{
  "placements": [
    {
      "divName": "Test Placement",
      "networkId": "**Your Network ID**",
      "siteId": "**Your Site ID**",
      "adTypes": [16],
      "eventIds": [20,21],
      "campaignId":"**Your Campaign ID**"
    }
  ]
}

Request cURL

curl -H 'Content-Type:application/json' -X POST -d '{"placements":[{"divName":"Test Placement","networkId":XXXX,"siteId":XXXX,"campaignId":XXX,"eventIds": [20,21],"adTypes":[16]}]}' https://e-<networkId>.adzerk.net/api/v2
  1. In the response, you'll get the event URLs under the events object:

Custom Events

{
  "adId": 111,
  "creativeId": 222,
  "flightId": 333,
  "campaignId": 444,
  "clickUrl": "https://e-1234.adzerk.net/r...?",
  "impressionUrl": "https://e-1234.adzerk.net/i.gif...",
  "events": [
        { "id": 20,
          "url": "https://e-1234.adzerk.net/e.gif...?"
        },
        { "id": 21,
          "url": "https://e-1234.adzerk.net/e.gif...?"
        }
  ]
}
  1. Either insert the event URL into your ad to automatically fire when someone clicks that event, or GET the endpoint server-side when you've registered the event.
  2. Have the custom event fire.
  3. Go to Reporting and see the 'Like' and/or 'Share' column populate!

Keyword Targeting

Use this if you want to test key/value pair targeting on specific keywords.

Specifically, you'll set the ad so that it'll appear only if a certain keyword is passed in the Decision API Request. More info on keyword targeting is here.

Below uses the Test Campaign created in the Decision API Quickstart.

Setting It Up

  1. Edit the Test Flight.

  2. Go to the Keyword Targeting section.

  3. Put "Test" in the box.

  4. Save.

Seeing It In Action

  1. In the Decision API Request, include the keywords field, with the corresponding trigger word.

Keyword

{
  "placements": [
    {
      "divName": "Test Placement",
      "networkId": "**Your Network ID**",
      "siteId": "**Your Site ID**",
      "adTypes": [16],
      "campaignId":"**Your Campaign ID**"
    }
  ],
    "keywords": ["test"]
}

Request cURL

curl -H 'Content-Type:application/json' -X POST -d '{"placements":[{"divName":"Test Placement","networkId":XXXX,"siteId":XXXX,"campaignId":XXX,"adTypes":[16]}],"keywords":["test"]}' https://e-<networkId>.adzerk.net/api/v2
  1. Your "Test Ad" should appear in the response.
  2. Now, ping the Decision API again, but instead of test as the keyword, put test2. If set up correctly, you'll receive nothing in the response.

Custom Targeting

Similar to Keyword Targeting, Custom Targeting works with a key/value pair; however, Custom Targeting can use advanced logic, like comparisons, operators, and Reserved Keys.

For this example, let's use age (you don't actually have to be collecting it for this to work). We'll also be using the same Test Campaign/Flight/Ad created in the Decision API Quickstart.

Setting It Up

  1. Edit the Test Flight.
  2. Go to the Custom Targeting section.
  3. Write age > 25.
  4. Save.

Also, make sure that Keyword Targeting section is blank if you already tried that above.

Seeing It In Action

  1. In the Decision API Request, include the properties object, with the key/value pair of age: 30.

Custom

{
  "placements": [
    {
      "divName": "Test Placement",
      "networkId": "**Your Network ID**",
      "siteId": "**Your Site ID**",
      "adTypes": [16],
      "campaignId":"**Your Campaign ID**",
      "properties": {
        "age": 30
      }
    }
  ]
}

Request cURL

curl -H 'Content-Type:application/json' -X POST -d '{"placements":[{"divName":"Test Placement","networkId":XXXX,"siteId":XXXX,"campaignId":XXX,"properties": {"age": 30},"adTypes":[16]}]}' https://e-<networkId>.adzerk.net/api/v2

  1. Since age is greater than 25, the ad should appear in the response.

  2. Now, change age to 20 in the request, and notice how the Ad Decision Engine doesn't respond with the ad!