In-App UI

JavaScript

SDK

GuideClient

GuideClient reference

Complete reference for the GuideClient in the Knock JavaScript SDK.

Client for managing in-app guides, including real-time updates, location tracking, and engagement events.

Constructor

Initializes a new guide client instance.

Parameters:

knockKnock

The Knock client instance to use for API requests.

channelIdstring

The channel ID for the guides integration.

targetParamsTargetParams

Optional targeting parameters for guide selection (e.g., user properties, tenant).

optionsConstructorOpts

Optional configuration options for the guide client.

Constructor Options:

trackLocationFromWindowboolean

Whether to automatically track location changes from the browser window. Defaults to true.

throttleCheckIntervalnumber

Interval in milliseconds for throttle checking. Defaults to 30000 (30 seconds).

orderResolutionDurationnumber

Duration in milliseconds to wait before resolving guide order. Defaults to 50ms.

Returns: KnockGuideClient

Properties

`store`

A Tanstack Store instance containing the current state of guides, location, and other client data.

Type: Store<StoreState, (state: StoreState) => StoreState>

Core Methods

`fetch`

Fetches guides from the API based on the current targeting parameters and optional filters.

Parameters:

optsobject

Optional fetch options.

opts.filtersQueryFilterParams

Optional filter parameters to apply to the guide query.

Returns: Promise<QueryStatus>

Example:

`subscribe`

Subscribes to real-time guide updates via websocket connection.

Returns: void

Example:

`unsubscribe`

Unsubscribes from real-time guide updates and cleans up websocket connections.

Returns: void

`cleanup`

Performs complete cleanup of the guide client, including unsubscribing from websockets, removing event listeners, and clearing intervals.

Returns: void

Example:

Selection Methods

`selectGuides`

Selects multiple guides based on the current state and optional filters.

Parameters:

stateStoreState

The current store state.

filtersSelectFilterParams

Optional filters to apply during selection.

Filter Parameters:

typestring

Filter guides by type (e.g., 'tooltip', 'modal', 'banner').

keystring

Filter guides by specific guide key.

Returns: KnockGuide<C>[]

Example:

`selectGuide`

Selects a single guide based on priority, throttling rules, and group staging logic.

Parameters:

stateStoreState

The current store state.

filtersSelectFilterParams

Optional filters to apply during selection.

Returns: KnockGuide<C> | undefined

Example:

Location Tracking

`setLocation`

Manually sets the current location for guide activation rule evaluation.

Parameters:

hrefstring

The URL to set as the current location.

additionalParamsPartial<StoreState>

Optional additional state parameters to update.

Returns: void

Example:

Engagement Methods

`markAsSeen`

Marks a guide step as seen by the user.

Parameters:

guideGuideData

The guide containing the step.

stepGuideStepData

The step to mark as seen.

Returns: Promise<KnockGuideStep | undefined>

`markAsInteracted`

Marks a guide step as interacted with by the user.

Parameters:

guideGuideData

The guide containing the step.

stepGuideStepData

The step to mark as interacted.

metadataGenericData

Optional metadata about the interaction.

Returns: Promise<KnockGuideStep | undefined>

`markAsArchived`

Marks a guide step as archived by the user.

Parameters:

guideGuideData

The guide containing the step.

stepGuideStepData

The step to mark as archived.

Returns: Promise<KnockGuideStep | undefined>

Example:

Debug Support

The guide client supports debug mode through URL parameters:

knock_guide_key - Forces a specific guide to show
knock_preview_session_id - Shows preview guides from a specific session

Example: