API

Überblick

Diese Anleitung behandelt die API-Aufgabe. Die vollständige API-Dokumentation findest du hier.

API-Aufgaben werden verwendet, um Aufgaben auf externen Plattformen zu automatisieren. Du kannst sie nutzen, um zu bestätigen, dass ein Nutzer sich registriert oder einen Kauf getätigt hat, einen PR für ein Issue auf GitHub geöffnet hat oder um Reddit zu unterstützen. Die Möglichkeiten sind endlos. Um zu starten und die Funktionalität auszuprobieren, bieten wir einen einfachen Endpunkt an, den du für Partnerschaften mit anderen Zealy-Communities nutzen kannst. Erfahre unten mehr über die Einrichtung.

Grundlagen

Eine "API"-Aufgabe erstellen

1. Klicke auf 'Aufgabe hinzufügen'.
2. Wähle 'Api'.
3. Definiere den aufzurufenden Endpunkt und einen API-Schlüssel, falls erforderlich.
4. Wähle, wie sich die Nutzer identifizieren können. Du kannst auswählen zwischen E-Mail, Twitter, Discord, Wallet-Adresseoder Zealy Connect.

• Wenn du Wallet-Verbindungwählst, kannst du auch das zu verwendende Netzwerk auswählen.

• Wenn du Zealy Connectwählst, befolge diese Schritte:

  1. Definiere die Weiterleitungs-URL: Diese URL wird für die Authentifizierung verwendet. Wir leiten Nutzer zu dieser URL weiter, damit sie sich in deinem System authentifizieren können.

  

  2. Generiere ein Community-Geheimnis: Ein Community-Geheimnis ist erforderlich, damit Zealy Connect funktioniert. Du kannst das Geheimnis in den Zealy Connect-Einstellungen unter dem Bereich Integrationen in deinen Community-Einstellungen erstellen.

  

Für ausführliche Informationen zur Funktionsweise von APIs siehe die API-Dokumentation und für Anleitungen zur Verwaltung von Zealy Connect siehe die Zealy Connect-Dokumentation.

Integration mit Domino

Domino ist das Web3-Zapier. Es ermöglicht dir, die Funktionen von Zealy zu erweitern und Aufgaben automatisch zu überprüfen, die nicht nativ unterstützt werden, wie zum Beispiel:

• Prüfen, ob der Twitter-Name oder die Bio eines Nutzers ein bestimmtes Wort enthält
• Prüfen des NFT- und Token-Guthabens eines Nutzers
• Überprüfen, ob ein Nutzer eine bestimmte Anzahl von Personen auf Discord eingeladen hat
• Und vieles mehr

Sieh dir deren Dokumentation für die Integration an.

Endpunkt-Tests

Bei der Konfiguration des Endpunkts führen wir automatisch die folgenden Tests aus, um sicherzustellen, dass der Endpunkt wie erwartet funktioniert:

1. Prüfen, ob der Aufruf nicht länger als 10 Sekunden dauert
2. Überprüfen, ob die Fehlermeldung im richtigen Format vorliegt, damit wir sie dem Nutzer anzeigen können
3. Sicherstellen, dass keine unerwarteten Statuscodes auftreten. Der Endpunkt sollte nur 200 oder 400 zurückgeben.

Einen benutzerdefinierten Endpunkt erstellen

Anfrage

Du kannst die API-Aufgaben mit einem benutzerdefinierten POST Endpunkt verwenden, der den folgenden Body akzeptiert:

{
  /**
   * The user id on Zealy
   */
  userId: string;
  /**
   * Your community id on Zealy, if you use the endpoint
   * on multiple communities this might be useful
   */
  communityId: string;
  /**
   * Your community's subdomain on Zealy, if you use the endpoint
   * on multiple communities this might be useful
   */
  subdomain: string;
  /**
   * The id of the quest
   */
  questId: string;
  /**
   * This will be generated on every claim as a way to look up an error.
   * It will also be displayed for the user when a claim fails.
   */
  requestId: string;
  /**
   * Accounts will be sent if at least one identification method has been configured
   */
  accounts?: {
    /**
     * The user's email address
     */
    email?: string;
    /**
     * The user's Ethereum wallet address that he has authenticated with
     */
    wallet?: string;
    /**
     * The user's Discord id and handle
     */
    discord?: {
      id: string;
      handle: string;
    };
    /**
     * The user's Twitter id and username
     */
    twitter?: {
      id: string;
      username: string;
    };
    /**
     * Your platform user ID stored as part of the Zealy Connect integration
    */
    zealy-connect: string
  };
}

Du kannst ihn mit einem API-Schlüssel schützen, der bei der Erstellung der Aufgabe festgelegt wird. Der API-Schlüssel wird in den Headern wie folgt gesendet:

{
  "X-Api-Key": apiKey,
}

Antwort

Wenn die Aktion vom Nutzer erfolgreich ausgeführt wurde, solltest du einen 200 Status zurückgeben. Der Nutzer kann die Aufgabe dann erfolgreich beanspruchen.

{
  "message": "User completed the action"
}

Andernfalls sollte der 400 Status in der Antwort zusammen mit einer Nachricht im Body zurückgegeben werden. Die Nachricht wird mit dem generierten requestId angezeigt, um dir und dem Nutzer bei der Fehlerbehebung zu helfen. Stelle sicher, dass sie so beschreibend wie möglich ist.

{
  "message": "We could not find a user with email kenny@zealy.io"
}

Codebeispiel

// server.js
//
// Use this sample code to handle quest verification in your endpoint.
//
// 1) Paste this code into a new file (server.js)
//
// 2) Install dependencies
//   npm install express
//
// 3) Run the server on http://localhost:3000
//   node server.js
 
const express = require('express');
const app = express();
 
const apiKey = '5888a6800dbac634e52d8504f097e064'; // Replace with your API key configured in Zealy task
 
app.post('/claim', express.raw({ type: 'application/json' }), (req, res) => {
  const payload = req.body;
  const headers = req.headers
 
  if (apiKey !== headers['x-api-key']) {
    throw new Error('Invalid API Key')
  }
 
 
  const success = true; // Replace with custom logic
 
  if (!success) {
    return res.status(400).send({
      message: 'Validation failed' // Replace with custom error message - will be displayed to the user
    })
  }
 
  return res.status(200).send({
    message: "Quest completed"
  })
});
 
app.listen(3000, () => console.log('Running on port 3000'));

Lokales Testen mit ngrok

Bei der Entwicklung und lokalen Testung deines benutzerdefinierten Endpunkts benötigst du eine Möglichkeit, deinen lokalen Server im Internet verfügbar zu machen, damit Zealy API-Anfragen an ihn senden kann. ngrok ist ein Tool, das sichere Tunnel zu localhost erstellt und sich perfekt für diesen Zweck eignet. Befolge diese Schritte, um ngrok einzurichten und deinen Endpunkt zu testen:

Schritt 1: Installiere ngrok Lade ngrok von der ngrok-Website herunter. Befolge die Installationsanweisungen für dein Betriebssystem.

Schritt 2: Richte ngrok ein Melde dich für ein kostenloses ngrok-Konto an und erhalte deinen Authtoken vom ngrok-Dashboard. Verbinde dein ngrok-Konto, indem du ngrok authtoken YOUR_AUTH_TOKEN in deinem Terminal ausführst und YOUR_AUTH_TOKEN durch den Token aus deinem ngrok-Dashboard ersetzt.

Schritt 3: Starte deinen lokalen Server Stelle sicher, dass dein lokaler Server, der den Endpunkt hostet, läuft. Wenn dein Server beispielsweise eine Node.js-App ist, könntest du node server.js ausführen.

Schritt 4: Stelle deinen lokalen Server mit ngrok bereit Öffne ein neues Terminalfenster und starte einen ngrok-Tunnel zum Port deines lokalen Servers (z. B. 3000) mit ngrok http http://127.0.0.1:3000. ngrok zeigt eine Weiterleitungs-URL im Terminal an (z. B. https://abc123.ngrok.io). Dies ist die öffentliche URL, die Zealy verwendet, um deinen lokalen Server zu erreichen.

Schritt 5: Konfiguriere deine API-Aufgabe in Zealy Verwende die ngrok-Weiterleitungs-URL als Endpunkt-URL, wenn du deine API-Aufgabe in Zealy einrichtest. Stelle sicher, dass du einen erforderlichen Pfad anhängst, zum Beispiel https://abc123.ngrok.io/claim.

Hinweis: Denke daran, dass ngrok-URLs temporär sind und sich jedes Mal ändern, wenn du ngrok neu startest, es sei denn, du hast ein kostenpflichtiges Abonnement, das benutzerdefinierte Subdomains unterstützt. Stelle sicher, dass du den Endpunkt in Zealy jedes Mal aktualisierst, wenn du ngrok neu startest.

Wenn du diese Schritte befolgst, kannst du deinen benutzerdefinierten Endpunkt einfach in einer lokalen Entwicklungsumgebung testen und debuggen, bevor du ihn auf einem Produktionsserver bereitstellst.

Zealy Connect-Integration

Bei Verwendung von Zealy Connect leiten wir den Nutzer zu der während der Aufgaben-Einrichtung angegebenen URL weiter. Wir fügen die folgenden Query-Parameter hinzu:

• zealyUserId: Eine eindeutige Kennung für den Nutzer im Zealy-System, die verwendet wird, um ihn mit deiner Plattform zu verknüpfen.
• callback: Die URL, zu der der Nutzer nach Abschluss der Authentifizierung zurückgeleitet wird, damit er die Aufgabe beanspruchen kann.
• signature: Ein SHA-256-Hash, der verwendet wird, um die Authentizität der Anfrage zu überprüfen und sicherzustellen, dass sie von Zealy stammt.

Hier ist ein vollständiges Beispiel für einen Endpunkt, den du als Ausgangspunkt verwenden kannst:

 
const YOUR_COMMUNITY_SECRET = "fdb68b155a1ccf2e636c7cd7e0816530"; // Replace with your secret generated in Settings > Integrations > Zealy Connect
 
app.get("/connect", (req, res) => {
  // Extract the query parameters
  const { zealyUserId, signature, callbackUrl } = req.query;
 
  /**
   * Verifying signature to ensure the request is coming from Zealy
   */
  const fullUrl = new URL(
    `${req.protocol}://${req.get("host")}${req.originalUrl}`
  );
  fullUrl.searchParams.delete("signature");
 
  const hmac = crypto.createHmac("sha256", YOUR_COMMUNITY_SECRET);
  hmac.update(fullUrl.toString());
  const generatedSignature = hmac.digest("hex");
 
  if (generatedSignature !== signature){
    return res.status(400).send("Invalid signature");
  }
 
  /**
   * Redirect to login if the user is not authenticated
   */
  if (!req.session.user) {
    res.redirect(`/login?redirect=${encodeURIComponent(req.originalUrl)}`); // Redirect back after the user logs in
  }
 
  /**
   * Save the Zealy User ID (optional)
  */
  // await updateUser(req.session.user.id, { zealyId: zealyUserId });
 
 
  /**
   * Redirect Back to Zealy
   */
  const userId = req.session.user.id; // Replace with your platform user ID
 
  const callbackWithParams = new URL(callbackUrl as string);
  callbackWithParams.searchParams.append("identifier", userId);
 
  const hmac = crypto.createHmac("sha256", YOUR_COMMUNITY_SECRET);
  hmac.update(callbackWithParams.toString());
  const callbackSignature = hmac.digest("hex");
 
  callbackWithParams.searchParams.append("signature", callbackSignature);
 
  res.redirect(callbackWithParams.toString());
});

1. Überprüfe die Signatur

Das Erste, was deine Anwendung tun sollte, ist die Validierung der Signatur mit deinem Community-Geheimnis. Diese Validierung stellt sicher, dass der Aufruf wirklich von uns kommt und nicht verändert wurde.

Wir verwenden den SHA256-Hash-Algorithmus, um die Signatur zu erzeugen. Zur Überprüfung kannst du den folgenden Ansatz verwenden:

const fullUrl = new URL(
  `${req.protocol}://${req.get("host")}${req.originalUrl}`
);
fullUrl.searchParams.delete("signature");
 
const hmac = crypto.createHmac("sha256", YOUR_COMMUNITY_SECRET);
hmac.update(fullUrl.toString());
const generatedSignature = hmac.digest("hex");
 
const isSignatureValid = generatedSignature === req.query.signature;

2. Verwende die Zealy User ID

Der nächste Schritt hängt davon ab, was du tun möchtest, aber Kunden melden in der Regel den aktuellen Benutzer auf ihrer Plattform an und verknüpfen die Benutzer-ID ihrer Plattform mit der Zealy User ID. Unten findest du ein Beispiel:

  /**
   * Redirect to login if the user is not authenticated
   */
  if (!req.session.user) {
    res.redirect(`/login?redirect=${encodeURIComponent(req.originalUrl)}`); // Redirect back after the user logs in
  }
 
  /**
   * Save the Zealy User ID (optional)
  */
  // await updateUser(req.session.user.id, { zealyId: zealyUserId });
 

3. Zurück zu Zealy weiterleiten

Der letzte Schritt besteht darin, den Benutzer mit der Benutzer-ID deiner Plattform zurück zu Zealy weiterzuleiten, damit wir dem Benutzer erlauben können, die Aufgabe zu beanspruchen, und zwar über den Callback-Query-Parameter, den wir bereitstellen. Du musst außerdem eine Signatur erzeugen, damit wir überprüfen können, dass der Aufruf von dir stammt und nicht verändert wurde. Siehe das Beispiel unten:

const callbackWithParams = new URL(callbackUrl as string);
callbackWithParams.searchParams.append("identifier", connectedUserId); // Set it to your platform user ID
 
const hmac = crypto.createHmac("sha256", YOUR_COMMUNITY_SECRET);
hmac.update(callbackWithParams.toString());
const callbackSignature = hmac.digest("hex");
 
callbackWithParams.searchParams.append("signature", callbackSignature);
 
res.redirect(callbackWithParams.toString());

4. Zealy

Sobald wir den Callback erhalten, validieren wir die Signatur und speichern die Benutzer-ID deiner Plattform, damit wir sie als Teil des API-Task-Bodys senden können.

Der Benutzer kann nun die Aufgabe und jede andere Aufgabe beanspruchen, die Zealy Connect mit derselben Redirect-URL verwendet. Wir merken uns dies, damit der Benutzer sich nicht für jede Aufgabe verbinden muss.

Wenn du die Zealy Connect-Verknüpfung eines Benutzers löschen musst, kannst du die Delete Zealy Connect for Member API-Routeverwenden. Diese Route ermöglicht es dir, die Zealy Connect-Verknüpfung für ein bestimmtes Mitglied zu entfernen. Nach dem Aufruf dieser Route muss der Benutzer sein Konto erneut verbinden, um Zealy Connect-Funktionen wieder zu nutzen.

FAQ