API

Panoramica

Questa guida riguarda la quest API. Puoi trovare la nostra documentazione API completa qui.

Le quest API servono ad automatizzare le quest su piattaforme esterne. Puoi usarle per confermare che l'utente si è registrato o ha effettuato un acquisto, ha aperto una PR per un issue su Github o per aggiungere il supporto Reddit. Le possibilità sono infinite. Per iniziare e provare la funzionalità offriamo un endpoint di base che puoi usare per creare partnership con altre community Zealy. Scopri di più su come configurarlo qui sotto.

Nozioni di base

Creare una quest "API"

1. Clicca su 'Aggiungi attività'.
2. Seleziona 'Api'.
3. Definisci l'endpoint da chiamare e una chiave API se necessario.
4. Scegli come gli utenti possono identificarsi. Puoi selezionare tra Email, Twitter, Discord, Indirizzo del wallet, oppure Zealy Connect.

• Se scegli la connessione del wallet, puoi anche scegliere quale rete utilizzare.

• Se scegli Zealy Connect, segui questi passaggi:

  1. Definisci l'URL di reindirizzamento: Questo URL verrà utilizzato per l'autenticazione. Reindirizzeremo gli utenti a questo URL per consentire loro di autenticarsi nel tuo sistema.

  

  2. Genera un segreto della community: La generazione di un segreto della community è necessaria per Zealy Connect per funzionare. Puoi creare il segreto dalla Impostazioni di Zealy Connect nella sezione Integrazioni nelle impostazioni della tua community.

  

Per informazioni approfondite su come dovrebbero funzionare le API, consulta Documentazione API e per indicazioni sulla gestione di Zealy Connect, consulta la documentazione di Zealy Connect.

Integrazione con Domino

Domino è lo Zapier del Web3. Ti consente di estendere le capacità di Zealy e verificare automaticamente le attività non supportate nativamente, come:

• Verificare se il nome o la bio Twitter di un utente contiene una parola specifica
• Verificare il saldo di NFT e token di un utente
• Verificare che un utente abbia invitato un certo numero di persone su Discord
• E molto altro

Consulta la loro documentazione per l'integrazione.

Test dell'endpoint

Durante la configurazione dell'endpoint eseguiremo automaticamente i seguenti test per assicurarci che l'endpoint funzioni come previsto:

1. Verifica che la chiamata non richieda più di 10 secondi
2. Verifica che il messaggio di errore sia nel formato corretto così da poterlo mostrare all'utente
3. Assicurandoti che non sia nessuno dei codici di stato imprevisti. L'endpoint dovrebbe restituire solo 200 o 400.

Creazione di un endpoint personalizzato

Richiesta

Puoi usare le attività API con un POST endpoint personalizzato che accetta il seguente corpo:

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

Puoi proteggerlo con una chiave API impostata durante la creazione dell'attività. La chiave API verrà inviata negli header in questo modo:

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

Risposta

Se l'azione è stata eseguita con successo dall'utente, dovresti restituire un 200 Lo stato. L'utente completerà quindi con successo la quest.

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

Altrimenti, il 400 lo stato deve essere restituito nella risposta insieme a un messaggio nel corpo. Il messaggio sarà visualizzato con il generato requestId per aiutare te e l'utente a risolvere eventuali problemi. Assicurati che sia il più descrittivo possibile.

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

Esempio di codice

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

Test locale con ngrok

Quando sviluppi e testi il tuo endpoint personalizzato in locale, hai bisogno di un modo per esporre il tuo server locale a internet affinché Zealy possa inviargli richieste API. ngrok è uno strumento che crea tunnel sicuri verso localhost ed è perfetto per questo scopo. Segui questi passaggi per configurare ngrok e testare il tuo endpoint:

Passaggio 1: installa ngrok Scarica ngrok dal sito web di ngrok. Segui le istruzioni di installazione per il tuo sistema operativo.

Passaggio 2: configura ngrok Registrati per un account ngrok gratuito e ottieni il tuo authtoken dalla dashboard di ngrok. Collega il tuo account ngrok eseguendo ngrok authtoken YOUR_AUTH_TOKEN nel terminale, sostituendo YOUR_AUTH_TOKEN con il token dalla tua dashboard di ngrok.

Passaggio 3: avvia il tuo server locale Assicurati che il tuo server locale che ospita l'endpoint sia in esecuzione. Ad esempio, se il tuo server è un'app Node.js, potresti eseguire node server.js.

Passaggio 4: esponi il tuo server locale con ngrok Apri una nuova finestra del terminale e avvia un tunnel ngrok verso la porta del tuo server locale (ad es. 3000) usando ngrok http http://127.0.0.1:3000. ngrok mostrerà un URL di inoltro nel terminale (ad es. https://abc123.ngrok.io). Questo è l'URL pubblico che Zealy userà per raggiungere il tuo server locale.

Passaggio 5: configura la tua attività API in Zealy Usa l'URL di inoltro di ngrok come URL dell'endpoint quando configuri la tua attività API in Zealy. Assicurati di aggiungere qualsiasi percorso richiesto, ad esempio, https://abc123.ngrok.io/claim.

Nota: Ricorda, gli URL di ngrok sono temporanei e cambiano ogni volta che riavvii ngrok, a meno che tu non abbia un abbonamento a pagamento che supporta sottodomini personalizzati. Assicurati di aggiornare l'endpoint in Zealy ogni volta che riavvii ngrok.

Seguendo questi passaggi, puoi facilmente testare e fare il debug del tuo endpoint personalizzato in un ambiente di sviluppo locale prima di distribuirlo su un server di produzione.

Integrazione di Zealy Connect

Quando utilizzi Zealy Connect, reindirizzeremo l'utente all'URL specificato durante la configurazione dell'attività. Includeremo i seguenti parametri di query:

• zealyUserId: Un identificatore univoco per l'utente nel sistema Zealy, utilizzato per collegarlo alla tua piattaforma.
• callback: L'URL per reindirizzare l'utente al termine dell'autenticazione, così può completare l'attività.
• signature: Un hash SHA-256 utilizzato per verificare l'autenticità della richiesta, assicurando che provenga da Zealy.

Ecco un esempio completo di endpoint che puoi usare come punto di partenza:

 
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. Verifica la firma

La prima cosa che la tua applicazione deve fare è validare la firma usando il tuo community secret. Questa validazione garantisce che la chiamata provenga realmente da noi e non sia stata modificata.

Utilizziamo l'algoritmo di hash SHA256 per generare la firma. Per verificarla, puoi usare il seguente approccio:

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. Usa lo Zealy User ID

Il passo successivo dipende da cosa vuoi fare, ma i clienti di solito effettuano il login dell'utente corrente sulla tua piattaforma e collegano l'ID utente della tua piattaforma con lo Zealy User ID. Di seguito un esempio:

  /**
   * 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. Reindirizza di nuovo a Zealy

L'ultimo passo è reindirizzare l'utente di nuovo a Zealy con l'ID utente della tua piattaforma, così possiamo consentire all'utente di riscattare l'attività, usando il parametro di query callback che forniamo. Devi anche generare una firma così possiamo verificare che la chiamata provenga da te e non sia stata modificata. Vedi l'esempio di seguito:

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

Una volta ricevuto il callback, convalideremo la firma e memorizzeremo l'ID utente della tua piattaforma così possiamo inviarlo come parte del corpo dell'attività API.

L'utente ora potrà riscattare l'attività e qualsiasi altra attività che utilizza Zealy Connect con lo stesso URL di reindirizzamento. Lo ricorderemo così l'utente non dovrà connettersi per ogni attività.

Se devi eliminare l'associazione Zealy Connect di un utente, puoi usare Route API Delete Zealy Connect for Member. Questa route consente di rimuovere l'associazione Zealy Connect per un membro specifico. Dopo aver chiamato questa route, l'utente dovrà riconnettere il proprio account per usare di nuovo le funzionalità di Zealy Connect.

FAQ