TagLocationOptions
The options
object parameter allows to override the default automatic tracking behavior of Location Taggers APIs.
Option | Possible value |
---|---|
trackClicks | boolean | { waitUntilTracked: true} | { waitUntilTracked: WaitUntilTrackedOptions} |
trackBlurs | boolean | { trackValue: boolean} |
trackVisibility | boolean | { mode: 'auto' } | { mode: 'manual': isVisible: boolean } |
parent | TagLocationReturnValue |
validate | { locationUniqueness: bolean } |
All options are optional and can be either omitted or set to undefined
to revert to the default values.
options.trackClicks
Used to customize whether and how click Event Listeners are attached to Tagged Elements.
options.trackClicks.waitUntilTracked
Some interactions may lead to the current session being closed. For example external links.
To avoid losing those events the waitUntilTracked
option can be specified. This will attach a capture Event Listener which will attempt to wait for the Tracker to finish its work before allowing the User Agent to follow its destination.
When setting waitUntilTracked
to true
we will use some sensible defaults for WaitUntilTrackedOptions
.
Custom values can be specified as well:
WaitUntilTrackedOptions
Option | Possible value |
---|---|
intervalMs | number |
timeoutMs | number |
flushQueue | true | false | onTimeout |
In the following example we are instructing our Mutation Observer to attach a Click Event handler that will attempt to wait for up to 3 seconds, polling every 100ms and flushing the TrackerQueue
only on timeout.
<link
{...tagLink({
id: 'external',
href: 'https://www.external.com',
options: {
trackClicks: {
waitUntilTracked: {
intervalMs: 100,
timeoutMs: 3000,
flushQueue: 'onTimeout'
},
}
}
})}
href="https://www.external.com"
>Bye</link>
options.trackBlurs
Used to either force or prevent blur Event Listeners being attached to Tagged Elements.
options: {
trackBlurs: true
};
// or, to prevent tracking
options: {
trackBlurs: false
};
Track also input values
To capture values the trackValue
option can be specified. This will result in an InputValueContext to be attached to the event.
options: {
trackBlurs: {
trackValue: true
}
}
options.trackVisibility
Used to customize whether to track trackHiddenEventEvent and trackVisibleEvent events, either automatically or manually.
Visibility mode:auto
Either trackHiddenEvent or trackVisibleEvent are triggered when Tagged Elements are added or removed to/from the DOM.
options: {
trackVisibility: true
};
// or
options: {
trackVisibility = {
mode: 'auto'
}
}
Visibility mode:manual
Either trackHiddenEvent or trackVisibleEvent are triggered whenever the isVisible
boolean state attribute changes.
options: {
trackVisibility = {
mode: 'manual',
isVisible: boolean
}
}
Disable automatic Visibility tracking
options: {
trackVisibility = false
}
options.parent
Used to override how the parent of a Tagged Element gets determined. When reconstructing the Location Stack the given parent
will be followed instead of the DOM tree.
A practical is to track dynamically placed nodes in the DOM, such as React Portals.
const parentDiv = tagContent({ id: 'section' });
<div {...parentDiv}>
<Modal {...tagOverlay({ id: 'portal-modal', options: { parent: parentDiv } })}>
...
</Modal>
</div>
See Example of Component using Portals for another example.
options.validate
Used to configure client-side validation.
Option | Possible value |
---|---|
locationUniqueness | boolean |
options.validate.locationUniqueness
Sometimes the same piece of UI can have mutually exclusive variants, e.g. a menu switching to its mobile version via CSS.
In those cases uniqueness checking can be disabled setting validate.locationUniqueness
to false.