Handle an Open URL

When a user selects a file and clicks the "Open with" context menu item, Drive redirects the user to that app's Open URL defined when you Configure a Drive integration.

If you checked the "Importing" box when you configured a Drive integration, the user can select a combination of app-specific and Google Workspace files to open. App-specific files are defined in the Default Mime Types and Default File Extensions fields when you configured a Drive integration. Google Workspace files are defined in the Secondary Mime Types and Secondary File Extensions fields when you configured a Drive integration.

For each file that the user wants to open, Drive checks the MIME types against the default and secondary mime types you defined:

  • For MIME types defined in the Default Mime Types field, the fileID is passed on to your app. For information on how to handle app-specific files, refer to Handle an Open URL for an app-specific document

  • 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 Doc in the Drive UI and Secondary Mime Types field suggests your app supports text/html, text/plain, or application/pdf, the Drive UI asks the user if they want to convert to HTML, Plain text, or PDF. For information on how to handle Google Workspace files, refer to Handle an Open URL for a Google Workspace document. For a list of Google Workspace Documents, conversion formats, and corresponding mime types, refer to Google Workspace documents and corresponding export MIME types.

Handle an Open URL for an app-specific document

As mentioned in Configure a drive UI integration, your app receives template variables holding 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": ["0Bz0bd"],
  "action":"open",
  "userId":"103354693083460731603"
}

To handle this information:

  1. Detect the open value in the state parameter to verify that this is a request to open a file.

  2. Check permissions, fetch file metadata, and download the file content using the files.get method.

The state parameter is URL-encoded, so your app must handle the escape characters and parse it as JSON.

Handle an Open URL for a Google Workspace document

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 an app-specific Open URL is:

{
  "exportIds": ["0Bz0bd"],
  "action":"open",
  "userId":"103354693083460731603"
}

To handle this information:

  1. Detect the open value in the state parameter to verify that this is a request to open a file.

  2. Check permissions, fetch file metadata, and determine mime type.

  3. Convert the file content using the files.export method. The following snippet shows how to convert a file as a new file type.

    Java

    String fileId = "1ZdR3L3qP4Bkq8noWLJHSr_iBau0DNT4Kli4SxNc2YEo";
    OutputStream outputStream = new ByteArrayOutputStream();
    driveService.files().export(fileId, "application/pdf")
        .executeMediaAndDownloadTo(outputStream);
    

    Python

    file_id = '1ZdR3L3qP4Bkq8noWLJHSr_iBau0DNT4Kli4SxNc2YEo'
    request = drive_service.files().export_media(fileId=file_id,
                                                 mimeType='application/pdf')
    fh = io.BytesIO()
    downloader = MediaIoBaseDownload(fh, request)
    done = False
    while done is False:
        status, done = downloader.next_chunk()
        print "Download %d%%." % int(status.progress() * 100)
    

    Node.js

    var fileId = '1ZdR3L3qP4Bkq8noWLJHSr_iBau0DNT4Kli4SxNc2YEo';
    var dest = fs.createWriteStream('/tmp/resume.pdf');
    drive.files.export({
      fileId: fileId,
      mimeType: 'application/pdf'
    })
        .on('end', function () {
          console.log('Done');
        })
        .on('error', function (err) {
          console.log('Error during download', err);
        })
        .pipe(dest);
    
  4. Display converted files as read-only or present a dialog box allowing the user to save the file as a file of the new type.

The state parameter is URL-encoded, so your app must handle the escape characters and parse it as JSON.

Next step

In addition to launching an application from Google Drive UI, applications can display a file picker to select content from within the app itself. See the files picker guide for additional details.

Apps should display converted files as read-only, or let users save them as new files.