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: This is a test token that will expire in 24h. To implement Cord fully, you need to generate tokens in your backend and send them to the client.
// See https://docs.cord.com/in-depth/authentication and https://docs.cord.com/reference/server-libraries for more information.
<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: This is a test token that will expire in 24h. To implement Cord fully, you need to generate tokens in your backend and send them to the client.
// See https://docs.cord.com/in-depth/authentication and https://docs.cord.com/reference/server-libraries for more information.
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 section or tab its own location (the granularity will become clearer and more necessary with some of our other components, for example the Presence Facepile). In the opposite case, if you want to show the same set of comments in two different pages, then you just have to set the same location on each. If your page has several logically distinct modes under the same URL, you can make each mode its own location. See our in-depth guide on location for all the details.
Location is expressed as a JavaScript object. Its keys can be any strings. You will typically want to identify at least the current page, and so there is typically at least a page key. Beyond that, you can add as many other keys as you need to identify the location. 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.
<Sidebar location={{ page: "dashboards", tab: "metrics" }} /><cord-sidebar location='{ "page": "dashboards", "tab": "metrics" }'></cord-sidebar>You can set a location on many Cord components, including Sidebar. As an experiment, try setting the location to {page: 'play-game', game: 'checkers'} – this is what you might do if you had several distinct games under the same “play game” URL. Now, add a comment. Next, change the location to {page: 'play-game', game: 'chess'} and reload the page. You should no longer see the comment. Finally, change the location back and reload the page again – the comment should re-appear.
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.
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 must backfill all of your existing users and organizations in a batch. You need to do this so you can get out-of-the-box @mention functionality.
You only need to fully mirror your existing users and organizations in Cord once, ideally before you launch so that it is exactly representative of your application’s state. After that, your code from step 7 of the integration guide should keep those synced users and organizations up to date with changes that occur in your backend.
Use the batch-update REST API to do this, which will allow you to sync multiple users and organizations with a single API call.
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.There’s a lot more to Cord than what you’ve seen so far.
On this page