usePressEventTracker

Returns a ready-to-trigger trackPressEvent by retrieving ReactTracker instance and LocationStack automatically.

usePressEventTracker = (
hookParameters: {
tracker?: Tracker,
options?: TrackEventOptions,
locationStack?: LocationStack,
globalContexts?: GlobalContexts
} = {}
) => (
callbackParameters: {
tracker?: Tracker,
options?: TrackEventOptions,
locationStack?: LocationStack,
globalContexts?: GlobalContexts
} = {}
) => Promise<TrackerEvent>

Parameters

The hook and callback share tracker, options, locationStack and globalContexts parameters.

This allows composing the Event's payload by combining parameters provided to the hook and/or the callback:

  • tracker: Custom tracker instance. By default, useTracker() is used, which can be overridden by providing this parameter to the hook, or later to the callback. If both hook and callback have tracker parameters, the callback takes precedence.

  • options: The callback options are shallow merged onto the hook's ones. E.g. the parameters with the same name from the callback's options will overwrite the hook's ones.

  • locationStack: The callback and hook LocationStack are merged with the result of useLocationStack(). This allows to combine the LocationStack of parent components with the virtual Locations provided to either the hook or callback, or both.

  • globalContexts: The callback and hook GlobalContexts items are simply merged together.


Hook Parameters

typedefault value
optionaltrackerReactTrackeruseTracker()
optionaloptionsTrackEventOptions
optionallocationStackLocationStackuseLocationStack()
optionalglobalContextsGlobalContexts

Callback Parameters

typedefault value
optionaltrackerReactTracker
optionaloptionsTrackEventOptions
optionallocationStackLocationStack
optionalglobalContextsGlobalContexts

TrackEventOptions

The Tracker can leverage its Queue for sending synchronous events. Here is an overview of how that works:

Returns

A callback with the same parameters of the hook itself.

(callbackParameters: {
tracker?: Tracker,
options?: TrackEventOptions,
locationStack?: LocationStack,
globalContexts?: GlobalContexts
} = {}) => Promise<TrackerEvent>

Usage

Scenario: declaratively wrapping a third party download button
import { PressableContextWrapper, usePressEventTracker } from "@objectiv/tracker-react";

const trackPressEvent = usePressEventTracker();

<PressableContextWrapper id={'pressable'}>
<DownloadButton
onClick={() => {
trackPressEvent();
}}
>
Download
</DownloadButton>
</PressableContextWrapper>
Scenario: virtual location wrapper
import { makePressableContext } from "@objectiv/tracker-core";
import { usePressEventTracker } from "@objectiv/tracker-react";

const trackPressEvent = usePressEventTracker();

<ContextualMenu
onMenuItemPress={(menuItem) => {
trackPressEvent({
// Wrap this event in a virtual location representing the clicked menu item
locationStack: [
makePressableContext({
id: menuItem.id
})
]
});
}}
/>
Scenario: synchronous PressEvent callback
import { makePressableContext } from "@objectiv/tracker-core";
import { usePressEventTracker } from "@objectiv/tracker-react";

const trackPressEvent = usePressEventTracker();

const trackSynchronousPressEvent = usePressEventTracker({
options: {
waitForQueue: true
}
});

// We can use a regular callback and specify the necessary options ad-hoc for this button
<Button
onClick={async () => {
await trackPressEvent({
options: {
waitForQueue: true
}
});
}}
/>

// Or use the pre-configured callback to keep event handlers leaner
<Button
onClick={async () => {
await trackSynchronousPressEvent();
}}
/>