All the necessary steps for integrating Cord with your app
You’ll need to take steps on both the frontend and backend of your app. We’ll start with the frontend.
Don’t have an app at the moment?
That’s okay, just create a sample react app by pasting the line below in your terminal:
It might take a minute or two the first time you run this command.
Adding a component requires you to supply a client auth token, so that Cord’s servers know who’s using the component. For now, just use the sample token in the code below; later in this guide, you’ll learn how to generate auth tokens on your backend.
import { CordProvider, Sidebar } from "@cord-sdk/react";
export const App = () => (
// TODO: Replace this sample token - use client auth token sent from backend
<CordProvider clientAuthToken="<CLIENT_AUTH_TOKEN>">
<YourApp />
<Sidebar />
</CordProvider>
);<!-- This goes in your <head> tag -->
<script src="https://app.cord.com/sdk/v1/sdk.latest.js"></script>
<script>
// TODO: Replace this sample token - use client auth token sent from backend
window.CordSDK.init({
client_auth_token: "<CLIENT_AUTH_TOKEN>",
});
</script>
<!-- This goes at the top level of your <body> tag -->
<cord-sidebar ></cord-sidebar>Now, when you view your app in a browser, you should see the Cord sidebar on the right-hand side.
Cord needs to know what part of your app each user is currently using, so we can show their presence to others. Locations are how Cord expresses points of interest in your app’s user interface.
The most basic location is simply the page a user is viewing, but you can get as precise as you want. If your page has several sections or tabs, you can make each one its own location. See our in-depth guide on location for all the details.
You can set a location on many Cord components, including Sidebar. When a user is on the page with the sidebar, Cord will show that user as present in the location you pass to the Sidebar.
Location is expressed as a JavaScript object. Its keys can be any strings, but by convention, there is at least a page key.
<Sidebar location={{ page: "dashboards", tab: "metrics" }} /><cord-sidebar location='{ "page": "dashboards", "tab": "metrics" }'></cord-sidebar>If you don’t supply a location to a Cord component that needs one, it will use the current URL (including query parameters) as its location. This may work fine for some apps, but we recommend always setting locations explicitly.
By setting CSS variables, you can extensively customize the appearance of Cord components, so that they match your app’s design and branding.
Use our live CSS editor to see what’s possible and generate the required CSS rules.
npm install @cord-sdk/servergo get cord.com/serverimplementation "com.cord:server:0.0.+"Currently, the backend SDK’s only functionality is generating auth tokens; if your language isn’t listed here, see our guide on authentication to learn how to write auth token generation yourself.
The Cord components in your frontend talk directly to Cord’s servers. To do so, they need a client auth token to identify the user. Your backend will generate a client auth token and send it to your frontend on every page load.
The client auth token also identifies the organization. Organizations are the scope of collaboration within Cord: users can interact only with other users in the same organization.
To generate a client auth token, you’ll need an ID for the user who is viewing the page, and for the organization they are part of. You can use your app’s user IDs; Cord can accept any string as a user or organization ID. You’ll also include some details about the user and organization. You’ll see why in the next step.
You’ll need to get your app ID and secret from the Cord console. Keep them in a secure place on your backend, and only send client auth tokens to your frontend. Your secret should never leave your backend.
import { getClientAuthToken } from "@cord-sdk/server";
// "user" and "org" are your app's model objects
const clientAuthToken = getClientAuthToken(APP_ID, SECRET, {
user_id: user.id,
organization_id: org.id,
user_details: {
email: user.email,
name: user.name,
profile_picture_url: user.profilePictureURL,
},
organization_details: {
name: org.name,
},
});
// Send clientAuthToken to your frontend, and replace the sample token
// from step 2 with it.import (
cord "cord.com/server"
)
// "User" and "Organization" are your app's model classes
func getClientAuthToken(u User, o Organization) (string, error) {
return cord.ClientAuthToken(kAppID, kSecret,
cord.ClientAuthTokenData{
UserID: u.id,
OrganizationID: o.id,
UserDetails: &cord.UserDetails{
Email: u.email,
Name: u.name,
ProfilePictureURL: u.profilePictureURL,
},
OrganizationDetails: &cord.OrganizationDetails{
Name: o.name,
},
})
}
// Send the result of getClientAuthToken() to your frontend, and replace
// the sample token from step 2 with it.import com.cord.server.Cord;
import com.cord.server.ClientAuthTokenData;
import com.cord.server.PlatformUserVariables;
import com.cord.server.PlatformOrganizationVariables;
// "user" and "org" are your app's model objects
String clientToken = Cord.getClientAuthToken(
APP_ID,
SECRET,
new ClientAuthTokenData
.ClientAuthTokenDataBuilder(user.getId(), org.getId())
.organizationDetails(new PlatformOrganizationVariables
.PlatformOrganizationVariablesBuilder(org.getName())
.build())
.userDetails(new PlatformUserVariables
.PlatformUserVariablesBuilder(user.getEmail())
.firstName(user.getFirstName())
.lastName(user.getLastName())
.profilePictureUrl(user.getProfilePictureUrl())
.build())
.build());
// Send clientToken to your frontend, and replace the sample token from
// step 2 with it.Cord needs to know some basic details about your users and organizations, so that we can render our components. By including those details in client auth tokens, you’ll keep us updated about active users and organizations.
However, there are other situations where your backend will need to send us user and organization details directly, via our REST API:
When you create a new user in your app, you’ll send their details to Cord, so that they can immediately be @Mention-ed by other users, and they’ll have a good first-time experience with Cord.
When a user updates their details in your app (for example, if they change their name or profile picture), you’ll update that user in Cord, so that the user’s appearance in Cord is always up to date.
When you delete or deactivate a user or organization, you’ll send that change to Cord so it can be reflected in Cord components.
Check out how to authenticate to the REST API, and the reference pages for creating and updating users, and creating and updating organizations.
After you first integrate with Cord, but before you launch to users, you’ll backfill all of your existing users and organizations in a batch. This is a one-time operation. You won’t need to modify the main flows of your app.
Use the batch-update REST API to do this.
There’s a lot more to Cord than what you’ve seen so far.
On this page