When the website widget shows, and how often

Triggers

• When the page loads, optionally after a wait.
• After time on the page, counted only while the page is in view.
• After scrolling down the page by a share of it.
• When the visitor is about to leave (desktop). Phones and tablets have no such signal; choose whether to fall back to time on the page or scroll depth, or not show.
• When your site reports an event, optionally after a wait. See Events below.
• When someone clicks an element, optionally after a wait. See Clicks below.
• Only when your site calls SurveyRock('show'). Your site decides, for example after a purchase.

Events

Your site can tell the widget what a visitor just did:

SurveyRock('track', 'checkout_completed');

Choose When your site reports an event as the trigger and enter the event’s name. The widget shows when your site tracks that event, after the wait if you set one. Event names are letters, digits and _, starting with a letter, up to 64 characters.

• An event tracked earlier on the same page view also counts. In a single-page app that includes earlier routes, so a widget limited to /thanks can show there after checkout_completed was tracked on /checkout.
• The widget’s other rules still apply: pages, devices, visitors, visitor details, share of visitors, how often, and the Website’s quiet period. To skip the quiet period, call SurveyRock('show') from your own code instead.
• track can be called before the widget has loaded; it’s held until then.
• The widget holds the events your site reports in memory for the page view. It stores something in the visitor’s browser only for events that a Visitor history rule names, and then only a count and the first and last dates, not any detail of the event.
• The event’s name is kept with the answer, so workflows can tell answers apart by the moment that prompted them ({{trigger.response.widgetEvent}}, below). Like rules, event names are readable in your site’s public widget config, so don’t put anything sensitive in one.

Clicks

Choose When someone clicks an element and enter a CSS selector for the button or link, such as #cancel-plan or .upgrade-button. No code on your site is needed.

• A click on anything inside the element counts too, and elements your site adds after the page loads are covered.
• The click still does what it always did: the widget never stops it, and the card appears after the click has been handled.
• A link or form that loads another page leaves no time for the card. For those, report an event on the next page with SurveyRock('track', …) and use the event trigger instead.
• The settings say at once if the selector isn’t one a browser can read. If no element on the page matches it, the widget simply doesn’t show.
• The widget’s other rules still apply, as for every trigger, and the selector is readable in your site’s public widget config like every rule.

Who sees it

• Pages: rules on the page’s path: is, starts with, contains, ends with, plus exceptions. With no rule, every page. Turn on Match the query string too to match ?plan=team. Single-page apps are followed as the address changes.
• Devices: all, desktop only, or phones and tablets only.
• Visitors: everyone, signed-in visitors only (those your site identifies), or visitors who are not signed in.
• Share of visitors: show it to a percentage. Each visitor is placed once, so the same person keeps the same answer.
• Visitor details (Growth plan and up): show it only to visitors whose details match. See below.
• Visitor history (Growth plan and up): show it only to visitors who have done something before, or who came from a campaign. See below.

Visitor details

On the Growth plan and up, a widget can be shown only to visitors whose traits match, the details your site passes with identify:

SurveyRock('identify', { userId: 'u_123', traits: { plan: 'pro', role: 'admin', seats: 12 } });

In the widget’s settings, under Visitor details, add up to 10 rules. A visitor must match every rule. Each rule names a trait and compares it:

Rule	Matches when the trait
is / is not	equals the value, or doesn’t. Is not also matches a visitor without the trait; add is set to require it
contains	contains the text
is one of	equals any of a list, such as pro, team
is set / is not set	has a value, or has none
is more than / is less than	is a number above or below the value

Text is compared without regard to upper and lower case. true and false match a trait sent as a boolean. Trait names are letters, digits and _, starting with a letter.

A visitor your site doesn’t identify, or identifies without traits, never matches a widget that has rules. If your site calls identify after the page has loaded, for example once a sign-in finishes, the widget is checked again then. The preview in the settings has a Preview as field: type details such as plan=pro, seats=12 to see whether that visitor would get the widget.

Two things to know before you write a rule:

• Rules are public. They’re part of your site’s widget config, which any visitor’s browser downloads and can read. Don’t put anything sensitive in a rule, such as a customer’s name, an email address or an internal account code you wouldn’t show on the page.
• Traits aren’t signed. Anyone can change them in their own browser, so a rule decides who is asked, never whose answer it is. Answers are linked to a person only by the signed identity.

If your plan changes to one without visitor details, a widget with rules stops showing until you upgrade or remove its rules.

Visitor history

On the Growth plan and up, a widget can be shown only to visitors whose history on this browser matches, under Visitor history in the widget’s settings. A visitor must match every rule.

What they’ve done before. Each rule names an event and asks:

Rule	Matches when the event
has happened / has never happened	has happened at least once, or never
at least / at most N times	has happened that many times or more, or that many or fewer
happened in the last / hasn’t happened in the last N days	last happened within that many days, or not

The events are the ones your site reports with SurveyRock('track', 'checkout_completed') (Events), plus two the widget counts itself:

• sr_pageview: pages viewed, including a single-page app’s route changes.
• sr_visit: visits. A new visit starts when a page is viewed 30 minutes or more after the last one. First visit is sr_visit at most 1 time; returning visitor is sr_visit at least 2 times.

Counts include the page being viewed.

Where the visit came from. Rules on the visit’s first page: the referring site (its host name only, such as www.google.com, so use contains google. to match any of Google’s; a link from the same host name as the page counts as none), or its utm_source, utm_medium or utm_campaign value, with is, is not, contains, is one of, is set and is not set. They’re kept for the rest of the visit.

Things to know:

• History is per browser. It’s kept in the visitor’s browser, so a visitor on a phone and a laptop has two histories, and clearing site data starts it again.
• Only what your rules name is counted. The widget counts the events your widgets’ rules name, and visits and the source only when a rule uses them. Nothing else your site tracks is stored. If you remove a rule, what it counted stops growing, and is deleted the next time the widget updates its record after 400 days without a change. See Cookies and consent.
• Rules are public, like every rule: they’re readable in your site’s widget config.
• Preview as takes history too: checkout_completed=2, utm_source=google beside any visitor details.
• If your plan changes to one without visitor history, a widget with these rules stops showing until you upgrade or remove them.

How often

• After someone answers: never ask again, or ask again after a number of days.
• After someone closes it without answering: never again, or after a number of days (30 to start with).
• Quiet period (on the Website): after any widget shows, the others wait this many days. 0 turns it off. A widget your site opens with SurveyRock('show') doesn’t wait; one shown by an event trigger does.

Counting an answer when the card is closed

With Count an answer when the visitor closes the card or leaves the page on (the default), a visitor who answers and then closes the card or leaves the page has a finished response, so your Response Submitted workflows run. The response is marked closed before the end, and workflows can test it ({{trigger.response.closedEarly}}).

Record the page the answer came from keeps the page’s path with each answer. Turn it off if the paths themselves are sensitive.

Workflow fields

Response Submitted workflows can use {{trigger.response.channel}}, {{trigger.response.widgetName}}, {{trigger.response.pageUrl}} (the page’s path, when the widget records pages), {{trigger.response.widgetEvent}} (the event that opened it, when the trigger is an event) and {{trigger.response.closedEarly}}. Three templates start from them: a Zendesk ticket for a low help-centre rating, a HubSpot task for a detractor in your product, and a Slack post for every comment from your pricing page.

Setting up for the first time? Start with Add the website widget to your site.