The displayConditions key controls how, when, and for how long any single module is displayed/hidden. All options can be combined with one another for maximum control. Each module requires its own set of displayConditions. By default all modules will leverage showOnInit. Once other display conditions are set, they will override this default.

var module = new pathfora.Message({
  displayConditions: {
    showDelay: 10,
    impressions: {
      session: 2
    }
  }
});

pathfora.initializeWidgets([module]);

Some display conditions may require that cookies be enabled to work properly.

showOnInit

Determines if the rendered module is displayed as soon as it is initialized or waits for another event.

showOnInit boolean
Value Behavior
true default module will be displayed as soon as it has been loaded
false module will be added to DOM but not displayed until another trigger instructs it to
// example: loads immediately after initializing the module

displayConditions: {
  showOnInit: true
}

showDelay

Adds a delay, in seconds, that must be completed before module is loaded.

showDelay int
Value Behavior
0 default using 0 disables the showDelay property and will show immediately
0 – ∞ module will be displayed after waiting x seconds after initialization
// example: loads after a 10 second delay

displayConditions: {
  showDelay: 10
}

showOnMissingFields

By default, a module will be hidden if tried to include an entity field that the user does not have. showOnMissingFields can override this beahvior.

showOnMissingFields int
Value Behavior
false default module will be hidden if the field does not exist and no fallback is defined
true module will show regardless of the missing field value, and the template will be replaced by an empty string.
displayConditions: {
  showOnMissingFields: true
}

hideAfter

Adds a countdown, in seconds, that must hides module on expiration.

hideAfter int
Value Behavior
0 default using 0 disables the showDelay property and will not be hidden
0 – ∞ module will hidden from screen after x seconds have passed
// example: hide module after 10 seconds

displayConditions: {
  hideAfter: 10
}

displayWhenElementVisible

Triggers the module when a specific DOM element enters the viewport.

Key Type Behavior
displayWhenElementVisible string selector for the element which when visible will trigger the module
// example: show module when the .footer is visible

displayConditions: {
  displayWhenElementVisible: '.footer'
}

scrollPercentageToDisplay

Triggers the modal after a percentage of the page scroll has been performed.

scrollPercentageToDisplay int
Value Behavior
0 default using 0 disables the property and will show immediately
0 – 100 module will hidden until x percent of total scroll has been performed
// example: show module when the 50 percent of the page scroll has been completed

displayConditions: {
  scrollPercentageToDisplay: 50
}

pageVisits

Triggers the module when the user visits the page a certain amount of times. The total number of page visits is saved in cookie PathforaPageView to compare against this value.

pageVisits int
Value Behavior
0 default using 0 disables the property and will show on all visits
0 – ∞ module will show only when the user has visited more than x times
// example: show module after they have visited at least 3 times

displayConditions: {
  pageVisits: 3
}

date

Display the module in a specified interval of time.

date object
Key Type Behavior
start_at string optional valid ISO 8601 formatted date for date to start showing module
end_at string optional valid ISO 8601 formatted date for date to stop showing module
// example: show module starting February 12, 2017

displayConditions: {
  date: {
    start_at: '2017-02-12T11:00:00.000Z'
  }
}
// example: hide module starting February 12, 2017

displayConditions: {
  date: {
    end_at: '2017-02-12T11:00:00.000Z'
  }
}
// example: show module between February 12, 2017 and March 12, 2017

displayConditions: {
  date: {
    start_at: '2017-02-12T11:00:00.000Z',
    end_at: '2017-03-12T11:00:00.000Z'
  }
}

impressions

Hide the module after a certain number of impressions or global impressions across all widgets. The current number of impressions is saved in a cookie PathforaImpressions_[module id] to compare against this value.

impressions object
Key Type Behavior
widget object optional contains settings specific to the widget itself
global object optional contains settings specific to the widget but based upon all consumable or consumed widgets
widget / global object
Key Type Behavior
session int optional count of how many session-based impressions before showing the module
total int optional (not supported for global) count of how many total (multisession) impressions before showing the module
// example: hide module after the second impression in the same session

displayConditions: {
  impressions: {
    widget: {
      session: 2
    }
  }
}
// example: hide module after five total impressions

displayConditions: {
  impressions: {
    widget: {
      total: 5
    }
  }
}
// example: hide the module after the second impression in the same session
// or if it has been seen five times ever

displayConditions: {
  impressions: {
    widget: {
      session: 2,
      total: 5
    }
  }
}

hideAfterAction

Hide the module after a particular action has been taken (closed, cancel, or confirm). The current number of impressions is saved in a cookie Pathfora[action]_[module id] to compare against this value.

hideAfterAction object
Key Type Behavior
closed object optional settings for hiding the module based on the close action
cancel object optional settings for hiding the module based on the cancel button click action
confirm object optional settings for hiding the module based on the confirm button action
closed / confirm / cancel object
Key Type Behavior
hideCount int optional count of times module has been closed manually by user before hiding the module
duration int optional how long the module should be hidden in seconds
// example: hide module for 6 minutes after 5th close

displayConditions: {
  hideAfterAction: {
    closed: {
      hideCount: 5,
      duration: 60 * 6
    }
  }
}
// example: hide module permanently after confirmation has been clicked

displayConditions: {
  hideAfterAction: {
    confirm: {
      hideCount: 1
    }
  }
}
// example: hide module for 1 week after cancel has been clicked

displayConditions: {
  hideAfterAction: {
    cancel: {
      hideCount: 1,
      duration: 60 * 60 * 24 * 7
    }
  }
}
// example: all of the above

displayConditions: {
  hideAfterAction: {
    cancel: {
      hideCount: 1,
      duration: 60 * 60 * 24 * 7
    },
    confirm: {
      hideCount: 1
    },
    closed: {
      hideCount: 5,
      duration: 60 * 6
    }
  }
}

showOnExitIntent

Only display the module when the user is about to leave the page.

showOnExitIntent boolean
Value Behavior
true module will be displayed as soon as the user is about to leave the page.
false default module will be displayed either on init or when manually invoked, depending on showOnInit
// example: loads immediately after initializing the module

displayConditions: {
  showOnExitIntent: true
}

Exit Intent Modal - Live Preview

manualTrigger

Control when a module is triggered with javascript. Use this displayCondition in conjunction with the triggerWidgets.

manualTrigger boolean
Value Behavior
true module will be displayed when triggerWidgets method is called.
false default module will be displayed either on init or when manually invoked, depending on showOnInit
// example: this script alone will not display the module

var module = new pathfora.Message({
  id: 'trigger-message',
  layout: 'modal',
  msg: 'You clicked the button!',
  displayConditions: {
    manualTrigger: true
  }
});

pathfora.initializeWidgets([module]);
<!-- module will display when the user clicks this button -->
<input type="submit" value="Click to display module" onclick="pathfora.triggerWidgets(['trigger-message'])">

urlContains

Only display the module on pages that match the url conditions defined.

object in urlContains array
Key Type Behavior
match string optional name of the matching rule (see below)
value string value to match the current page url against
exclude boolean optional if true, the module will not display on any page that matches this rule
match string
Value Type Behavior
simple string default fuzzy match that removes the URL protocol and query string before matching
exact string the url must match what is typed exactly: protocol, query params, etc.
string string sub-string match against the url
regex string evaluates regex against the url
// example: simple match

displayConditions: {
  urlContains: [
    {
      match: 'simple',
      value: 'www.getlytics.com'
    }
  ]
}

// Matches:
// https://www.getlytics.com
// http://www.getlytics.com
// http://www.getlytics.com?ad_campaign=1ed387faed

// Doesn't Match:
// http://www.getlytics.com/blog
// https://activate.getlytics.com
// example: exact match

displayConditions: {
  urlContains: [
    {
      match: 'exact',
      value: 'https://www.getlytics.com/resources?id=a763efd12c'
    }
  ]
}

// Matches:
// https://www.getlytics.com/resources?id=a763efd12c

// Doesn't Match:
// http://www.getlytics.com/resources?id=a763efd12c
// https://getlytics.com/resources?id=a763efd12c
// https://www.getlytics.com/resources?id=a763efd12c&something=that-will-404
// example: string match

displayConditions: {
  urlContains: [
    {
      match: 'string',
      value: '/blog/'
    }
  ]
}

// Matches:
// http://www.getlytics.com/blog/
// http://getlytics.com/blog/some-post-in-the-past
// https://www.getlytics.com/blog/tag/customer-data-platform?referrer=thegreatgoogle

// Doesn't Match:
// https://www.getlytics.com/
// http://getlytics.com/careers
// example: regex match

displayConditions: {
  urlContains: [
    {
      match: 'regex',
      value: '\/integrations\/.+?\?.*?ref=our_partner'
    }
  ]
}

// Matches:
// http://www.getlytics.com/integrations/campaignmonitor?ref=our_partner
// http://www.getlytics.com/integrations/campaignmonitor?session=125929&ref=our_partner
// https://www.getlytics.com/blog/tag/customer-data-platform?referrer=thegreatgoogle

// Doesn't Match:
// http://www.getlytics.com/integrations/campaignmonitor?ref=some_stranger
// http://www.getlytics.com/integrations?ref=our_partner
// http://www.getlytics.com/blog/adroll?session=125929&ref=our_partner

metaConatins

Only display the module on pages that have meta tags that match the conditions defined.

Note that metaContains does not support partial matches as urlContains does. Treat metaContains values as having the exact match rule.

object in metaContains array
Key Type Behavior
property string optional property attribute of the meta tag
content string optional value of the content attribute of the meta tag to match against
name string optional name attribute of the meta tag
// example match based on og:type

displayConditions: {
  metaContains: [
    {
      property: 'og:type',
      content: 'website'
    }
  ]
}

// Matches:
// <meta property="og:type" content="website" />