In-App UI
JavaScript
SDK
Reference

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:

apiKeystring*
The public API key for the Knock environment.
optionsKnockOptions
Additional options to pass through.

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:

userIdstring*
The authenticated user to retrieve a feed for
userTokenstring
JWT for the authenticated user. Not required in development environments.
optionsAuthenticateOptions
Additional options to authenticate your Knock user with.

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:

items.received.realtimeevent
Invoked whenever items are received in realtime from the socket.
items.received.pageevent
Invoked whenever items are received from performing a fetch. Will be invoked for the initial fetch as well.
items.received.*event
Invoked when any event with a name matching this pattern is emitted, e.g. `items.received.realtime` or `items.received.page`.
items.archivedevent
Invoked when one or more items are archived.
items.unarchivedevent
Invoked when one or more items are unarchived.
items.seenevent
Invoked when one or more items are seen.
items.unseenevent
Invoked when one or more items are unseen.
items.readevent
Invoked when one or more items are read.
items.unreadevent
Invoked when one or more items are unread.
items.all_archivedevent
Invoked when all items in the current scope are marked as archived.
items.all_seenevent
Invoked when all items in the current scope are marked as seen.
items.all_readevent
Invoked when all items in the current scope are marked as read.
items.*event
Invoked when any event with a name matching this pattern is emitted, e.g. `items.read` or `items.archived`.

Params:

eventNameenum of `messages.new` | `items.received.realtime` | `items.received.page` | `items.received.*`
The type of event to bind to.
callbackfunction
A function to be invoked when the event is triggered.

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:

itemOrItemsFeedItemOrItems
A single `FeedItem` or a list of `FeedItem` to perform the update on.

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:

itemOrItemsFeedItemOrItems
A single `FeedItem` or a list of `FeedItem` to perform the update on.

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:

itemOrItemsFeedItemOrItems
A single `FeedItem` or a list of `FeedItem` to perform the update on.

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:

itemOrItemsFeedItemOrItems
A single `FeedItem` or a list of `FeedItem` to perform the update on.

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:

itemOrItemsFeedItemOrItems
A single `FeedItem` or a list of `FeedItem` to perform the update on.

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:

itemOrItemsFeedItemOrItems
A single `FeedItem` or a list of `FeedItem` to perform the update on.

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:

itemOrItemsFeedItemOrItems
A single `FeedItem` or a list of `FeedItem` to perform the update on.
metadataRecord<string, any>
Additional metadata to be stored with the interaction event.

Returns: Promise<ApiResponse>

fetch

#

Fetches

Emits items.received.page events on a successful fetch.

Params:

optionsFetchFeedOptions
Options to pass through to the feed request

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:

propertiesobject
An object of key-value pairs for attributes you want to associate with the user.

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.

preferenceSetString
The preference set from Knock
tenantString (optional)
The tenant from Knock

Returns: Promise<ApiResponse>

Example:

setPreferences

#

Updates the authenticated user's preferences by calling the set preferences endpoint directly from the client.

Params:

preferenceSetSetPreferencesProperties
The preferences to set for the current user.

Returns: Promise<ApiResponse>

Example:

getChannelData

#

Retrieves channel data for the authenticated user by calling the get channel data endpoint directly from the client.

channelIdString
The channel ID from Knock

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:

channelIdString
The channel ID to update the channel data for
channelDataAny
The data to update for the channel data

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:

channelClientInAppMessagesChannelClient
messageTypestring

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:

itemOrItemsInAppMessage | InAppMessage[]

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:

preferenceSetSetPreferencesProperties
The preferences to set for the current user.

Returns: Promise<ApiResponse>

Example:

Types

#

KnockOptions

#
hoststring
A base URL to use for all API requests to Knock
logLevel'debug' | null
When set to debug, will output log events

AuthenticateOptions

#

Options to pass through to the authenticate method.

onUserTokenExpiring(oldToken: string) => Promise<string | void>
A callback to provide that will fire before a user Token expires. By default will fire 30s before the token is set to expire. If a string is returned from the resolved promise, that will be used as the new user token.
timeBeforeExpirationInMsnumber
Determines the amount of time in milliseconds before the token expires that the callback should be fired.

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.

itemsFeedItem[]
An ordered list of feed items to be rendered.
pageInfoPageInfo
The page info of the last successful fetch.
metadataFeedMetadata
The current feed metadata including unread, unseen, read, and total counts of items in the feed.
loadingboolean
Whether or not the feed is currently loading.
networkStatusNetworkStatus
Represents the various network states the feed can be in, including differentiating between 'fetching more' and 'fetching'.