TagLocationOptions

The options object parameter allows to override the default automatic tracking behavior of Location Taggers APIs.

OptionPossible value
trackClicksboolean | { waitUntilTracked: true} | { waitUntilTracked: WaitUntilTrackedOptions}
trackBlursboolean | { trackValue: boolean}
trackVisibilityboolean | { mode: 'auto' } | { mode: 'manual': isVisible: boolean }
parentTagLocationReturnValue
validate{ locationUniqueness: bolean }
info

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

OptionPossible value
intervalMsnumber
timeoutMsnumber
flushQueuetrue | 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.

OptionPossible value
locationUniquenessboolean

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.