google_drive_picker 1.0.0
google_drive_picker: ^1.0.0 copied to clipboard
A modern Flutter Google Drive file picker with OAuth, search, thumbnails, filters, and downloads.
Google Drive Picker #
google_drive_picker is a modern Flutter file picker for browsing, searching,
and downloading files from a user's Google Drive.
The package uses Google Sign-In 7 and OAuth directly. It does not require Firebase Authentication or a Google API key.
Features #
- Read-only Google Drive OAuth authorization
- Paginated listing across My Drive and Shared Drives
- Thumbnail previews with list/grid views and file-type filters
- Search, adaptive download confirmation, loading, empty, and error states
- Google Drive shortcut resolution and download-permission checks
- Blob-file downloads and Google Workspace exports:
- Google Docs →
.docx - Google Sheets →
.xlsx - Google Slides →
.pptx - Google Drawings →
.png
- Google Docs →
- Sanitized filenames and temporary-file storage
- Typed service errors and automatic HTTP client cleanup
Requirements #
| Requirement | Minimum |
|---|---|
| Flutter | 3.29 |
| Dart | 3.7 |
| Android | SDK 21 |
| iOS | 12.0 |
| macOS | 10.15 |
The current API returns a dart:io File; web is not supported.
Install #
dependencies:
google_drive_picker: ^1.0.0
Then run:
flutter pub get
Values you need #
Create these values in the Google Cloud console. OAuth client IDs are public identifiers, not secrets.
| Target | Create in Google Auth Platform | Used by the app |
|---|---|---|
| Android | Android OAuth client | Registered remotely; not pasted into Dart |
| Android sign-in | Web application OAuth client | serverClientId / GOOGLE_SERVER_CLIENT_ID |
| iOS | iOS OAuth client | clientId / GIDClientID |
| iOS callback | Reversed iOS client ID | CFBundleURLTypes URL scheme |
| macOS | iOS OAuth client using the macOS bundle ID | Same client-ID and URL-scheme setup as iOS |
You do not need:
- A Google API key
- A service-account key
- Firebase Authentication
- An OAuth client secret inside the Flutter application
Never embed a web OAuth client secret, service-account JSON, access token, or signing private key in the app or repository.
Google Cloud setup #
1. Create or select a project #
Open the Google Cloud project selector and create or select the project that will own the OAuth configuration.
Use separate development and production Cloud projects when you need isolated test users, consent settings, quotas, or credentials.
2. Enable the Google Drive API #
Open APIs & Services → Library, search for Google Drive API, open it, and select Enable.
Direct page: Google Drive API
Enabling a Drive UI integration or Google Workspace Marketplace listing is not required for this package.
3. Configure Google Auth Platform #
Open Google Auth Platform for the selected project and complete:
- Branding — set the application name, support email, logo/domain details when applicable, and developer contact email.
- Audience — choose Internal for a supported Google Workspace organization-only app, or External for other Google accounts.
- Audience → Test users — while publishing status is Testing, add every Google account that should be allowed to sign in.
- Data Access → Add or remove scopes — add:
https://www.googleapis.com/auth/drive.readonly
This is the scope requested by the package. It permits viewing and downloading Drive files but not creating, editing, or deleting them.
Testing-mode authorization is intended for development and can expire, causing test users to be asked for consent again. Before public release, review the current Google OAuth verification and restricted-scope requirements.
4. Create OAuth clients #
Open Google Auth Platform → Clients, select Create client, and create the platform clients described below.
Direct page: OAuth clients
Android configuration #
Find the application ID #
For the included example it is:
com.immichtv.google_drive_picker.example
For another app, read applicationId from
android/app/build.gradle or android/app/build.gradle.kts. Use the exact
value for the build variant being tested.
Generate signing fingerprints #
From the Flutter application's android directory run:
./gradlew signingReport
On Windows use:
.\gradlew signingReport
Under the intended variant, copy its SHA-1 fingerprint. Register debug, release, and flavor-specific signing certificates separately when they differ. For a Play-distributed build using Play App Signing, also register the app signing certificate shown under Play Console → Setup → App integrity; it can differ from the upload certificate.
Create the Android OAuth client #
In Google Auth Platform → Clients → Create client:
- Select Android.
- Enter a recognizable name.
- Enter the exact Android package/application ID.
- Enter the matching SHA-1 fingerprint.
- Create the client.
Repeat for any package-name/signing-certificate combination not covered by the first client.
Create the Web OAuth client used by Android #
Create another client with application type Web application. Copy its client ID, which looks like:
123456789012-abcdefghijklmnopqrstuvwxyz.apps.googleusercontent.com
Only the client ID is used. Do not put the generated client secret in Flutter.
Pass that web client ID to the example:
cd example
flutter run \
--dart-define=GOOGLE_SERVER_CLIENT_ID=YOUR_WEB_OAUTH_CLIENT_ID
Alternatively, Android can obtain the web client ID through a properly
configured google-services.json and Google Services Gradle integration. That
route does not require Firebase Authentication, but it does require the normal
Google Services setup. The --dart-define route is the smallest setup for this
example.
iOS configuration #
Find the bundle identifier #
The included example uses:
com.example.example
For another app, open ios/Runner.xcodeproj in Xcode and inspect
Runner target → Signing & Capabilities → Bundle Identifier, or inspect
PRODUCT_BUNDLE_IDENTIFIER in the Xcode project.
Create the iOS OAuth client #
In Google Auth Platform → Clients → Create client:
- Select iOS.
- Enter a recognizable name.
- Enter the exact bundle identifier.
- Create the client.
- Copy the normal client ID and the displayed iOS URL scheme. You can also
download the configuration plist and read
CLIENT_IDandREVERSED_CLIENT_ID.
Example normal client ID:
123456789012-abcdefghijklmnopqrstuvwxyz.apps.googleusercontent.com
Corresponding reversed client ID / URL scheme:
com.googleusercontent.apps.123456789012-abcdefghijklmnopqrstuvwxyz
Add the URL scheme #
Add the reversed OAuth client ID as a URL scheme in Info.plist:
<key>CFBundleURLTypes</key>
<array>
<dict>
<key>CFBundleTypeRole</key>
<string>Editor</string>
<key>CFBundleURLSchemes</key>
<array>
<string>YOUR_REVERSED_CLIENT_ID</string>
</array>
</dict>
</array>
For the example, replace YOUR_REVERSED_CLIENT_ID in
example/ios/Runner/Info.plist.
Supply the normal iOS client ID #
Choose either configuration method.
Method A — pass it when running the example:
cd example
flutter run \
--dart-define=GOOGLE_CLIENT_ID=YOUR_IOS_OAUTH_CLIENT_ID
Method B — add it to ios/Runner/Info.plist:
<key>GIDClientID</key>
<string>YOUR_IOS_OAUTH_CLIENT_ID</string>
Then initialize without an explicit clientId. The reversed URL scheme is
required for both methods so Google can return to the application after
authentication.
macOS configuration #
Create an iOS OAuth client using the macOS bundle identifier, then apply the
same GIDClientID and reversed URL scheme configuration to
macos/Runner/Info.plist.
Google Sign-In on macOS also requires keychain sharing. Add the access group
required by the current google_sign_in_ios integration documentation to the
Runner entitlements. This repository's example currently contains Android and
iOS targets only.
Run the included example #
Install packages:
flutter pub get
cd example
flutter pub get
List available devices:
flutter devices
Run Android:
flutter run \
-d YOUR_ANDROID_DEVICE_ID \
--dart-define=GOOGLE_SERVER_CLIENT_ID=YOUR_WEB_OAUTH_CLIENT_ID
Run iOS:
flutter run \
-d YOUR_IOS_DEVICE_OR_SIMULATOR_ID \
--dart-define=GOOGLE_CLIENT_ID=YOUR_IOS_OAUTH_CLIENT_ID
If identifiers are already supplied through native configuration, omit their
corresponding --dart-define arguments.
Usage #
Initialize once before runApp. Platform configuration can provide the client
identifiers, so both arguments are optional:
import 'dart:io';
import 'package:flutter/material.dart';
import 'package:google_drive_picker/google_drive_picker.dart';
Future<void> main() async {
WidgetsFlutterBinding.ensureInitialized();
await GoogleDrivePicker.instance.initialize(
clientId: optionalIosClientId,
serverClientId: optionalWebClientId,
);
runApp(const MyApp());
}
When supporting both Android and Apple platforms from one codebase, only pass the Apple client ID on iOS/macOS:
await GoogleDrivePicker.instance.initialize(
clientId: (Platform.isIOS || Platform.isMacOS) ? iosClientId : null,
serverClientId: webClientId,
);
The included example performs this platform check automatically for its
GOOGLE_CLIENT_ID value.
Open the picker from a user interaction:
final File? file = await GoogleDrivePicker.instance.pickFile(
context: context,
);
if (file != null) {
// Open it, inspect it, or copy it to permanent application storage.
debugPrint(file.path);
}
Sign out when your application needs to end the Google session:
await GoogleDrivePicker.instance.signOut();
File lifecycle #
The returned file is written to the platform temporary directory. The operating system may delete it at any time. Copy it to application documents or other permanent storage if it must survive cache cleanup.
An existing temporary file with the same name may be replaced by a later download.
Errors and cancellation #
- Cancelling Google Sign-In or closing the picker returns
null. GoogleDriveAuthorizationExceptionindicates that Drive authorization was not available.GoogleDriveFileExceptioncovers unsupported exports, missing metadata, and files the user cannot download.- Other Google Sign-In, Drive API, network, and filesystem failures propagate to the caller.
Wrap picker calls in try/catch and present an appropriate retry action.
Production release checklist #
- Replace the sample package and bundle identifiers with identifiers owned by your application.
- Use production OAuth clients that exactly match those identifiers.
- Register Android debug, upload, and Play App Signing certificates as applicable.
- Move the Google Auth Platform audience out of Testing when appropriate.
- Complete brand/OAuth verification required for the selected audience and Drive scope.
- Provide verified homepage, privacy-policy, and terms URLs when requested by Google Auth Platform.
- Test release builds; debug credentials do not automatically authorize a differently signed release build.
- Verify sign-in with an account that is not a project owner.
- Review Drive API quotas and error reporting in the production Cloud project.
- Never log authorization headers, access tokens, or downloaded user content.
Official configuration references #
- Google Auth Platform OAuth clients
- Google OAuth app verification
- Google Drive API scopes
- Google Sign-In for Android
- Google Sign-In for iOS and macOS
Migration and support #
- Migration guide from 1.x
- Troubleshooting guide
- Complete example
- Changelog
The deprecated setAPIKey method is a no-op retained only for short-term source
compatibility. New code should not call it.