These custom data fields allow for the maximum amount of personalization and customization.
Data (String) | Key - We explain these in detail below. | Value - We explain these in detail below. |
Data (Number) | Key | Value |
Data (JSON) | Key | Value |
What are each of the data options?
The different options are ways to structure data to be available in metadata with the breakdown being:
String – a string is just text or words that are put in double quotation marks to show that they are important and part of the information to be used. You can use strings to write names, messages, and all sorts of text in JSON.
Number – A number in JSON is like writing down how many things you have. It can be a whole number, like how many candies you have, or it can be a number with a decimal, like how much juice is left in your glass. You don't need to put them inside quotation marks; you can just write the numbers as they are.
JSON (JavaScript Object Notation) - JSON is flexible, and you can use different data types together to represent various kinds of information within the same JSON structure. This makes JSON a versatile format.
Examples of Custom Data endpoint
Examples of Custom Data endpoint
Path to all custom data returned in the data source for specific widget is widget.data.metadata.custom. Assuming widget is already pointing to the widget connected to this data source.
Data(string)
Data(number)
Data(JSON) This data type can have it's values accessed using dot or bracket notation. If I wanted to access the author in this JSON object I would do something like this. Assuming
widgetis already pointing to the widget connected to this data source.widget.data.metadata.custom.customJSON.metadata.authorwould give me back"Rebuy Engine"
What are keys and values?
Think of keys as the name or descriptor of the object, like someone's name, location, clothing type.
Think of values as the specific data that applies to the keys, like Samantha, New York City, baby clothes.
Each of these are written in the format "key" : "value" This is how it will be shown in Inspect on a browser (which you’ll need in order to use the metadata in a rule).
Here are some examples of how it could look or be used!
“first_name” : “Matthew”
“last_name” : “Smith”
“customer” : “true”
What if I need unique or custom metadata?
Data Sources has you covered! At the bottom of each Data Sources setup page is the option to add metadata.
In this field, you can type free-form to create any metadata that you need to be available. Here are a few examples to help you think through ways to use this functionality.
Example 1
You have a Data Source that is always used for a discount like “Buy this and save 20%”. Leverage the Metadata section to store the discount code.
Input in the Metadata Section:
“discount_code” : “BUYNOW20”
What it looks like to use it in a Data Source rule:
Buy right now and save 20% with code {{ metadata.custom.discount_code }} during checkout!
Example 2
You want to monitor URLs for influencer UTMs.
Input in the Metadata Section:
“influencer_name” : “James”
What it looks like to use it in a Data Source rule:
Here are some of {{ metadata.custom.influencer_name }}’s favorites!
Using Metadata in Data Sources: A Crash Course in JSON
Finding The Metadata Available To Use
Finding the available metadata that can be used in Data Sources is quite easy. You’ll need the Data Source ID to do this, so first we’ll go through how to find the Data Source ID and then we’ll go through the steps for finding available metadata.
Finding Data Source ID
Starting on the Data Source setup screen, look at the URL. The URL syntax will look like /data_sources/id/######/edit – the number in the URL is the Data Source ID. There is an example image below to show what it looks like.
Finding Metadata in the Browser
Step 1 - Start with the page containing the widget you’d like to use in the metadata in.
Step 2 - Next, access Inspect using one of the following ways
Option 1: Right-click any part of the page and choose Inspect.
Option 2: In the top menu bar, select View > Developer > Developer Tools.
Option 3: Use the shortcut control-shift-C on Windows or command-option-C on macOS.
Step 3 - Once in Inspect, click “Network” in the top navigation bar.
Step 4 - Type the Data Source ID in the “Filter” text field and refresh the page.
Step 5 - The Inspect log will have a new line item, like the image below. Click this line.
Step 6 - When you click on the new line in the log, a panel will appear to the right. Be sure “Preview” is selected in the top navigation bar in the panel (like the image below).
You should see the word “metadata” with an arrow next to it. Click the arrow and it will open all of the available metadata. In the example below, you’ll see all available metadata including custom metadata that was created using the custom metadata field in the Data Source.
Writing Syntax With Available Metadata For Use In Data Sources
So you’ve got the available metadata but how do you use it in Data Sources? We’ll discuss how to write the notations, but if you need more information, this resource is a great place to start.
To write this, we’ll use dot notation or standard object notation. This is relatively simple in the context of coding complexities, but for non-technical users it can feel more overwhelming. The simple analogy below attempts to help you connect the dot notation concepts to something we’re already familiar with, making it easier to understand.
Dot Notation Analogy
I want a soda. Where do I go to get it? If I'm in a typical house, it could be in the basement, the garage, the pantry, or maybe the fridge. Do I want a cold soda or a warm soda? If I want it cold, I'd probably get it from the fridge (maybe the garage depending on if it's winter).
So, in Python you can have many objects, and you would name them in this case, basement, garage, pantry, and fridge. If you asked for a soda, I still wouldn't know which object to grab it from. If you used the dot notation, get fridge.soda, I would know to look in the fridge and get the cold soda. (source)
Hopefully that analogy helps you think about how to write dot notation. So with that, let’s try to write out a couple of our own examples. Let’s say this is the metadata we’re looking at:
{
"first_name" : "Sammy",
"last_name" : "Shark",
"location" : "San Diego",
"Customer" : true
}
Let’s write out how we would use this metadata in the widget language settings for, say, a title:
Faves picked for you, {{ metadata.first_name }}!
In the above example, we see that the dot notation is directing us to the “metadata” object, and then the “first_name” object within “metadata”.
The Data Source Return looks like: Faves picked for you, Sammy!
{{ metadata.first_name.last_name }}, you’ll love these!
This example is similar to the first, it directs us to the “metadata” object, and then the “first_name” and “last_name” objects within “metadata”.
The Data Source Return looks like: Sammy Shark, you’ll love these!
Perfect Picks for {{ metadata.location }}!
In this example we’re directed to the “metadata” object and then the “location” object within “metadata”.
The Data Source Return looks like: Perfect Picks for San Diego!
Adding a Default Option for Language Settings
What happens if it’s a user that’s never purchased from you before therefore their name isn’t available in the metadata? No stress! There’s a simple solution. We can use what’s called a default option for this. A default option gives the Data Source something to fall back to if the necessary metadata isn’t available. For example, you have the Data Source setup to use the visitor’s first name. If the first name isn’t available, instead of it being an awkward blank space, you can have Friend or Bestie or something similar so it still looks complete and intentional.
For this section, we’re going to use the first example from above:
{{ metadata.first_name }}, you’ll love these!
The new Data Source language rule that includes the default would look like:
{{ metadata.first_name | default : ‘Bestie’ }}, you’ll love these!
This resource provides more in-depth info on using defaults in liquid.
Putting A Data Source Together
Tips for Getting Started:
Determine what conditions you want met to trigger the RETURN outcome, and then determine what you want the RETURN outcome to contain.
Some widget placements will be relatively fixed, possibly with only the language changing. Other widget placements may have a number of rules to allow for personalization across different audiences.
Placement and audience are equally important when building a Data Source.
If you’re targeting a specific audience, be sure to add a general audience rule to merchandise to everyone else.
Below are a few examples of different ways to set up Data Sources to support merchant needs/requests.
Example 1
Merchant Ask:
The merchant wants to have recommendations on their homepage.
First, let’s get a bit more info to help inform our next steps.
Do they want to tailor recommendations to audiences (customers/non-customers, geolocation-based, etc.)? If so, how do they want to segment audiences, and do they have the necessary info to do that (e.g., customer tags, etc.)
Do they want specific collections, products, etc. recommended? Or would they prefer to leverage AI-powered endpoints (e.g., AI endpoint, Similar Products, etc.)?
Do they want to use personalized language on the widget?
Now that we have the answers to these questions we can get started. For the sake of this example, we’ll put the answers we’re working with below.
Segment based on customer/non-customers.
Use Similar Products endpoint
Yes, fully branded language
This will require two rules to accommodate the customer and non-customer audience segments.
The first rule would look like the image below:
You’ll notice the metadata used in the title to pull the customer’s first name, the branded language for the ‘Add to Cart’ and ‘Added to Cart’ buttons. You’ll also see I have marked “Exit if Matched”. This is because we want the widget to stop pulling from the Data Source if this one is matched (i.e., if it is a customer, this is all we want returned).
The second rule would look like the image below:
In this rule, you notice we’ve selected “IF Anything” because this applies to non-customers and we want it to always return the products and language.
Example 2
Merchant Ask:
The merchant wants to adjust their homepage widget to work for general audiences, PPC traffic, and returning customers.
Info you need to get started:
Applicable PPC UTM parameters or URLs
Any UTM parameters/URLs for customer email/SMS marketing links
Rule 1 would like the image below:
You can put all of your applicable PPC UTM parameters or URLs in the right-hand field, separated by commas. You can add additional custom language as well. This rule is returning a collection we can assume is related to fall, Halloween, and spooky season and the PPC ads driving the traffic.
Rule 2 would look like the image below:
This rule is for return customers. You can see there are two elements in the IF portion of the rule. Like the PPC rule, you can list all of your applicable UTM parameters/URLs from customer marketing (emails & SMS). In this rule, we’re pulling products with tags ‘fall’, ‘spookyseason’, and ‘halloween’ and returning them with a custom title.
Rule 3 would look like the image below:
This is the ‘general audience’ rule. You’ll notice the additional custom language. This rule is last so that if a user matches either of the previous rules, the widget will reflect the most applicable experience. This is also why each of the previous rules have toggled on “Exit if Matched”. Additionally, the PPC ad rule is first in the event that returning customers see a PPC ad and click through the ad to your site.