Skip to documentation content

Client Permissions

On this page

    The client permissions object and related methods.

    {{ client_permissions }}

    The client_permissions object is available on every page, and contains information about whether or not the user (or developer) has granted permission to use specific features. By default the only feature controlled by this is sessions, but the permission system may be "extended" arbitrarily by the developer to control additional features. The permissions feature requires cookies in order to work. Requests made without cookies (such as by bots or browsers with cookies disabled) will always behave like an initial page-load without existing permission information.

    Properties
    Name Type Description
    object_type string Will always be client_permissions
    is_valid boolean Will always be true
    cookiename string The name of the cookie used for storing permissions. Will always be "_mp_permissions"
    has_cookie boolean True if the permissions cookie was already set prior to this request. False on the first page load, after the client has cleared their cookies, or on all requests from browsers with cookies disabled
    cookie_expires {{ time }} The date and time that the permissions cookie is set to expire
    min_permission_expiration_date {{ time }} The next date and time that one of the permissions is set to expire. Note that this does not distinguish between "allow" and "deny" permissions and will ignore permissions with no expiration date set. If there are no permissions with expiration dates set this property will be empty
    max_permission_expiration_date {{ time }} The latest date and time that one of the permissions is set to expire. Note that this does not distinguish between "allow" and "deny" permissions and will ignore permissions with no expiration date set. If there are no permissions with expiration dates set this property will be empty
    do_not_track boolean Whether or not the browser sent the "DNT" header in the request
    keys list The list of permissions (both allowed and denied) stored in the client_permissions object
    * {{ permission }} Specific permissions may be accessed using {{ client_permissions.permissionname }} or {{ client_permissions['permission-name'] }}
    allow_* boolean Shortcut to check if a specified permission is both defined AND allowed in the permission system.
    output string JSON representation of the client_permissions object, similar to calling {{ client_permissions | inspect: 3, false }}

    The client_permissions object is copyable, and when copied using the {% copy_to_dictionary %} method the keys will be the permission names and the values will be the corresponding permission objects. The client_permissions object may also be enumerated using the {% for %} method, which will loop through all of the related permission objects when the for loop is started. Permissions that are added during enumeration will NOT be included, permissions that are removed during enumeration WILL be included, and permissions that are modified during enumeration will be included along with their updated properties.

    Example Client PermissionsShows how a developer can use different client permission flags control messaging and how to check for expiring permissions.
    Liquid
    {%- if client_permissions.do_not_track -%}
    <p>You have requested that we do not track your information. Consequently we will return a simple generic response even though it may not provide the best experience.</p>
{%- else -%}
    {%- if client_permissions.allow_all -%}
        {%- comment %}In this example "all" refers to a custom permission defined by the developer{% endcomment -%}
        <p>You have granted us unlimited power! You should have the best possible experience.</p>
        {%- if client_permissions.all.expires < request.date | add_weeks: 2 -%}
            <p>Your permissions will expire on {{ client_permissions.all.expires | date: 'MMM dd' }}. If you want to continue receiving the best possible experience, <a href="#">follow these instructions</a>.</p>
        {%- endif -%}
    {%- else -%}
        {%- if client_permissions.allow_generous -%}
            <p>You have allowed "generous" permissions. While not the best, this still allows for a good experience.</p>
        {%- elsif client_permissions.allow_limited -%}
            <p>You have allowed "limited" permissions. This is only slightly better than a completely anonymous experience.</p>
        {%- else -%}
            <p>You have not allowed any permissions. Your experience will be fully generic.</p>
        {%- endif -%}
        <p>To customize your options and improve your experience, <a href="#">click here</a>.</p>
    {%- endif -%}
{%- endif -%}

    Performs a series of simple checks to determine the client's permission level and adjust the messaging accordingly. Starts with checking for the "do_not_track" flag, which is set by browsers that have enabled "Do Not Track" functionality, then checks for a series of custom permissions defined by the developer in order from most to least permissive. If the client has enabled the custom "all" permission, it also checks to see when it will expire. This example displays a simple message describing the client's permission level, but it could easily be adapted to set a variable, include a child template, or perform another action instead.

    Example Client Permissions allow adsDemonstrates how the client_permissions object could be used to control the display of ads on a page.
    Liquid
    {%- if client_permissions.allow_advertisements -%}
    {%- assign allowed_ads = client_permissions.advertisements.value | default: "all" | split: "&" -%}
    <ul>
    {%- for ad in allowed_ads -%}
        <li>{{ad | replace: '-' " " | replace: '_' " " | capitalize }} advertisements are allowed until {{client_permissions.advertisements.expires | date: 'MMMM dd, yyyy, H:mm'}}.</li>
    {%- endfor -%}
    </ul>
{%- endif -%}

    Use a custom "advertisements" permission to control the display of ads on a page. In this example, the value of the advertisements permission is expected to be a delimited list of keys separated by ampersands. For each key, output a human-readable version of the key and the expiration date of the permission. Alternatively, the keys could be used to dynamically display a random advertistement from the specific category or for some other purpose.

    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_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.

    {{ permission }}

    An object containing information about permission allowed or denied in the permissions system and accessed using the {{ client_permissions }} object.

    Properties
    Name Type Description
    object_type string Will always be permission
    is_valid boolean Will always be true
    value string The value stored with the permission. May be empty
    name string The name of the permission (eg: "session", or any custom value set by the developer)
    allowed boolean True if the permission is set to "allow". False if the permission is set to "deny"
    expires {{ time }} The date that the permission (either allowed or denied) is set to expire
    Example Client Permissions allow adsDemonstrates how the client_permissions object could be used to control the display of ads on a page.
    Liquid
    {%- if client_permissions.allow_advertisements -%}
    {%- assign allowed_ads = client_permissions.advertisements.value | default: "all" | split: "&" -%}
    <ul>
    {%- for ad in allowed_ads -%}
        <li>{{ad | replace: '-' " " | replace: '_' " " | capitalize }} advertisements are allowed until {{client_permissions.advertisements.expires | date: 'MMMM dd, yyyy, H:mm'}}.</li>
    {%- endfor -%}
    </ul>
{%- endif -%}

    Use a custom "advertisements" permission to control the display of ads on a page. In this example, the value of the advertisements permission is expected to be a delimited list of keys separated by ampersands. For each key, output a human-readable version of the key and the expiration date of the permission. Alternatively, the keys could be used to dynamically display a random advertistement from the specific category or for some other purpose.

    {% set_client_permission %}

    Defines whether the client has granted or deined permission for a particular feature (eg: sessions). The only permission defined by default is the session permission (configurable in the site properties). However, the template developer may use this mechanism for their own purposes as well. The permissions defined by this method will be stored in the permissions cookie, which may be read and/or modified by client-side javascript.

    {% set_client_permission [allow|deny|1|0]? permission_name renew? [with:value]? [always|for duration|until date]? %}
    Parameters
    mode optionalliteral
    Must be one of allow, deny, 1 (alias for allow), or 0 (alias for deny). Defaults to allow
    permission_name requiredstring
    The name of the permission to allow or deny. Defaults to the session permission
    renew optionalliteral
    If this permission has already been allowed or denied, the original permission expiration date will only be updated if &quot;renew&quot; is specified
    value optionalstring
    The value to store along with the specified permission
    always optionalbool
    Specifies that the permission should not expire, which is a shortcut for a 50-year expiration date
    for optionalliteral
    Specify in combination with the duration. If specified, the always and until clauses are not allowed
    duration optionalstring
    How long until the permission should expire, specified as "num [minutes|hours|days|weeks|months|years]" where num is a positive integer. May either be specified directly in the method or read from a variable
    until optionalliteral
    Specify in combination with the date. If specified, the always and for clauses are not allowed
    date optionaldate
    The date that the permission will expire. If it is in the past, the permission will automatically be denied as expired

    If none of the expiration clauses are specified, the permission expiration date will default to 1 year in the future. Remember that the expiration date specified here is for the permission, not for the effects of the permission. In the case of sessions, the expiration date defines how long the user has granted permission to have a session, regardless of the number or duration of sessions during that timeframe. If the permission has a value, the value will be stored along with the permission regardless of whether the permission has been allowed or denied. Permissions will never expire in the middle of a session - if a permission would be set to expire in the middle of a session, it will automatically be extended until the end of the session to prevent odd mid-session permission change bugs.

    Example How to use the set_client_permission method to allow or deny permissionsAllow or deny client permissions (e.g. session, ads) and set expiration or store values.
    Liquid
    {%- if request.query_params.allow_session == "true" -%}
	{%- var allow_length = "1 year" -%}
	{%- if request.query_params.allow_months -%}
		{%- set allow_length = request.query_params.allow_months | append: " months" -%}
	{%- endif -%}
	{%- set_client_permission allow session renew for allow_length -%}
{%- elsif request.query_params.deny_session == "true" -%}
	{%- set_client_permission deny renew -%}
	--equivalent to {% set_client_permission deny session renew for 1 year -%}
{%- endif -%}

    Allow Session Permission

    Liquid
    {%- if request.query_params.allow_session == "true" -%}
	{%- set_client_permission allow renew -%}
{%- endif -%}

    Allow the session permission for the default timeframe (1 year). If the session has already been allowed, the renew argument will cause it to be updated with the new timeframe. Equivalent to {% set_client_permission allow session renew for 1 year %}

    Simple Use Case

    Liquid
    {%- if request.query_params.allow_ads == "true" -%}
	{%- set_client_permission allow 'ads' renew always -%}
{%- endif -%}

    If the "allow_ads" query parameter is set to true, update the client permission to allow the "ads" permission which will never expire.

    Store A Permission Value

    Liquid
    {%- if request.query_params.allowed_ids is_valid -%}
	{%- set_client_permission allow 'partner_ids' with:request.query_params.allowed_ids -%}
{%- endif -%}
{%- if request.query_params.denied_ids is_valid -%}
	{%- set_client_permission deny 'denied_ids' with:request.query_params.denied_ids -%}
{%- endif -%}

    If the "allowed_ids" query parameter was passed in the request, store it's value in the allowed partner_ids permission. If the "denied_ids" query parameter was passed in the request, store it's value in the denied denied_ids permission. For both of these permissions, the expiration date will use the default timeframe (1 year) if the permission was not previously specified, and will remain unchanged if the permission was previously specified.

    Dynamically Set the Length of a Permission

    Liquid
    {%- if request.query_params.allow_session == "true" -%}
	{%- var allow_length = "1 year" -%}
	{%- if request.query_params.allow_months is_int true and request.query_params.allow_months > 0 -%}
		{%- set allow_length = request.query_params.allow_months | append: " months" -%}
	{%- endif -%}
	{%- set_client_permission allow session renew for allow_length -%}
{%- elsif request.query_params.deny_session == "true" -%}
	{%- set_client_permission deny renew -%}
{%- endif -%}

    If the "allow_session" query parameter is set to true, sets or renews the session permission. The session permission is allowed for a default of 1 year, but if the "allow_months" query parmeter is a positive number then it will be used to set the length of the session permission. If the "deny_session" query parameter is set to true, updates the session permission to be denied for the default timeframe (1 year).

    Set a Permission to Expire at a Specific Time

    Liquid
    {%- if event.end_date is_valid -%}
	{%- set_client_permission allow event.name.value until:event.end_date -%}
{%- endif -%}

    If event.end_date is a valid date, set a permission with the name of the event to allow until the specified date. The permission will expire at event.end_date.

    Set Permissions Dynamically

    Liquid
    {%- if request.query_params.allow_networks -%}
	{%- var networks = request.query_params.allow_networks | split: ',' -%}
	{%- for network in networks -%}
		{%- if network is_valid -%}
			{%- set_client_permission allow network -%}
		{%- endif -%}
	{%- endfor -%}
{%- endif -%}

    If the "allow_networks" query parameter was passed in the request, set a permission for each network in the list. This works because "network" is a variable containin a string. If it were not a variable on the current scope, then the permission would be named "network" instead.

    Prefer strings for static permission names

    Liquid
    {% set_client_permission allow partner_ids with:request.query_params.allowed_ids %}

    This code will sometimes work by setting a permission with the name "partner_ids", but if there is also a variable with that name then the value of the variable will be used instead, resulting in unexpected behavior. This can be easily avoided by placing the permission name in single or double quotes.

    Example How to use the unset_client_permission method

    Simple Use Case

    Liquid
    {%- if request.query_params.user_confirmation != permissions.external_user.value -%}
	{%- unset_client_permission external_user -%}
	<p>Some error message about failed confirmation and please try again</p>
{%- endif -%}

    If the "user_confirmation" query parameter is not equal to the value of the "external_user" permission, unset the "external_user" permission and display an error message.

    Unset Permissions Dynamically

    Liquid
    {%- var unset_parties = request.query_params.third_party_unknowns | split: ',' -%}
{%- for party in unset_parties -%}
	{%- unset_client_permission party -%}
{%- endfor -%}

    Loop through a dynamic list of permissions and unset each one.

    Unset Permissions Dynamically Using the Expanded Variable Syntax

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

    If the "unset_permissions" query parameter was included in the request, convert the comma-delimited list of permission names to a space-delimited list and unset the permissions with those names using the expanded variable syntax.

    Safely Unset Client Permissions

    Liquid
    {%- if unsafely_nuke_the_permissions -%}
	{%- unset_client_permission -%}
{%- elsif safely_nuke_the_permissions -%}
	{%- var oldSession = session.allowed -%}
	{%- unset_client_permission -%}
	{%- if oldSession -%}
		{%- set_client_permission allow session -%}
	{%- endif -%}
{%- endif -%}

    Check whether all permissions should be unset or only most by safely unsetting all but the specified values. If not all permission should be unset, then store the values of permissions that should be preserved in separate variables, unset all permissions, and restore the permissions that should be preserved.

    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.

    {% unset_client_permission %}

    Removes the specified permissions from the permissions cookie. Note that this is not the same as denying permission since there will be no record that permission was either granted or denied after the permission has been unset.

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

    Simple Use Case

    Liquid
    {%- if request.query_params.user_confirmation != permissions.external_user.value -%}
	{%- unset_client_permission external_user -%}
	<p>Some error message about failed confirmation and please try again</p>
{%- endif -%}

    If the "user_confirmation" query parameter is not equal to the value of the "external_user" permission, unset the "external_user" permission and display an error message.

    Unset Permissions Dynamically

    Liquid
    {%- var unset_parties = request.query_params.third_party_unknowns | split: ',' -%}
{%- for party in unset_parties -%}
	{%- unset_client_permission party -%}
{%- endfor -%}

    Loop through a dynamic list of permissions and unset each one.

    Unset Permissions Dynamically Using the Expanded Variable Syntax

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

    If the "unset_permissions" query parameter was included in the request, convert the comma-delimited list of permission names to a space-delimited list and unset the permissions with those names using the expanded variable syntax.

    Safely Unset Client Permissions

    Liquid
    {%- if unsafely_nuke_the_permissions -%}
	{%- unset_client_permission -%}
{%- elsif safely_nuke_the_permissions -%}
	{%- var oldSession = session.allowed -%}
	{%- unset_client_permission -%}
	{%- if oldSession -%}
		{%- set_client_permission allow session -%}
	{%- endif -%}
{%- endif -%}

    Check whether all permissions should be unset or only most by safely unsetting all but the specified values. If not all permission should be unset, then store the values of permissions that should be preserved in separate variables, unset all permissions, and restore the permissions that should be preserved.