API

Overzicht

Deze handleiding gaat over de API-taak. Je vindt onze volledige API-documentatie hier.

API-quests worden gebruikt om quests op externe platforms te automatiseren. Je kunt het gebruiken om te bevestigen dat de gebruiker zich heeft geregistreerd of een aankoop heeft gedaan, een PR voor een issue op Github heeft geopend of om Reddit-ondersteuning toe te voegen. De mogelijkheden zijn eindeloos. Om aan de slag te gaan en de functionaliteit uit te proberen, bieden we een basis-endpoint dat je kunt gebruiken voor partnerschappen met andere Zealy-communities. Lees hieronder meer over hoe je het instelt.

Basis

Een "API"-taak aanmaken

1. Klik op 'Taak toevoegen'.
2. Selecteer 'Api'.
3. Definieer het endpoint dat moet worden aangeroepen en een API-sleutel indien nodig.
4. Kies hoe de gebruikers zich kunnen identificeren. Je kunt kiezen uit E-mail, Twitter, Discord, Walletadres, of Zealy Connect.

• Als je kiest voor walletverbinding, kun je ook kiezen welk netwerk je gebruikt.

• Als je kiest voor Zealy Connect, volg dan deze stappen:

  1. Definieer de redirect-URL: Deze URL wordt gebruikt voor authenticatie. We sturen gebruikers naar deze URL om zich in jouw systeem te authenticeren.

  

  2. Genereer een community-geheim: Het genereren van een community-geheim is vereist voor Zealy Connect om te werken. Je kunt het geheim aanmaken via de Zealy Connect-instellingen onder de Integraties-sectie in je community-instellingen.

  

Voor diepgaande informatie over hoe API's horen te werken, zie de API-documentatie en voor richtlijnen over het beheren van Zealy Connect, raadpleeg de Zealy Connect-documentatie.

Integratie met Domino

Domino is de Web3 Zapier. Het stelt je in staat de mogelijkheden van Zealy uit te breiden en taken die niet native worden ondersteund automatisch te beoordelen, zoals:

• Controleren of de Twitter-naam of bio van een gebruiker een specifiek woord bevat
• Het NFT- en tokensaldo van een gebruiker controleren
• Verifiëren dat een gebruiker een bepaald aantal mensen op Discord heeft uitgenodigd
• En nog veel meer

Bekijk hun documentatie voor integratie.

Endpoint testen

Bij het configureren van het endpoint voeren we automatisch de volgende tests uit om te controleren of het endpoint werkt zoals verwacht:

1. Controleren of de aanroep niet langer dan 10 seconden duurt
2. Controleren of het foutbericht de juiste indeling heeft, zodat we het aan de gebruiker kunnen tonen
3. Zorg ervoor dat het geen van de onverwachte statuscodes is. Het endpoint mag alleen 200 of 400 retourneren.

Een aangepast endpoint maken

Verzoek

Je kunt de API-taken gebruiken met een aangepast POST endpoint dat de volgende body accepteert:

{
  /**
   * 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
  };
}

Je kunt het beveiligen met een API-sleutel die wordt ingesteld bij het maken van de taak. De API-sleutel wordt als volgt in de headers verzonden:

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

Respons

Als de actie succesvol door de gebruiker is uitgevoerd, moet je een 200 status. De gebruiker claimt de taak vervolgens succesvol.

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

Anders wordt de 400 status in het antwoord teruggegeven, samen met een bericht in de body. Het bericht wordt weergegeven met de gegenereerde requestId om jou en de gebruiker te helpen eventuele problemen op te lossen. Zorg dat het zo beschrijvend mogelijk is.

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

Codevoorbeeld

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

Lokaal testen met ngrok

Wanneer je je aangepaste endpoint lokaal ontwikkelt en test, heb je een manier nodig om je lokale server op internet beschikbaar te maken, zodat Zealy er API-verzoeken naartoe kan sturen. ngrok is een tool die beveiligde tunnels naar localhost maakt en is hier perfect voor. Volg deze stappen om ngrok in te stellen en je endpoint te testen:

Stap 1: Installeer ngrok Download ngrok van de website van ngrok. Volg de installatie-instructies voor je besturingssysteem.

Stap 2: ngrok instellen Meld je aan voor een gratis ngrok-account en haal je authtoken op uit het ngrok-dashboard. Verbind je ngrok-account door ngrok authtoken YOUR_AUTH_TOKEN in je terminal uit te voeren en YOUR_AUTH_TOKEN te vervangen door het token uit je ngrok-dashboard.

Stap 3: Start je lokale server Zorg ervoor dat je lokale server die het endpoint host actief is. Als je server bijvoorbeeld een Node.js-app is, kun je node server.js uitvoeren.

Stap 4: Stel je lokale server beschikbaar met ngrok Open een nieuw terminalvenster en start een ngrok-tunnel naar de poort van je lokale server (bijv. 3000) met ngrok http http://127.0.0.1:3000. ngrok toont een forwarding-URL in de terminal (bijv. https://abc123.ngrok.io). Dit is de openbare URL die Zealy gebruikt om je lokale server te bereiken.

Stap 5: Configureer je API-taak in Zealy Gebruik de ngrok forwarding-URL als de endpoint-URL bij het instellen van je API-taak in Zealy. Voeg eventueel een vereist pad toe, bijvoorbeeld https://abc123.ngrok.io/claim.

Opmerking: Onthoud dat ngrok-URL's tijdelijk zijn en elke keer veranderen wanneer je ngrok opnieuw start, tenzij je een betaald abonnement hebt dat aangepaste subdomeinen ondersteunt. Zorg ervoor dat je het endpoint in Zealy elke keer bijwerkt wanneer je ngrok opnieuw start.

Door deze stappen te volgen, kun je je aangepaste endpoint eenvoudig testen en debuggen in een lokale ontwikkelomgeving voordat je het naar een productieserver implementeert.

Zealy Connect-integratie

Bij gebruik van Zealy Connect sturen we de gebruiker door naar de URL die tijdens de taakinstelling is opgegeven. We voegen de volgende queryparameters toe:

• zealyUserId: Een unieke identificatie voor de gebruiker in het Zealy-systeem, gebruikt om hen aan je platform te koppelen.
• callback: De URL om de gebruiker terug te sturen nadat de authenticatie is voltooid, zodat zij de taak kunnen claimen.
• signature: Een SHA-256-hash die wordt gebruikt om de authenticiteit van het verzoek te verifiëren en te waarborgen dat het van Zealy afkomstig is.

Hier is een volledig voorbeeld-endpoint dat je als startpunt kunt gebruiken:

 
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. Controleer de handtekening

Het eerste dat je applicatie moet doen, is de handtekening valideren met je community secret. Deze validatie zorgt ervoor dat de oproep echt van ons afkomstig is en niet is gewijzigd.

We gebruiken het SHA256-hashalgoritme om de handtekening te genereren. Om deze te verifiëren, kun je de volgende aanpak gebruiken:

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. Gebruik het Zealy-gebruikers-ID

De volgende stap hangt af van wat je wilt doen, maar klanten loggen meestal de huidige gebruiker in op je platform en koppelen het gebruikers-ID van je platform aan het Zealy-gebruikers-ID. Hieronder staat een voorbeeld:

  /**
   * 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. Terugleiden naar Zealy

De laatste stap is de gebruiker terugleiden naar Zealy met het gebruikers-ID van je platform, zodat we de gebruiker de taak kunnen laten claimen, via de callback-queryparameter die we bieden. Je moet ook een handtekening genereren, zodat we kunnen verifiëren dat de oproep van jou afkomstig is en niet is gewijzigd. Zie het voorbeeld hieronder:

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

Zodra we de callback ontvangen, valideren we de handtekening en slaan we het gebruikers-ID van je platform op, zodat we het kunnen meesturen in de body van de API-taak.

De gebruiker kan nu de taak claimen en elke andere taak die Zealy Connect met dezelfde redirect-URL gebruikt. We onthouden dit, zodat de gebruiker niet voor elke taak opnieuw hoeft te verbinden.

Als je de Zealy Connect-koppeling van een gebruiker wilt verwijderen, kun je de API-route Zealy Connect voor lid verwijderengebruiken. Met deze route kun je de Zealy Connect-koppeling voor een specifiek lid verwijderen. Na het aanroepen van deze route moet de gebruiker zijn account opnieuw koppelen om de functies van Zealy Connect weer te gebruiken.

FAQ