Send feedback on this topic

JSON return tag

The JSON return tag uses a BlueKai pixel to deliver data directly to the first-party page in JSON format. Real-time parsing or targeting can pull data out of the DOM at the time the page is rendered. The user must visit the site to initiate data delivery.

The JSON return tag works as follows:

  1. The user visits the partner's site that has a BlueKai JSON return tag.
  2. BlueKai servers evaluate the user in relation to campaign data.
  3. BlueKai formats user data in JSON format.
  4. The JSON response is returned to the page as a JavaScript object (bk_results) so that it can be evaluated by first-party servers.

Requirements

Deploying the JSON return tag

To deploy the JSON return tag on your site:

  1. Create a BlueKai container using the container tool in the UI or the containers API and note its site ID.

    Delivery Partners Receiving EU Data. To receive data via the JSON Return Tag for user profiles located in the European Union (EU), you must have signed Oracle's General Data Protection Regulation (GDPR) Right to Use agreement. Contact your Oracle Account Representative to obtain and sign the agreement.

  2. Select the JS tag type in the code generator and then click Copy in the code box.
  3. If you use the containers API, copy and paste the following example and replace the site ID with your container's site ID.

    JS return tag

    http://tags.bluekai.com/site/your_site_id?ret=js&limit=1

    Sample response data

    var bk_results = {"campaigns":[{"campaign": 45404, "timestamp": 1390523817, "categories": [{"categoryID": 17,"timestamp": 1390520921}]}]}

  4. Paste the JS tag in the <head> element of each web page you plan to optimize as demonstrated in the following example:
    <head>
      //BlueKai JS Tag
      <script type="text/javascript" src="http://tags.bluekai.com/site/15415?ret=js&limit=1"</script>
      //existing_head_code …
    </head>
  5. Create an audience to select the users you want to target.
  6. Create a campaign to deliver user data directly to your site via a JSON return tag.
  7. In the Delivery Method section, set JSON Return Tag to Yes.
    Image of the JSON Return Tag selection set to Yes in the create campaign window

    The Win Frequency is set to Win Every Time, which means that your campaign delivers users every time they get tagged with a category. This ensures that customized site content linked to your campaign is displayed to users every time they visit your web page.

  8. (Optional) To pass macros in the JSON return tag, enter a pixel in the Pixel URL box with the following syntax where yourSiteID is the same site ID you generated:

    http://tags.bluekai.com/site/yourSiteID

    Then select one or more macros from the Additional Macros list and click Verify and Add to add the pixel to the campaign. The following example demonstrates a pixel that passes the audience name and a random 32-bit integer:

    http://tags.bluekai.com/site/24328?&BkDmpAudienceName=$DMP_Audience_Name_Macro&rnd=$RAND

    Paste a Pixel section Create Campaign window

  9. (Optional) To win only on specific sites, set Win on Sites to Win on Selected Containers (Site IDs) in the Advanced Settings section and then select one or more site IDs from the list. The JSON return tag will return data only for the specified site IDs. For example, if you select site ID 24328 and a JSON return tag is called with a different site ID, this campaign will not be included in the JavaScript object returned to your web page. This enables you to control the amount of data is delivered to your web page by the JSON return tag.Advanced Settings section of the Create Campaign window
    If this option is not displayed, contact My Oracle Support (MOS) to request this feature.
  10. Click Save.

Sample JSON return tag results

The following sample JSON return tag provides the sample results:

http://tags.bluekai.com/site/24328?ret=js&amp;limit=1

Sample results for a JSON return tag with no macros appended.

var bk_results = {
"campaigns":[
{
"campaign": 228419,
"timestamp": 1390523817,
"categories": [
{
"categoryID": 1134438,
"timestamp": 1390520921}
]}]};

Timestamps: The campaign timestamp represents when the user was last won by the campaign. The category timestamp represents when the users was last classified into the category that qualified them for that campaign.

Sample results for a JSON return tag with the audience name and random number (cache busting) macros appended:

var bk_results = {
"campaigns": [
{
"campaign": 228419,
"BkDmpAudienceName": "Smartphone Purchasers",
"rnd": "1672281914",
"timestamp": 1445886595,
"categories": [
{
"categoryID": 1134438,
"timestamp": 1445880062
}]},]};

Multiple Campaign IDs: JSON return tags can include multiple campaign IDs. The bk_results object includes all the campaigns IDs that won the user (unless you configured the Win on Sites setting), and each campaign ID includes the category IDs that caused the user to be won by the campaign. Typically, you will add business logic to your web page that customizes the content or ads displayed to the user based on the campaign ID, category IDs, or an audience ID (if you are an audience injection partner).

Related

Containers API

Creating containers

json return tag