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:
The Knock client instance to use for API requests.
The channel ID for the guides integration.
Optional targeting parameters for guide selection (e.g., user properties, tenant).
Optional configuration options for the guide client.
Constructor Options:
Whether to automatically track location changes from the browser window. Defaults to true.
Interval in milliseconds for throttle checking. Defaults to 30000 (30 seconds).
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:
Optional fetch options.
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:
The current store state.
Optional filters to apply during selection.
Filter Parameters:
Filter guides by type (e.g., 'tooltip', 'modal', 'banner').
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:
The current store state.
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:
The URL to set as the current location.
Optional additional state parameters to update.
Returns: void
Example:
Engagement Methods#
markAsSeen
#Marks a guide step as seen by the user.
Parameters:
The guide containing the step.
The step to mark as seen.
Returns: Promise<KnockGuideStep | undefined>
markAsInteracted
#Marks a guide step as interacted with by the user.
Parameters:
The guide containing the step.
The step to mark as interacted.
Optional metadata about the interaction.
Returns: Promise<KnockGuideStep | undefined>
markAsArchived
#Marks a guide step as archived by the user.
Parameters:
The guide containing the step.
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 showknock_preview_session_id
- Shows preview guides from a specific session
Example: