Beta Feature Tutorial: 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.

If you have not yet read New Beta Feature: Linked Data, we recommend reading that prior to this article, in order to better understand Linked Data, what it does and how your team could leverage it to create highly personalized and relevant message campaigns.

Introduction

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/YAHOO/{}.json?rows=1

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']] }}



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

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:

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:

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


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