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/react

Copy

Initialization

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

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.

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.

enableTasks

optional

boolean

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

navigate

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:
- orgID - the org ID of the thread being navigated to; this can be used to change the org 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 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;
}

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.

ScreenshotOptions Fields

captureWhen

optional

string[]

enum: ( "new-annotation" | "share-via-email" | "new-thread" | "new-message" )

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

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

string

enum: ( "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.

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

Docs

Go to the Cord Console