Skip to documentation content

Session

On this page

    The session object and methods for session-scoped data.

    {{ session }}

    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.

    Properties
    Name Type Description
    object_type string Will always be session
    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.

    Example Check if this is the client's first sessionDetect the first time a client has a session (e.g. for onboarding or messaging).
    Liquid
    {%- if client.allowed and client.num_sessions == 1 -%}
	<p>This is your first session {% if session.first_page %}AND your first page!{% endif %}</p>
{%- endif -%}
    Example Use session properties (first_page, unique_pages, num_errors)Use session.first_page, session.unique_pages, and session.num_errors to tailor content based on session state.

    First page in session

    Liquid
    {%- if session.first_page -%}
	<p>This is your first pageload this session!</p>
{%- endif -%}

    Unique pages count

    Liquid
    {%- if session.unique_pages > 10 -%}
	<p>Need help finding what you're looking for? <a href="#">Try this!</a></p>
{%- endif -%}

    Session error count

    Liquid
    {%- if session.num_errors > 3 -%}
	<p>We appear to be having trouble meeting your needs. Please <a href="#">contact us directly</a> so that we can assist you and fix the trouble for future visitors, or continue browsing for what you need.</p>
{%- endif -%}
    Example Generate a list of visited pages. If the page response code isn't successful then return the response codeBuild a list of visited pages (e.g. from session) and return the response code when the page is not successful.
    Liquid
    <h4>Recent Requests</h4>
<ol>
{%- for pageview in session.history limit:10 -%}
	<li>
		<strong>{{ date | date: 'H:mm:ss' }}</strong> -
		{%- if pageview.code == 200 -%}
			<a href="{{pageview.url}}">
				{{-pageview.title-}}
			</a>
		{%- else -%}
			{{-pageview.code-}}
		{%- endif -%}
	</li>
{%- endfor -%}
</ol>
    Example List all custom properties on client, session, or userIterate over the client, session, or profile to list all custom properties. The same patterns works for each object type.

    Enumerate Client properties

    Liquid
    <h4>Client Properties:</h4>
<ul>
{%- for property in client -%}
	<li><strong>{{property}}</strong> = {{ client[property] }}</li>
{%- endfor -%}
</ul>

    This example outputs a list of all of the client properties for the current client. Using {% for property in client.properties %} would produce the same result.

    Enumerate Session properties

    Liquid
    <h4>Session Properties:</h4>
<ul>
{%- for property in session -%}
	<li><strong>{{property}}</strong> = {{ session[property] }}</li>
{%- endfor -%}
</ul>

    This example outputs a list of all of the session properties for the current session. Using {% for property in session.properties %} would produce the same result.

    Enumerate Profile attributes (mostly safe)

    Liquid
    <h4>Profile Attributes:</h4>
<ul>
{%- for property in profile -%}
	<li><strong>{{property}}</strong> = {{ profile[property] }}</li>
{%- endfor -%}
</ul>

    This example will work as long as there are no profile settings with the same names as the profile attributes. In that case, the profile setting would be output instead of the profile attribute. To avoid this, you can use profile.attributes[property] instead.

    Enumerate Profile attributes (safe)

    Liquid
    <h4>Profile Attributes:</h4>
<ul>
{%- for property in profile -%}
	<li><strong>{{property}}</strong> = {{ profile.attributes[property] }}</li>
{%- endfor -%}
</ul>

    Outputs a list of all of the profile settings for the current profile, and does not risk outputting profile settings instead of profile attributes.

    Example Reference session (or other) custom properties by name or bracket notationAccess custom properties on session (or client, user, site) using dot notation or bracket notation for names with special characters.
    Liquid
    {%- if session.is_valid -%}
	{%- if session.custom_property_name -%}
		<p>Custom Property: {{session.custom_property_name}}</p>
	{%- endif -%}
	{%- if session['custom_property_name_2'] -%}
		<p>Custom Property 2: {{session['custom_property_name_2']}}</p>
	{%- endif -%}
{%- endif -%}
    Example Working with specific object propertiesThere are multiple ways to reference properties on most objects. This example demonstrates several patterns for accessing properties on a few different object types.

    Reference properties on the user object

    Liquid
    {%- if user.is_valid -%}
	{%- if user.custom_property_name -%}
		<p>Custom Property: {{user.custom_property_name}}</p>
	{%- endif -%}
	{%- if user['custom_property_name_2'] -%}
		<p>Custom Property 2: {{user['custom_property_name_2']}}</p>
	{%- endif -%}
{%- endif -%}

    Reference properties on the client object

    Liquid
    {%- if client.is_valid -%}
	{%- if client.custom_property_name -%}
		<p>Custom Property: {{client.custom_property_name}}</p>
	{%- endif -%}
	{%- if client['custom_property_name_2'] -%}
		<p>Custom Property 2: {{client['custom_property_name_2']}}</p>
	{%- endif -%}
{%- endif -%}

    Reference properties on the session object

    Liquid
    {%- if session.is_valid -%}
	{%- if session.custom_property_name -%}
		<p>Custom Property: {{session.custom_property_name}}</p>
	{%- endif -%}
	{%- if session['custom_property_name_2'] -%}
		<p>Custom Property 2: {{session['custom_property_name_2']}}</p>
	{%- endif -%}
{%- endif -%}

    Reference custom fields on the site object

    Liquid
    {%- if site.custom_property_name -%}
	<p>Custom Property: {{site.custom_property_name}}</p>
{%- endif -%}
{%- if site['custom_property_name_2'] -%}
	<p>Custom Property 2: {{site['custom_property_name_2']}}</p>
{%- endif -%}

    {{ page_view }}

    An object containing information about a previous request in the current session

    Properties
    Name Type Description
    object_type string Will always be page_view
    is_valid boolean Will always be true
    url string The full requested url - including the scheme (http/https), the host (domain), and the path, but not including the query string or the hash
    guid string The unique identifier for the requested page, or empty if no page was found (ie: a 404 request)
    browser_title string The browser title of the requested page
    title string The entity title of the requested page
    date {{ time }} The request date
    code integer The HTTP response code. Some common response codes are 200 "OK", 404 "Not Found", and 500 "Internal Error"
    Example Generate a list of visited pages. If the page response code isn't successful then return the response codeBuild a list of visited pages (e.g. from session) and return the response code when the page is not successful.
    Liquid
    <h4>Recent Requests</h4>
<ol>
{%- for pageview in session.history limit:10 -%}
	<li>
		<strong>{{ date | date: 'H:mm:ss' }}</strong> -
		{%- if pageview.code == 200 -%}
			<a href="{{pageview.url}}">
				{{-pageview.title-}}
			</a>
		{%- else -%}
			{{-pageview.code-}}
		{%- endif -%}
	</li>
{%- endfor -%}
</ol>

    {% set_session %}

    Saves custom properties on the session. Note that this doesn't mean much unless the user (or the developer) has granted permission for sessions.

    {% set_session properties %}
    Parameters
    properties requireddictionary
    Key:value pairs with unique keys. May use the variable arguments syntax.
    Example How to use the set_session method

    Simple Use Case

    Liquid
    {%- if request.query_params.sortby -%}
	{%- set_session sortby:request.query_params.sortby -%}
{%- endif -%}
{%- var sortby = session.sortby | default: 'post_date' -%}
{%- blog_post_collection posts sort_by:sortby -%}

    This example uses the set_session method to save the "sortby" query parameter, so that future visits to the same page will utilize the same sorting even if it does not include the sortby parameter.

    Advanced Use Case

    Liquid
    {%- if submission.is_valid and submission.object_type = 'form_submission' -%}
	{%- var forms_submitted = session.submittedForms | to_int | plus: 1 -%}
	{%- var session_formname = form.name.value | prepend:'submitted_' -%}
	{%- set_session formSubmitted:"true" submittedForms:forms_submitted domain:submission.domain &session_formname:'true' -%}
{%- endif -%}

    If submission is a valid form submission object, this examples saves four session variables for later use: formSubmitted will be set to "true", submittedForms will be incremented by 1, domain will be set to the submission domain, and a dynamic session variable constructed from the name of the form prepended by "submitted" will also be set to "true".

    {% unset_session %}

    Removes custom properties from the session.

    {% unset_session properties? %}
    Parameters
    properties optionallist
    One or more values. May use the variable arguments syntax. The names of the properties to remove. If not included, all properties will be removed
    Example How to use the unset_session method

    Simple Use Case

    Liquid
    {%- if client_permissions.do_not_track -%}
	{%- unset_session -%}
{%- endif -%}

    If the browser sent the "Do Not Track" header, remove all session properties.

    Unset Multiple Session Properties

    Liquid
    {%- if request.query_params.ad_setting == "false" -%}
	{%- set_client_permission deny ads -%}
	{%- unset_session facebook_advertiser_id google_ads_id other_third_party_ids -%}
{%- endif -%}

    Checks if the "ad_setting=false" query parameter was sent with the request, and if it was, explicitly deny the "ads" client permission and unset the three specified session properties. Multiple properties can be unset at once by providing each property name as a separate argument to the unset_session method.

    Unset Session Properties Dynamically

    Liquid
    {%- var props = request.query_params.clearprops | split: ',' -%}
{%- for prop in props -%}
	{%- unset_session &prop -%}
{%- endfor -%}

    Checks if the "clearprops" query parameter was included in the request, and if it was, unset the specified session properties using the reference variable syntax.

    Unset Session Properties Dynamically (Alternate Syntax)

    Liquid
    {%- var props = request.query_params.clearprops | split: ',' | join: ' ' -%}
{%- if props is_valid -%}
	{%- unset_session *props -%}
{%- endif -%}

    Checks if the "clearprops" query parameter was included in the request, and if it was, converts the comma-delimited list of property names to a space-delimited list and unsets the session properties with those names using the expanded variable syntax.