Live Content API

You can use the Live content API endpoint to insert content recommendations in your website and mobile apps. In order to use the Live content API, you would need to follow the steps outlined below. 

If you are interested in using this feature, please contact support@blueshift.com before getting started.  

 

Create a slot in the Blueshift dashboard.

c3c723a-Screen_Shot_2017-10-16_at_11.21.00_AM.png

You can customize the JSON API response by setting up a JSON template. The JSON template can use user variables as well as content recommendations in the response. You can build your JSON response end-point using the Liquid programming language. Each time a Live content API call is made for a user, the Liquid endpoint gets the entire user and recommendation context, and you can customize the response.

b5f8663-Screen_Shot_2017-02-03_at_4.23.32_PM.png

Enter the JSON template name, and select the recommendation algorithm to use. You can customize the recommendations with the recommendation studio. You can preview the recommendations for a user and see the response by clicking "Show Recommended content".

58981f3-Screen_Shot_2017-02-03_at_4.23.53_PM.png

Next, you can customize the JSON response that will be served when the API is called.

e90945f-Screen_Shot_2017-02-03_at_4.24.05_PM.png

Here is a sample JSON response that includes Liquid macros and variables:

  • JSON
{
  "user": {
    "firstname": "{{user.firstname}}",
    "lastname": "{{user.lastname}}"
  },
  "products": [
    {% for product in products %}
    {% if forloop.first == false %}, {% endif %}
    {
      "name": "{{product.title}}",
      "sku": "{{product.sku}}",
      "image_url": "{{product.image}}",
      "url": "{{product.web_link}}",
      "price": "{{product.price}}"
    }
    {% endfor %}
  ]
}

The above JSON template gets translated in to a response that looks like this with the user and product attributes filled in:

  • JSON
{
  "user": {
    "firstname": "Jane",
    "lastname": "Doe"
  },
  "products": [{
    "name": "Saint Joan",
    "sku": "9780140437911",
    "image_url": "https://images.randomhouse.com/cover/9780140437911",
    "url": "http://www.blueshiftreads.com/products/drama-european-english-irish-scottish-welsh/saint-joan",
    "price": "14"
  },
  {
    "name": "Free Baseball",
    "sku": "9780142410806",
    "image_url": "https://images.randomhouse.com/cover/9780142410806",
    "url": "http://www.blueshiftreads.com/products/juvenile-fiction-sports-recreation-baseball-softball/free-baseball",
    "price": "5.99"
  },
  {
    "name": "Summer of the Swans, the (Puffin Modern Classics)",
    "sku": "9780142401149",
    "image_url": "https://images.randomhouse.com/cover/9780142401149",
    "url": "http://www.blueshiftreads.com/products/juvenile-fiction-family-siblings/summer-of-the-swans-the-puffin-modern-classics",
    "price": "6.99"
  },
  {
    "name": "Haunted Castles",
    "sku": "9780143124016",
    "image_url": "https://images.randomhouse.com/cover/9780143124016",
    "url": "http://www.blueshiftreads.com/products/fiction-horror/haunted-castles",
    "price": "22"
  }]
}

Create a Live content campaign and enter the campaign name, select the target segment, flight dates, the slot name and the JSON template (created above).

9cf984c-Screen_Shot_2017-10-16_at_11.00.49_AM.png

The Live content API call takes several parameters including:

  • slot: The name of the "slot" on your website/mobile app as registered in the Blueshift dashboard above
  • api_key: Your event API Key available from the Blueshift dashboard Account settings
  • email: The user's email (if applicable)
  • customer_id: The user's customer_id (if applicable)
  • cookie: The user's blueshift cookie (if applicable)
  • device_id: The user's mobile device id (if applicable)
  • context: Any additional information you want to make available for personalization (products to exclude, categories to include/exclude etc)
  • seed_item_ids : array of item_ids that form the basis for replay or related items
  • exclude_item_ids : array of item_ids to exclude from the response
  • exclude_categories : array of categories to exclude from the response
  • page_number : If pagination is enabled for your account set this to get more pages of recommendations

cURL

curl -H "Content-Type: application/json" -X POST -d '
{
"slot":"<SLOT>",
"api_key": "<API_KEY>",
"user": {
 "customer_id": "<CUSTOMER_ID>",
 "email": "<CUSTOMER_EMAIL>",
 "cookie": "<BLUESHIFT_COOKIE>",
 "device_id": "<CUSTOMER_ID"
},
"context": {
   "seed_item_ids": ["<item_id_1>", "<item_id_2>",...],
   "exclude_item_ids": ["<item_id_1>", "<item_id_2>",...],
   "exclude_categories": ["category1", "category2",...],
   "page_number" : 2
 }
}' https://api.getblueshift.com/live

The response would include the JSON content as created in the JSON template with the user attributes and content recommendations filled in.

JSON

{
    "content": {
        "products": [
            {
                "image_url": "https://images.randomhouse.com/cover/9780140437911",
                "name": "Saint Joan",
                "price": "14.0",
                "sku": "9780140437911",
                "url": "http://www.blueshiftreads.com/products/drama-european-english-irish-scottish-welsh/saint-joan"
            },
            {
                "image_url": "https://images.randomhouse.com/cover/9780142410806",
                "name": "Free Baseball",
                "price": "5.99",
                "sku": "9780142410806",
                "url": "http://www.blueshiftreads.com/products/juvenile-fiction-sports-recreation-baseball-softball/free-baseball"
            },
            {
                "image_url": "https://images.randomhouse.com/cover/9780142401149",
                "name": "Summer of the Swans, the (Puffin Modern Classics)",
                "price": "6.99",
                "sku": "9780142401149",
                "url": "http://www.blueshiftreads.com/products/juvenile-fiction-family-siblings/summer-of-the-swans-the-puffin-modern-classics"
            },
            {
                "image_url": "https://images.randomhouse.com/cover/9780143124016",
                "name": "Haunted Castles",
                "price": "22.0",
                "sku": "9780143124016",
                "url": "http://www.blueshiftreads.com/products/fiction-horror/haunted-castles"
            }
        ],
        "user": {
            "firstname": "Jane",
            "lastname": "Doe"
        }
    },
    "feedback": {
        "errors": [],
        "selected_experiment_uuid": "175d4f44-f1f0-438c-ad38-f4ede2047974",
        "selected_trigger_uuid": "d181abb6-d5d5-4120-8c9b-c0de724576d6",
        "skipped_triggers": {
            "d181abb6-d5d5-4120-8c9b-c0de724576d6": "Active ( launch preview simulation is enabled )"
        }
    },
    "success": true,
    "tracking": {
        "click_url": "http://api.getblueshift.com/track?uid=d1a50376-4f62-46d0-b4a3-36ca0bd2f9cc&eid=175d4f44-f1f0-438c-ad38-f4ede2047974&mid=42a62e43-438a-4cf9-ac1d-a24706fe3065&a=click",
        "impression_url": "http://api.getblueshift.com/track?uid=d1a50376-4f62-46d0-b4a3-36ca0bd2f9cc&eid=175d4f44-f1f0-438c-ad38-f4ede2047974&mid=42a62e43-438a-4cf9-ac1d-a24706fe3065&a=open"
    }
}

The API response contains:

  • content: product recommendations and user attributes as created in the JSON template above
  • tracking: impression_url when the content is shown to the user and click_url that should be called when the user clicks on the creative. This helps us track the performance of the campaign and report statistics correctly in the campaign dashboard
  • success: boolean indicating the API call was successful if true. If it's set to false, do not render results.
  • feedback: Additional metadata useful for diagnostics.

The Live content API response returns a impression_url and a click_url.

Example:

  • Tracking url response in JSON
"tracking": {
    "click_url": "http://api.getblueshift.com/track?uid=d1a50376-4f62-46d0-b4a3-36ca0bd2f9cc&eid=175d4f44-f1f0-438c-ad38-f4ede2047974&mid=42a62e43-438a-4cf9-ac1d-a24706fe3065&a=click",
    "impression_url": "http://api.getblueshift.com/track?uid=d1a50376-4f62-46d0-b4a3-36ca0bd2f9cc&eid=175d4f44-f1f0-438c-ad38-f4ede2047974&mid=42a62e43-438a-4cf9-ac1d-a24706fe3065&a=open"
}

The URLs above contain information to count the impressions and clicks. You can call them by simply doing a HTTP GET operation on the urls.

impression_url: The website/app should asynchronously call back the impression_url once the content is displayed. The callback updates the impression and unique impression counts for the Live content campaign reporting.

click_url: The website/app should asynchronously call back the click_url after the user clicks on the content. The callback updates the clicks and unique clicks counts for the Live content campaign reporting.

Both these callbacks respond back with a 200 ok and the response can be ignored. Downstream attribution for purchase, revenue and custom goals also require instrumenting the impression and click callbacks, and should happen automatically once these are setup.

  • Timeouts/Errors: Handle any timeouts or errors so that your app/website can render a page correctly in case of Blueshift server timeouts.
  • Tracking: Ensure you call the click and impression urls so that stats are captured correctly for the campaign.
Was this article helpful?
0 out of 0 found this helpful
Have more questions? Submit a request