Linked Data
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 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 toBasic <token>
, substituting<token>
with a base64 encoding of the stringusername: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 %}
Updated over 2 years ago