New Beta Feature: Linked Data

Thanks for agreeing to be a beta tester for one of our newest features. Your feedback is essential to the continued improvement of the Leanplum Platform.

What it Does

Linked Data allows you to inject automated contextual data stored in other sources, such as your data warehouse or any service provider, into all messaging channels. Linked data can be combined with existing Leanplum user profile data to create highly personalized and relevant message campaigns. The data is pulled down from the source you define and injected into the content of a message at the time it is sent, allowing you to send messages with content such as: top recommended products, weather right now or today’s menu. Linked data is one of our most flexible messaging features we've ever built and is available in beta right now.

Once you have set up and defined your Linked Data sources in the Leanplum App Settings (see Setup section below), you can immediately begin to reference Linked Data information in your messages. We built Linked Data for unlimited flexibility by allowing you to use Jinja-­style syntax to help turn raw data from any source into a useful, human-readable message.

Setup

To get started, you need an API or some other server that returns a JSON response. This can be your own backend, or you could be using a third­party backend. Later in this document, there will be a tutorial that walks you through using a third­party backend.

  1. Define your Linked Data sources by providing the base URLs.
  2. On the Leanplum dashboard, go to Manage Apps > Keys & Settings.
  3. Each Linked Data source has a name and a URL.
  4. The URL may optionally have parameters, which are indicated with {} symbols.
    1. If there are parameters, then these parameters will be filled out when you compose your message in Leanplum.

Here are some example URLs:

  • https://www.quandl.com/api/v3/datasets/WIKI/AAPL.json
    • This requires no parameters, it always returns the current Dow Jones Industrial Average
  • http://jsonplaceholder.typicode.com/users
    • This also requires no parameters, it returns a list of all users
  • http://jsonplaceholder.typicode.com/users/{}
    • This is an example of using one parameter, which is the ID of the user. This will return a record for that user. E.g., http://jsonplaceholder.typicode.com/users/4 

Add the Linked Data URLs in Leanplum Keys & Settings:

How You Could Use it

As we mentioned earlier, once your Linked Data source is connected to Leanplum, you can use Jinja-style syntax in your message.

For example, suppose the "recommend" Linked Data returns a JSON payload representing the 3 products most recommended for the given user id, such as:

[
{"name": "Bracelet", "sku": 1234, "price": 19.99},
{"name": "Scarf", "sku": 5678, "price": 39.99},
{"name": "Belt", "sku":4501, "price": 24.67}
]

The most basic example is to import the contents of the Linked Data directly into the message. If you want to send a push notification with the contents of the first recommended item:

We think you'll love this {{ linkedData.recommend[userId][0]['name'] }},
on sale for ${{ linkedData.recommend[userId][0]['price'] }}

You can also use Jinja syntax in the Open Action of the push notification, so you can deep link the user to the correct item:

myapp://view_item/{{ linkedData.recommend[userId][0]['sku'] }}

You can leverage Jinja for more sophisticated things, like constructing a For loop that iterates through all the product recommendations, or using an if/else block to make the message conditional on the contents of the Linked Data, such as showing alternate content if there are no product recommendations for that user.

For more details on all of your syntax options, please see the Leanplum Templating Language reference.

Tutorial

For this Tutorial, we'll use the Quandl API for stock quotes, because it is free to use and does not require any API keys. For the purpose of this tutorial, we also assume you have a test app on Leanplum configured with either in­app messages or push notifications.

Tip: First, confirm that in­app messages or push notifications are working by composing a draft and clicking the Preview button, and verifying it appears on your test device.

Let's assume that your users have a User Attribute that contains their favorite stock. For example:
FavoriteStock=AAPL

You can set this yourself by calling our REST API:

https://www.leanplum.com/api?action=setUserAttributes&appId=APP_ID&clientKey=CLIENT_KEY& userId=USER_ID&userAttributes={"FavoriteStock":"AAPL"}

Do this for your own test device (you can verify your own User ID by going to Test Devices).

Go to Keys & Settings and define a new Linked Data source.

  • Name: stockquote

  • URL: https://www.quandl.com/api/v3/datasets/WIKI/AAPL.json

Next, you can compose a message (could be either an in­app message or a push notification) that contains references the Linked Data. For example:

Your stock quote for {{userAttribute['FavoriteStock']}} is
{{ linkedData.stockquote[userAttribute['FavoriteStock']] }}



Screen_Shot_2016-08-17_at_4.27.07_PM.png

If you click the Preview button, you'll see:

Screen_Shot_2016-08-17_at_3.44.08_PM.png

This is because our message is just echoing the entire contents of the JSON response from the Linked Data URL.

Next, let's do some further parsing to get the field we really want. Modify the message to:

Your stock quote for {{userAttribute['FavoriteStock']}} is
{{ linkedData.stockquote[userAttribute['FavoriteStock']]['dataset']['data'][0][4] }

The result is looking better:

Screen_Shot_2016-08-17_at_3.46.19_PM.png

Now, let's assume we want to round the stock quote to 2 decimal places:

{{ linkedData.stockquote[userAttribute['FavoriteStock']]['dataset']['data'][0][4] | round(2) }}

Result:

Screen_Shot_2016-08-17_at_3.46.27_PM.png

Technical Questions

For the purposes of these technical questions, assume we have the following Linked Data sources defined:

property URL
recommend http://api.example.com/product_recs?userId={}
inventory http://api.example.com/product_recs?store_id={}&sku={}
storeHours http://api.example.com/store_hours?store_id={}
pricing http://api.example.com/pricing.json

 

Caching and Scalability

  • Leanplum makes the requests to the Linked Data URLs at the time the message is sent.
  • Leanplum will cache the results of a specific Linked Data URL for 5 minutes.
  • If your message has a Linked Data parameter that is unique per user, then Leanplum will make a separate request per message.
    • For example, your message has:
      linkedData.recommend[userId]
    • This is a unique request per user, so if your message is sent to 1,000 users, then 1,000 separate requests must be made to your Linked Data source.
    • Please make sure your API endpoint can handle this load.
  • If your message uses the same Linked Data source for all users, then only 1 request will be made.

    • For example, your message has:

      linkedData.pricing
    • This is the same request per user, so if your message is sent to 1,000 users at the same time, Leanplum will only fetch it once for the first user, and used the cached results for the other 999 users.

  • If your message has a Linked Data parameter that varies but is not unique, then each unique instance will be cached.

    ○ For example, your message has:

    linkedData.storeHours['userAttribute.localStoreId']

    ○ This will be cached for each unique localStoreId that you have.
    ○ So, if the message is sent to 1,000 users but you only have 10 localStoreIds, then at most your API will be called 10 times.

Error Handling

If the Linked Data URL returns an error (HTTP response other than 200) or times out after 30 seconds, the Linked Data value will evaluate to null.

If you attempt to render the null value directly in the template, the message will be skipped ­ that is, no message will be sent for that user. For example:

{% set rec = linkedData.recommend[userId] %}We think you'll love {{ rec['name'] }}, on sale now for {{ rec['price'] }}!

If the Linked Data retrieval fails, the message will not be sent to that user.

However, if you check the response for null, this gives you the flexibility to decide what to do if the Linked Data URL fails, such as provide alternate text:


{% set rec = linkedData.recommend[userId] %}
{% if rec == null %}
     Check out our latest specials!
{% else %}
     We think you'll love {{ rec['name'] }}, on sale now for {{ rec['price'] }}!
{% endif %}

Authentication

Currently, Linked Data does not support Basic Authentication. However, we do support https, and you can embed a secret key in your Linked Data URL to protect your API endpoint. For example:
https://api.example.com/inventory?key=h5J16Ck5RdzUKoZe&store_id={}&sku={}

If you have other authentication needs, please let us know.

Please contact support@leanplum.com with any additional questions.


Was this article helpful?
Have more questions? Submit a request