Add Visitor Context Rule

You are here: Administrators Reference > Site Administration > Visitor Context > Visitor Context Rules > Add Visitor Context Rule

Add Visitor Context Rule

Access this dialog by selecting Add Rule from the Visitor Context Rules dialog. Use this dialog to set conditions for assigning visitors to predefined groups based on their browsing behavior.

When a visitor: Pick from the dropdown, as shown above. Additional options display, based on your selection:

Navigates to this page: Creates a rule triggered when a visitor navigates to a specific page you select within your site.
Navigates to a page in this subsite: Creates a rule triggered when a visitor navigates to the subsite you specify.
Navigates to a page in this subsite or below: Creates a rule triggered when a visitor navigates to any page within the subsite (including child subsites) you specify.
Arrives from a URL: Creates a rule triggered when a visitor comes to your site from the URL you specify. Click the Choose button to select a subsite URL, then select from the comparison dropdown shown below and enter all or part of a web address to match in the text field that displays.

Arrives from a search engine: Creates a rule triggered when a visitor comes to your site from a known search engine using the search term you specify. Select from the comparison dropdown, as shown above, and enter all or part of the search term to match in the text field that displays. (See About Search Engines for details.)
Searches within the site: Creates a rule triggered when a visitor searches within your site using the term you specify. Select from the comparison dropdown, as shown above, and enter all or part of a search term in the text field that displays.
Has a cookie set: Creates a rule triggered when a visitor's cookie set contains a specific value. Enter the name of the cookie to check, select from the comparison dropdown as shown above, and enter the cookie value you want to match.
Has a parameter in the URL: Creates a rule triggered when a visitor sets a specific URL value while navigating your site. Enter the name of the URL parameter to check, then pick from the comparison dropdown as shown above, and enter all or part of the value to match.
Submits this form: Creates a rule triggered when a visitor completes the form you select. Pick from a dropdown list of forms used at your site.
Submits this form with a specific field value: Creates a rule triggered when a visitor submits the form you select with the specific field value you specify. Pick from the dropdown list of forms used at your site, then select a form field, comparison operator, and a value to match.
Has an IP address: Creates a rule triggered when a visitor has the IP address you specify. Pick from the comparison dropdown, and enter all or part of a numeric IP address to match.
Is recognized by this custom module: Creates a rule triggered by custom evaluation criteria you specify in the fields shown below.

Before you can define a module here, you must first create a CFML file in a location that can be referenced as a cfmodule template path. This is typically in the /customcf directory for the site. See Creating a Custom Detection Module, below, for more information.

Once you've created a module, select Is recognized by this custom module from the When a visitor dropdown, then enter the path to your module in the Module Path field.

Note that this cfmodule path is relative to the root or to a defined mapping, not a disk path. Since there's already a mapping to the site root, in the customcf case the path would be:

/{mysitename}/customcf/my-module-name.cfm

If CommonSpot can't find the file using the path you provide, an alert displays on save.

The Module Parameter field enables you to reuse a module in multiple rules, with different behavior. Enter any value that suits your purposes, or leave it blank if your module doesn’t need it. The value you enter is passed unaltered to your module, as attributes.moduleParameter. Your code can then use that value in any way you require.

Note that this value is a simple text string, with no inherent meaning; it is not evaluated or processed in any way. It's up to your module to use it as you see fit.

Add them to this group: Displays predefined groups. Pick from the dropdown.

Keep them in it: Specify how long to keep visitors in their assigned group.

Permanently maintains members in this group with no expiration date.
For this session only maintains members in this group for the current browser session only.
Number of Days prompts you to enter the length of time to maintain members in this group.

Check this rule (for certain rule types only): Pick from the dropdown:

At session start checks the rule once at the beginning of each site session. Use this to limit lookups for rules that are not affected by subsequent browsing behavior.
At each request checks the rule for each HTTP request. Use this option for more granular tracking, for states that may change between requests.

Description: Optionally enter a description for the rule.

Creating a Custom Detection Module,

Custom detection modules let you write custom ColdFusion code to detect any conditions you require.

Your module must test for whether the conditions you've defined are met, and return a true or false boolean value indicating whether to trigger the rule. Do this by setting a variable in the caller scope whose name is passed into the module as attributes.returnVariable.

Code typically looks like this:

isTriggered = {the result of your custom logic};

caller[attributes.returnVariable] = isTriggered;

Note the last line carefully. Do not set attributes.returnVariable directly - it won't have the desired effect.

Important Note: Do not set other variables in the caller scope. Doing so can have unpredictable results that may affect your entire site.

If the module doesn't set the required variable, or sets it to a non-boolean value, the rule will not trigger.

CommonSpot also passes the value entered in the rule’s Module Parameter field into your module, as attributes.moduleParameter, This value has no inherent meaning, it’s solely for use by the rule’s logic. It lets you use the same module in multiple rules, while invoking different behavior in each one, based on this value.

The sample module provided demonstrates this capability. You’ll find it here:

/commonspot/samples/visitorcontextruledetectionmodule/

Important Note: Test modules carefully before deploying them to a production site. Module errors are logged, rather than displayed on the page, so review logs first if you're not getting the expected results. Defective rules that are checked on every request will produce errors on every CommonSpot page, potentially creating many log entries on a busy site.

Related Links

You can download PDF versions of the Content Contributor's, Administrator's, and Elements Reference documents from the support section of paperthin.com (requires login).

The following guides are available from the support site and are in the /docs/directory of your CommonSpot Server:

You can also download these other guides from the support section of paperthin.com (with login):

For technical support:

http://www.paperthin.com/support/