API

Prezentare generală

Acest ghid se referă la sarcina API. Poți găsi documentația completă a API-ului nostru aici.

Sarcinile API sunt folosite pentru a automatiza questurile pe platforme externe. Le poți folosi pentru a confirma că utilizatorul s-a înregistrat sau a făcut o achiziție, a deschis un PR pentru o problemă pe Github sau pentru a adăuga suport Reddit. Posibilitățile sunt nelimitate. Pentru a începe și a încerca funcționalitatea, oferim un endpoint de bază pe care îl poți folosi pentru parteneriate cu alte comunități Zealy. Află mai multe despre cum să îl configurezi mai jos.

Noțiuni de bază

Crearea unei sarcini „API”

1. Faceți clic pe „Adăugați sarcină”.
2. Selectați „Api”.
3. Definiți endpointul de apelat și o cheie API dacă este necesar.
4. Alegeți cum se pot identifica utilizatorii. Puteți selecta dintre Email, Twitter, Discord, Adresă portofel, sau Zealy Connect.

• Dacă alegeți conectarea portofelului, puteți alege și ce rețea să utilizați.

• Dacă alegeți Zealy Connect, urmați acești pași:

  1. Definiți URL-ul de redirecționare: Acest URL va fi folosit pentru autentificare. Vom redirecționa utilizatorii către acest URL pentru a se autentifica în sistemul dvs.

  

  2. Generați un secret al comunității: Generarea unui secret al comunității este necesară pentru Zealy Connect să funcționeze. Poți crea secretul din Setările Zealy Connect din secțiunea Integrări din setările comunității tale.

  

Pentru informații detaliate despre modul în care ar trebui să funcționeze API-urile, te rugăm să consulți Documentația API și pentru îndrumări privind gestionarea Zealy Connect, vă rugăm să consultați Documentația Zealy Connect.

Integrare cu Domino

Domino este Zapier-ul Web3. Vă permite să extindeți capacitățile Zealy și să verificați automat sarcini care nu sunt acceptate nativ, cum ar fi:

• Verificarea dacă numele sau biografia de Twitter a unui utilizator conține un anumit cuvânt
• Verificarea soldului de NFT și tokenuri al unui utilizator
• Verificarea faptului că un utilizator a invitat un anumit număr de persoane pe Discord
• Și multe altele

Consultați documentația pentru integrare.

Testarea endpointului

La configurarea endpointului, vom rula automat următoarele teste pentru a ne asigura că endpointul funcționează conform așteptărilor:

1. Verificăm ca apelul să nu dureze mai mult de 10 secunde
2. Verificăm că mesajul de eroare este în formatul corect pentru a-l putea afișa utilizatorului
3. Asigură-te că nu este niciunul dintre codurile de stare neașteptate. Endpoint-ul ar trebui să returneze doar 200 sau 400.

Crearea unui endpoint personalizat

Cerere

Poți folosi sarcinile API cu un endpoint personalizat POST care acceptă următorul corp:

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

Îl poți proteja cu o cheie API setată la crearea sarcinii. Cheia API va fi trimisă în antete astfel:

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

Răspuns

Dacă acțiunea a fost efectuată cu succes de către utilizator, ar trebui să returnezi un 200 status. Utilizatorul va revendica apoi cu succes sarcina.

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

În caz contrar, 400 statusul trebuie returnat în răspuns împreună cu un mesaj în corp. Mesajul va fi afișat împreună cu elementul generat requestId pentru a te ajuta pe tine și utilizatorul să depanați eventualele probleme. Asigură-te că este cât mai descriptiv posibil.

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

Exemplu de cod

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

Testare locală cu ngrok

Când dezvolți și testezi endpointul personalizat local, ai nevoie de o modalitate de a expune serverul local pe internet, astfel încât Zealy să poată trimite cereri API către acesta. ngrok este un instrument care creează tuneluri securizate către localhost și este perfect pentru acest scop. Urmează acești pași pentru a configura ngrok și a-ți testa endpointul:

Pasul 1: Instalează ngrok Descarcă ngrok de pe site-ul ngrok. Urmează instrucțiunile de instalare pentru sistemul tău de operare.

Pasul 2: Configurează ngrok Înregistrează-te pentru un cont ngrok gratuit și obține authtoken-ul din panoul de control ngrok. Conectează-ți contul ngrok rulând ngrok authtoken YOUR_AUTH_TOKEN în terminal, înlocuind YOUR_AUTH_TOKEN cu tokenul din panoul de control ngrok.

Pasul 3: Pornește serverul local Asigură-te că serverul tău local care găzduiește endpoint-ul rulează. De exemplu, dacă serverul tău este o aplicație Node.js, ai putea rula node server.js.

Pasul 4: Expune serverul local cu ngrok Deschide o fereastră nouă de terminal și pornește un tunel ngrok către portul serverului tău local (de ex., 3000) folosind ngrok http http://127.0.0.1:3000. ngrok va afișa un URL de redirecționare în terminal (de ex., https://abc123.ngrok.io). Acesta este URL-ul public pe care Zealy îl va folosi pentru a ajunge la serverul tău local.

Pasul 5: Configurează sarcina API în Zealy Folosește URL-ul de redirecționare ngrok ca URL de endpoint atunci când configurezi sarcina API în Zealy. Asigură-te că adaugi orice cale necesară, de exemplu, https://abc123.ngrok.io/claim.

Notă: Reține că URL-urile ngrok sunt temporare și se schimbă de fiecare dată când repornești ngrok, cu excepția cazului în care ai un abonament plătit care acceptă subdomenii personalizate. Asigură-te că actualizezi endpointul în Zealy de fiecare dată când repornești ngrok.

Urmând acești pași, poți testa și depana cu ușurință endpointul personalizat într-un mediu de dezvoltare local înainte de a-l implementa pe un server de producție.

Integrarea Zealy Connect

Când folosești Zealy Connect, vom redirecționa utilizatorul către URL-ul specificat în timpul configurării taskului. Vom include următorii parametri de interogare:

• zealyUserId: Un identificator unic pentru utilizator în sistemul Zealy, folosit pentru a-l conecta cu platforma ta.
• callback: URL-ul către care utilizatorul este redirecționat după finalizarea autentificării, pentru a putea revendica taskul.
• signature: Un hash SHA-256 folosit pentru a verifica autenticitatea cererii, asigurând că aceasta provine de la Zealy.

Iată un exemplu complet de endpoint pe care îl poți folosi ca punct de plecare:

 
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. Verifică semnătura

Primul lucru pe care ar trebui să îl facă aplicația ta este să valideze semnătura folosind secretul comunității tale. Această validare asigură că apelul provine într-adevăr de la noi și nu a fost modificat.

Folosim algoritmul de hash SHA256 pentru a genera semnătura. Pentru a o verifica, poți folosi următoarea abordare:

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. Folosește ID-ul de utilizator Zealy

Pasul următor depinde de ce vrei să faci, dar clienții de obicei autentifică utilizatorul curent pe platforma ta și leagă ID-ul de utilizator al platformei tale cu ID-ul de utilizator Zealy. Mai jos este un exemplu:

  /**
   * 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. Redirecționează înapoi către Zealy

Ultimul pas este să redirecționezi utilizatorul înapoi către Zealy cu ID-ul de utilizator al platformei tale, astfel încât să putem permite utilizatorului să revendice sarcina, folosind parametrul de interogare callback pe care îl oferim. De asemenea, trebuie să generezi o semnătură pentru a putea verifica că apelul provine de la tine și nu a fost modificat. Vezi exemplul de mai jos:

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

Odată ce primim callback-ul, vom valida semnătura și vom stoca ID-ul de utilizator al platformei tale, astfel încât să îl putem trimite ca parte a corpului sarcinii API.

Utilizatorul va putea acum să revendice sarcina și orice altă sarcină care folosește Zealy Connect cu același URL de redirecționare. Vom reține acest lucru, astfel încât utilizatorul să nu trebuiască să se conecteze pentru fiecare sarcină.

Dacă trebuie să ștergi asocierea Zealy Connect a unui utilizator, poți folosi Ruta API Delete Zealy Connect for Member. Această rută îți permite să elimini asocierea Zealy Connect pentru un anumit membru. După apelarea acestei rute, utilizatorul va trebui să își reconecteze contul pentru a folosi din nou funcțiile Zealy Connect.

Întrebări frecvente