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>.

React:
# On the command line:
npm install @cord-sdk/react
Vanilla JavaScript:
<!-- This goes in your <head> tag -->
<script src="https://app.cord.com/sdk/v1/sdk.latest.js"></script>
# On the command line:
npm install @cord-sdk/react
Copy

Initialization #

You initialize Cord with a single call, though the details depend on if you're using React or vanilla JavaScript.

React:
import { CordProvider } from "@cord-sdk/react";

export const App = () => (
  <CordProvider clientAuthToken="...">
    <YourApp />
    <CordComponents />
  </CordProvider>
);
Vanilla JavaScript:
window.CordSDK.init({
  client_auth_token: "...",
});
import { CordProvider } from "@cord-sdk/react";

export const App = () => (
  <CordProvider clientAuthToken="...">
    <YourApp />
    <CordComponents />
  </CordProvider>
);
Copy

💡

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.

Vanilla JavaScript:
window.CordSDK.updateOptions({enable_slack: false})
window.CordSDK.updateOptions({enable_slack: false})
Copy

CordProvider Properties #


clientAuthToken #

required
string
The client auth token to use when connecting to Cord.

enableAnnotations #

optional
boolean
If set to true, the annotations feature will be enabled. If set to false, the feature will be disabled.
This value defaults to true.

enableSlack #

optional
boolean
Whether to enable users to connect to their Slack accounts. This value defaults to true.

enableTasks #

optional
boolean
Whether to enable the use of the tasks integration in all components.

optional
function

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;
}

screenshotOptions #

optional
ScreenshotOptions
A configuration object that controls behavior for screenshots taken by some Cord component. The available sub-options are listed below.

threadOptions #

optional
ThreadOptions
A configuration object that controls behavior for all threads that appear on the page. The available sub-options are listed below.

customEventMetadata #

optional
JSON
Any additional metadata that should be included in events generated by Cord. At the moment this is only useful for customers using our Segment integration. The value you provide will be attached to Segment events as the custom_event_metadata property.

beforeMessageCreate #

optional
function

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 ClientCreateMessage object 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 #

optional
Translations
A set of translations to use in Cord components. This is an object where the keys are language codes and the values are objects representing translation keys. See the detailed guide to customizing Cord's text for more details.

language #

optional
string
The user language to display in components. This must be used in combination with the translations option to have any effect.

ScreenshotOptions Fields #


captureWhen #

optional
string[]
Define when to take a screenshots of the page. To disable screenshot capture altogether, pass an empty array. To disable viewing existing screenshots in messages, set the screenshot option showScreenshot property to false.
This value defaults to ['new-annotation', 'share-via-email'].
Allowed values are new-thread, new-message, new-annotation, share-via-email.

showScreenshot #

optional
boolean
If 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.
This value defaults to true.

blur #

optional
boolean
If 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.
When the blurred screenshot is shown is controlled by the option below this one.
This value defaults to false.

showBlurred #

optional
"outside_page" | "everywhere"
When set to "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.
This option does nothing if you aren't also blurring screenshots using the option above this one.
This value defaults to "outside_page".

ThreadOptions Fields #


additionalSubscribersOnCreate #

optional
array
A list of user IDs that will be subscribed to every new thread that is created during this SDK session.
Example:
{
  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.

React:
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>);
}
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>);
}
Copy

Ask Cordy