Linked Data

Linked Data Overview

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 real-time information such as:

inventory information, e.g. "top recommended products"
flight times and delays
weather forecasts
inferred demographic data based on the current user’s attributes

Linked Data also allows you to pull your message content localization data from an external source and automate this part of the process.

Once you have set up and defined your Linked Data sources, you can immediately begin to reference Linked Data information in your messages. Linked Data is built 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.

Set up a Linked Data Source

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.

On the Leanplum dashboard, navigate to ⋯ More -> Linked Data and click Add New Source
Fill-in the requested source properties - URL, HTTP Headers (optional), and HTTP request type
Preview the setup to ensure that the data source queries the URL for its associated web service properly
Click Save Source to name the source and save it

URL

This is the URL to a web service that returns a valid data feed.
The URL may optionally have parameters, which are indicated with {} symbols. If there are parameters, then these parameters will be filled out when you compose your message in Leanplum.

Example URLs:

URL	Description
https://www.quandl.com/api/v3/datasets/WIKI/AAPL.json	This URL requires no parameters. It always returns the current Apple (ticker: AAPL) stock value.
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
http://jsonplaceholder.typicode.com/users/{}/favorite/{}	This is an example of using two parameters. This will return a record for that user's favorite item E.g., http://jsonplaceholder.typicode.com/users/4/favorite/sneekers
https://sampleapis.com/futurama/graphql?raw&query={Character(id:"{}") {name}}	This is a an example for querying GraphQL endpoints over HTTP. The GraphQL query is embedded in the query parameters.

HTTP Headers

You can include custom HTTP headers in the web service request. Click the + button to add as many headers as necessary. You can use an HTTP header to embed an authentication key in your Linked Data URL.

Authentication

To configure basic authentication for a API endpoint:

Make sure you are using an HTTPS endpoint. This ensures that the credentials are encrypted when sent over the network.
Set the Authorization header to Basic <token>, substituting <token> with a base64 encoding of the string username:password.

Example
To authenticate with the user demo and the password p@55w0rd, add a header Authorization with value Basic ZGVtbzpwQDU1dzByZA==.

Preview

The Preview section in the source details page helps you ensure that your Linked Data Source is properly set up before it is saved.

Edit a Linked Data Source

To edit a Linked Data Source, navigate to ⋯ More -> Linked Data and click on the source.

Duplicate a Linked Data Source

To Duplicate a Linked Data Source:

Navigate to ⋯ More -> Linked Data and click on the source to be duplicated
On the source details page open the Save options dropdown and select Save as a new source

Delete a Linked Data Source

To delete a Linked Data Source, navigate to ⋯ More -> Linked Data and click the Delete button for the respective Data Source.

Use a Linked Data Source

When authoring a message, you can call the Linked Data Source through a Jinja expression. In this example, recommend is the name of the Linked Data Source.

{{ linkedData['recommend'] }}

If your Linked Data Source URL contains parameter placeholders ({}), you can pass values to be interpolated by placing them in square brackets:

{{ linkedData['recommend'][userId] }}

For more information on how to use the items returned from the Linked Data Source, see the Message Templating topic.

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 between 5-20 minutes.
If your message has a Linked Data parameter that is unique per user, then Leanplum will make a separate request per message.

Jinja expression	Number of calls for 100 users	Explanation
`linkedData['recommend'][userId]`	100	Since the linked data is different for each user, the source URL is called for every user ID. Please make sure your API endpoint can handle this load.
`linkedData['pricing']`	1	Since the same linked data is used for all users, the source URL is requested once, and then cached.
`linkedData['storeHours']['userAttribute.localStoreId']`	Once per unique `localStoreId` user attribute.	This will be cached for each unique localStoreId value in Leanplum. If there are 10 localStoreId values, the API endpoint will be called at most 10 times, once for each localStoreId found in the target audience.

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 %}