Come integrare l’API di Google Calendar nella tua app

In questa guida spiegheremo nel dettaglio come integrare la Google Calendar API nella tua app, coprendo la configurazione del progetto Google Cloud, gli scope richiesti, i possibili problemi e un esempio reale di autorizzazione.

Prerequisiti

Questa guida presuppone che tu disponga di un indirizzo email, di un dominio esistente da usare durante la configurazione del progetto Google Cloud, di alcune conoscenze di programmazione e di un’idea abbastanza chiara di ciò che stai cercando di creare.

Questa guida è utile anche se non hai mai lavorato con la Google Calendar API e vuoi familiarizzare con tutti i passaggi necessari per integrarla nella tua app.

Come usare e integrare la Google Calendar API nella tua app

1. Registrati alla Google Developer Console

Se non hai un account Google Developer Console, creane uno su https://console.cloud.google.com/.

2. Crea o scegli un progetto Google Cloud esistente

Google Cloud consente a sviluppatori e organizzazioni di avere più progetti. Assicurati di trovarti nel progetto corretto quando esegui le operazioni seguenti.

Fai clic sul menu a discesa dei progetti in alto a sinistra. Il nome di solito corrisponde al nome del tuo progetto.

Seleziona un progetto esistente oppure crea un nuovo progetto cliccando "New Project" in alto a destra del modale.

3. Abilita i servizi Google Calendar API

Dopo aver creato un account e verificato di essere nel progetto giusto, segui questi passaggi per abilitare i servizi Google Calendar API:

1. Vai alla Google Cloud Console

2. Fai clic su “APIs & Services”

   

3. Fai clic su “Enable APIs and services”

   

4. Cerca “Google Calendar API”

   

5. Fai clic su "Enable" per abilitare il servizio.

   

4. Configura la schermata di consenso OAuth

Dopo aver abilitato i servizi Google Calendar API, il passo successivo è configurare la schermata di consenso OAuth. È l’interfaccia che gli utenti vedono quando collegano il loro calendario alla tua app. In genere possono vedere il logo, il nome dell’app, i permessi richiesti e altro.

1. Clicca sulla scheda "OAuth Consent Screen".

   

2. Clicca "Get Started".

   

3. Compila la sezione “App Information”. Inserisci il nome dell’app e l’email di supporto.

   

4. Scegli il pubblico. Può essere interno o esterno. Scegli interno se l’app non sarà pubblica e solo gli utenti della tua organizzazione possono collegarsi; esterno se possono accedere anche account pubblici.

   

5. Inserisci le informazioni di contatto. Google richiede un’email per notificare eventuali modifiche al progetto.

   

6. Spunta la casella "Agree to the Google API Services: User Data Policy".

   

7. Clicca “Create”.

   

5. Crea il tuo client OAuth

Dopo aver configurato la schermata di consenso OAuth, puoi creare il client OAuth per il progetto. Clicca la scheda “Clients”, poi “Create Client”.

In alternativa, clicca "Create OAuth Client" nella pagina di panoramica.

Puoi creare client per ogni piattaforma su cui l’app verrà eseguita. Ad esempio, se stai sviluppando una web app e un’app iOS, dovrai creare un ID client OAuth separato per ciascuna piattaforma.

In questo esempio, creiamo un client “Web Application” chiamato “Web Client”.

In questo flusso imposteremo anche gli authorized JavaScript origins e gli authorized redirect URI.

Nel campo Authorized JavaScript origins inserisci il dominio/URL che ospita la tua web app, ad esempio: myapp.domain.com

Nel campo Authorized redirect URLs inserisci tutti gli URL di reindirizzamento che userai dopo l’autenticazione. L’URL deve includere il protocollo.

Dopo aver compilato i campi, clicca “Create”. Google aprirà un modale con Client ID e Client Secret. Copiali e conservali in un luogo sicuro (di solito in un file .env). Puoi anche scaricare il JSON e salvarlo in un gestore segreto come 1Password.

6. Aggiungi alcuni utenti di test

Durante lo sviluppo locale non potrai collegare account Google Calendar se non autorizzi alcuni utenti di test. Questo perché l’app è esterna e non ancora approvata da Google.

Per aggiungere utenti di test:

1. Clicca la scheda “Audience”.

   

2. Scorri fino alla sezione “Test Users”.

   

3. Clicca “Add Users” e inserisci l’email dell’utente.

   

7. Aggiungi gli scope di calendario che intendi usare

A seconda del caso d’uso potresti dover richiedere scope diversi. Pensa agli scope come ai permessi necessari per accedere ai dati privati dell’utente, ad esempio elencare i calendari o visualizzare eventi.

Google divide gli scope in sensibili e non sensibili. Se aggiungi scope sensibili dovrai sottoporre l’app a verifica. Questo vale anche se l’app è già verificata e aggiungi nuovi scope sensibili.

Per gestire gli scope:

1. Clicca la scheda "Data Access".

   

2. Clicca "Add or remove scopes".

   

3. Cerca lo scope per nome o valore e aggiungilo.

   

8. Familiarizza con la Google Calendar API

Ora che abbiamo configurato il client Google e tutte le informazioni necessarie, è bene esplorare la Google Calendar API.

Consiglio di leggere la pagina panoramica della Google Calendar API e di consultare gli endpoint principali, come quelli di eventi e calendari.

9. Usa un servizio Unified Calendar API per integrare più provider con una sola API

Se Google Calendar è l’unico provider che vuoi integrare, puoi saltare questo passaggio. Altrimenti, ti consigliamo di usare una Unified Calendar API, che offre un’unica API per tutti i provider di calendari.

Un’API unificata ti permette di integrare facilmente altri provider (es. Outlook) senza scrivere ulteriore codice, evitando di mantenere più integrazioni o gestire cambiamenti breaking.

Esempio di flusso di autorizzazione Google Calendar

Il diagramma seguente mostra un semplice flusso OAuth che consente agli utenti di collegare Google Calendar alla tua app.

Google offre client per Node.js, Python, ecc., ma per semplicità useremo solo chiamate HTTP e TypeScript.

Lato Client (UI)

Per prima cosa, renderizziamo un pulsante “Connect Google Calendar”.

const googleOauthUrl = getGoogleOAuthUrl()
<button href="googleOauthUrl" rel="noopener noreferrer"> Connect Google Calendar </button>

Consigliamo di usare una funzione utility per ottenere l’URL OAuth di Google, migliorando la leggibilità del codice e la gestione dei parametri.

const SCOPES = [
  "openid",
  "email",
  "https://www.googleapis.com/auth/calendar.calendarlist",
  "https://www.googleapis.com/auth/calendar.events",
  "https://www.googleapis.com/auth/calendar.readonly",
  // aggiungi altri scope se necessario
];

export interface ClientState {
  session: Session;
  returnUrl?: string;
}

export function stateToB64(session: ClientState): string {
  return encode(JSON.stringify(session));
}

export function getGoogleOAuthUrl(
  state: ClientState,
) {
  const params = new URLSearchParams({
    client_id: process.env.GOOGLE_CLIENT_ID || "",
    redirect_uri: `${getHostName()}/api/connect/google`, // modifica se necessario response_type: "code",
    scope: SCOPES.join(" "),
    prompt: "consent",
    access_type: "offline",
    state: stateToB64(state),
  });
  return `https://accounts.google.com/o/oauth2/v2/auth?${params}`;
}

Il parametro prompt può avere i valori none, consent o select_account.

• consent: mostra di nuovo il modale di autorizzazione, utile se aggiungi nuovi scope.

• select_account: obbliga l’utente a scegliere un account.

• none: non mostra schermate di autenticazione o consenso.

Lato API (Backend)

Creiamo poi l’handler API, responsabile di ricevere il codice da Google e scambiarlo con i token.

Nell’esempio usiamo zod per la validazione.

import { z } from "zod";
const successSchema = z.object({
  code: z.string(),
  scope: z.string(),
  state: z.string(),
});

const errorSchema = z.object({
  error: z.string(),
});
type ErrorParams = z.infer<typeof errorSchema>;

const querySchema = z.union([successSchema, errorSchema]);

// Handler const googleHanlder: NextApiHandler = async (req, res) => {
  try {
    const result = querySchema.parse(req.query);
    if (isError(result)) {
      const q = new URLSearchParams({
        error: "ACCESS_DENIED",
      });
      return res.redirect(`/?${q}`);
    }

    const { session, returnUrl } = stateFromB64(result.state);

    if (!hasRequiredScopes(result.scope)) {
      const q = new URLSearchParams({
        error: "MISSING_REQUIRED_PERMISSIONS",
      });
      return res.redirect(`/?${q}`);
    }

    const { access_token, refresh_token, id_token, expires_in } =
      await exchangeCodeForTokens(result.code);
    const { email } = decodeIdToken(id_token);

    const connection = await upsertConnection(
      {
        email,
        accessToken: access_token,
        refreshToken: refresh_token,
        expiresInSeconds: expires_in,
        status: ConnectionStatus.ACTIVE,
        provider: CalendarProvider.GOOGLE,
        scopes: result.scope,
        reminderCount: 0,
        lastRemindedAt: null,
      },
      session.user
    );

    const q = new URLSearchParams({
      cid: connection.id,
    });
    if (returnUrl) q.append("returnUrl", returnUrl);

    res.redirect(returnUrl ? returnUrl : `/calendars/google?${q}`);
  } catch (e: any) {
    let error = JSON.stringify(e);

    const querystr =
      typeof req.query === "string" ? req.query : JSON.stringify(req.query);
    console.error("Error in googleHandler", querystr);
    console.error("Failed to connect Google account", e);

    const q = new URLSearchParams({
      error,
    });
    return res.redirect(`/?${q}`);
  }
};

Come per il lato client, consigliamo di avere funzioni utility per scambiare il codice con i token, decodificare l’ID token e ottenere lo stato da base64.

export async function exchangeCodeForTokens(code: string) {
  const data = new FormData();
  data.append("code", code);
  data.append("client_id", process.env.GOOGLE_CLIENT_ID || "");
  data.append("client_secret", process.env.GOOGLE_CLIENT_SECRET || "");
  data.append("redirect_uri", `${getHostName()}/api/connect/google`);
  data.append("grant_type", "authorization_code");

  try {
    const result = await fetch("https://oauth2.googleapis.com/token", {
      method: "POST",
      body: data,
    });

    const json = await result.json();
    if (json.error) throw json;

    const parsed = responseSchema.parse(json);
    return parsed;
  } catch (e) {
    console.error("Exchange failed");
    throw e;
  }
}

export function decodeIdToken(idToken: string) {
  const data = jwt.decode(idToken);
  if (typeof data === "string" || !data?.email) {
    throw new Error(`Could not parse id_token: ${idToken}`);
  }

  return data;
}

function isError(query: Record<string, any>): query is ErrorParams {
  return Boolean(query.error);
}

export function stateFromB64(encoded: string): ClientState {
  const str = decode(encoded);
  return JSON.parse(str) as ClientState;
}

Possibili problemi con l’integrazione della Google Calendar API

• La verifica può richiedere settimane: pianifica in anticipo. L’approvazione può tardare e potresti ricevere un rifiuto iniziale, quindi considera questo nel tuo timeline.

• I webhook scadono dopo circa 24 ore: rinnovali sempre. Puoi usare cron job per rinnovarli 20 minuti prima della scadenza.

• Richiedi solo gli scope necessari. Google è severa nella verifica e gli utenti diffidano di permessi eccessivi.

• Gestisci quote e rate-limiting. Google applica limiti per progetto e per utente; usa back-off esponenziale per non superarli.

• Evita di registrare dati personali. Rimuovi descrizioni, email dei partecipanti e altre info sensibili dai log.

Integra più provider di calendario con la OneCal Unified Calendar API

In OneCal abbiamo sincronizzato milioni di eventi tra Google Calendar, Outlook e iCloud. Conosciamo le complessità di ogni API e come farle funzionare insieme.

Per questo stiamo sviluppando una Unified Calendar API che supporta Outlook, Google Calendar e iCloud Calendar fin da subito, consentendoti di integrare tutti i principali provider con un’unica API robusta e facile da usare.

Unisciti alla lista d’attesa della Unified Calendar API per ricevere una notifica appena lanceremo il nuovo prodotto.

Domande frequenti

Perché devo aggiungere utenti di test?

Un’app esterna non verificata può essere usata solo da account di test autorizzati durante lo sviluppo e prima che Google la approvi.

Per quanto tempo restano attivi i webhook di Google Calendar?

Gli abbonamenti alle notifiche push scadono dopo circa 24 ore, quindi il backend deve rinnovarli prima della scadenza.

Esiste un modo più semplice per aggiungere in seguito i calendari Outlook o iCloud?

Sì. Una Unified Calendar API come la OneCal Unified Calendar API consente di integrare Google, Outlook e iCloud tramite un’unica API, risparmiando tempo e costi di sviluppo e manutenzione.

Ho bisogno di “offline_access” per i processi in background?

Sì. Aggiungendo access_type=offline all’URL di consenso si ottiene un token di aggiornamento, così il server può chiamare l’API anche quando l’utente non è presente.