Go to Qubit

Opentag documentation

Filters

Filters in Opentag are a way of setting up intelligent rules to determine when a tag should or should not fire.

Overview

By default when when adding a new script to a container, there will be an include all filter for the new script to make sure the your script will execute on all the pages with the container.

Tip: Users can add, remove and change the priority of filters. The system will go through the list of filters in order (from top to bottom).

When adding a filter, choose one of the two filter types: include or exclude.

  • include filters will make sure that if the pattern matches, the script will be run on the page
  • exclude filters will make sure that if the pattern matches, the script will not run on the page.

URL-based filters

URL-based filters allow you to fire tags based upon the URL of the page being viewed. These require a pattern type. The options are:

  • all
  • containing
  • matches exactly
  • starts with
  • ends with
  • regular expression

Every pattern type, except for all, require a pattern to be entered.

  • all covers every url that the container is on
  • containing covers every url that pattern is a part of (case-insensitive)
  • matches exactly covers the url that only matches exactly the pattern.
  • starts with covers urls that only start with the specified pattern. for this pattern type, make sure to have the full url and inlcude http:// or https://
  • ends with covers urls that only end with the specified pattern. this pattern will also match any parameters at the end of the url.
  • regular expression allows the users to enter any custom regular expression in the pattern
Hint: Most of the time, the only filter you’ll need are containing filters.

Example:

Let’s assume you have the following site structure:

  • yourdomain.com/index.html
  • yourdomain.com/category
  • yourdomain.com/category/shoes/index.html
  • yourdomain.com/category/shoes/shoe1.html
  • yourdomain.com/category/shoes/shoe2.html
  • yourdomain.com/category/shoes/shoe3.html
  • yourdomain.com/category/shirts/index.html
  • yourdomain.com/category/shirts/shirt1.html
  • yourdomain.com/category/shirts/shirt2.html
  • yourdomain.com/category/shirts/shirt3.html
  • yourdomain.com/cart/
  • yourdomain.com/cart/basket
  • yourdomain.com/cart/payment/
  • yourdomain.com/cart/payment/billing
  • yourdomain.com/cart/payment/shipping
  • yourdomain.com/cart/payment/payment
  • yourdomain.com/cart/payment/confirmation

To run a script only on all pages except shopping cart pages the filter setting would be:

  • include all
  • exclude containing /cart/

To run a script only on all pages but shopping cart pages, while additionally allowing scripts to run on the payment confirmation screen, the filter setting would be:

  • include all
  • exclude containing /cart/
  • include containing /cart/payment/confirmation

To run a script only on payment pages, but not on any other page, the filter setting would be:

  • include containing /payment/

To run a script only on shoe product pages but not the category index, the filter setting would be:

  • include regular expression /category/shoes/shoe.*.html

Session-based filters

Session-based filters allow you to run a script in your container based on the users behavior during their current or previous visits to you site. The filters are no longer only dependent on the current page URL, but can depend on previous pages and actions a user may have taken during their journey on a given site.

Examples

Below are some example use cases for triggering tags based on session variable values:

Visit based:

  • Only trigger a script after 5th page view
  • Only trigger a script after 7 seconds on the page
  • Trigger a script only on a given page if the user came to a page from a specific previous page
  • Trigger a script only if the user has been to a specific page on the site through out their journey
  • Trigger a script only if this is a user’s third or more visit to the site
  • Trigger a script only if the user’s landing page is a specific url or parameter

Referrer based:

  • Trigger a script on a given page or on all pages only if the user came from Google paid search
  • Trigger a script on a given page or on all pages only if the user came from a partner site
  • Trigger a script on the a specific (e.g. conversion) page only if the user’s first session’s referrer was a specific site
  • Trigger a script on the specific page only if the user’s last session’s referrer was a specific site
  • Trigger a script on the specific page only if the user’s any session referrer was a specific site
  • Support for multi click attribution: remember all the referrers among a potential list and trigger the relevant script on the conversion page.
De-duping? Referrer based filters are used for de-duplication. Visit our de-duplication page to find out more.

Cookie based:

  • Trigger a script only if the user has a specific cookie set
  • Trigger a script only if the user has a specific cookie set to a specific value or range

In a given filter, you can set up logic that can use multiple variables and and/or logic to build the condition a script should fire upon satisfying.

To build a session-based filter, while editing a script, click on Edit button for the script in the Advanced Features > Filters section.

List of all types of session variables

Using the following variables one can build logic to trigger or not trigger a script in a container:

Numeric variables:

  • Time on current page (in milliseconds)
  • Visit number
  • Has numeric cookie
  • Page view count (in the current session)
  • Time on site (in milliseconds, since the beginning of the current session)

String variables:

  • Has cookie
  • Any session referrer (any of first session referrer and the last four)
  • First session referrer
  • Last session referrer
  • Landing page URL of the current session
  • Current page referrer
  • Current page URL

Numeric operators:

For any variable that has a numeric value following are the allowed operators and operations:

  • Greater than
  • Greater than or equal
  • Less than
  • Less than or equal
  • Equal
  • Not Equal

String operators:

For any variable that has a string value following are the allowed operators and operations:

  • With exact value
  • Is not
  • Containing
  • Does not contain
  • Starts with
  • Does not start with
  • End with
  • Does not end with
  • Matching regular expression

For any string variable, you can also have another condition that controls the life span of the action. For example, if the any session referrer within 5 days matches the rule, the filter may activate the script.

Building advanced logic with session-based filters

Using the AND and OR logic blocks you can build filter logic in your tags. Here are a few points you should keep in mind:

  • Only the first rule can be Time on Page
  • If the first rule is time on page the following ones in the same group can only be grouped by AND

Practical uses for session-based filters

Universal Variable – Often you may want to run a tag based on a Universal Variable parameter. We’ve put together an article in our support center detailing how to do this.

CPA de-duplication – To ensure you are not double paying for a sale via a conversion implement rules to ensure that only the correct channels get rewarded for the sale. Visit our de-duplication page to find out more..

IP configuration for local market targeting – If you want to run specific marketing campaigns in certain markets you can filter based on market geography

AJAX friendly – Allows you to fire scripts based on JavaScript events for example on ajax-based checkout pages. A useful way of approaching this is to use of our UV listener to fire tags when a Universal Variable parameter changes.

Support multiple attribution models – by configuring your session variables you can make sure that affiliate tags only fire based on first, last or any referrer of the user session.

Custom JavaScript

If the logic within URL and session-based filters isn’t enough, you can click the “customise” button in the filter to enable advanced mode.

opentag-customise

You’ll then be shown two code boxes: the custom script, and the custom starter.

Custom script

IF the tag should fire.

Custom Script is where the rest of the logic gets executed when the event is attached to the page and is executed. If the logic in this section returns true the filter passes, if it returns false, it does not pass and this script will not be executed on the page.

For example, if you want to fire a tag when the global JavaScript variable myVar exists:

function (session) {
  if (window.myVar) {
    return true;
  } else {
    return false;
  }
}
Note: The custom script will pass whenever anything “truthy” is returned.

Custom starter

WHEN the tag should fire.

Custom Starter is where you attach the event to the page. This is can be used with a setTimeout function or for code that attaches to your page events (on click etc). It is passed two variables: a callback and the session variable. Only when the callback function is executed, will the script be fired. For example, if you wanted to fire the tag after two seconds:

function (session, cb) {
  setTimeout(cb, 2000);
}

You can also fire a tag multiple times by passing the true argument to the callback:

function (session, cb) {
  $(document).ready(function () {
    $("a.my-link").on("click", function () {
      cb(true);
    });
  });
}

Note: If you’re looking to fire tags on click, please see this article in our support center.

The session variable

The session variable can be accessed in both the custom script and custom starter, and can be used for implementing advanced session-based filters. This is the same data that regular session-based filters use.

Note: The session variable is a cookie with an age of 365 days. As a result, the data is persistent across sessions.

getCookie(“cookieName”)

Type: function

Get any cookie by name.

sessionCount

Type: Number (integer)

The number of times the customer has visited your site. On their first visit, will be 1.

sessionStartTime

Type: Number (integer)

The JavaScript timestamp of when the customer started their current visit.

pageViews

Type: Number (integer)

The total number of page views the customer has had in their lifetime (the current device and browser) on your website. On their first visit and first session, this will be 1.

pageStartTime

Type: Number (integer)

The JavaScript timestamp of when the customer viewed the current page.

referrer

Type: Array

referrer[0] is the first referrer. The last object in the array is the last referrer. Has a maximum size of 5 to limit the size of the cookie. As a result, some referrer data can be lost if the customer has been referred from multiple sources.

referrer[].url

Type: String

The URL of the referrer. If not referred, has value direct.

referrer[].landing

Type: String

The URL on your site that a user landed on when the new referrer was set.

referrer[].time

Type: Number (integer)

sessionLandingPage

Type: String

The page where the user landed on the most recent session. Note that this is the same as the landing parameter in the last referrer object.

Example session variable:

{
  "getCookie": function () { ... },
  "sessionCount": 59,
  "sessionStartTime": 1388754411416,
  "pageStartTime": 1388754411416,
  "pageViews": 161,
  "sessionLandingPage": "http://demo.qubitproducts.com/demo/index.html",
  "referrer": [
    {
      "url": "direct",
      "landing": "http://demo.qubitproducts.com/demo/index.html",
      "time": 1382438335648
    },
    {
      "url": "http://www.hotukdeals.com/vouchers/highstreetshoppr.co.uk",
      "landing": "http://demo.qubitproducts.com/demo/index.html",
      "time": 1382445400008
    }
  ]
}

Was this helpful?