Image pixel delivery

Image pixel delivery (also known as "push pixel") is a method for delivering data to clients. When a user qualifies for the desired audience, an image pixel is fired to the client. This image pixel and its macros inform the client which attributes the user has. The client can store this in the user’s cookie or profile store for later targeting.

Tip: While image pixel delivery is still available, Server data transfer or JSON return are the preferred delivery methods.

The pixel must be a standard 1x1 image pixel with an image return type. User experience guard (UXG) tests each pixel on entry into the Oracle Data Cloud platform and then every 15 minutes to make sure that the pixel is meeting your desired latency requirements. If a failure occurs, tests repeat each minute.

Basic workflow

  1. Any valid 1x1 image pixel would be placed as the delivery method in the Create Campaign dialog. Macros can be placed on the end of the pixel depending on the needs of the client’s ad server. For example, you could include the $CAMPAIGNS macro:

    http://example.com/partner/test_pixel.gif?$CAMPAIGNS

  2. When the platform sees a user that qualifies for an audience, we fire the above pixel expanding the $CAMPAIGNS so that you know what type of attributes the user has. Expanded pixel example:

    http://example.com/bk_partner/test_pixel.gif?1234|2345|3456

Macros

The following macros can be used in the pixel URL as key value pairs.

Macro Replaced by
$_BK_EXID A ID
$CAMPAIGNS List of recently winning campaign IDs*
$CATEGORIES List of tag category numbers matching this campaign win*
$COLO Returns the ID of the colocation server that the user hits. Used only for the user data API.
$LEAF_CATEGORIES Same as $CATEGORIES, but only include the lowest categories in the tree (no parent nodes)*
$PRICE Win price for this campaign
$RAND A random 32-bit unsigned integer value, which is useful for cache busting purposes
$REPEAT_VISITOR(siteID)
  • Returns a "0" if the user has never been seen on the partner's siteIDs called in the macro
  • Returns a "1" if the user has been seen on the partner's siteIDs called in the macro
  • Returns nothing for invalid sites or sites for which the user does not have access
  • Returns new visitor indication for all siteIDs for the partner if no siteID is listed is listed in the macro. To list multiple siteIDs, separate the siteIDs by a comma. For example: $REPEAT_VISITOR(1234,9876,3241). Multiple siteIDs are treated as an OR condition: if the user has been seen on any of the sites listed, a 1 is returned. A 0 is returned if the user has never been seen on any of the siteIDs.
$TIMESTAMP Current Unix time (in seconds since Jan. 1 1970 UTC)
$URL_ENCODED_ARG(keyName) Returns the value of the named phint matching “keyName” in the argument passed. This macro requires the campaign and site to be owned by the same partner.**

*Note: By default, items are separated by vertical bar (|) characters. To change the separator, append square brackets with the separator character, such as: $CATEGORIES[,]
*To limit the number of items in one call, append parentheses with a number, such as: $CAMPAIGNS(5)
*To do both of the above, use parentheses FIRST then square brackets, such as: $CATEGORIES(8)[,]. The opposite will NOT work.

** For example:

If you pass: https://stags.bluekai.com/site/4712?ret=html&phint=url_arg%3DPHINT_PASSED&limit=10&r=43132838&url_arg=URL_PASSED

And then drop: http://sometag.example.com?foo=$URL_ENCODED_ARG(url_arg)

You will get: http://sometag.example.com?foo=URL_PASSED|phint_passed

Learn more

Pixel URL macros