To display your app in Google Drive when a user creates or opens a file, you must first configure a Drive UI integration. Configuration is also required to list your app in the Google Workspace Marketplace.
- Sign in to the Google API Console.
- At the top of the page, next to the Google APIs logo, select your app’s project. The APIs and Services dashboard appears.
- At the bottom of the APIs & Services dashboard, click Google Drive API. If you don’t see this option, you must enable the Google Drive API.
- In the left-hand nav, click Drive UI Integration. The Configuration page appears.
- Enter an application name in the Application Name field. The application name is displayed to users in the Manage apps dialog in the Google Drive UI (gear icon > settings > Manage Apps).
- Enter a short description in the Short Description field. The short description is displayed to users in the Manage apps dialog in the Google Drive UI (gear icon > settings > Manage Apps).
- (optional) Enter a long description in the Long Description field.
Upload one or more icons to display in a user's list of connected Drive apps and in the "Open with" context menu item. Icons should be in PNG format with a transparent background. Icons can ake up to 24 hours to appear in Drive.
If you want to allow users to use the Drive UI's "Open with" context menu item, enter a url to your app in the Open URL field. This URL is used by the "Open With" context menu item.
- This URL must contain a fully-qualified domain
name;
localhost
doesn't work. - You must verify ownership of this URL before you can list your app in the Google Workspace Marketplace.
- By default, a
state
query parameter is appended to this URL to pass data from the Drive UI to your app. For information on the contents of thestate
parameter, refer to Thestate
parameter.
- This URL must contain a fully-qualified domain
name;
Enter default mime types and file extensions in the Default Mime Types and Default File Extensions fields. Default mime types and file extensions represent files that your app is uniquely built to open. For example, your app might open a native format for layering and editing images. Only include standard media types and make sure they’re free of typos and misspellings. If your app only opens shortcut or third-party shortcut files, you can leave MIME type blank.
Enter secondary mime types and file extensions in the Secondary Mime Types and Secondary File Extensions fields. Secondary mime types and file extensions represent files that your app can open, but aren’t specific to your app. For example, your app might be an image editing app that opens png and jpg images. Only include standard media types and make sure they’re free of typos and misspellings. If your app only opens shortcut or third-party shortcut files, you can leave MIME type blank.
If you want users to click on the Drive UI's New button and create a new file with your app, check Allow users to create new documents using this application. The New URL and Document Name fields appear.
- This URL must contain a fully-qualified domain
name;
localhost
doesn't work. - You must verify ownership of this URL before you can list your app in the Google Workspace Marketplace.
- By default, a
state
query parameter is appended to this URL to pass data from the Drive UI to your app. For information on the contents of thestate
parameter, refer to Thestate
parameter.
- This URL must contain a fully-qualified domain
name;
Enter a URL in the New URL field. This URL is used by the "New" button to redirect the user to your application.
(Optional) If you want your app to be able to open Google Workspace-supported files, check Importing.
(Optional) If your app needs to manipulate files on shared drives, check Shared drive support. For further information on how to support shared drives in your app, refer to Implement shared drive support
Click Save Changes.
Request the drive.install scope
You must request the
https://www.googleapis.com/auth/drive.install
scope to integrate with
the Drive UI. When requesting this scope, users see a dialog similar to this:
For more information about scopes you can request for Drive apps, and how to request them, see What scope or scopes does my app need?
The state
parameter
By default, a state
parameter is appended to the Open and New URL to pass data
from the Drive UI to your app. This parameter contains a JSON-encoded string
containing template variables with data about the request to your app. The
variables included depend on the type of URL used (Open URL or New URL):
Template variable | Description | Applicable to which URL type? |
---|---|---|
{ids} |
A comma-separated list of file IDs that are being opened. | Open URL |
{exportIds} |
A comma-separated list of file IDs that are being exported (used only when opening native Google documents). | Open URL |
{folderId} |
The id of the parent folder. | New URL |
{userId} |
The profile ID that uniquely identifies the user. | Open URL and New URL |
{action} |
The action being performed. This value is
open when using an Open URL or create
when using a New URL.
|
Open URL and New URL |
The state
parameter is URL-encoded, so your app must handle the escape
characters and parse it as JSON. Apps can detect the create
value in the
state
parameter to verify that this is a request to create a new file.
Example state information for a New URL (in JSON notation)
The state
information for a New URL is:
{
"action":"create",
"folderId":"0ADK06pfg",
"userId":"103354693083460731603"
}
Example state information for an Open URL (in JSON notation)
The state
information for an Open URL is:
{
"ids": ["0Bz0bd"],
"action":"open",
"userId":"103354693083460731603"
}
The ids are used to fetch file metadata and download file content. Once it has the file ID and an access token, your app can check permissions, fetch the file metadata, and download the file content as described in the reference documentation for files.get.
Next steps
An installed app needs to be able to handle create and open actions launched from the Drive UI. See Handle a New URL or Handle a Open URL to learn more.