Personalization

Almost all of the liquid personalization capability os controlled by the permissions system. If the session permission has been allowed than the personalization discussed here will be usable. If the session permission has been denied, however, then the effects of personlization will effectively be nothing. Except for cookies - those are not subject to the personalization system.

Note that the session permission may be set to allow by default in the site settings - which may be desirable for some sites and undesirable for others thanks to European GDPR regulations.

Cookies

There are several liquid tags and objects designed specifically for referencing, setting, and unsetting cookies, these are the {{ cookies }} object, {% set_cookie %} tag, and {% unset_cookie %} tag.

Note that, while is is technically possible to use cookies for personalization even without user permission, it is not advisable to do so in most circumstances for three reasons:

  1. There is much more overhead related to cookies than there is to other methods of communication.
  2. Cookies may be added, removed, modified, and copied using client-side scripts.
  3. The personalization system was created for a reason and bypassing it could lead to unanticipated legal, technical, or other problems.

There are valid uses for cookies, however. Some of those reasons are:

  1. Saving information that is queryable and updatable using both template code and client-side javascript.
  2. Saving or accessing information between sites or domains that share a base domain name.
  3. Saving information for an extended period of time (longer than the session permission) or in order to make it accessible before/during/after a migration to or from another system.

Client

In liquid, the "client" object represents all of the interactions in a browser on a specific computer. Note that this may be conceptually identicial to a user or it may encompass multiple users sharing a browser (as in the case of a public or a shared computer).

Data may be saved to and retrieved from the client, which lasts for as long as the session permission is allowed. This means that if the session permission expires or is denied, the system will forget all data associated with the client.

To save data to the client use {% set_client %}. To query data saved on the client use the {{ client }} object. To remove data from the client use {% unset_client %}.

Note that saving data to the client is different than saving data to the session in that the data saved to a client will be remembered between sessions - for as long as the session permission lasts.

For performance and other reasons, you may only save a limited amount of information on the client. The number of properties that can be saved to the client may vary by site, and can be queried using {{ client.max_properties }}. If more properties are added than are allowed, then the oldest properties will automatically be unset.

Additionally, there are other useful properties that are accessible on the client - including the date of the first request, the number of pages viewed, the number of sessions that this client has created, and more.

Session

In liquid, the "session" object represents all of the client interactions within a limited amount of time. By default the session length is 60 minutes but the session length may be customized for a site in the site settings. Note that the session length is the amount of time between interactions before a new session is created - not the amount of time from the first interaction (so if the session length is 60 minutes and the user requests a new page every 59 minutes then their session will last indefinitely).

Although not strictly true it is generally assumed that while a client may encompass multiple users each session is only related to a single user. This is one of the key differences between the session and the client.

Data saved to and retrieved from the session will only last as long as the session remains active. To save data to the session use {% set_session %}. To query data saved on the session use the {{ session }} object. To remove data from the session use {% unset_session %}.

One other difference between the session and the client is that while the client can only save a limited number of properties, the session is not limited in the number of properties that may be saved to it (although we do not guarantee optimal performance if you start adding thousands of properties to sessions).

The session object also has some useful properties that the developer may utilize - including the session start time, the session end time (if the user does not make any further requests before then) the number of pages viewed, the number of unique pages viewed (ignores refreshes or going back to previously-viewed pages), the number of error pages viewed (eg: 404, 500, etc... errors), and more.

One final useful property of the session object worth noting here is the session history - which is a list of pages that the user has viewed during their current session. Using this property, it is possible to (for example) display links to the last 10 pages the user visited. One limitation of the session history is that it only stores the last 100 request the user has made - if a user has made more than 100 requests then you will only be able to query the 100 most recent requests.

{{page.visited}}

One final "trick" you can do with the personalization system is identify whether a user has visited a specific page during their current session using the Liquid Page property. This could be useful, for example, to identify whether the user is returning the current page or viewing it for the first time. Or to identify whether or not the user has previously visited the pricing page, a conversion page, or any other page on the same domain as the page they are currently viewing.

Developer Overview

Liquid Markup