Mit einem OAuth-Dienst verbinden

Manche Dienste, etwa Google, GitHub oder Spotify, geben die Daten einer Person erst heraus, wenn sie sich anmeldet und zustimmt. Diese Anmeldung übernimmt eine Integration, mit OAuth 2.0. Wer Ihr Widget hinzufügt, verbindet sein Konto einmal, und Ihr Widget bekommt ein Zugriffstoken, mit dem es den Dienst im Namen dieser Person aufruft.

1. Ihr Widget beim Dienst registrieren

Legen Sie in den Entwicklereinstellungen des Dienstes eine OAuth-App an. Wenn er nach einer Weiterleitungs-URI fragt, manchmal auch Callback-URL genannt, geben Sie genau diese ein:

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

Der Dienst gibt Ihnen dann eine Client-ID und ein Client-Secret. In seiner Dokumentation stehen sein Autorisierungsendpunkt, sein Token-Endpunkt und seine Bereiche.

2. Die Integration hinzufügen

1. Wählen Sie im Widget-Studio Datei > Eingaben und dann den Tab Integrationen.

2. Füllen Sie unter Neue Integration Folgendes aus:

   Feld	Was Sie eingeben
   Name der Integration	Ein Name dafür, etwa github. Sie verwenden ihn in Ihrem Code.
   Client-ID	Vom Dienst.
   Client-Secret	Vom Dienst. Es wird sicher gespeichert und nie wieder angezeigt.
   Autorisierungsendpunkt	Die Anmeldeadresse des Dienstes, endet oft auf /authorize.
   Token-Endpunkt	Die Adresse, die Tokens ausgibt, endet oft auf /token.
   Bereiche	Die Berechtigungen, die Ihr Widget braucht, so getrennt, wie der Dienst es erwartet: durch Leerzeichen, Kommas oder +.

3. Wählen Sie Neue Integration erstellen.

Das Formular zeigt auch die Weiterleitungs-URI, die Sie registrieren, mit einer Schaltfläche zum Kopieren. Verwendet der Dienst ungewöhnliche Namen für seine OAuth-Parameter, ändern Sie sie unter Erweitert.

Um die Integration selbst auszuprobieren, wählen Sie Verbinden und melden sich an. Ihr Status wechselt zu Verbunden.

3. In Ihrem Code verwenden

Umschließen Sie den Teil Ihres Widgets, der das Konto braucht, mit RequireIntegration. Darin liefert Ihnen useIntegration das Zugriffstoken:

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

Solange niemand sein Konto verbunden hat, zeigt RequireIntegration statt seines Inhalts eine Aufforderung zum Verbinden. Blotch erneuert Tokens, wenn sie ablaufen.

Alles, was useIntegration zurückgibt, finden Sie in der Referenz unter Integrationen.

Eine Integration später hinzufügen

Wer Ihr Widget aktualisiert, wird gebeten, eine neue Integration zu verbinden. Fügen Sie einem bereits veröffentlichten Widget eine hinzu, wird die nächste Version deshalb ein Major-Update. Siehe Versionsnummern.

Änderungen an den Einstellungen einer bestehenden Integration gelten sofort, ohne dass Sie veröffentlichen müssen.