Skip to content

Kepler.gl is a powerful open source geospatial analysis tool for large-scale data sets.

feat(demo-app): add Google Drive cloud storage provider (#3623)

Igor Dykhtab313dfa28997
diff --git a/.env.template b/.env.template
index a6ed4bead..920d176cd 100644
--- a/.env.template
+++ b/.env.template
@@ -9,3 +9,4 @@ FoursquareClientId=...
FoursquareDomain=...
FoursquareAPIURL=...
FoursquareUserMapsURL=...
+GoogleDriveClientId=...
diff --git a/docs/api-reference/cloud-providers/README.md b/docs/api-reference/cloud-providers/README.md
index f9c4faeec..c0ccc0d03 100644
--- a/docs/api-reference/cloud-providers/README.md
+++ b/docs/api-reference/cloud-providers/README.md
@@ -37,7 +37,13 @@ Cloud-providers providers can implement the following properties
## Adding a new Cloud Provider
-An instance of the provider is added to array of cloud providers in the file `src/cloud-providers/providers.js` then passed to kepler.gl demo app. An example provider: [Dropbox Provider](https://github.com/keplergl/kepler.gl/blob/master/examples/demo-app/src/cloud-providers/dropbox-provider.js)
+An instance of the provider is added to the array of cloud providers in
+[`examples/demo-app/src/cloud-providers/index.js`](https://github.com/keplergl/kepler.gl/blob/master/examples/demo-app/src/cloud-providers/index.js)
+then passed to the kepler.gl demo app.
+
+Example providers:
+- [Dropbox](https://github.com/keplergl/kepler.gl/blob/master/examples/demo-app/src/cloud-providers/dropbox/dropbox-provider.js)
+- [Google Drive](https://github.com/keplergl/kepler.gl/blob/master/examples/demo-app/src/cloud-providers/google-drive/google-drive-provider.js)
```js
import {Provider} from '@kepler.gl/cloud-providers';
diff --git a/examples/demo-app/README.md b/examples/demo-app/README.md
index 9c6fbf847..e4f35ca8b 100644
--- a/examples/demo-app/README.md
+++ b/examples/demo-app/README.md
@@ -44,8 +44,11 @@ CARTO_CLIENT_ID=<your_carto_client_id>
FOURSQUARE_CLIENT_ID=<your_foursquare_client_id>
FOURSQUARE_DOMAIN=<your_foursquare_domain>
FOURSQUARE_USER_MAPS_URL=<your_foursquare_user_map_url>
+GoogleDriveClientId=<your_google_oauth_web_client_id>
```
+For Google Drive, create an OAuth 2.0 **Web application** client in [Google Cloud Console](https://console.cloud.google.com/), enable the **Google Drive API**, and add your demo-app origin (e.g. `http://localhost:8080`) to Authorized JavaScript origins. Only the client ID is required (no API key).
+
#### 3. Start the app
```sh
diff --git a/examples/demo-app/esbuild.config.mjs b/examples/demo-app/esbuild.config.mjs
index c9dcc1ad2..03a5ac4b3 100644
--- a/examples/demo-app/esbuild.config.mjs
+++ b/examples/demo-app/esbuild.config.mjs
@@ -117,6 +117,7 @@ const config = {
'process.env.FoursquareDomain': JSON.stringify(process.env.FoursquareDomain || ''),
'process.env.FoursquareAPIURL': JSON.stringify(process.env.FoursquareAPIURL || ''),
'process.env.FoursquareUserMapsURL': JSON.stringify(process.env.FoursquareUserMapsURL || ''),
+ 'process.env.GoogleDriveClientId': JSON.stringify(process.env.GoogleDriveClientId || ''),
'process.env.NODE_ENV': NODE_ENV
},
plugins: [
diff --git a/examples/demo-app/src/cloud-providers/google-drive/google-drive-icon.js b/examples/demo-app/src/cloud-providers/google-drive/google-drive-icon.js
new file mode 100644
index 000000000..af9bd5049
--- /dev/null
+++ b/examples/demo-app/src/cloud-providers/google-drive/google-drive-icon.js
@@ -0,0 +1,52 @@
+// SPDX-License-Identifier: MIT
+// Copyright contributors to the kepler.gl project
+
+// Simplified Google Drive mark (public domain geometry), adapted for IconWrapper.
+import React, {Component} from 'react';
+import {Icons} from '@kepler.gl/components';
+import PropTypes from 'prop-types';
+
+export default class GoogleDriveIcon extends Component {
+ static propTypes = {
+ /** Set the height of the icon, ex. '16px' */
+ height: PropTypes.string,
+ colors: PropTypes.arrayOf(PropTypes.string)
+ };
+
+ static defaultProps = {
+ height: '16px',
+ predefinedClassName: 'data-ex-icons-google-drive',
+ totalColor: 1
+ };
+
+ render() {
+ return (
+ <Icons.IconWrapper {...this.props} viewBox="0 0 87.3 78">
+ <path
+ d="M6.6 66.85l3.85 6.65c.8 1.4 1.95 2.5 3.3 3.3l13.75-23.8H0c0 1.55.4 3.1 1.2 4.5l5.4 9.35z"
+ fill="#0066da"
+ />
+ <path
+ d="M43.65 25L29.9 1.2C28.55 2 27.4 3.1 26.6 4.5L1.2 48.35c-.8 1.4-1.2 2.95-1.2 4.5h27.5L43.65 25z"
+ fill="#00ac47"
+ />
+ <path
+ d="M73.55 76.8c1.35-.8 2.5-1.9 3.3-3.3l1.6-2.75 7.65-13.25c.8-1.4 1.2-2.95 1.2-4.5H59.85l5.25 9.1 8.45 14.7z"
+ fill="#ea4335"
+ />
+ <path
+ d="M43.65 25L57.4 1.2C56.05.4 54.5 0 52.9 0H34.4c-1.6 0-3.15.45-4.5 1.2L43.65 25z"
+ fill="#00832d"
+ />
+ <path
+ d="M59.85 53H27.5l-13.75 23.8c1.35.8 2.9 1.2 4.5 1.2h50.8c1.6 0 3.15-.45 4.5-1.2L59.85 53z"
+ fill="#2684fc"
+ />
+ <path
+ d="M73.4 26.5l-12.7-22c-.8-1.4-1.95-2.5-3.3-3.3L43.65 25l16.2 28h27.45c0-1.55-.4-3.1-1.2-4.5l-12.7-22z"
+ fill="#ffba00"
+ />
+ </Icons.IconWrapper>
+ );
+ }
+}
diff --git a/examples/demo-app/src/cloud-providers/google-drive/google-drive-provider.js b/examples/demo-app/src/cloud-providers/google-drive/google-drive-provider.js
new file mode 100644
index 000000000..2a0485534
--- /dev/null
+++ b/examples/demo-app/src/cloud-providers/google-drive/google-drive-provider.js
@@ -0,0 +1,702 @@
+// SPDX-License-Identifier: MIT
+// Copyright contributors to the kepler.gl project
+
+import {KEPLER_FORMAT, Provider} from '@kepler.gl/cloud-providers';
+import {loadScript} from '../../utils/load-script';
+import GoogleDriveIcon from './google-drive-icon';
+
+const NAME = 'google-drive';
+const DISPLAY_NAME = 'Google Drive';
+const STORAGE_KEY = 'google-drive';
+const APP_FOLDER_NAME = 'Kepler.gl';
+const MIME_JSON = 'application/json';
+const MIME_PNG = 'image/png';
+const DRIVE_API = 'https://www.googleapis.com/drive/v3';
+const DRIVE_UPLOAD_API = 'https://www.googleapis.com/upload/drive/v3';
+const USERINFO_API = 'https://www.googleapis.com/oauth2/v3/userinfo';
+const GIS_SCRIPT_URL = 'https://accounts.google.com/gsi/client';
+const DRIVE_SCOPE = 'https://www.googleapis.com/auth/drive.file';
+const SCOPES = [DRIVE_SCOPE, 'openid', 'profile', 'email'].join(' ');
+
+const PRIVATE_STORAGE_ENABLED = true;
+const SHARING_ENABLED = false;
+const MANAGEMENT_URL = 'https://drive.google.com/drive/my-drive';
+
+/**
+ * Google Drive cloud provider using Google Identity Services (token model)
+ * and Drive API v3 REST. Only Client ID is required (no API key).
+ *
+ * Create an OAuth 2.0 Web client in Google Cloud Console, enable Drive API,
+ * and authorize your demo-app origin (e.g. http://localhost:8080).
+ */
+export default class GoogleDriveProvider extends Provider {
+ constructor({clientId, appName = APP_FOLDER_NAME} = {}) {
+ super({name: NAME, displayName: DISPLAY_NAME, icon: GoogleDriveIcon});
+ this.clientId = clientId || null;
+ this.appName = appName;
+ this._accessToken = null;
+ this._tokenClient = null;
+ this._folderId = null;
+ this._shareUrl = null;
+ // Serialize GIS token requests — TokenClient exposes a single callback pair.
+ this._tokenRequestChain = Promise.resolve();
+ this._thumbnailCache = new Map();
+ }
+
+ isEnabled() {
+ return Boolean(this.clientId);
+ }
+
+ hasPrivateStorage() {
+ return PRIVATE_STORAGE_ENABLED;
+ }
+
+ hasSharingUrl() {
+ return SHARING_ENABLED;
+ }
+
+ hasLazyThumbnails() {
+ return true;
+ }
+
+ getManagementUrl() {
+ return MANAGEMENT_URL;
+ }
+
+ getShareUrl(fullUrl = true) {
+ if (!this._shareUrl) {
+ return '';
+ }
+ return fullUrl
+ ? `${window.location.protocol}//${window.location.host}${this._shareUrl}`
+ : this._shareUrl;
+ }
+
+ getMapUrl(loadParams = {}) {
+ const {id} = loadParams;
+ return id || '';
+ }
+
+ async getAccessToken() {
+ const stored = this._readStorage();
+
+ // Reuse cached token only while expiresAt says it is still valid
+ if (stored?.token && !this._isExpired(stored)) {
+ const scope = stored.scope || '';
+ if (scope && !scope.split(/\s+/).includes(DRIVE_SCOPE)) {
+ this._clearStorage();
+ this._accessToken = null;
+ return null;
+ }
+ this._accessToken = stored.token;
+ return this._accessToken;
+ }
+
+ const hadToken = Boolean(this._accessToken || stored?.token);
+ this._accessToken = null;
+
+ // Silent refresh after expiry (or if memory still held a stale token)
+ if (hadToken && this.clientId) {
+ try {
+ await this._ensureTokenClient();
+ const tokenResponse = await this._requestAccessToken({prompt: ''});
+ if (!this._hasDriveScope(tokenResponse)) {
+ this._clearStorage();
+ this._accessToken = null;
+ return null;
+ }
+ return tokenResponse.access_token;
+ } catch (err) {
+ this._clearStorage();
+ this._accessToken = null;
+ return null;
+ }
+ }
+
+ return null;
+ }
+
+ async getUser() {
+ const token = await this.getAccessToken();
+ if (!token) {
+ return null;
+ }
+
+ const stored = this._readStorage();
+ if (stored?.user && !this._isExpired(stored)) {
+ return stored.user;
+ }
+
+ try {
+ const user = await this._fetchUser(token);
+ this._writeStorage({token, user});
+ return user;
+ } catch (err) {
+ this._clearStorage();
+ this._accessToken = null;
+ return null;
+ }
+ }
+
+ getUserName() {
+ const stored = this._readStorage();
+ return stored?.user?.name || '';
+ }
+
+ async login() {
+ if (!this.clientId) {
+ throw new Error(
+ 'Google Drive Client ID is not configured. Set GoogleDriveClientId in your .env file.'
+ );
+ }
+
+ await this._ensureTokenClient();
+ // Must be called from a user gesture so the consent popup is not blocked.
+ // Google may grant Sign-In scopes but not Drive (granular consent) — verify and re-ask.
+ let tokenResponse = await this._requestAccessToken({prompt: 'select_account'});
+ if (!this._hasDriveScope(tokenResponse)) {
+ tokenResponse = await this._requestAccessToken({
+ prompt: 'consent',
+ scope: DRIVE_SCOPE
+ });
+ }
+ if (!this._hasDriveScope(tokenResponse)) {
+ throw new Error(
+ 'Google Drive access was not granted. On the consent screen, allow Google Drive / See, edit, create, and delete only the specific Google Drive files you use with this app.'
+ );
+ }
+
+ const user = await this._fetchUser(tokenResponse.access_token);
+ this._writeStorage({
+ token: tokenResponse.access_token,
+ user,
+ scope: tokenResponse.scope
+ });
+ return user;
+ }
+
+ async logout() {
+ const token = this._accessToken || this._readStorage()?.token;
+ if (token && window.google?.accounts?.oauth2?.revoke) {
+ await new Promise(resolve => {
+ window.google.accounts.oauth2.revoke(token, resolve);
+ });
+ }
+ this._accessToken = null;
+ this._folderId = null;
+ this._shareUrl = null;
+ this._thumbnailCache = new Map();
+ this._clearStorage();
+ }
+
+ async listMaps() {
+ const token = await this._requireToken();
+ const folderId = await this._ensureAppFolder(token);
+ const q = [`'${folderId}' in parents`, `mimeType = '${MIME_JSON}'`, 'trashed = false'].join(
+ ' and '
+ );
+
+ const data = await this._driveFetch(
+ `${DRIVE_API}/files?q=${encodeURIComponent(
+ q
+ )}&fields=files(id,name,modifiedTime,description)&orderBy=modifiedTime desc&pageSize=100`,
+ {token}
+ );
+
+ // One metadata list for PNGs — CloudItem lazy-loads bytes via getMapThumbnail.
+ const pngQ = [`'${folderId}' in parents`, `mimeType = '${MIME_PNG}'`, 'trashed = false'].join(
+ ' and '
+ );
+ const pngData = await this._driveFetch(
+ `${DRIVE_API}/files?q=${encodeURIComponent(pngQ)}&fields=files(id,name)&pageSize=100`,
+ {token}
+ );
+ const thumbnailIdByTitle = {};
+ (pngData.files || []).forEach(png => {
+ const title = png.name.replace(/\.png$/i, '');
+ if (!thumbnailIdByTitle[title]) {
+ thumbnailIdByTitle[title] = png.id;
+ }
+ });
+
+ return (data.files || []).map(file => {
+ const title = file.name.replace(/\.json$/i, '');
+ return {
+ id: file.id,
+ title,
+ description: file.description || '',
+ updatedAt: file.modifiedTime ? new Date(file.modifiedTime).getTime() : undefined,
+ privateMap: true,
+ loadParams: {
+ id: file.id,
+ path: file.name,
+ thumbnailId: thumbnailIdByTitle[title]
+ }
+ };
+ });
+ }
+
+ async getMapThumbnail(map) {
+ if (map?.thumbnail) {
+ return map.thumbnail;
+ }
+ const thumbnailId = map?.loadParams?.thumbnailId;
+ if (!thumbnailId) {
+ return undefined;
+ }
+ if (this._thumbnailCache.has(thumbnailId)) {
+ return this._thumbnailCache.get(thumbnailId);
+ }
+
+ try {
+ const token = await this._requireToken();
+ const response = await fetch(`${DRIVE_API}/files/${thumbnailId}?alt=media`, {
+ headers: {Authorization: `Bearer ${token}`}
+ });
+ if (!response.ok) {
+ return undefined;
+ }
+ const blob = await response.blob();
+ const dataUrl = await this._blobToDataUrl(blob);
+ this._thumbnailCache.set(thumbnailId, dataUrl);
+ return dataUrl;
+ } catch (err) {
+ return undefined;
+ }
+ }
+
+ async uploadMap({mapData, options = {}}) {
+ const token = await this._requireToken();
+ const {map, thumbnail} = mapData;
+ const title = (map.info && map.info.title) || 'Untitled Map';
+ const description = (map.info && map.info.description) || '';
+ const fileName = `${title}.json`;
+ const folderId = await this._ensureAppFolder(token);
+
+ const existing = await this._findFileByName(token, folderId, fileName);
+ if (existing && !options.overwrite) {
+ throw this.getFileConflictError();
+ }
+
+ let fileMeta;
+ if (existing && options.overwrite) {
+ fileMeta = await this._updateJsonFile(token, existing.id, map, description);
+ } else {
+ fileMeta = await this._createMultipartFile({
+ token,
+ name: fileName,
+ description,
+ parents: [folderId],
+ mimeType: MIME_JSON,
+ body: JSON.stringify(map)
+ });
+ }
+
+ if (thumbnail) {
+ const pngName = `${title}.png`;
+ const existingPng = await this._findFileByName(token, folderId, pngName);
+ if (existingPng) {
+ await this._updateBinaryFile(token, existingPng.id, thumbnail, MIME_PNG);
+ } else {
+ await this._createMultipartFile({
+ token,
+ name: pngName,
+ parents: [folderId],
+ mimeType: MIME_PNG,
+ body: thumbnail
+ });
+ }
+ }
+
+ if (options.isPublic) {
+ await this._makePublic(token, fileMeta.id);
+ this._shareUrl = `/demo/map/${NAME}?id=${fileMeta.id}`;
+ return {
+ id: fileMeta.id,
+ title,
+ description,
+ privateMap: false,
+ loadParams: {id: fileMeta.id, path: fileName},
+ shareUrl: this.getShareUrl(true),
+ folderLink: MANAGEMENT_URL
+ };
+ }
+
+ return {
+ id: fileMeta.id,
+ title,
+ description,
+ privateMap: true,
+ loadParams: {id: fileMeta.id, path: fileName}
+ };
+ }
+
+ async downloadMap(loadParams = {}) {
+ // listMaps sets {id, path: fileName}; URL loads may pass ?path=<fileId>
+ const id = loadParams.id || loadParams.path;
+ if (!id || String(id).endsWith('.json')) {
+ throw new Error('Google Drive: no file id provided in loadParams');
+ }
+
+ const token = await this._requireToken();
+ const response = await fetch(`${DRIVE_API}/files/${id}?alt=media`, {
+ headers: {Authorization: `Bearer ${token}`}
+ });
+
+ if (!response.ok) {
+ if (response.status === 401) {
+ this._accessToken = null;
+ this._clearStorage();
+ }
+ const errText = await response.text();
+ throw new Error(`Google Drive download failed: ${response.status} ${errText}`);
+ }
+
+ const map = await response.json();
+ return {map, format: KEPLER_FORMAT};
+ }
+
+ // —— private helpers ——
+
+ async _requireToken() {
+ const token = await this.getAccessToken();
+ if (!token) {
+ throw new Error('Not logged in to Google Drive');
+ }
+ return token;
+ }
+
+ async _ensureTokenClient() {
+ if (!window.google?.accounts?.oauth2) {
+ await loadScript(GIS_SCRIPT_URL);
+ }
+ if (!window.google?.accounts?.oauth2) {
+ throw new Error('Google Identity Services failed to load');
+ }
+ if (!this._tokenClient) {
+ // callback is set per request in _requestAccessToken
+ this._tokenClient = window.google.accounts.oauth2.initTokenClient({
+ client_id: this.clientId,
+ scope: SCOPES,
+ callback: () => {}
+ });
+ }
+ }
+
+ _hasDriveScope(tokenResponse) {
+ if (!tokenResponse?.access_token) {
+ return false;
+ }
+ if (window.google?.accounts?.oauth2?.hasGrantedAllScopes) {
+ return window.google.accounts.oauth2.hasGrantedAllScopes(tokenResponse, DRIVE_SCOPE);
+ }
+ const granted = tokenResponse.scope || '';
+ return granted.split(' ').includes(DRIVE_SCOPE);
+ }
+
+ _requestAccessToken({prompt, scope} = {}) {
+ const run = () =>
+ new Promise((resolve, reject) => {
+ this._tokenClient.callback = response => {
+ if (response.error) {
+ reject(new Error(response.error_description || response.error));
+ return;
+ }
+ this._accessToken = response.access_token;
+ const expiresIn = Number(response.expires_in) || 3600;
+ this._writeStorage({
+ token: response.access_token,
+ expiresAt: Date.now() + expiresIn * 1000,
+ scope: response.scope,
+ user: this._readStorage()?.user
+ });
+ resolve(response);
+ };
+ this._tokenClient.error_callback = error => {
+ reject(new Error(error?.type || 'Google OAuth error'));
+ };
+ const overrides = {};
+ if (prompt !== undefined) {
+ overrides.prompt = prompt;
+ }
+ if (scope) {
+ overrides.scope = scope;
+ }
+ this._tokenClient.requestAccessToken(overrides);
+ });
+
+ // Queue so overlapping silent refresh + login cannot overwrite callbacks.
+ const next = this._tokenRequestChain.then(run, run);
+ this._tokenRequestChain = next.then(
+ () => undefined,
+ () => undefined
+ );
+ return next;
+ }
+
+ async _fetchUser(token) {
+ const response = await fetch(USERINFO_API, {
+ headers: {Authorization: `Bearer ${token}`}
+ });
+ if (!response.ok) {
+ throw new Error('Failed to fetch Google user profile');
+ }
+ const profile = await response.json();
+ return {
+ name: profile.name || profile.email || 'Google User',
+ email: profile.email || '',
+ thumbnail: profile.picture
+ };
+ }
+
+ async _ensureAppFolder(token) {
+ if (this._folderId) {
+ return this._folderId;
+ }
+
+ // Only My Drive root — avoids picking a same-named folder elsewhere in Drive.
+ // If duplicates exist at root, prefer the oldest (original app folder).
+ const escapedName = this.appName.replace(/'/g, "\\'");
+ const q = [
+ `name = '${escapedName}'`,
+ `'root' in parents`,
+ `mimeType = 'application/vnd.google-apps.folder'`,
+ 'trashed = false'
+ ].join(' and ');
+
+ const listed = await this._driveFetch(
+ `${DRIVE_API}/files?q=${encodeURIComponent(
+ q
+ )}&fields=files(id,name,createdTime)&orderBy=createdTime&pageSize=10`,
+ {token}
+ );
+
+ if (listed.files && listed.files.length) {
+ this._folderId = listed.files[0].id;
+ return this._folderId;
+ }
+
+ const created = await this._driveFetch(`${DRIVE_API}/files?fields=id,name`, {
+ token,
+ method: 'POST',
+ headers: {'Content-Type': 'application/json'},
+ body: JSON.stringify({
+ name: this.appName,
+ mimeType: 'application/vnd.google-apps.folder',
+ parents: ['root']
+ })
+ });
+
+ this._folderId = created.id;
+ return this._folderId;
+ }
+
+ async _findFileByName(token, folderId, name) {
+ const q = [
+ `'${folderId}' in parents`,
+ `name = '${name.replace(/'/g, "\\'")}'`,
+ 'trashed = false'
+ ].join(' and ');
+
+ const data = await this._driveFetch(
+ `${DRIVE_API}/files?q=${encodeURIComponent(q)}&fields=files(id,name)&pageSize=1`,
+ {token}
+ );
+ return data.files && data.files[0] ? data.files[0] : null;
+ }
+
+ async _createMultipartFile({token, name, parents, mimeType, body, description}) {
+ const metadataPayload = {name, mimeType, parents};
+ if (description !== undefined) {
+ metadataPayload.description = description;
+ }
+ const metadata = JSON.stringify(metadataPayload);
+ const boundary = 'keplergl_google_drive_boundary';
+ const delimiter = `--${boundary}\r\n`;
+ const closeDelimiter = `\r\n--${boundary}--`;
+
+ let filePart;
+ if (body instanceof Blob) {
+ const buffer = await body.arrayBuffer();
+ filePart = new Uint8Array(buffer);
+ } else {
+ filePart = typeof body === 'string' ? body : JSON.stringify(body);
+ }
+
+ const preamble =
+ `${delimiter}Content-Type: application/json; charset=UTF-8\r\n\r\n` +
+ `${metadata}\r\n` +
+ `${delimiter}Content-Type: ${mimeType}\r\n\r\n`;
+
+ const preambleBytes = new TextEncoder().encode(preamble);
+ const closingBytes = new TextEncoder().encode(closeDelimiter);
+ const contentBytes =
+ typeof filePart === 'string' ? new TextEncoder().encode(filePart) : filePart;
+
+ const requestBody = new Uint8Array(
+ preambleBytes.length + contentBytes.length + closingBytes.length
+ );
+ requestBody.set(preambleBytes, 0);
+ requestBody.set(contentBytes, preambleBytes.length);
+ requestBody.set(closingBytes, preambleBytes.length + contentBytes.length);
+
+ return this._driveFetch(
+ `${DRIVE_UPLOAD_API}/files?uploadType=multipart&fields=id,name,description`,
+ {
+ token,
+ method: 'POST',
+ headers: {
+ 'Content-Type': `multipart/related; boundary=${boundary}`
+ },
+ body: requestBody
+ }
+ );
+ }
+
+ async _updateJsonFile(token, fileId, map, description = '') {
+ const fileMeta = await this._driveFetch(
+ `${DRIVE_UPLOAD_API}/files/${fileId}?uploadType=media&fields=id,name`,
+ {
+ token,
+ method: 'PATCH',
+ headers: {'Content-Type': MIME_JSON},
+ body: JSON.stringify(map)
+ }
+ );
+
+ // Media upload does not update metadata; patch description separately.
+ await this._driveFetch(`${DRIVE_API}/files/${fileId}?fields=id,name,description`, {
+ token,
+ method: 'PATCH',
+ headers: {'Content-Type': 'application/json'},
+ body: JSON.stringify({description})
+ });
+
+ return {...fileMeta, description};
+ }
+
+ _updateBinaryFile(token, fileId, blob, mimeType) {
+ return this._driveFetch(`${DRIVE_UPLOAD_API}/files/${fileId}?uploadType=media&fields=id,name`, {
+ token,
+ method: 'PATCH',
+ headers: {'Content-Type': mimeType},
+ body: blob
+ });
+ }
+
+ async _makePublic(token, fileId) {
+ try {
+ await this._driveFetch(`${DRIVE_API}/files/${fileId}/permissions`, {
+ token,
+ method: 'POST',
+ headers: {'Content-Type': 'application/json'},
+ body: JSON.stringify({role: 'reader', type: 'anyone'})
+ });
+ } catch (err) {
+ const msg = String(err.message || err);
+ // Drive returns 409 / alreadyExists when the permission is already set
+ if (/alreadyExists|already exists|409|conflict/i.test(msg)) {
+ return;
+ }
+ throw err;
+ }
+ }
+
+ async _driveFetch(url, {token, method = 'GET', headers = {}, body} = {}) {
+ const response = await fetch(url, {
+ method,
+ headers: {
+ Authorization: `Bearer ${token}`,
+ ...headers
+ },
+ body
+ });
+
+ if (!response.ok) {
+ let message = response.statusText || 'Request failed';
+ let reason = '';
+ try {
+ const errJson = await response.json();
+ message = errJson.error?.message || message;
+ reason = errJson.error?.errors?.[0]?.reason || errJson.error?.status || '';
+ } catch (e) {
+ // ignore parse errors
+ }
+ const detail = [response.status, reason, message].filter(Boolean).join(' ');
+ if (response.status === 401) {
+ this._accessToken = null;
+ this._clearStorage();
+ throw new Error('Google Drive session expired. Log in again.');
+ }
+ if (
+ response.status === 403 &&
+ /insufficient.*(scope|authentication)/i.test(`${message} ${reason}`)
+ ) {
+ this._accessToken = null;
+ this._clearStorage();
+ throw new Error(
+ 'Google Drive permission is missing. Log out of Google Drive in Kepler, then log in again and allow Drive access (do not uncheck it on the consent screen).'
+ );
+ }
+ throw new Error(`Google Drive API error: ${detail}`);
+ }
+
+ if (response.status === 204) {
+ return null;
+ }
+ return response.json();
+ }
+
+ _blobToDataUrl(blob) {
+ return new Promise((resolve, reject) => {
+ const reader = new FileReader();
+ reader.onload = () => resolve(reader.result);
+ reader.onerror = reject;
+ reader.readAsDataURL(blob);
+ });
+ }
+
+ _readStorage() {
+ if (!window.localStorage) {
+ return null;
+ }
+ try {
+ const raw = window.localStorage.getItem(STORAGE_KEY);
+ return raw ? JSON.parse(raw) : null;
+ } catch (err) {
+ return null;
+ }
+ }
+
+ _writeStorage({token, user, expiresAt, scope}) {
+ if (!window.localStorage) {
+ return;
+ }
+ const prev = this._readStorage() || {};
+ window.localStorage.setItem(
+ STORAGE_KEY,
+ JSON.stringify({
+ token: token !== undefined ? token : prev.token,
+ user: user !== undefined ? user : prev.user,
+ expiresAt: expiresAt !== undefined ? expiresAt : prev.expiresAt,
+ scope: scope !== undefined ? scope : prev.scope,
+ timestamp: new Date().toISOString()
+ })
+ );
+ }
+
+ _clearStorage() {
+ if (window.localStorage) {
+ window.localStorage.removeItem(STORAGE_KEY);
+ }
+ }
+
+ _isExpired(stored) {
+ if (!stored?.expiresAt) {
+ // Unknown expiry — treat as still usable until a request fails
+ return false;
+ }
+ // Refresh a minute early
+ return Date.now() > stored.expiresAt - 60 * 1000;
+ }
+}
diff --git a/examples/demo-app/src/cloud-providers/index.js b/examples/demo-app/src/cloud-providers/index.js
index c1ea2e3dc..50bca696e 100644
--- a/examples/demo-app/src/cloud-providers/index.js
+++ b/examples/demo-app/src/cloud-providers/index.js
@@ -6,6 +6,7 @@ import {CLOUD_PROVIDERS_CONFIGURATION} from '../constants/default-settings';
import DropboxProvider from './dropbox/dropbox-provider';
import CartoProvider from './carto/carto-provider';
import FoursquareProvider from './foursquare/foursquare-provider';
+import GoogleDriveProvider from './google-drive/google-drive-provider';
const {
DROPBOX_CLIENT_ID,
@@ -13,10 +14,12 @@ const {
FOURSQUARE_CLIENT_ID,
FOURSQUARE_DOMAIN,
FOURSQUARE_API_URL,
- FOURSQUARE_USER_MAPS_URL
+ FOURSQUARE_USER_MAPS_URL,
+ GOOGLE_DRIVE_CLIENT_ID
} = CLOUD_PROVIDERS_CONFIGURATION;
const DROPBOX_CLIENT_NAME = 'Kepler.gl Demo App';
+const GOOGLE_DRIVE_APP_NAME = 'Kepler.gl';
export const DEFAULT_CLOUD_PROVIDER = 'dropbox';
@@ -28,7 +31,11 @@ export const CLOUD_PROVIDERS = [
userMapsURL: FOURSQUARE_USER_MAPS_URL
}),
new DropboxProvider(DROPBOX_CLIENT_ID, DROPBOX_CLIENT_NAME),
- new CartoProvider(CARTO_CLIENT_ID)
+ new CartoProvider(CARTO_CLIENT_ID),
+ new GoogleDriveProvider({
+ clientId: GOOGLE_DRIVE_CLIENT_ID,
+ appName: GOOGLE_DRIVE_APP_NAME
+ })
];
export function getCloudProvider(providerName) {
diff --git a/examples/demo-app/src/constants/default-settings.js b/examples/demo-app/src/constants/default-settings.js
index 0fa1d59c7..d383926d8 100644
--- a/examples/demo-app/src/constants/default-settings.js
+++ b/examples/demo-app/src/constants/default-settings.js
@@ -43,6 +43,14 @@ export const DEFAULT_FEATURE_FLAGS = {
cloudStorage: true
};
+/**
+ * Public OAuth Web client ID for the Kepler.gl demo Google Drive provider.
+ * Safe to ship in the client bundle (same as DropboxClientId). Override via
+ * GoogleDriveClientId env for local/Netlify if needed.
+ */
+export const DEFAULT_GOOGLE_DRIVE_CLIENT_ID =
+ '955797395662-m2aetl68gd71shdgtsmbbj2pvuk1psgc.apps.googleusercontent.com';
+
export const CLOUD_PROVIDERS_CONFIGURATION = {
MAPBOX_TOKEN: process.env.MapboxAccessToken, // eslint-disable-line
DROPBOX_CLIENT_ID: process.env.DropboxClientId, // eslint-disable-line
@@ -51,5 +59,7 @@ export const CLOUD_PROVIDERS_CONFIGURATION = {
FOURSQUARE_CLIENT_ID: process.env.FoursquareClientId, // eslint-disable-line
FOURSQUARE_DOMAIN: process.env.FoursquareDomain, // eslint-disable-line
FOURSQUARE_API_URL: process.env.FoursquareAPIURL, // eslint-disable-line
- FOURSQUARE_USER_MAPS_URL: process.env.FoursquareUserMapsURL // eslint-disable-line
+ FOURSQUARE_USER_MAPS_URL: process.env.FoursquareUserMapsURL, // eslint-disable-line
+ GOOGLE_DRIVE_CLIENT_ID:
+ process.env.GoogleDriveClientId || DEFAULT_GOOGLE_DRIVE_CLIENT_ID // eslint-disable-line
};
diff --git a/examples/demo-app/src/utils/load-script.js b/examples/demo-app/src/utils/load-script.js
new file mode 100644
index 000000000..20b23e7c8
--- /dev/null
+++ b/examples/demo-app/src/utils/load-script.js
@@ -0,0 +1,47 @@
+// SPDX-License-Identifier: MIT
+// Copyright contributors to the kepler.gl project
+
+/**
+ * Dynamically load an external script once.
+ * @param {string} src
+ * @returns {Promise<void>}
+ */
+export function loadScript(src) {
+ if (typeof document === 'undefined') {
+ return Promise.reject(new Error('Cannot load script outside the browser'));
+ }
+
+ const existing = document.querySelector(`script[src="${src}"]`);
+ if (existing) {
+ if (existing.dataset.loaded === 'true') {
+ return Promise.resolve();
+ }
+ return new Promise((resolve, reject) => {
+ existing.addEventListener(
+ 'load',
+ () => {
+ existing.dataset.loaded = 'true';
+ resolve();
+ },
+ {once: true}
+ );
+ existing.addEventListener(
+ 'error',
+ () => reject(new Error(`Failed to load script: ${src}`)),
+ {once: true}
+ );
+ });
+ }
+
+ return new Promise((resolve, reject) => {
+ const script = document.createElement('script');
+ script.src = src;
+ script.async = true;
+ script.onload = () => {
+ script.dataset.loaded = 'true';
+ resolve();
+ };
+ script.onerror = () => reject(new Error(`Failed to load script: ${src}`));
+ document.head.appendChild(script);
+ });
+}
diff --git a/src/cloud-providers/src/provider.ts b/src/cloud-providers/src/provider.ts
index 80fa23ad3..e11632107 100644
--- a/src/cloud-providers/src/provider.ts
+++ b/src/cloud-providers/src/provider.ts
@@ -16,6 +16,8 @@ export type MapListItem = {
description: string;
loadParams: any;
imageUrl?: string;
+ /** Data URL or remote URL for the map preview; may be filled lazily via getMapThumbnail */
+ thumbnail?: string;
updatedAt?: Millisecond;
privateMap?: boolean;
};
@@ -224,6 +226,28 @@ export default class Provider {
return [];
}
+ /**
+ * Optional: resolve a map preview when the storage gallery tile becomes visible.
+ * Providers that omit thumbnails from `listMaps` can implement this to lazy-load them.
+ * Default returns `map.thumbnail` when already present.
+ * @param map - list item from `listMaps`
+ * @returns thumbnail data URL / URL, or undefined
+ * @public
+ */
+ // eslint-disable-next-line @typescript-eslint/no-unused-vars
+ async getMapThumbnail(map: MapListItem): Promise<string | undefined> {
+ return map.thumbnail || undefined;
+ }
+
+ /**
+ * When true, storage gallery tiles call `getMapThumbnail` once they become visible
+ * instead of expecting `listMaps` to include thumbnail bytes/URLs.
+ * @public
+ */
+ hasLazyThumbnails(): boolean {
+ return false;
+ }
+
/**
* This method will be called when user select a map to load from the storage map viewer
* @param {*} loadParams - the loadParams property of each visualization object
diff --git a/src/components/src/modals/cloud-components/cloud-item.spec.tsx b/src/components/src/modals/cloud-components/cloud-item.spec.tsx
index 2eae09767..58d8eda8e 100644
--- a/src/components/src/modals/cloud-components/cloud-item.spec.tsx
+++ b/src/components/src/modals/cloud-components/cloud-item.spec.tsx
@@ -3,7 +3,7 @@
// @ts-nocheck
import React from 'react';
-import {fireEvent} from '@testing-library/react';
+import {fireEvent, waitFor} from '@testing-library/react';
import {renderWithTheme} from '../../../../../test/helpers/component-jest-utils';
import {CloudItem} from './cloud-item';
@@ -15,11 +15,34 @@ describe('CloudItem', () => {
const mockVis = {
title: 'Test Title',
description: 'Test Description',
- lastModification: new Date().toISOString(),
+ updatedAt: Date.now(),
thumbnail: 'test-thumbnail.jpg',
privateMap: true
};
+ let observerCallback;
+ beforeEach(() => {
+ observerCallback = null;
+ class MockIntersectionObserver {
+ constructor(cb) {
+ observerCallback = cb;
+ }
+ observe() {
+ // Immediately report visible for lazy-load tests
+ if (observerCallback) {
+ observerCallback([{isIntersecting: true}]);
+ }
+ }
+ disconnect() {
+ return undefined;
+ }
+ unobserve() {
+ return undefined;
+ }
+ }
+ global.IntersectionObserver = MockIntersectionObserver;
+ });
+
it('renders without crashing', () => {
const {getByText} = renderWithTheme(<CloudItem vis={mockVis} onClick={nop} />);
expect(getByText('Test Title')).toBeInTheDocument();
@@ -56,7 +79,7 @@ describe('CloudItem', () => {
expect(getByText('Test Title')).toBeInTheDocument();
expect(getByText('Test Description')).toBeInTheDocument();
expect(
- getByText(`Last modified ${moment.utc(mockVis.lastModification).fromNow()}`)
+ getByText(`Last modified ${moment.utc(mockVis.updatedAt).fromNow()}`)
).toBeInTheDocument();
});
@@ -66,4 +89,18 @@ describe('CloudItem', () => {
fireEvent.click(getByText('Test Title'));
expect(onClickMock).toHaveBeenCalled();
});
+
+ it('lazy-loads thumbnail when tile becomes visible', async () => {
+ const getMapThumbnail = jest.fn().mockResolvedValue('lazy-thumb.jpg');
+ const provider = {
+ hasLazyThumbnails: () => true,
+ getMapThumbnail
+ };
+ const vis = {...mockVis, thumbnail: undefined};
+ const {findByRole} = renderWithTheme(<CloudItem vis={vis} onClick={nop} provider={provider} />);
+
+ const thumb = await findByRole('thumbnail-wrapper');
+ await waitFor(() => expect(getMapThumbnail).toHaveBeenCalledWith(vis));
+ expect(thumb.style.backgroundImage).toContain('lazy-thumb.jpg');
+ });
});
diff --git a/src/components/src/modals/cloud-components/cloud-item.tsx b/src/components/src/modals/cloud-components/cloud-item.tsx
index ac86b1725..aae617819 100644
--- a/src/components/src/modals/cloud-components/cloud-item.tsx
+++ b/src/components/src/modals/cloud-components/cloud-item.tsx
@@ -2,7 +2,7 @@
// Copyright contributors to the kepler.gl project
import moment from 'moment/moment';
-import React from 'react';
+import React, {useEffect, useRef, useState} from 'react';
import styled from 'styled-components';
import {Base} from '../../common/icons';
@@ -106,11 +106,62 @@ const StyledVisualizationItem = styled.div`
}
`;
-export const CloudItem = ({vis, onClick}) => {
- const thumbnailStyle = {backgroundImage: `url(${vis.thumbnail})`};
+export const CloudItem = ({vis, onClick, provider}) => {
+ const [thumbnail, setThumbnail] = useState(vis.thumbnail);
+ const rootRef = useRef(null);
+ const loadingRef = useRef(false);
+
+ useEffect(() => {
+ setThumbnail(vis.thumbnail);
+ loadingRef.current = false;
+ }, [vis.id, vis.thumbnail]);
+
+ useEffect(() => {
+ if (
+ thumbnail ||
+ !provider?.hasLazyThumbnails?.() ||
+ !provider?.getMapThumbnail ||
+ !rootRef.current
+ ) {
+ return;
+ }
+
+ let cancelled = false;
+ const el = rootRef.current;
+ const observer = new IntersectionObserver(
+ entries => {
+ const entry = entries[0];
+ if (!entry?.isIntersecting || loadingRef.current || cancelled) {
+ return;
+ }
+ loadingRef.current = true;
+ Promise.resolve(provider.getMapThumbnail(vis))
+ .then(url => {
+ if (!cancelled && url) {
+ setThumbnail(url);
+ }
+ })
+ .catch(() => {
+ // Keep placeholder icon on failure
+ })
+ .finally(() => {
+ observer.disconnect();
+ });
+ },
+ {root: null, rootMargin: '100px', threshold: 0.01}
+ );
+
+ observer.observe(el);
+ return () => {
+ cancelled = true;
+ observer.disconnect();
+ };
+ }, [thumbnail, provider, vis]);
+
+ const thumbnailStyle = thumbnail ? {backgroundImage: `url(${thumbnail})`} : undefined;
return (
- <StyledVisualizationItem onClick={onClick}>
- {vis.thumbnail ? (
+ <StyledVisualizationItem ref={rootRef} onClick={onClick}>
+ {thumbnail ? (
<div role="thumbnail-wrapper" className="vis_item-thumb" style={thumbnailStyle}>
{Object.prototype.hasOwnProperty.call(vis, 'privateMap') ? (
<PrivacyBadge privateMap={vis.privateMap} />
diff --git a/src/components/src/modals/cloud-components/cloud-maps.tsx b/src/components/src/modals/cloud-components/cloud-maps.tsx
index 3c0ffde04..9c89a5009 100644
--- a/src/components/src/modals/cloud-components/cloud-maps.tsx
+++ b/src/components/src/modals/cloud-components/cloud-maps.tsx
@@ -37,7 +37,12 @@ export const CloudMaps = ({provider, onSelectMap, isLoading, maps, error}) => {
<StyledFlexContainer>
{(maps ?? []).length ? (
maps.map(vis => (
- <CloudItem key={vis.id} onClick={() => onSelectMap(provider, vis)} vis={vis} />
+ <CloudItem
+ key={vis.id}
+ onClick={() => onSelectMap(provider, vis)}
+ provider={provider}
+ vis={vis}
+ />
))
) : (
<div className="visualization-list__message">
diff --git a/webpack/shared-webpack-configuration.js b/webpack/shared-webpack-configuration.js
index ab5e48e3f..cb08e62cc 100644
--- a/webpack/shared-webpack-configuration.js
+++ b/webpack/shared-webpack-configuration.js
@@ -46,7 +46,10 @@ const WEBPACK_ENV_VARIABLES = Object.keys(ENV_VARIABLES_WITH_INSTRUCTIONS).reduc
...acc,
[key]: null
}),
- {}
+ {
+ // Optional until set in Netlify / local env (not required for production build validation)
+ GoogleDriveClientId: null
+ }
);
module.exports = {
diff --git a/website/esbuild.config.mjs b/website/esbuild.config.mjs
index f15b79579..02600a7ad 100644
--- a/website/esbuild.config.mjs
+++ b/website/esbuild.config.mjs
@@ -66,7 +66,8 @@ const config = {
'process.env.FoursquareClientId': JSON.stringify(process.env.FoursquareClientId || ''),
'process.env.FoursquareDomain': JSON.stringify(process.env.FoursquareDomain || ''),
'process.env.FoursquareAPIURL': JSON.stringify(process.env.FoursquareAPIURL || ''),
- 'process.env.FoursquareUserMapsURL': JSON.stringify(process.env.FoursquareUserMapsURL || '')
+ 'process.env.FoursquareUserMapsURL': JSON.stringify(process.env.FoursquareUserMapsURL || ''),
+ 'process.env.GoogleDriveClientId': JSON.stringify(process.env.GoogleDriveClientId || '')
},
plugins: [
replace({