Script options

This page lists every option of the tag, so you can switch a feature on and know whether to do it in the dashboard or on the tag itself. Most sites never need to touch the tag after pasting it.

Attributes of the tag #

Each option is an attribute on the tag. The Script column says which of the two scripts acts on it: the light one at /js/script.js or the full one at /js/script.full.js. Add the tracker explains the two.

An option that is switched on or off is on when its value is true, written like data-campaigns="true". The attribute without a value counts as off.

In the dashboard or on the tag #

You can switch on most options without touching your site. Settings, Installation has a section called Tracking options with a switch for UTM campaigns, Hash page paths, Web Vitals, Auto conversions, Debug logging and Cross-domain. Each switch is the same as its attribute.

One setting has no attribute on purpose: Remember returning visitors, on Settings, Visitors. It sets a cookie, so only the dashboard can switch it on, never a tag. See returning visitors.

The rule for which one wins is short:

• On in the dashboard means on for every visitor, whatever the tag says.
• Off in the dashboard means the tag decides.

So an option is on when either place switches it on. To switch one off, it has to be off in both.

A change in the dashboard can take up to 5 minutes to reach your site, because a browser may keep the settings it fetched for that long.

Switching on Web Vitals, Cross-domain or Remember returning visitors changes which script your site needs. Settings, Installation then prints the tag for the full script, and you replace the old tag with it. Until you do, Web Vitals stays off on your site and nobody is remembered.

The explicit form of the tag #

The script fetches the dashboard settings while a page loads, and waits for them for at most 800 milliseconds before it counts the first page view. When the answer is slower than that, the first page view of that page goes out with the options of the tag only. For campaign capture that can mean a missed campaign.

If that matters to you, use the explicit form. Under Settings, Installation, the Snippet control has two choices, Minimal and Explicit. Explicit prints the same tag with one attribute for every option that is switched on, so the options are there from the first moment. It is written as plain HTML. On another platform, add the same attributes to that platform's tag.

The endpoint attribute #

data-endpoint replaces the address the script sends visits to. By default that is the server the script itself was loaded from, which is right for every normal installation. The dashboard never prints this attribute. It is set by hand.

It exists for a forwarding address you run yourself. Be careful with it: a visit that arrives through a relay looks to Clear Saga as if it came from the relay. Location, the count of visitors, IP exclusions and bot filtering would all judge the relay and not your visitor, so the numbers would be wrong.

This attribute is also not first-party collection, where the script and its requests are served from your own domain. That feature is not built. See what works today.

Cross-domain, revenue and the store cart #

The first of these attributes does less than its name suggests. The other two work with a connected Shopify store.

• data-cross-domain is read by the full script and then ignored. Following a visitor from one domain to another is not built, so a visitor who moves between two domains is counted once on each. See what works today.
• The Cross-domain switch in the dashboard does one thing: visits that arrive from the hostnames you list are not counted as a referral source.
• data-revenue makes the full script create a random id for each page load, keep it in memory and add it to every hit. It connects no store by itself. On a site with a connected Shopify store, an order that carries the id is credited to the visit behind it.
• data-shopify-cart writes that id into the cart of a Shopify theme, and the id is read from the order when it arrives. Its value is the cart's item count, which Liquid prints in the tag of the Connect dialog, or true. With a count of zero the script waits until a first item has been added, so a shopper who only browses gets no cart from it. With true it writes on every page load.

Attributes for your own elements #

A second group of attributes goes on elements of your pages, not on the tag.

Limits of values #

Values that are too long are shortened, not refused.

• An event name is cut at 64 characters.
• A UTM value is cut at 120 characters.
• A page path is stored with at most 512 characters.
• The share of a section that must be visible is between 0.1 and 1, and 0.5 when you set nothing. The delay is given in milliseconds and can be at most 10 seconds.
• Events sent before the first page view has gone out are held and sent after it, up to 50 of them.

Next: Custom events, Campaigns and UTM tags, Troubleshooting