API

Automatisez des actions sur des plateformes externes

Par Fredrika

Sur cette page

Aperçu

Ce guide porte sur la tâche API. Vous trouverez notre documentation API complète ici.

Les quêtes API servent à automatiser des quêtes sur des plateformes externes. Vous pouvez l'utiliser pour confirmer qu'un utilisateur s'est inscrit ou a effectué un achat, a ouvert une PR pour un ticket sur Github ou pour ajouter la prise en charge de Reddit. Les possibilités sont infinies. Pour commencer et tester la fonctionnalité, nous proposons un endpoint basique que vous pouvez utiliser pour établir des partenariats avec d'autres communautés Zealy. Découvrez comment le configurer ci-dessous.

Bases

Créer une tâche « API »

Cliquez sur « Ajouter une tâche ».
Sélectionnez « Api ».
Définissez l'endpoint à appeler et une clé API si nécessaire.
Choisissez comment les utilisateurs peuvent s'identifier. Vous pouvez sélectionner Email, Twitter, Discord, Adresse de portefeuille, ou Zealy Connect.

Si vous choisissez la connexion de portefeuille, vous pouvez également choisir le réseau à utiliser.

Nouvelles blockchains

Si vous choisissez Zealy Connect, suivez ces étapes :
1. Définissez l'URL de redirection : Cette URL sera utilisée pour l'authentification. Nous redirigerons les utilisateurs vers cette URL pour qu'ils s'authentifient dans votre système.
1. Générez un secret de communauté : La génération d'un secret de communauté est requise pour que Zealy Connect fonctionne. Vous pouvez créer le secret depuis les paramètres Zealy Connect dans la section Intégrations des paramètres de votre communauté.

Pour des informations détaillées sur le fonctionnement attendu des API, consultez la documentation API et pour des conseils sur la gestion de Zealy Connect, reportez-vous à la documentation Zealy Connect.

Intégration avec Domino

Domino est le Zapier du Web3. Il vous permet d'étendre les capacités de Zealy et de vérifier automatiquement des tâches qui ne sont pas prises en charge nativement, telles que :

Vérifier si le nom ou la bio Twitter d'un utilisateur contient un mot spécifique
Vérifier le solde de NFT et de tokens d'un utilisateur
Vérifier qu'un utilisateur a invité un certain nombre de personnes sur Discord
Et bien d'autres

Consultez leur documentation pour l'intégration.

Test de l'endpoint

Lors de la configuration de l'endpoint, nous exécutons automatiquement les tests suivants pour nous assurer que l'endpoint fonctionne comme prévu :

Vérifier que l'appel ne prend pas plus de 10 secondes
Vérifier que le message d'erreur est au bon format afin que nous puissions l'afficher à l'utilisateur
S'assurer qu'il ne s'agit pas d'un code de statut inattendu. L'endpoint ne doit renvoyer que 200 ou 400.

Créer un endpoint personnalisé

Requête

Vous pouvez utiliser les tâches API avec un POST endpoint personnalisé acceptant le corps suivant :

POST https://domain.com/endpoint

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

Vous pouvez le protéger avec une clé API définie lors de la création de la tâche. La clé API sera envoyée dans les en-têtes comme ceci :

Headers

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

Réponse

Si l'action a été effectuée avec succès par l'utilisateur, vous devez renvoyer un statut 200 . L'utilisateur pourra alors réclamer la tâche avec succès.

RESPONSE 200

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

Sinon, le statut 400 doit être renvoyé dans la réponse avec un message dans le corps. Le message sera affiché avec le requestId généré pour vous aider, vous et l'utilisateur, à déboguer les problèmes. Assurez-vous qu'il soit aussi descriptif que possible.

RESPONSE 400

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

Exemple de code

// 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 local avec ngrok

Lors du développement et du test de votre endpoint personnalisé en local, vous avez besoin d'un moyen d'exposer votre serveur local à Internet afin que Zealy puisse lui envoyer des requêtes API. ngrok est un outil qui crée des tunnels sécurisés vers localhost et est parfait pour cela. Suivez ces étapes pour configurer ngrok et tester votre endpoint :

Étape 1 : Installer ngrok Téléchargez ngrok depuis le site web de ngrok. Suivez les instructions d'installation pour votre système d'exploitation.

Étape 2 : Configurer ngrok Créez un compte ngrok gratuit et récupérez votre authtoken depuis le tableau de bord ngrok. Connectez votre compte ngrok en exécutant ngrok authtoken YOUR_AUTH_TOKEN dans votre terminal, en remplaçant YOUR_AUTH_TOKEN par le token de votre tableau de bord ngrok.

Étape 3 : Démarrer votre serveur local Assurez-vous que votre serveur local qui héberge l'endpoint est en cours d'exécution. Par exemple, si votre serveur est une application Node.js, vous pouvez exécuter node server.js.

Étape 4 : Exposer votre serveur local avec ngrok Ouvrez une nouvelle fenêtre de terminal et démarrez un tunnel ngrok vers le port de votre serveur local (par exemple, 3000) en utilisant ngrok http http://127.0.0.1:3000. ngrok affichera une URL de transfert dans le terminal (par exemple, https://abc123.ngrok.io). C'est l'URL publique que Zealy utilisera pour atteindre votre serveur local.

Étape 5 : Configurer votre tâche API dans Zealy Utilisez l'URL de transfert ngrok comme URL d'endpoint lors de la configuration de votre tâche API dans Zealy. Assurez-vous d'ajouter tout chemin requis, par exemple, https://abc123.ngrok.io/claim.

Remarque : N'oubliez pas que les URL ngrok sont temporaires et changent à chaque redémarrage de ngrok, sauf si vous avez un abonnement payant prenant en charge les sous-domaines personnalisés. Assurez-vous de mettre à jour l'endpoint dans Zealy à chaque redémarrage de ngrok.

En suivant ces étapes, vous pouvez facilement tester et déboguer votre endpoint personnalisé dans un environnement de développement local avant de le déployer sur un serveur de production.

Intégration Zealy Connect

Lors de l'utilisation de Zealy Connect, nous redirigerons l'utilisateur vers l'URL spécifiée lors de la configuration de la tâche. Nous inclurons les paramètres de requête suivants :

zealyUserId: Un identifiant unique pour l'utilisateur dans le système Zealy, utilisé pour le lier à votre plateforme.
callback: L'URL vers laquelle rediriger l'utilisateur après l'authentification afin qu'il puisse réclamer la tâche.
signature: Un hachage SHA-256 utilisé pour vérifier l'authenticité de la requête, en s'assurant qu'elle provient bien de Zealy.

Voici un exemple complet d'endpoint que vous pouvez utiliser comme point de départ :

 
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. Vérifier la signature

La première chose que votre application doit faire est de valider la signature à l'aide du secret de votre communauté. Cette validation garantit que l'appel provient réellement de nous et n'a pas été modifié.

Nous utilisons l'algorithme de hachage SHA256 pour générer la signature. Pour la vérifier, vous pouvez utiliser l'approche suivante :

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. Utilisez l'ID utilisateur Zealy

L'étape suivante dépend de ce que vous souhaitez faire, mais les clients connectent généralement l'utilisateur actuel sur votre plateforme et associent l'ID utilisateur de votre plateforme à l'ID utilisateur Zealy. Voici un exemple :

  /**
   * 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. Rediriger vers Zealy

La dernière étape consiste à rediriger l'utilisateur vers Zealy avec l'ID utilisateur de votre plateforme afin que nous puissions permettre à l'utilisateur de réclamer la tâche, en utilisant le paramètre de requête callback que nous fournissons. Vous devez également générer une signature afin que nous puissions vérifier que l'appel provient de vous et n'a pas été modifié. Voir l'exemple ci-dessous :

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

Une fois le callback reçu, nous validerons la signature et stockerons l'ID utilisateur de votre plateforme afin de pouvoir l'envoyer dans le corps de la tâche API.

L'utilisateur pourra désormais réclamer la tâche ainsi que toute autre tâche utilisant Zealy Connect avec la même URL de redirection. Nous mémoriserons cela afin que l'utilisateur n'ait pas à se connecter pour chaque tâche.

Si vous devez supprimer l'association Zealy Connect d'un utilisateur, vous pouvez utiliser la route API Delete Zealy Connect for Member. Cette route vous permet de supprimer l'association Zealy Connect d'un membre spécifique. Après avoir appelé cette route, l'utilisateur devra reconnecter son compte pour utiliser à nouveau les fonctionnalités de Zealy Connect.