Introduction

You can get the app and editor integration API key by registering via this link.

Authentication

All API requests are authenticated using the apiKey associated with your account and specific app integration.

For example, when an integration with TinyMCE is requested through the Dashboard, an apiKey will be generated for this integration. This key will be unique to this integration and the specified domains.

You can manage your integrations and API keys in the Dashboard.

An API key may be automatically set for some integrations, such as Zendesk. For other integrations, like TinyMCE, you will need to provide the key as part of a configuration object. Please refer to an integration documentation for specific instructions and sample code.

Integrations

API based integrations, such as TinyMCE and Quill, allow multiple domains and subdomains to be registered.

If your app is deployed across multiple top-level domains, for example, myapp1.io, and myapp2.io, you need to add individually in the Dashboard to enable co-editing.

Another common scenario is where your app is deployed across multiple subdomains belonging to a single top-level domain. For example, you might be using a top-level domain myapp.io, while individual subscriptions might get team1.myapp.io, team2.myapp.io, etc. To enable co-editing across all subdomains, you only need to register the top-level domain myapp.io.

If co-editing is to be offered as a differentiated service across service tiers, you can control whether to enable co-editing based on the individual subscription, using the client side API.

localhost

We enable localhost development by default across all API-based integrations. There is no need to add it to the list of domains.

TinyMCE

The TinyMCE integration enables real-time co-editing directly inside the TinyMCE editor.

To get started, enable the Wave plugin in the TinyMCE external_plugins object by adding an entry for the wave. Then, to start a co-editing session, supply a configuration object to the plugin. The minimal required attributes for this configuration object are docId, username and apiKey, which are explained below.

You can use the demo API key 7bdf58a1-e722-4868-bee9-b7e7c65a09b6 without an account. It can be used to enable co-editing sessions with two users per session and 100 sessions per month. To support more users per collaboration session, please sign up for an account.

Note: if you do not specify an apiKey in the config object, we will supply the default demo API key by default.

For general information about TinyMCE plugins, please click here.

TinyMCE Configuration

external_plugins:
string Wave TinyMCE plugin URL
wave:
string A configuration object for the plugin

Wave Configuration

docId:
string The unique document id for the document. For a content management service, this would normally be the id when the document is first created.
username:
string The name of the user joining the co-editing session. For a content management service, this should be set for each logged-in user based on their credentials. This name will be displayed during real-time co-editing.
apiKey:
string The API key for the TinyMCE integration in your Wave account.
autoStart:
(optional)
boolean Set to true, if co-editing session should start automatically on tinymce.onload event. Set to false, to initialize but delay start the co-editing (see the start() client API). Default setting is true.
 
 
  var config = {
    docId    : "docId",
    username : "Joe Smith",
    apiKey   : "7bdf58a1-e722-4868-bee9-b7e7c65a09b6" //demo API Key
  };

  tinymce.init({
    external_plugins : {
      wave : "https://cdn2.stage.codox.io/waveTinymce/plugin.min.js"
    },
    wave   : config 
  }
 
              

Quill

Wave integration for Quill enables real-time co-editing directly inside the Quill editor.

Wave Configuration

app:
string static value "quilljs"
docid:
string the unique id for the document. For a content management service, this would normally be the id when the document is first created.
username:
string The name of the user joining the co-editing session. For a content management service, this should be set for each logged-in user based on their credentials. This name will be displayed during real-time co-editing sessions.
apiKey:
string The API key for the Quill integration in your Wave account.
editor:
Object The Quill editor reference where co-editing should be enabled
autoStart:
(optional)
boolean Set to true, if co-editing session should start automatically on init(config). Set to false to initialize but delay start the co-editing (see the start() client API). Default setting is true.
           
var editor = new Quill("#editor", {modules: {'toolbar': toolbar }, theme: "snow" }); 

var config = {
  "app"      : "quilljs",
  "editor"   : editor,
  "docId"    : "docId",  
  "username" : "Joe Smith", 
  "apiKey"   : "8a97c7db-5155-4245-9f9d-16e3dfd11ef2"
};


//start co-editing
var codox = new Codox();
codox.init(config);

           
                

Client API

Wave API based integrations for TinyMCE and Quill will load and expose a client API that allows the developer to programmatically control how and when co-editing sessions should be started. The client shim automatically creates a globally accessible Codox class. An instance of the Codox class should be created for each editor participating in a co-editing session.

 
           
var codox =  new Codox();
           
                

.init(config)

Initialize a Codox instance with app specific configurations

Configuration parameters

app:
string static value: quilljs, tinymce
docid:
string the unique id for the document. For a content management service, this would normally be the id when the document is first created.
username:
string The name of the user joining the co-editing session. For a content management service, this should be set for each logged-in user based on their credentials. This name will be displayed during real-time co-editing.
apiKey:
string The API key for the app integration
editor:
Object The editor reference where co-editing should be enabled
showUI:
(optional)
boolean Set to true, if user presence UI should be displayed. Set to false to disable. Default setting is true.
autoStart:
(optional)
boolean Set to true, if co-editing session should start automatically. Set to false to initialize but delay the start of co-editing(see start). Default setting is true.
 
 
//this example provides the initialization parameters, but does not automatically 
//co-editing by setting 'autoStart' to false 

var editor = new Quill("#editor", {modules: {'toolbar': toolbar }, theme: "snow" });

var config = {
  "app"      : "quilljs",
  "editor"   : editor,
  "docId"    : "docId",
  "username" : "Joe Smith",
  "autoStart": false,
  "apiKey"   : "8a97c7db-5155-4245-9f9d-16e3dfd11ef2"
};

var codox = new Codox();
codox.init(config);
 
                

.start(config)

Explicitly start or join a co-editing session. The configuration parameters are identical to those for init(config). The client will immediately start/join a session, thus ignoring any value set for autoStart.

If init(config) has been invoked against the client API, start() will start/join the session based on the existing config values.

 
 
//this example provides the initialization parameters, and starts the co-editing session
//explicitly via a call to .start(config)

var editor = new Quill("#editor", {modules: {'toolbar': toolbar }, theme: "snow" });

var config = {
  "app"      : "quilljs",
  "editor"   : editor,
  "docId"    : "docId",
  "username" : "Joe Smith",
  "apiKey"   : "8a97c7db-5155-4245-9f9d-16e3dfd11ef2"
};

var codox = new Codox();

//the following is the same as codox.start(config), but allows delayed start
codox.init(config);
codox.start(); 

 
                

.stop()

Explicitly remove the client from a co-editing session. If the client is the last one in a co-editing session, the entire session will be stopped and removed.