Slot

Before you use the live content API to endpoint to create a JSON that you can use to insert recommendations in your site and mobile apps, create a slot for your site and setup a JSON template. If you want to use this feature, contact us to get started.

Perform the following steps to create a slot and its corresponding JSON template.

Create the slot

Create a slot on the Blueshift dashboard.

Setup a JSON template

Set up a JSON template to customize the API response of the Live content. 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.

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

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

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

{
  "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 JSON template gets translated in to a response that looks like this with the user and product attributes filled in:

{
  "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

Create a Live content campaign and enter the campaign name, select the target segment, flight dates, the slot name and the JSON template that you create.

Integrate the live content in your site or app

Now, you can use the endpoint to integrate the live content from our platform to your site.

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.

Add tracking callbacks

The live content API response returns an impression_url and a click_url. For example:

"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-click counts for the live content campaign reporting.

Both these callbacks respond 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.

Best practices

• 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.