Frequency capping

Frequency capping decides how often a visitor sees a given tour, tooltip, or announcement. All three are created with Show once per visitor turned on. Turn it off per item in the dashboard's visibility settings and it shows on every visit to a page that matches its targeting. Surveys work differently: they re-ask after a configurable number of days (90 by default) instead of a show-once toggle.

Show once

With Show once per visitor on (the default for a new tour, tooltip, or announcement):

  • The first time the visitor reaches a page that matches the targeting rules, the item shows.
  • Once it counts as seen, they won't see it again.

What counts as seen depends on the surface:

  • Tour — completed or dismissed. "Dismiss" includes closing the tour mid-way, navigating away, and closing the tab while a tour is open.
  • Tooltip — dismissed with its close button. Opening the popover alone does not count, so a tooltip stays available until the visitor explicitly closes it.
  • Announcement — dismissed, or its call-to-action completed.

How it's enforced

When the StepsKit embed fetches active tours, tooltips, and announcements, the server filters out "show once" items that this visitor has already seen. That filter is keyed on the visitor's id, which is why visitor identification matters.

The check is fail-open: if the events lookup fails (rare), the item is returned and shown rather than withheld. We'd rather show something twice than swallow a real impression.

Anonymous visitors

If data-user-id (or id in setUserAttributes) isn't set, the visitor is anonymous. "Show once" then falls back to a session-scoped check using browser storage:

  • Works within the current browser session.
  • Resets when the visitor clears site data or uses another device or browser.

For most marketing-site use cases this is fine. For an authenticated product, always pass id.

Identifying the user before the first fetch

The cleanest pattern is to render data-user-id directly into the script tag server-side, so the very first tour fetch carries the correct visitor:

<script
  src="https://cdn.stepskit.com/stepskit.latest.js"
  data-api-key="YOUR_API_KEY"
  data-user-id="user_123"
  async
></script>

If you can only identify client-side, use setUserAttributes({ id }, { autoRefresh: true }). StepsKit's init/refresh coordination guarantees a "show once" tour won't play against a stale anonymous fetch — see Visitor identification.