Javascript SDK API Reference
Complete API reference for the Knock Javascript SDK.
In this section, you'll find the documentation for the classes and methods available in the @knocklabs/client library.
Knock
The top-level Knock class, used to interact with a client instance.
Params:
Example:
userId
Returns the user ID of the authenticated user.
Returns: string
feeds
Returns a FeedClient instance that can be initialized to return a feed.
Optionally a feed can be initialized with a default set of FeedClientOptions which will be applied to all subsequent requests.
Returns: Feed instance
Example:
user
Returns a UserClient instance to interact with the users API for the current, authenticated user.
Returns: UserClient instance
Example:
preferences
Returns a Preferences instance to interact with the preferences API for the current, authenticated user.
Returns: Preferences instance
Example:
client
Returns an instance of an authenticated ApiClient that can be used to make HTTP and Websocket requests to Knock.
Returns: ApiClient instance
authenticate
Authenticates the current user and creates a new Knock session.
Params:
Returns: void
Example:
teardown
Tears down a current session and disconnects any connected sockets.
Returns: void
ApiClient
The API client exposes direct functions for communicating with the Knock API over HTTP and websocket.
socket
Returns: a Socket
FeedClient
initialize
Creates a new Feed instance.
teardownInstances
Tears down any current feed instances.
reinitializeInstances
Reinitializes any current feed instances by reconnecting their realtime connections.
Feed
Represents the connection between a user and a feed, including methods for interacting with the items on that feed. Also includes a stateful store that can be used to build in-app notification experiences easily. See FeedStoreState for more on the shape of the store.
store
Returns: StoreApi<FeedStoreState>
listenForUpdates
Connects the feed instance to the realtime socket so that any new items published to the feed are received over the websocket.
Returns: void
Example:
on
Binds an event handler to be invoked when the event is triggered.
Events:
Params:
Returns: void.
Example:
off
Unbinds an existing event handler previously bound with on. Use this method to cleanup bound event handlers.
Returns: void.
getState
Programmatically access the current FeedStoreState.
Returns: FeedStoreState.
markAllAsSeen
Marks all of the items in the store optimistically as seen and performs a server-side request to mark all items on the feed in the current scope as seen. Broadcasts a items:all_seen event.
Please note: this operation is deferred and may take some time to process all items in the feed.
Returns: Promise<ApiResponse>
markAsSeen
Marks the given items as seen. Will perform the operation optimistically, including updating the current metadata in the FeedStoreState.
Params:
Returns: Promise<ApiResponse>
markAsUnseen
Removes the seen status on the item or items given. Will perform the operation optimistically, including updating the current metadata in the FeedStoreState.
Params:
Returns: Promise<ApiResponse>
markAllAsRead
Marks all of the items in the store optimistically as read and performs a server-side request to mark all items on the feed in the current scope as read. Broadcasts a items:all_read event.
Please note: this operation is deferred and may take some time to process all items in the feed.
Returns: Promise<ApiResponse>
markAsRead
Sets the read status on the item or items given. Will perform the operation optimistically, including updating the current metadata in the FeedStoreState.
Params:
Returns: Promise<ApiResponse>
markAsUnread
Removes the read status on the item or items given. Will perform the operation optimistically, including updating the current metadata in the FeedStoreState.
Params:
Returns: Promise<ApiResponse>
markAllAsArchived
Marks all of the items in the store optimistically as archived and performs a server-side request to mark all items on the feed in the current scope as archived. Broadcasts a items:all_archived event.
Please note: this operation is deferred and may take some time to process all items in the feed.
Returns: Promise<ApiResponse>
markAsArchived
Sets the archived status on the item or items given. Will perform the operation optimistically, including updating the current metadata in the FeedStoreState. Broadcasts a items:archived event.
Params:
Returns: Promise<ApiResponse>
markAsUnarchived
Removes the archived status on the item or items given. Will perform the operation optimistically, including updating the current metadata in the FeedStoreState.
Params:
Returns: Promise<ApiResponse>
markAsInteracted
Sets the interacted status on the item or items given. Will perform the operation optimistically, including updating the current metadata in the FeedStoreState. Broadcasts an items:interacted event.
Params:
Returns: Promise<ApiResponse>
fetch
Fetches
Emits items.received.page events on a successful fetch.
Params:
Returns: Promise<ApiResponse>
fetchNextPage
Fetches the next page of the feed items (if there are any more to fetch).
Emits items.received.page events on a successful fetch.
Note: this will apply any current feed filters and append returned items to the end of the current set of items.
UserClient
get
Retrieves the current, authenticated user by calling the get user endpoint directly from the client.
Returns: Promise<ApiResponse>
Example:
identify
Identifies a user by calling the identify user endpoint directly from the client.
Params:
Returns: Promise<ApiResponse>
Example:
getAllPreferences
Retrieves all preferences for the authenticated user by calling the get preferences endpoint directly from the client.
Returns: Promise<ApiResponse>
Example:
getPreferences
Retrieves a preference set for the authenticated user by calling the get preferences endpoint directly from the client.
Returns: Promise<ApiResponse>
Example:
setPreferences
Updates the authenticated user's preferences by calling the set preferences endpoint directly from the client.
Params:
Returns: Promise<ApiResponse>
Example:
getChannelData
Retrieves channel data for the authenticated user by calling the get channel data endpoint directly from the client.
Returns: Promise<ApiResponse>
Example:
setChannelData
Updates the channel data for the current user by calling the set channel data endpoint directly from the client.
Params:
Returns: Promise<ApiResponse>
Example:
InAppMessagesChannelClient
subscribe
Subscribes the given in-app message client to the socket to receive real-time in-app message updates.
unsubscribe
Unsubscribes the given in-app message client from the socket, cleaning up any connection handlers in the process.
store
Exposes a @tanstack/store store for setting message and query information per in-app message client.
InAppMessagesClient
An in-app message client represents the query for a single UI element to the in-app messages API.
constructor
Initializes a new in-app message client. Used to track the state of messages returned from the API for a particular message type.
Params:
Returns: InAppMessagesClient
fetch
Initiates a fetch to the in-app messages API to retrieve messages, setting the result of the fetch and the returned messages in the in-app message channel client store.
Returns: Promise<ApiResponse>
markAs{status}
Marks one or more messages as the provided status, optimistically updating the status in the process on the store.
Params:
Returns: Promise<ApiResponse>
Preferences
get
Retrieves a preference set for the authenticated user by calling the get preferences endpoint directly from the client.
Returns: Promise<ApiResponse>
Example:
set
Updates the authenticated users preferences by calling the set preferences endpoint directly from the client.
Params:
Returns: Promise<ApiResponse>
Example:
Types
KnockOptions
AuthenticateOptions
Options to pass through to the authenticate method.
FeedStoreState
A zustand state store that holds the current feed state, including item counts, for easy notification feed rendering within your application. The FeedStoreState is entirely managed by the Feed instance, and any calls to fetch(), markAsX, or fetchNextPage will update the state accordingly.