Connettersi a un servizio OAuth

Alcuni servizi, come Google, GitHub o Spotify, condividono i dati di una persona solo dopo che questa ha effettuato l’accesso e ha dato il suo consenso. Un’integrazione gestisce quell’accesso tramite OAuth 2.0. Chi aggiunge il tuo widget collega il proprio account una volta sola, e il tuo widget ottiene un token di accesso per chiamare il servizio per suo conto.

1. Registrare il widget presso il servizio

Nelle impostazioni per sviluppatori del servizio, crea un’app OAuth. Quando ti chiede un URI di reindirizzamento, a volte chiamato URL di callback, inserisci esattamente:

https://console.blotch.app/oauth/callback

Il servizio ti fornisce poi un client ID e un client secret, e la sua documentazione indica l’endpoint di autorizzazione, l’endpoint del token e gli ambiti.

2. Aggiungere l’integrazione

1. Nello Studio dei widget, scegli File > Input, poi la scheda Integrazioni.

2. In Nuova integrazione, compila:

   Campo	Cosa inserire
   Nome integrazione	Un nome, come github. Lo userai nel tuo codice.
   Client ID	Te lo fornisce il servizio.
   Client Secret	Te lo fornisce il servizio. Viene conservato in modo sicuro e non viene più mostrato.
   Endpoint di autorizzazione	L’indirizzo di accesso del servizio, che spesso termina con /authorize.
   Endpoint del token	L’indirizzo che rilascia i token, che spesso termina con /token.
   Ambiti	I permessi di cui ha bisogno il tuo widget, separati come si aspetta il servizio: spazi, virgole o +.

3. Fai clic su Crea nuova integrazione.

Il modulo mostra anche l’URI di reindirizzamento da registrare, con un pulsante per copiarlo. Se il servizio usa nomi insoliti per i suoi parametri OAuth, cambiali in Avanzate.

Per provare tu stesso l’integrazione, fai clic su Connetti e accedi. Il suo stato diventa Connesso.

3. Usarla nel codice

Racchiudi in RequireIntegration la parte del widget che ha bisogno dell’account. Al suo interno, useIntegration ti dà il token di accesso:

import { RequireIntegration, useIntegration } from "~lib/integrations";
import { Paragraph } from "~lib/typography";
import { useFetch } from "~lib/use-fetch";

type GitHubUser = {
  readonly login: string;
};

const Profile = () => {
  const { accessToken } = useIntegration();

  const { data } = useFetch<GitHubUser>("https://api.github.com/user", {
    headers: { Authorization: `Bearer ${accessToken}` },
  });

  return <Paragraph>Signed in as {data.login}</Paragraph>;
};

export const Widget = () => (
  <RequireIntegration name="github">
    <Profile />
  </RequireIntegration>
);

Finché nessuno ha collegato il proprio account, RequireIntegration mostra un invito a collegarlo al posto del suo contenuto. Blotch rinnova i token quando scadono.

Per tutto ciò che restituisce useIntegration, vedi Integrazioni nel riferimento.

Aggiungere un’integrazione in seguito

A chi aggiorna il widget viene chiesto di collegare la nuova integrazione, quindi aggiungerne una a un widget già pubblicato fa della versione successiva un aggiornamento principale. Vedi Numeri di versione.

Le modifiche alle impostazioni di un’integrazione esistente hanno effetto subito, senza pubblicare.