A client-side Javascript library to interact with user-facing Knock features, such as feeds.
Note: this is a lower level library designed for building UI on top of
See the documentation for usage examples.
Via NPM:
npm install @knocklabs/client
Via Yarn:
yarn add @knocklabs/client
To configure the client library you will need:
- A public API key (found in the Knock dashboard)
- A feed channel ID (found in the Knock dashboard)
- A user ID, and optionally an auth token for production environments
import Knock from "@knocklabs/client";
const knockClient = new Knock(process.env.KNOCK_API_KEY);
knockClient.authenticate(
// The id of the user you want to authenticate against
currentUser.id,
// You only need this in production environments
currentUser.knockToken,
);
You can find an example usage in a React application in the example/App.js file, which is a plain-old Create React App.
import Knock from "@knocklabs/client";
const knockClient = new Knock(process.env.KNOCK_API_KEY);
// Authenticate the user
knockClient.authenticate(currentUser.id, currentUser.knockToken);
// Initialize the feed
const feedClient = knockClient.feeds.initialize(
process.env.KNOCK_FEED_CHANNEL_ID,
// Optionally you can provide a default scope here:
// { tenant: "jurassic-park", source: "new-comment" },
);
// Connect to the real-time socket
const teardown = feedClient.listenForUpdates();
// Setup a callback for when a batch of items is received (including on first load and subsequent page load)
feedClient.on("items.received.page", ({ items }) => {
console.log(items);
});
// Setup a callback for when new items arrive in real-time
feedClient.on("items.received.realtime", ({ items }) => {
console.log(items);
});
// Listen to all received items
feedClient.on("items.received.*", ({ items }) => {
console.log(items);
});
// Fetch the feed items
feedClient.fetch({
// Fetch a particular status only (defaults to all)
status: "all" | "unread" | "unseen",
// Pagination options
after: lastItem.__cursor,
before: firstItem.__cursor,
// Defaults to 50
page_size: 10,
// Filter by a specific source
source: "notification-key",
// Filter by a specific tenant
tenant: "jurassic-park",
});
teardown();
// Initialize the feed as in above examples
const feedClient = knockClient.feeds.initialize(
process.env.KNOCK_FEED_CHANNEL_ID,
);
// Gives you all of the items currently in the store
const { items } = feedClient.store.getState();
// The feed store uses zustand
import create from "zustand";
// Initialize the feed as in above examples
const feedClient = knockClient.feeds.initialize(
process.env.KNOCK_FEED_CHANNEL_ID,
);
const useFeedStore = create(feedClient.store);
// Retrieves all of the items
const items = useFeedStore((state) => state.items);
// Retrieve the badge counts
const meta = useFeedStore((state) => state.metadata);
// Initialize the feed as in above examples
const feedClient = knockClient.feeds.initialize(
process.env.KNOCK_FEED_CHANNEL_ID,
);
// Mark one or more items as read
feedClient.markAsRead(feedItemOrItems);
// Mark one or more items as seen
feedClient.markAsSeen(feedItemOrItems);
// Mark one or more items as archived
feedClient.markAsArchived(feedItemOrItems);
// Mark one or more items as unread
feedClient.markAsUnread(feedItemOrItems);
// Mark one or more items as unseen
feedClient.markAsUnseen(feedItemOrItems);
// Mark one or more items as unarchived
feedClient.markAsUnarchived(feedItemOrItems);
// Set an entire preference set
await knockClient.preferences.set({
channel_types: { email: true, sms: false },
workflows: {
"dinosaurs-loose": {
channel_types: { email: false, in_app_feed: true },
},
},
});
// Retrieve a whole preference set
const preferences = await knockClient.preferences.get();
// Granular preference setting for channel types
await knockClient.preferences.setChannelType("email", false);
// Granular preference setting for workflows
await knockClient.preferences.setWorkflow("dinosaurs-loose", {
channel_types: {
email: true,
in_app_feed: false,
},
});