Skip to documentation content

Client

On this page

    The client object and methods for client-scoped personalization data.

    {{ client }}

    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.

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

    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 How to use the set_client method to store custom data on the client

    Simple Use Case

    Liquid
    {%- if request.query_params.hide_popup_for_all_time -%}
	{%- set_client show_popup:"false" -%}
{%- endif -%}

    This example uses the set_client method to save the "show_popup" query parameter, so that future visits to the same page will not show the popup.

    Multiple Dynamic Values

    Liquid
    {%- if submission.is_valid -%}
	{%- var forms_submitted = client.submittedForms | to_int | plus: 1 -%}
	{%- var client_formname = form.name.value | prepend: 'submitted' -%}
	{%- set_client submittedForms:forms_submitted lastKnownEmail:submission.email &client_formname:'true' -%}
{%- endif -%}

    This example uses the set_client method to save multiple dynamic values on the client for later use. The submittedForms variable is incremented by 1, the lastKnownEmail variable is set to the submission email, and a dynamic variable constructed from the name of the form prepended by 'submitted' will also be set to 'true'.

    Example Count client sessions within a time window (e.g. one year)Count how many sessions the client has had within a time window (e.g. one year) for analytics or limits.
    Liquid
    {%- if client.allowed and client.num_sessions > 6 and client.VIP != "true" and client.first_request_date < request.date | add_years: -1 -%}
	<p>You have viewed this site {{ client.num_sessions }} since {{ client.first_request_date | date: 'MMMM yyyy' }}. During that time you have looked at {{ client.num_pages }} pages. We are happy that you have taken so much interest in us, and would like to invite you to <a href="#"> join our VIP club</a>!</p>
{%- endif -%}
    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 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 -%}

    {% set_client %}

    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.

    {% set_client properties %}
    Parameters
    properties requireddictionary
    Key:value pairs with unique keys. May use the variable arguments syntax.
    Example How to use the set_client method to store custom data on the client

    Simple Use Case

    Liquid
    {%- if request.query_params.hide_popup_for_all_time -%}
	{%- set_client show_popup:"false" -%}
{%- endif -%}

    This example uses the set_client method to save the "show_popup" query parameter, so that future visits to the same page will not show the popup.

    Multiple Dynamic Values

    Liquid
    {%- if submission.is_valid -%}
	{%- var forms_submitted = client.submittedForms | to_int | plus: 1 -%}
	{%- var client_formname = form.name.value | prepend: 'submitted' -%}
	{%- set_client submittedForms:forms_submitted lastKnownEmail:submission.email &client_formname:'true' -%}
{%- endif -%}

    This example uses the set_client method to save multiple dynamic values on the client for later use. The submittedForms variable is incremented by 1, the lastKnownEmail variable is set to the submission email, and a dynamic variable constructed from the name of the form prepended by 'submitted' will also be set to 'true'.

    {% unset_client %}

    Removes custom properties from the client.

    {% unset_client 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 Unset the client when Do Not Track is presentWhen the Do Not Track header is present, unset the client so no client-specific data is stored.
    Liquid
    {%- if client_permissions.do_not_track -%}
	{%- unset_client -%}
{%- endif -%}

    If the client has enabled "Do Not Track" functionality, use the unset_client method without any arguments to unset ALL client properties.

    Example How to use the unset_client method to clear client properties

    Simple Use Case

    Liquid
    {%- if request.query_params.reset_counters == "true" -%}
	{%- unset_client login_counter error_counter home_counter work_counter kitchen_counter -%}
{%- endif -%}

    Unsets the specified client properties if the "reset_counters" query parameter is present.

    Unset Client Properties Dynamically

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

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

    Unset Client Properties Dynamically (Alternate Syntax)

    Liquid
    {%- var props = request.query_params.clearprops | split: ',' | join: ' ' -%}
{%- if props is_valid -%}
	{%- unset_client *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 client properties with those names using the expanded variable syntax.