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.
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/react
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.
true
, the annotations feature will be
enabled. If set to false
, the feature will be disabled.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:
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 org if the object isn't visible to the current org
if (info.orgID !== myUser.orgID) {
myUser.setOrgID(info.orgID);
}
// 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.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"
.{
additionalSubscribersOnCreate: [123, 456],
}
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>);
}