DocumentationDeveloper PortalAPI EndpointsProduct Updates
API Endpoints
Contact Us

Slot

Use the live content slot to create a JSON response that you can integrate in your app or site.

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.

Live content requests with non-existing user identifiers

Blueshift creates a new user during a live content call if no matching user is found based on the parameters passed in the request.

For a new user to be created, the request must contain at least one unique user identifier. These identifiers can be customized for each account, but every account has at least the following: device_id and cookie. Most accounts also use email and customer_id as unique user identifiers, and some additionally use phone_number.

Without one of these unique user identifiers, Blueshift will not create a new user if no match is found based on the parameters passed in the live content request.

If there are no unique user identifiers we still will attempt to lookup the user based on the user parameters but if a user is not found we will not create a new user and live content will not be returned.


When live content campaign is Determined by a Segment:

*Live content campaign with segment (Determined by a Segment): If the live content campaign is targeting a segment of users and we don’t find a user based on the parameters passed, but a unique user identifier is present for the account in the request, we will create a new user on the fly. However, live content will not be returned for this user immediately because it takes a few minutes for the user to be indexed in our system, and we are unable to determine if the user belongs to the segment at this point. Subsequent requests after a few minutes may or may not return live content, depending on the segment criteria.

*Live content campaign without segment (targeting all users): If the live content campaign is not targeting a specific segment of users and we don’t find a user based on the parameters passed, but a unique user identifier is present for the account in the request, we will create a new user on the fly. Live content will be returned immediately for this user because there is no need to verify segment membership.

Live content campaign is Determined by other Campaigns

If the live content campaign targets users added by other campaigns, and we don’t find a user based on the parameters passed, but a unique user identifier is present for the account in the request, we will create a new user on the fly. However, live content will not be returned for this user because the user was not found within the account, making it impossible for the user to have been added to the live content campaign through another campaign.

General note on Live content campaign Determined by other Campaigns

We recommend distancing out the process of adding a user to a live content campaign from making a live content request. For example, if a webpage triggers an event to add user X to a campaign and later on the same page makes a live content request for content from that same campaign, the request might fail. This could happen because the user might not have been added to the campaign yet due to a potential race condition.

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.