There is a simple yet sophisticated permissions system accessible using liquid. This is the same permissions system that empowers personalization, and is available for utilization by template developers using a handful of liquid methods.
When discussing the permissions sytem, it is important to start with the fact that the permissions system utilizes a cookie to store the permissions that the user (or a developer) has allowed or denied along with some additional information. If a user with cookies disabled in their browser attempts to loadTo set client permissions a page, or if they clear their cookies before loading the page, the system will have no way of remembering which permissions they have allowed or denied.
Because the permissions are stored in a cookie, which by the nature of cookies is associated with a domain, if a sute has multiple domains each domain will by the nature of cookies have its own set of permissions - and therefore its own set of personalization information. If you are attempting to use the permissions system or personalization across multiple domains you will need to keep this in mind and compensate for it.
It is also important to note that, by default, if a user has not granted permissions the default state is denied. The only exception to this is the session permission, which may be set by default to "allow" in the site settings.
Finally, before digging deeper into the permissions system, keep in mind that it is possible for the template developer to utilize the permissions system in ways that were not intended or specifically designed by the Marketpath CMS team, and as such any use of the permissions system is the sole responsibility of the developer.
The permissions system is capable of saving values for a virtually unlimited number of permissions. Each stored permission has a name, whether the permission is allowed or denied, the date that the permission will expire, and an optional string value.
The expiration date and value do NOT depend on whether the permission was allowed or denied. In either case the permission will have an expiration date and may or may not have a value (depending on whether the developer assigned one or not).
Note that the permission expiration date indicates the date that the "allow" or "deny" will expire and should not be confused as the date that the permission will be denied. The difference is that a denied (or allowed) permission with an expiration date in 1 week will remain as it is until the expiration date and then will become "undefined".
An object containing information about permission allowed or denied in the permissions system and accessed using the {{ client_permissions }} object.
| Name | Type | Description |
|---|---|---|
| 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 |
{{ date }}
string
{{ time }}
{{ client_permissions }}
boolean
{{ session }}
All of the built-in liquid personalization tools rely on a special "session" permission. If session permission is allowed, the personalization tools will work. If session permission is denied, the personalization tools will not work.
If session permission is allowed, the value associated with the session is the client identifier. Changing the value of the session permission will have the undesirable consequence of resetting the client and session information without the benefits of resetting the client or denying session permission. Don't do it.
Do feel free to allow or deny sessions or change the expiration date ({% set_client_permission %}), or even reset the client ({% logout %}) as necessary.
To set client permissions, use the {% set_client_permission %} method. This includes both allowing and denying permissions as well as setting values and expiration dates.
To remove client permissions as though they had never been either allowed or denied, use the {% unset_client_permission %} method.
To check if a permission has been allowed or denied, or to check the value associated with a permission, use the {{ client_permissions }} object. (eg: {% if client_permissions.allow_thirdpartycookies %}{{ client_permissions.thirdpartycookies.value }}{% endif %}).
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.
| Name | Type | Description |
|---|---|---|
| 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.
Root Scope Reserved Variables
object
{{ client }}
{{ date }}
{{ request }}
{{ permission }}
string
{% unset_client %}
{{ cookies }}
{% unset_client_permission %}
{% set_client %}
{{ time }}
{% set_client_permission %}
empty
list
boolean
To grant or deny permissions using javascript, the developer will need to parse the "_mp_permissions" cookie. If there are multiple permissions allowed or denied, they are separated by the '|' character. Each permission is represented as a series of values separated by the '^' character. The first value is the permission name, the second value is '1' if the permission is allowed or '0' if the permission is denied, the third value is the date the permission is set to expire, and the final optional value is the value that is saved along with the permission.
An example permissions cookie value without any additional permissions might be something like this:
"session^1^9/25/2068 7:56:21 PM^44444444-4444-4444-4444-444444444444" Read: The user has allowed the "session" permission. Their allowance for sessions will expire in 50 years. The value of the session permission is 44444444-4444-4444-4444-444444444444 (their session identifier).
If the developer were to add an additional permission for third-party ads, the cookie value might look like this:
"session^1^9/25/2068 7:56:21 PM^44444444-4444-4444-4444-444444444444|thirdpartyads^0^9/25/2019 7:56:21 PM" In addition to the previous example, this signifies that the user has denied the "thirdpartyads" permission. Their denial for thirdpartyads will expire in 1 year.
Note that while a developer may modify the permissions cookie using javascript, if they set the cookie to an invalid format the effect could cause the system to forget all permissions just the same as if they had removed the session cookie altogether.