Visitors

Each time a user visits your web site, dotCMS identifies the individual user as a unique Visitor based on their session information. Information about each Visitor is collected and maintained in the Visitor object, where you can access it to get information about the Visitor and customize content delivery based on that information. Please select a section below for more information.

Note: The Visitor object is only available for users accessing dotCMS from the front-end. The Visitor object is removed from the session when a user logs into the dotCMS backend.

Information Collected

The following information is identified and maintained for each Visitor:

• Location Information:
  • Locale
  • Selected Language
  • Latitude and Longitude
  • Geolocation Information (city, continent, country, timezone, etc.)
• Assigned Persona
• Accrued (Collected) Tags
• User Agent and Device Information (enabling you to serve different content for different platforms and screen sizes)
• Referrer
• Number of Times Visited

Rules may be created with Conditions that trigger based on this information, and all of this information may be retrieved from the Visitor Object using Velocity code.

Assigned Persona

As the user browses different areas of your site, dotCMS uses your defined Rules to assign the Visitor to a specific Persona.

Once a Visitor has been assigned to a Persona, dotCMS begins displaying the site to the user in different ways, depending on how your Rules and Personas are defined. For example, your site may be configured to display competitive feature comparisons to prospective clients, but for existing clients your site may display messages encouraging users to upgrade to your newest product instead.

A Visitor can only be assigned one Persona at a time. However, depending on your defined Rules, a Visitor's Persona may be reassigned as the user's browsing behavior changes, allowing you to more clearly identify the user's needs or recognize changes in the user's status or interests.

Accrued (Collected) Tags

As each Visitor browses your site, dotCMS accrues (collects) tags to identify the content the user is most interested in. These collected tags:

• Are used when pulling personalized content.
• Can be used in Rules that assign Personas.
• Can be used to trigger Conditions in Rules that perform other Actions.
• May be accessed via Velocity code to help you select appropriate content for each user.

The same tags may be added to the accrued tags more than once. For example, if a user visits the same page 3 times, the tags from that page will be added to the accrued tags 3 times. For more information, please see Tag Counts, below.

Tags are added to the accrued tags from the following sources:

• Assigned Personas
• Visited pages
• Rules using the Add Tags to Visitor action
• Velocity code

Notes:

• Tags from assigned Personas and visited pages are added to the accrued tags automatically.
• But Tags are only accrued from Rules or Velocity code if you explicitly configure your Rules or code to add the tags.
• The Visitor's accrued tags can be read, added to, and removed using Velocity code. For more information please see Accessing the Visitor Object using Velocity, below.

Tag Counts

The accrued tags keeps track of how many times a tag has been added by appending a count to each tag in the list. Each tag in the accrued tags field is followed by a colon and the count of how many times that tag has been added to the visitor. For example, if a user visits a page with the tags “finance, retirement” 3 times, then the accrued tags field will contain the tags “finance:3, retirement:3”.

Accrued Tags from Assigned Personas

Each time a Visitor is assigned a new Persona based on your defined Rules, the tags for that Persona are assigned to the Visitor. If the same Visitor is later assigned to a different Persona based on your Rules, the tags for both Personas will be collected for the same Visitor, so your site can still identify and serve content based on both the user's current and previous interests and browsing habits.

Note that the Persona tags are only added to the Visitor's accrued tags when the Persona is changed. If a Rule triggers that assigns a Persona to a Visitor which is already assigned the same Persona, the tags from that Persona will not be added to the accrued tags again. However if the Visitor's assigned Persona is changed from one Persona (Persona 1) to a different Persona (Persona 2), and then later assigned back to the original Persona (Persona 1), the tags from the original Persona will be added to the accrued tags twice. Since the assigned Persona was changed to Persona 1 twice, the tags for Persona 1 will be added to the accrued tags both times.

Example:

As an example, consider the following changes to the Persona. The Assigned Persona column shows each time the Set Persona Action is triggered, and the Tags Added column shows whether or not the Persona tags will be added to the accrued tags field in each case.

Visited Pages

When a user visits any page on your site, the tags on that page are automatically added to the Visitor's accrued tags. Specifically, the following shows which tags are and are not accrued:

Note: This is the default behavior. To change which tags are automatically accrued from pages and content, please see Controlling Accrued Tags, below.

Since accrued tags keep a count of the number of times each tag is added, the more times a user visits a particular page or visits pages which display a particular contentlet, the higher the weight will be given to content with the same tags when you pull and display content using a personalized content pull.

Controlling Accrued Tags

By default dotCMS automatically accrues tags from all Pages a user visits and all contentlets displayed on those pages. However you may control which tags dotCMS automatically accrues to the Visitor object by modifying the following properties in the dotmarketing-config.properties file.

Note: It is strongly recommended that all changes to the dotmarketing-config.properties file be made through a properties file extension.

#When true accrues the tags found in the associated Contentlet to the URL Map
ACCRUE_TAGS_IN_URLMAPS=true
#When true accrues the tags found in the visited HTMLPage Contentlet
ACCRUE_TAGS_IN_PAGES=true
#When true accrues the tags found on each of the contentlets living inside the visited HTMLPage Contentlet
ACCRUE_TAGS_IN_CONTENTS_ON_PAGE=false

Note that you can not configure dotCMS to automatically add the tags of contentlets displayed via a content pull to the Visitor's accrued tags. However if the user clicks on a particular piece of content displayed in a content pull to display the content on it's own URL mapped page, then the tags from that content will be added to the accrued tags. This ensures that only content explicitly selected by the user affects the user's personalization experience.

Accessing the Visitor Object using Velocity

You can read and modify elements of the Visitor object using Velocity code. Please see the following sections for more information:

• Retrieving the Visitor Object
• Manually Adding Tags to the Visitor Object
• Manually Removing Tags from the Visitor Object
• Clearing All Tags from the Visitor Object

Retrieving the Visitor Object

Visitor object properties can be retrieved via Velocity using the following variables:

Notes:

• When you login to the dotCMS back-end, no visitor object is assigned until you display a page in the page editor.
  • The visitor object will only be filled in at that time.
  • Since the page is opened from the back-end, the $visitor.referrer property will show a reference to the dotCMS back-end.
• The $visitor.referrer property shows the initial referring page (the page that sent the user to your site the first time).
  • The $visitor.referrer property will only be filled if the user accessed your page through an external link.
  • If the user typed your site address directly into the browser, the $visitor.referrer property will be null.

Visitor Persona Tags

Since the Visitor object provides access to the currently assigned Persona, you may also access the Persona tag fields of the currently assigned Persona through the Visitor object:

Access to these fields may be useful when creating customized personalized content pulls.

Geolocation Object

The $visitor.geo object contains geolocation information for the visitor, including information about the country, city, time zone, and other geographical information. This information is derived from the user's IP address.

Note: The geolocation information object is not included when the $visitor object is displayed as a whole. To access the geolocation information object it must be referenced separately (e.g. $visitor.geo).

For more information on information available from the $visitor.geo object, please see the Visitor Geolocation documentation.

Manually Adding Tags to the Visitor Object

You may add tags to the Visitor object in Velocity using the $visitor.addTag() method.

#foreach($tag in $URLMapContent.tags)
    $visitor.addTag($tag)
#end

Manually Removing Tags from the Visitor Object

You may remove tags from the Visitor object in Velocity using the $visitor.removeTag() method.

The following example removes all tags from the accrued tags with a frequency count less than 3:

#foreach($tag in $visitor.accruedTags)
    #set($parsedTag, $tag.split(":"))
    #set($tagName, $parsedTag[0])
    #set($tagCount = 0)
    $tagCount.parseInt($parsedTag[1])
    #if($tagCount < 3)
        $visitor.removeTag($tagName)
    #end
#end

Clearing All Tags to the Visitor Object

You may clear all acrued tags on the Visitor object in Velocity by using the $visitor.clearTags() method. All acrued tags will be removed from the Visitor object, allowing a reset of the acrued tag history.

$visitor.clearTags()