Initialization
How to initialize the Cord SDK in the browser
On each page load, the Cord SDK needs to be initialized with the user's identity so Cord components can show the appropriate content. This is done by passing a client auth token to the Cord SDK. You can also pass configuration options to the initialization call to configure some of the SDK's behavior.
💡
Cord components can safely be put on the page before initialization, but they'll show a default state until initialization is done.
Installation #
If you're using React, there's no special setup beyond installing our npm package. The CordProvider component will make sure everything is loaded properly (see below). Otherwise, you'll need to make sure to load our SDK script in your page's <head>.
# On the command line:
npm install @cord-sdk/reactInitialization #
You initialize Cord with a single call, though the details depend on if you're using React or vanilla JavaScript.
import { CordProvider } from "@cord-sdk/react";
export const App = () => (
<CordProvider clientAuthToken="...">
<YourApp />
<CordComponents />
</CordProvider>
);💡
It's fine to reinitialize the SDK while the page is running. If you only change the configuration options, those changes will be applied. If you change the client auth token, all components will rerender with the new identity.
The initialization call also takes a configuration object to customize the behavior of all cord components on the page.
Updating Options #
If you want to change the configuration options while your application is running, call CordSDK.updateOptions with the new option values. Any option not passed will be left at its current value.
window.CordSDK.updateOptions({enable_slack: false})CordProvider Properties #
true, the annotations feature will be
enabled. If set to false, the feature will be disabled.true.true.A function that will be called before telling the browser to navigate to a new URL. This is particularly useful for single-page applications where there is custom navigation logic.
The navigate function has three arguments:
- the URL being navigated to
- the Cord location being navigated to
- an object with additional information about where is being navigated to:
- groupID - the group ID of the thread being navigated to; this can be used to change the group ID in the auth token if needed
- threadID - the ID of the thread being navigated to
If the function you pass returns true when called, the default navigation behavior will be skipped.
For example:
function navigate(url, location, info) {
// Change the URL to the new URL
history.pushState(null, null, url);
// Change to a different group if the object isn't visible to the current group
if (info.groupID !== myUser.groupID) {
myUser.setGroupID(info.groupID);
}
// Change app's view to load the appropriate information
myApp.setLocation(location);
// Don't have Cord navigate to a new page
return true;
}custom_event_metadata property.A function that will be called before a message is created from Cord components. This can be used to customize the message or take any other action in response.
The function will be given two arguments:
- A
ClientCreateMessageobject that contains the data for the message that is going to be created, which is safe to modify - An object that contains the context of the message, which has the following properties:
- threadID — the id of the thread the message will be added to
- firstMessage — a boolean indicating whether this is the first message in that thread
The function should return a ClientCreateMessage that contains the message details you want sent. This can be the same object that was provided or a new one. It can also return null or undefined to cancel the operation, in which case no message will be sent. It can also return a Promise yielding any of those values, in case you need to call an API or otherwise do a long-running operation.
For example:
function beforeMessageCreate(message, context) {
// Add another line to the message body
message.content.push({type: "p", children: [{text: "With love, from Cord"}]});
// Add some reactions
message.addReactions = ['💡', '😲', '🤩'];
return message;
}translations option to have any effect.ScreenshotOptions Fields #
showScreenshot property to false.['new-annotation', 'share-via-email'].true, messages with attached screenshots will show an
icon on the right hand side of the annotation pill to allow users
to view the screenshot in a modal. If false, the screenshot modal
will be hidden. Note that even if the screenshot option property captureWhen is disabled, previous screenshots taken will still be visible unless showScreenshot is set to false.true.true, blurred screenshots will be taken in
addition to unblurred screenshots. This can be used to hide
sensitive information on the page from people who have access to
the conversations but not all of the page contents.false."outside_page", unblurred
screenshots will be shown on the page they're taken on, but
blurred screenshots will be shown elsewhere. When set to
"everywhere", blurred screenshots will always be shown,
never unblurred screenshots. Note: The user who created a
screenshot will always see an unblurred screenshot, in all
locations, no matter the setting of this option."outside_page".ThreadOptions Fields #
{
additionalSubscribersOnCreate: [123, 456],
} Hooks #
useCordLocation #
The React API includes a useCordLocation hook that sets the location for all components on the page that don't have their location property set. It is a singleton for the entire CordProvider, so you should include only one component that uses it at a time, typically in the component for the screen that's currently active or as part of your app router.
import { CordProvider, PagePresence, useCordLocation } from "@cord-sdk/react";
function App(props: Props) {
return (
<CordProvider>
<PagePresence />
{props.page === "home" && <Home />}
{props.page === "settings" && <Settings />}
</CordProvider>
);
}
function Home(props: Props) {
useCordLocation({ page: "home" });
return (<div>Home!</div>);
}
function Settings(props: Props) {
useCordLocation({ page: "settings" });
return (<div>Settings</div>);
}