The Realtime API provides a persistent document for the data that users are collaborating on. Applications that provide collaborative editing features, but need to work with files in various formats, must adopt one or more strategies for converting data between the Realtime API document and other file formats.
The simplest approach for working with other file formats is importing and exporting files at the user's request. When the user opens a supported file with the application, the application creates a new file shortcut to represent the new collaborative version and initializes the model.
Similarly, applications may provide an export or "Save as" feature to serialize the model into one or more formats. This creates a new file that contains a snapshot of the model at the time it was saved.
In both cases, there is no connection between the collaborative document and the imported or exported file. Changes made to one are not reflected in the other.
Realtime document backed files
In some cases, it is preferable to have a strong association between a file and the collaborative document. Rather than import and create a new file, applications may attach a collaborative document directly to a file stored in Drive. This approach gives the appearance of adding collaborative editing features without creating a copy of the file. Before adopting this approach, it is important to understand how documents work in this configuration.
- The collaborative document and file are not automatically synchronized. As with importing and exporting, it is the responsibility of the app to serialize and deserialize the model to the underlying file as needed.
- Models are isolated by application. If a user opens the same file with two different collaborative apps, separate documents are created.
- The binary file may change at any time.
Detecting External Updates
When reading or writing from the underlying file, applications should record the
resulting md5Checksum which can be obtained from the
operation. This is the most reliable way to tell that the file is different
from the version that your application used to create the Realtime data model.
We do not recommend using the Drive REST API eTag for this purpose because it is affected by metadata changes, such as changing the title or permissions.
If the application determines that the file has been modified externally, you can choose resolve this conflict. Possible resolutions, ordered from safest to least safe, are:
- Show a diff and let the user choose which version to keep
- Automatically merge the changes
- Prompt and let the user choose which version to keep
- Overwrite the Realtime model with the binary file (last writer wins)
- Overwrite the binary file with the Realtime model (effectively reverts the binary file write)
To avoid confusion or potential data loss, always prompt the user before overwriting the data.
Automatic vs. Explicit Saving
Since changes to the model are not visible in the file until the file is saved, applications must decide when and how frequently changes to the model are saved to the file. Unlike a normal editor where unsaved changes are at risk of loss, changes to the collaborative document are persistent. Aggressively auto-saving while the user is editing is neither necessary nor recommended. Instead, applications may choose to automatically save after long periods of inactivity, at the end of an editing session, or at the user's request.