Conectarse a un servicio OAuth

Algunos servicios, como Google, GitHub o Spotify, solo comparten los datos de una persona después de que inicie sesión y dé su permiso. Una integración se encarga de ese inicio de sesión mediante OAuth 2.0. La persona que añade tu widget conecta su cuenta una sola vez, y tu widget obtiene un token de acceso para llamar al servicio en su nombre.

1. Registrar tu widget en el servicio

En los ajustes para desarrolladores del servicio, crea una aplicación OAuth. Cuando te pida una URI de redirección, a veces llamada URL de callback, escribe exactamente:

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

El servicio te da entonces un ID de cliente y un secreto de cliente, y su documentación indica su extremo de autorización, su extremo de token y sus ámbitos.

2. Añadir la integración

1. En el Estudio de widgets, elige Archivo > Entradas y luego la pestaña Integraciones.

2. En Nueva integración, rellena:

   Campo	Qué escribir
   Nombre de la integración	Un nombre para ella, como github. Lo usarás en tu código.
   ID de cliente	Te lo da el servicio.
   Secreto de cliente	Te lo da el servicio. Se guarda de forma segura y no se vuelve a mostrar nunca.
   Extremo de autorización	La dirección de inicio de sesión del servicio, que suele terminar en /authorize.
   Extremo de token	La dirección que entrega los tokens, que suele terminar en /token.
   Ámbitos	Los permisos que necesita tu widget, separados como espera el servicio: con espacios, comas o +.

3. Haz clic en Crear nueva integración.

El formulario también muestra la URI de redirección que debes registrar, con un botón para copiarla. Si el servicio usa nombres poco habituales para sus parámetros de OAuth, cámbialos en Avanzado.

Para probar la integración por tu cuenta, haz clic en Conectar e inicia sesión. Su estado cambia a Conectado.

3. Usarla en tu código

Envuelve en RequireIntegration la parte de tu widget que necesita la cuenta. Dentro, useIntegration te da el token de acceso:

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>
);

Hasta que alguien conecte su cuenta, RequireIntegration muestra una invitación a conectarla en lugar de su contenido. Blotch renueva los tokens cuando caducan.

Consulta Integraciones en la referencia para ver todo lo que devuelve useIntegration.

Añadir una integración más adelante

A las personas que usan tu widget se les pide que conecten una integración nueva cuando lo actualizan, así que añadir una a un widget ya publicado convierte la siguiente versión en una actualización mayor. Consulta Números de versión.

Los cambios en los ajustes de una integración existente se aplican de inmediato, sin publicar.