Realtime documents are attached to files in Google Drive to enable discovery and collaboration.
There are two primary use cases for Realtime Documents:
- To collaborate on a custom file type specific to your application (similar to a Google Doc)
- To collaborate on an existing binary file type (for instance, an image or a text file).
How you use the Realtime API has practical implications for the types of files you use and create in your applications. The Drive API supports two types of files that correspond to the two ways you can use the Realtime API:
- Shortcut files with no content that can be used as a placeholder for Realtime documents.
- Regular files with content such as text files, images, XML files, binaries, etc.
To create a file, use
from the Drive API.
The Realtime API automatically creates the Realtime document when you load
the Drive file for the first time via
If you don't rely on an existing physical file format, you should use a shortcut file
to interact with the Realtime document directly. Shortcut files are assigned the
special MIME type
application/vnd.google-apps.drive-sdk. For details, see
Create a shortcut to a file.
A shortcut file creates a file entry in Drive for your collaborative document.
Realtime documents can also be associated with regular Drive files. Regular files can be assigned any MIME type you choose. Unlike shortcut files, these files carry content—for instance a .java Drive file carries the actual text content of a Java source code file. These types of files can also be used as placeholders for a Realtime document. Note that the content of such a file is unaffected by the Realtime document and both live in parallel. You need to build some logic to handle synchronization between the file content and the Realtime document yourself.
Multiple applications can associate Realtime documents with the same file. In this circumstance, the binary content of a file may change. See Using Collaborative Models with Existing File Types for details on handling these potential conflicts.
In all cases, the created Drive file holds important metadata, like the title
and last modified date of the document. To read or edit this metadata,
files collection of the REST API.
Drive UI Integration
When you integrate with the Drive UI, users can create and open files stored in Drive with your application. This process is the same as for standard Drive web applications. See Enable the Drive Platform for details.