Triggers and frequency

Three things decide whether and when an item shows: where it matches, what starts it, and how often it may run.

Page patterns

Each item has pathPatterns. Origin matching ignores the port. A pattern is matched against the path of the page:

Pattern	Matches
/claims/:id	:name matches exactly one path segment
/claims/*	* matches anything
/search?type=open	Query parameters listed must be present. * is allowed as a value
#/inbox	A pattern starting with # matches the hash

The environments on the app list the origins where content may run. The content script is only registered for origins you have granted.

Triggers

Trigger	Starts when
page-load	The page matches. Optional delayMs
element-visible	A locator target becomes visible
element-click	A locator target is clicked
launcher	A launcher runs start-content for it
resource-center	The user opens it from the resource centre
url-param	The URL has the named parameter
idle	The user has been idle for a number of seconds
manual	Only started by an action or by Preview

The player arms page-load, element-visible, element-click, url-param and idle automatically when the page matches. launcher, resource-center and manual start only from a user action or from Preview. Checks warns about common mistakes:

Code	Meaning
trigger-needs-user	A launcher or resource-center trigger on a process only starts on a user action, so the frequency has no effect until then
idle-too-short	An idle trigger under 3 seconds fires while the user is still reading
url-param-empty	The url-param trigger has no name and never fires
trigger-unsupported	An announcement with a launcher trigger

Frequency

Value	Behaviour
once	Runs while the user has no progress record for it; any record (completed, dismissed, abandoned) ends it
once-per-version	Runs until a record exists at the current published version; publishing a new version runs it again
every-visit	Runs on a page load, at most once per page session
until-completed	Runs on each visit until it is completed at the current version
manual-only	Never starts by itself

Two things override the table: a snoozed item stays hidden until its snooze time passes, and an item that was left active or paused at the current version resumes at its saved step.

An optional schedule (from, to) limits the window. It works in whole days, inclusive, in the user's local time.

Worked example

Show a feature tip for one release only, to people on the claims search page, after a short delay:

1. Page pattern /claims/search. Trigger page-load with delay 1500 ms.
2. Frequency once-per-version.
3. Schedule from the release date to two weeks later.
4. Preview on page, then Publish. Publishing again later with a new version re-shows it.

Gotchas

• Eligibility uses progress stored in this browser. Clearing site data for the extension, or switching profile, resets it.
• once, once-per-version and until-completed depend on progress records. Preview never writes one.
• Segments are in the schema and are not evaluated. A segment condition inside a page match makes the match false today.
• Edit frequency while testing to every-visit, then set the real value before publishing.