When a user selects a file and clicks the
Drive UI's "Open with"
menu item
, Drive redirects
the user to that app's Open URL defined in
Configure a Drive UI
integration
.
If you checked the "Importing" box when you configured a Drive UI
integration, the user can select a combination of app-specific and
Google Workspace files to open. When you configure a Drive UI
integration, app-specific files are defined in the "Default MIME types" and
"Default file extensions" fields, whereas Google Workspace
files are defined in the "Secondary MIME types" and "Secondary file extensions"
fields.
For each file that the user wants to open, Drive checks the MIME
types against your defined default and secondary MIME types:
For MIME types defined in the "Default MIME types" field, the file ID is
passed to your app. For information on how to handle app-specific files,
see
Handle an Open URL for app-specific documents
.
For MIME types defined in the "Secondary MIME types" field, the
Drive UI displays a dialog asking the user what file type to
convert the Google Workspace file to. For example, if you select a
Google Docs file in the Drive UI and the "Secondary MIME
types" field suggests your app supports text/plain or application/pdf, the
Drive UI asks the user if they want to convert to Plain Text
or PDF.
For information on how to handle Google Workspace
files, see
Handle an Open URL for Google Workspace documents
.
For a list of Google Workspace documents and MIME type conversion formats,
see
Export MIME types for Google Workspace
documents
.
Handle an Open URL for app-specific documents
As mentioned in
Configure a Drive UI
integration
,
your app receives template variables with information for your app to open
the file. Your app receives a default set of template variables
within a
state
parameter. The
default
state
information for an app-specific Open URL is:
{
"ids": ["
ID
"],
"resourceKeys":{"
RESOURCE_KEYS
":"
RESOURCE_KEYS
"},
"action":"open",
"userId":"
USER_ID
"
}
This output includes the following values:
- ID
: The ID of the parent folder.
- RESOURCE_KEYS
: A JSON dictionary of file IDs mapped to
their respective resource keys.
open
: The action being performed. The value is
open
when using an Open
URL.
- USER_ID
: The profile ID that uniquely identifies the user.
Your app must act on this request by following these steps:
- Verify that the
action
field has a value of
open
and the
ids
field is
present.
- Use the
userId
value to create a new session for the user. For more
information on signed-in users, see
Users & new events
.
- Use the
files.get
method to check
permissions, fetch file metadata, and download the file content using
the
ID
values.
- If
resourceKeys
was set on the request, set the
X-Goog-Drive-Resource-Keys
request header. For more information on
resource keys, see
Access link-shared files using resource
keys
.
The
state
parameter is URL-encoded, so your app must handle the escape
characters and parse it as JSON.
Handle an Open URL for Google Workspace documents
As mentioned in
Configure a Drive UI
integration
, your app receives a default set of
template variables within a
state
parameter. The default
state
information
for a Google Workspace Open URL is:
{
"exportIds": ["
ID
"],
"resourceKeys":{"
RESOURCE_KEYS
":"
RESOURCE_KEYS
"},
"action":"open",
"userId":"
USER_ID
"
}
This output includes the following values:
- EXPORT_ID
: A comma-separated list of file IDs being
exported (used only when opening built-in Google documents).
- RESOURCE_KEYS
: A JSON dictionary of file IDs mapped to
their respective resource keys.
open
: The action being performed. The value is
open
when using an Open
URL.
- USER_ID
: The profile ID that identifies the user.
Your app must act on this request by following these steps:
Verify that this is a request to open a file by detecting both the
open
value in the
state
field and the presence of the
exportIds
field.
Use the
files.get
method to check
permissions, fetch file metadata, and determine the MIME type using the
EXPORT_ID
values.
Convert the file content using the
files.export
method. The following
code sample shows how to export a Google Workspace document to the
requested MIME type.
If
resourceKey
was set on the request, set the
X-Goog-Drive-Resource-Keys
request header. For more information on
resource keys, see
Access link-shared files using resource
keys
.
Display converted files as read-only or present a dialog letting the user to
save the file as the new file type.
The
state
parameter is URL-encoded, so your app must handle the escape
characters and parse it as JSON.
Users & new events
Drive apps should treat all "open with" events as potential
sign-ins. Some users might have multiple accounts, so the user ID in the
state
parameter might not match the current session. If the user ID in the
state
parameter doesn't match the current session, end the current session for your
app and sign in as the requested user.
In addition to opening an application from Google Drive UI, applications can
display a file picker to select content from within an app. For more
information, see the
Google Picker
.