Required Real-time Collaboration configuration options
List of all required RTC configuration options.
Contribute to this pageThe following options are required to use the Real-time Collaboration (RTC) plugin:
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:
- Encrypt new data in the collaboration session.
- 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
ornull
Key hint returned by the editor when connecting to an existing session. The keyHint
is retrieved from the RTC server using thedocumentId
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
isnull
.
ThekeyHint
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
Field | Type | Description |
---|---|---|
sub | string | The unique user ID (If sub is the same for two clients, the server will trust them as if they are the same user). |
exp | integer | A timestamp indicating the token expiry date and time. |
Optional JWT claims
Field | Type | Description |
---|---|---|
https://claims.tiny.cloud/rtc/document | string | The document ID that this JWT can access. If omitted, the JWT will be able to access any document on the same account. |
https://claims.tiny.cloud/rtc/role | string | The possible role values are: editor or viewer . viewer will put the editor into readonly mode and editor (default) will let the user edit the document. |
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))
});
Was this article helpful? Yes - No
Well, that's awkward . Would you mind opening an issue or helping us out?
Thanks for the feedback!
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.