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.
There are several liquid methods and objects designed specifically for referencing, setting, and unsetting cookies, these are the {{ cookies }} object, {% set_cookie %} method, and {% unset_cookie %} method.
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:
There are valid uses for cookies, however. Some of those reasons are:
The cookies object is available on every page, and contains information regarding the cookies sent with the request. Note that this will typically only include cookies for the current or top-level domain on multi-domain sites.
| Name | Type | Description |
| is_valid | Boolean | Will always be true |
| keys | list | The list of cookie names on the current request, including cookies that may have been added or removed after the request started processing. |
| * | String | Individual cookies on this request may be accessed using {{ cookies.cookieName }} or {{ cookies['cookie-name'] }} syntax |
| output | String | JSON representation of the cookies object, similar to {{ cookies | inspect: 3, false }} |
The cookies object is copyable, and when copied using the {% copy_to_dictionary %} the keys will be the names of the cookies and the values will be the corresponding cookie objects.
You may also treat this object as a list containing all of the cookie names which may be iterated using a {% for %} loop.
Sets a cookie in the HTTP response.
There are a small number of reserved and forbidden cookie names, the most prominent being "_mp_permissions" - the name of the cookie used by Marketpath for handling permissions. You must use the {% set_client_permission %} and {% unset_client_permission %} methods to manage permissions instead of manipulating the permissions cookie directly.
"Unsets" one or more cookies. Because of how cookies work, this will actually ADD the cookie to the response with an expiration date in the past.
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.
The client object is available on every page, and contains information about the history of the browser used to access the site. Note that most of these properties are only meaningful if the user has allowed permission for sessions.
Additionally, client properties require cookies in order to work. Requests made without cookies (such as by bots or browsers with cookies disabled) or without permission for session will always behave like an initial page-load without existing client information.
The client object is one of a handful of simple mechanisms to enable personalization on your site. Used well, these can be powerful tools for developers and website owners.
| Name | Type | Description |
| is_valid | Boolean | Whether or not the user (or developer) has granted permission for a session |
| allowed | Boolean | Whether or not the user (or developer) has granted permission for a session |
| id | String | The unique identifier for the client browser. If the user does not have permission for a session this will be empty |
| user_agent | String | The user-agent string sent with the request. This is an alias of request.user_agent |
| permissions | client_permissions | The permissions that are set for the current client. The shortcut for this is {{ client_permissions }} |
| session | session | The current session for the client. The shortcut for this is simply {{ session }} |
| cookies | cookies | The cookies for the current client. This is an alias of {{ request.cookies }} and the shortcut for this is {{ cookies }} |
| first_request_date | time | The date that we received the first request from this client. Note that this is dependent on a number of outside factors, including the client's use (and/or clearing) of cookies and their allowance of sessions |
| num_requests | Integer | The total number of requests made by this client since the first_request_date |
| num_pages | Integer | The total number of successful page requests made by this client since the first_request_date |
| num_sessions | Integer | The total number of sessions created for this client since the first_request_date |
| properties | list | The full list of custom properties that are set for the current client. Note that this list only includes the keys, the values will have to be retrieved using the keys |
| max_properties | Integer | The maximum number of properties that may be stored on the client object. Adding new properties beyond that limit will result in the oldest properties being replaced by the newer properties. The default limit to the number of properties is currently 100. If you need more than 100 client properties contact Marketpath about raising your limit |
| * | String | Individual custom properties for the client may be accessed using {{ client.propertyName }} or {{ client['property-name'] }} syntax |
| output | String | JSON representation of the client object, similar to {{ client | inspect: 4, false }} |
The client object is copyable, and when copied using the {% copy_to_dictionary %} method, the keys will be the custom property names and the values will be the corresponding custom property values.
The client object may also be enumerated as a list of strings, which will be the names of the custom properties saved on the client. Note that this list will only include the property names when the enumeration started and adding or removing client properties during enumeration will not affect the property names for the current enumeration.
Saves custom properties on the client that will survive across multiple sessions until they are changed, unset, or the "session" permission expires. Note that this doesn't mean much unless the user (or the developer) has granted permission for sessions.
Removes custom properties from the client.
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.
The session object is available on every page, and contains information about the user's current session. Note that most of these properties are only meaningful if the user has allowed permission for sessions.
Additionally, sessions require cookies in order to work. Requests made without cookies (such as by bots or browsers with cookies disabled) or without permission for sessions will always behave like an initial page-load without existing session information.
The session object is one of a handful of simple mechanisms to enable personalization on your site. Used well, these can be powerful tools for developers and website owners.
| Name | Type | Description |
| is_valid | Boolean | Whether or not the user (or template developer) has granted permission for a session |
| allowed | Boolean | Whether or not the user (or template developer) has granted permission for a session |
| id | String | The unique identifier for the user's session. This will contain a value even if the user is not allowed to have a session, but the value will change on every page load |
| first_page | Boolean | True if this is the first page load in the user's current session. Note that this will always return true if the user does not have permission for a session since we will have no "memory" of prior page loads for the current session |
| start_date | time | The time that the current session started (equivalent to the time that the first request was made for this session) |
| end_date | time | The time that the current session will expire if no more requests are made. Note that sessions are extended by every request and so the end_date will also be different on every request |
| num_requests | Integer | The total number of requests for the current session, including requests resulting in errors |
| num_pages | Integer | The total number of successful page requests for the current session. This is different than num_requests in that it does not include any requests which resulted in an HTTP response code other than 200. This also assumes that the current request will return a 200 response code |
| unique_pages | Integer | The total number of unique pages requested in the current session. This number could be significantly lower than num_pages if the user requests several pages multiple times |
| num_errors | Integer | The total number of errors returned in the current session. This includes any request that returns something other than a 200 response code |
| properties | list | The full list of custom properties that have been set for the current session. Note that this list only includes the keys, the values will have to be retrieved using the keys |
| history | list | A list containing the last 100 page views as page_view objects for the current session |
| * | String | Individual custom properties for the session may be accessed using {{ session.propertyName }} or {{ session['property-name'] }} syntax |
| output | String | JSON representation of the session object, similar to calling {{ session | inspect: 3, false }} |
The session object is copyable, and when copied using the {% copy_to_dictionary %} method the keys will be the custom session property names and the values will be the corresponding custom property values.
You may also treat this object as a list containing all of the property names which may be iterated using a {% for %} loop.
Saves custom properties on the session. Note that this doesn't mean much unless the user (or the developer) has granted permission for sessions.
Removes custom properties from the session.
One additional "trick" you can do with the personalization system is identify whether a user has visited a specific page during their current session using the {{entity.visited}} 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.
While the "client" and "session" objects are both temporary and are both limited to the live site, the "profile" is a permanent object accessible both on the live site and in from the management interface.
At its most basic, a "profile" represents a set of credentials and other personalization information. The credentials are stored securely and are not accessible via liquid, but the other personalization information is.
Profiles may either be created in the management interface or registered from the live site. In any case, all changes to a profile are synced between the management interface and the live site so that both environments are always up-to-date.
Authentication and registration on live sites should be handled using the {% auth %} method. This method also handles numerous other profile-related functionality - such as locking or unlocking accounts, changing the id, etc...
Once a profile is logged in, it is available in liquid from the {% profile %} object.
Profiles have two types of unstructured data. Profile attributes are simple key-value pairs that may be set and unset using the {% set_profile %} and {% unset_profile %} methods. Custom profile settings are defined at the site level and may be set and unset using the {% set_profile_setting %} and {% unset_profile_setting %} methods.
While it is possible for the same profile to be logged in from different clients and sessions, it is not advisable to make a design decision which requires this due to the increated risk of data corruption caused by simultaneous updates.
To learn more about profiles, refer to the full profile course.
| Name | Type | Description |
| object_type | String | Will always be datastore_item |
| is_valid | Boolean | True if this references a published profile |
| guid | String | The unique identifier for this profile |
| value | String | Contains the same value as guid |
| id | String | The identifier for the profile. May or may not be the same as email, depending on the site settings |
| String | Email address for this profile | |
| force_password_reset | Boolean | If true, the user must reset their password at next login |
| is_active | Boolean | If true, the profile is active and can be used. If false, the profile must be activated before it may be used |
| date_activated | time | The date that this profile was activated |
| date_activation_code_expires | time | The date when the activation code will expire and no longer be valid |
| date_first_activated | time | The date of the first successful activation for this profile |
| is_locked | Boolean | If true, this profile is temporarily locked and may not be used to sign in until it is unlocked |
| date_locked_through | time | If this profile is locked, this will be set to the date that the profile will be automatically unlocked |
| date_last_logged_in | time | The date that this profile was last used to sign in to the website |
| is_blocked | Boolean | If true, this profile has been permanently blocked and may not be used to sign in |
| date_blocked | time | If this profile is blocked, this will be set to the date when the profile was blocked |
| attributes | dictionary | The custom attributes for this profile. Attributes may either be manually set in the Marketpath CMS UI or programmatically set from template markup |
| logged_in | Boolean | True if this profile is presently logged in on the current request |
| can_login | Boolean | True if the profile exists, is active, and is not blocked or locked |
| settings | object | An object containing all of the custom profile settings for this profile |
| field_id | String | The identifier for this field |
| label | String | The label for this field |
| output | String | The default output that the profile produces when output directly to the template. Currently simply outputs the email, but the default output may change at any time. Template developers should avoid using this and should handle the output of profiles themselves |
Saves custom properties on the profile that will be accessible whenever the current profile is logged in. The properties will be saved to the profile's attribute dictionary. Note that this is meaningless unless the user is logged in.
Removes custom properties from the attribute dictionary of the currently logged-in profile. Note that this is meaningless unless the user is logged in.
There is no option to unset all attributes from a profile - attributes must be removed by name.
Saves custom values to predefined profile settings that will be accessible whenever the current profile is logged in. Note that this is meaningless unless the user is logged in.
Profile settings may include validation, in which case all settings will be validated before being set and any validation error will prevent the setting(s) from being set. Validation errors may optionally be output to a variable.
Removes custom values from the profile settings for the currently logged-in profile. Note that this is meaningless unless the user is logged in.
For settings with a default value this will reset them to the default, and for all other settings this will set them to empty/unselected/false. Profile settings may be required and include validation, in which case all settings will be validated before being removed and any validation error will prevent any settings from being set. Validation errors may optionally be output to a variable.
There is no option to unset all settings on a profile - settings must be unset by name.