Required Real-time Collaboration configuration options

The following options are required to use the Real-time Collaboration (RTC) plugin:

• rtc_document_id
• rtc_encryption_provider
• rtc_token_provider

For an example showing the minimum required configuration for RTC, see: Getting started with RTC - Configure the required TinyMCE RTC options.

rtc_document_id

The RTC plugin requires a unique identifier for editor content to enable collaboration, known as the document ID. The identifier set by the integrator is used by the RTC server as a permanent reference for the content. Tiny recommends using the same unique ID used by your server where possible, such as the unique page or document ID from a Content Management System (CMS).

Warning: Do not reuse the document ID for different documents, otherwise content will be overwritten. Each document must have a unique identifier.

When a client (user) connects:

• If the document ID already exists, the most recent version of the content is sent to the client’s editor.
• If the document ID does not exist, the client uploads the initial content as the first version of that document.

Warning: If the content is changed outside of an RTC session, a new document ID must be generated. Changes made outside the RTC session will be overwritten by the content on the RTC server during the next collaboration session.

Type

String

Example: Using rtc_document_id

This example shows the minimum required configuration for the Real-time Collaboration plugin, including the rtc_document_id option.

tinymce.init({
  selector: 'textarea#static-rtc-example',
  plugins: 'rtc',
  rtc_document_id: 'unique-document-id',
  rtc_encryption_provider: () => Promise.resolve({ key: 'a secret key' }),
  rtc_token_provider: () => Promise.resolve({ token: 'signed-JWT-token' })
});

rtc_encryption_provider

The RTC plugin requires an encryption key for end-to-end encryption. This key is not sent to the RTC server; the TinyMCE RTC service cannot read the editor content. The encryption key is used by the SubtleCrypto browser API to encrypt and decrypt the editor content in the user’s browser.

A key is required when the client needs to:

1. Encrypt new data in the collaboration session.
2. Read previously written data from the collaboration session.

For information on encryption for RTC, including suggestions on how to generate a secure encryption key and use key rotation, see: Real-time Collaboration (RTC) Encryption Setup.

Type

Function (Returns a Promise)

Input data

Field	Type	Description
documentId	string	The document ID from the rtc_document_id option.
keyHint	string or null	Key hint returned by the editor when connecting to an existing session. The keyHint is retrieved from the RTC server using the documentId for existing documents.

Return data

Field	Type	Required?	Description
key	string	required	The encryption key that is used to locally encrypt and decrypt content for the current session. This key needs to be the same for all users connecting to a document (documentId).
keyHint	string	optional	The key hint to provide to future users to assist with retreiving the correct key for a document. It is only recorded when the input keyHint is null. The keyHint must be a unicode string with a max length of 256 characters.

Warning: Do not include secret or sensitive information in the key hint. The key hint is stored by the server in plain text.

Example: Using rtc_encryption_provider

This example shows the minimum required configuration for the Real-time Collaboration plugin, including the rtc_encryption_provider option.

tinymce.init({
  selector: 'textarea#rtc-example',
  plugins: 'rtc',
  rtc_document_id: 'unique-document-id',
  rtc_encryption_provider: ({ documentId, keyHint }) =>
    fetch('/getKey', {
      method: 'POST',
      credentials: 'include',
      body: JSON.stringify({ documentId, keyId: keyHint })
    })
    .then((response) => response.json())
    .then(({ keyId, secret }) => ({ key: secret, keyHint: keyId }))
    .catch((error) => console.log('Failed to return encryption key\n' + error)),
  rtc_token_provider: () => Promise.resolve({ token: 'signed-JWT-token' })
});

rtc_token_provider

The RTC plugin and the RTC service uses JSON Web Tokens (JWT) to authenticate the user. The user’s token should include:

• A unique user ID (sub).
• A relative expiration time (exp).

The rtc_token_provider function will be called one or more times to refresh the token before it expires. For production usage, Tiny recommends a token provider with a dynamic request that produces a new JWT token with an updated exp claim.

For information on generating and serving JWTs for TinyMCE RTC, see: Real-time Collaboration (RTC) JWT Authentication Setup.

Type

Function (Returns a Promise)

Input parameters

Field	Type	Description
documentId	string	The document ID from the rtc_document_id option.

Return data

Field	Type	Description
token	string	A generated JWT token. This token should be signed with a private key as described in JWT authentication.

Required JWT claims

Optional JWT claims

Example: Using rtc_token_provider

This example shows the minimum required configuration for the Real-time Collaboration plugin, including the rtc_token_provider option.

tinymce.init({
  selector: 'textarea#rtc-example',
  plugins: 'rtc',
  rtc_document_id: 'unique-document-id',
  rtc_encryption_provider: () => Promise.resolve({ key: 'a secret key' }),
  rtc_token_provider: ({ documentId }) =>
    fetch('/getJwtToken', {
      method: 'POST',
      credentials: 'include',
      body: JSON.stringify({ documentId }),
    })
    .then((response) => response.json())
    .then(({ jwt })) => ({ token: jwt })
    .catch((error) => console.log('Failed to return a JWT\n' + error))
});

Can't find what you're looking for? Let us know.

Except as otherwise noted, the content of this page is licensed under the Creative Commons BY-NC-SA 3.0 License, and code samples are licensed under the Apache 2.0 License.