Parsers (data parsing engine)
A parser reads a value that already exists on your site, such as a JavaScript variable, a cookie, a local storage key, a URL parameter or the text of an element, and copies it into Personizely on every page load. The value goes either to the visitor's profile (a default or custom field) or to website data for the current session. Parsers let you target and personalize on data your site already has, without writing code to call the JavaScript API.
Available on: all platforms, on every plan.
How it works
- On every page load, before targets are evaluated, each parser reads its source.
- If it finds a value, it writes it to the destination: a visitor field, saved to the profile, or a website data key, kept for the browser session.
- If the value isn't there yet, the parser keeps checking for a few seconds, so values your site sets shortly after load are still picked up. Values set much later, for example after a click, aren't, unless the source is local storage.
- Local storage parsers keep listening. When your site changes that key later during the page view, in this tab or another tab, the new value is written again.
- Values are used by the Visitor fields and Data filters, by dynamic text and, for visitor fields, by your integrations.
Create a parser
- Go to Settings → Parsers and click Add a parser.
- Choose the Source and enter the Source key.
- Choose the Destination: Visitor or Data.
- For Visitor, pick the Field. For Data, enter the Data key.
- Save. The parser runs from the next page load.
Option | What it does | Values / default |
|---|---|---|
Source | Where the value is read from | Local storage (default), URL Query String, Cookie, Variable, CSS Selector |
Source key | What to read: the key, parameter, cookie name, variable path or selector | Text, up to 64 characters |
Destination | Where the value is written | Data (default), Visitor |
Data key | The website data key to set (Data destination) | Text, up to 64 characters. Use letters, digits and underscores so {data.key} works |
Field | The default or custom visitor field to set (Visitor destination) | Any visitor field or custom field |
Sources
Source | Source key | Reads | Example key |
|---|---|---|---|
Local storage | The local storage key | The stored string, exactly as saved. Keeps listening for changes | loyalty_tier |
URL Query String | The parameter name | The parameter in the current page's URL only. Missing on pages without it | ref |
Cookie | The cookie name | The raw cookie value, not URL-decoded. Cookies marked HttpOnly can't be read | customer_segment |
Variable | A path from window, using dots | The value of a global JavaScript variable | Shopify.currency.active, customerData.tier |
CSS Selector | A CSS selector | The visible text of the first matching element | .loyalty-badge, #account-email |
Notes on each source:
- Local storage values are strings. If your site stores JSON, the whole JSON string is copied, not one property of it. Use a Variable parser to read a property of an object.
- URL Query String isn't remembered across pages, unlike the Query String filter. Combine it with destination Visitor if you want to keep the value.
- CSS Selector reads the text as displayed. Elements that are hidden (display: none) have no visible text and return an empty value. Invalid selectors return nothing.
- Variable reads the value when the parser runs, and keeps checking for a few seconds if it isn't set yet.
Destinations
Destination | Where the value goes | How long it lasts | Use it for |
|---|---|---|---|
Visitor | The visitor's profile, in the field you pick | Across visits and devices the visitor is identified on | Data about the person: email, customer tier, account type |
Data | Website data under the key you set | The current browser session | Data about the current context: cart value from a custom cart, page type, A/B flags from your backend |
Writing Email or Phone with a parser identifies the visitor. If another profile has the same email or phone, the two profiles are merged.
Behavior details and limitations
- Values found late reach targets later. A value found on the first read is used by targets on that page. One found a few seconds later, or a later local storage change, is used when a widget trigger fires and on the next page.
- A visitor field is only updated when the value changes. Re-reading the same value on every page doesn't send it again.
- Values aren't cleared. If the source disappears (the cookie is deleted, the element isn't on a page), the field or data key keeps its last value.
- Single-page apps. Parsers run on each full page load. They aren't re-run on page changes inside a single-page app, except local storage parsers, which react to changes.
- Types. Values are copied as they are. Cookie, local storage, query string and selector values are text, so numeric comparisons in the Data filter extract the first number from the text (for example, $1,299.99 is read as 1299.99).
- Custom field types must match. A value that doesn't fit the custom field's type is rejected: non-numeric text for a number field, anything but YYYY-MM-DD for a date field, and any text for a checkbox field (checkboxes need a real true or false, which only a Variable parser can provide).
Examples
- Shopify currency in dynamic text: Source Variable, key Shopify.currency.active, Destination Data, key currency. Show "Prices in {data.currency or 'your currency'}".
- Loyalty tier from your app: Source Local storage, key loyalty_tier, Destination Visitor, Field "Loyalty tier" (a custom field). Target gold members with Visitor fields "Loyalty tier is gold".
- Logged-in email from the page: Source CSS Selector, key #account-email, Destination Visitor, Field Email. Visitors are identified on any page that shows their email.
Troubleshooting
- Parser does nothing → the source key is wrong (keys, cookie names and selectors are case-sensitive), or the value appears long after page load (for example only after a visitor action).
- Value has %20 or %40 in it → it came from a cookie, which is read without URL decoding. Store a decoded value in the cookie or read it with a Variable parser.
- Data filter doesn't match on the first page → the value was set after page load, so it was found after targets were evaluated. Use the target in a widget (checked when the trigger fires) or rely on it from the next page.