API

Pangkalahatang-tanaw

Ang gabay na ito ay tungkol sa API task. Makikita mo ang aming buong dokumentasyon ng API dito.

Ang mga API quest ay ginagamit upang i-automate ang mga quest sa mga panlabas na platform. Maaari mong gamitin ito upang kumpirmahin na ang user ay nagrehistro o bumili, nagbukas ng PR para sa isang isyu sa Github o upang magdagdag ng suporta sa Reddit. Walang hangganan ang mga posibilidad. Upang makapagsimula at masubukan ang functionality, nag-aalok kami ng isang basic endpoint na maaari mong gamitin para sa pakikipagtulungan sa iba pang Zealy community. Alamin pa ang tungkol sa kung paano ito i-set up sa ibaba.

Mga Batayan

Paglikha ng isang "API" Task

1. I-click ang 'Add task'.
2. Piliin ang 'Api'.
3. Tukuyin ang endpoint na tatawagin at isang API key kung kailangan.
4. Piliin kung paano makikilala ng mga user. Maaari kang pumili mula sa Email, Twitter, Discord, Wallet address, o Zealy Connect.

• Kung pipiliin ang wallet connection, maaari mo ring piliin kung aling network ang gagamitin.

• Kung pipiliin ang Zealy Connect, sundin ang mga hakbang na ito:

  1. Tukuyin ang redirect URL: Ang URL na ito ay gagamitin para sa authentication. I-redirect namin ang mga user sa URL na ito upang mag-authenticate sila sa iyong system.

  

  2. Bumuo ng community secret: Ang pagbuo ng community secret ay kinakailangan para gumana ang Zealy Connect . Maaari mong likhain ang secret mula sa Zealy Connect settings sa ilalim ng Integrations section sa iyong community settings.

  

Para sa malalim na impormasyon tungkol sa kung paano inaasahang gumana ang mga API, tingnan ang API documentation at para sa gabay sa pamamahala ng Zealy Connect, mangyaring sumangguni sa Zealy Connect documentation.

Integrasyon sa Domino

Ang Domino ay ang Web3 Zapier. Pinapayagan ka nitong palawakin ang mga kakayahan ng Zealy at awtomatikong suriin ang mga task na hindi native na sinusuportahan, tulad ng:

• Pagsuri kung ang Twitter name o bio ng isang user ay naglalaman ng isang partikular na salita
• Pagsuri sa NFT at token balance ng isang user
• Pag-verify na ang isang user ay nag-imbita ng tiyak na bilang ng mga tao sa Discord
• At marami pang iba

Tingnan ang kanilang documentation para sa integrasyon.

Pagsubok ng endpoint

Kapag kino-configure ang endpoint, awtomatiko naming patatakbuhin ang mga sumusunod na test upang matiyak na gumagana ang endpoint ayon sa inaasahan:

1. Pagsuri upang ang tawag ay hindi tumagal ng higit sa 10 segundo
2. Pag-verify na ang error message ay nasa tamang format upang maipakita namin ito sa user
3. Pagtiyak na wala itong anumang hindi inaasahang status code. Ang endpoint ay dapat lamang magbalik ng 200 o 400.

Paglikha ng custom na endpoint

Request

Maaari mong gamitin ang mga API task sa isang custom na POST endpoint na tumatanggap ng sumusunod na body:

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

Maaari mong protektahan ito gamit ang isang API key na itinakda kapag ginagawa ang task. Ang API key ay ipapadala sa mga header tulad nito:

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

Response

Kung matagumpay na naisagawa ng user ang aksyon, dapat kang magbalik ng 200 status. Matagumpay nang ma-claim ng user ang task.

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

Kung hindi, ang 400 status ay dapat ibalik sa response kasama ang isang mensahe sa body. Ang mensahe ay ipapakita kasama ang nabuong requestId upang matulungan ka at ang user na i-debug ang anumang isyu. Tiyakin na ito ay kasing deskriptibo hangga't maaari.

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

Halimbawa ng 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'));

Lokal na pagsubok gamit ang ngrok

Kapag nagde-develop at nagte-test ng iyong custom na endpoint nang lokal, kailangan mo ng paraan upang ilantad ang iyong lokal na server sa internet upang makapagpadala ang Zealy ng mga API request dito. Ang ngrok ay isang tool na gumagawa ng mga secure na tunnel sa localhost at perpekto para sa layuning ito. Sundin ang mga hakbang na ito upang i-set up ang ngrok at subukan ang iyong endpoint:

Hakbang 1: I-install ang ngrok I-download ang ngrok mula sa website ng ngrok. Sundin ang mga tagubilin sa pag-install para sa iyong operating system.

Hakbang 2: I-set up ang ngrok Mag-sign up para sa isang libreng ngrok account at kunin ang iyong authtoken mula sa ngrok dashboard. Ikonekta ang iyong ngrok account sa pamamagitan ng pagpapatakbo ng ngrok authtoken YOUR_AUTH_TOKEN sa iyong terminal, na pinapalitan ang YOUR_AUTH_TOKEN ng token mula sa iyong ngrok dashboard.

Hakbang 3: Simulan ang iyong lokal na server Tiyakin na tumatakbo ang iyong lokal na server na nagho-host ng endpoint. Halimbawa, kung ang iyong server ay isang Node.js app, maaari mong patakbuhin ang node server.js.

Hakbang 4: Ilantad ang iyong lokal na server gamit ang ngrok Magbukas ng bagong terminal window at magsimula ng ngrok tunnel sa port ng iyong lokal na server (hal., 3000) gamit ang ngrok http http://127.0.0.1:3000. Magpapakita ang ngrok ng forwarding URL sa terminal (hal., https://abc123.ngrok.io). Ito ang pampublikong URL na gagamitin ng Zealy upang maabot ang iyong lokal na server.

Hakbang 5: I-configure ang iyong API task sa Zealy Gamitin ang ngrok forwarding URL bilang endpoint URL kapag nagse-set up ng iyong API task sa Zealy. Tiyaking idagdag ang anumang kinakailangang path, halimbawa, https://abc123.ngrok.io/claim.

Tandaan: Tandaan, ang mga ngrok URL ay pansamantala at nagbabago tuwing i-restart mo ang ngrok, maliban kung mayroon kang bayad na subscription na sumusuporta sa custom subdomains. Tiyaking i-update ang endpoint sa Zealy tuwing i-restart mo ang ngrok.

Sa pagsunod sa mga hakbang na ito, madali mong masusubukan at ma-debug ang iyong custom na endpoint sa isang lokal na development environment bago ito i-deploy sa isang production server.

Integrasyon ng Zealy Connect

Kapag gumagamit ng Zealy Connect, i-redirect namin ang user sa URL na tinukoy sa panahon ng pag-set up ng task. Isasama namin ang mga sumusunod na query param:

• zealyUserId: Isang natatanging identifier para sa user sa Zealy system na ginagamit upang i-link sila sa iyong platform.
• callback: Ang URL upang i-redirect pabalik ang user pagkatapos makumpleto ang authentication upang ma-claim nila ang task.
• signature: Isang SHA-256 hash na ginagamit upang i-verify ang pagiging tunay ng request, na tinitiyak na nagmula ito sa Zealy.

Narito ang isang buong halimbawa ng endpoint na maaari mong gamitin bilang panimulang punto:

 
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. I-verify ang Signature

Ang unang dapat gawin ng iyong application ay i-validate ang signature gamit ang iyong community secret. Tinitiyak ng validation na ito na ang tawag ay tunay na nagmula sa amin at hindi nabago.

Ginagamit namin ang SHA256 hash algorithm para bumuo ng signature. Para i-verify ito, maaari mong gamitin ang sumusunod na paraan:

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. Gamitin ang Zealy User ID

Ang susunod na hakbang ay depende sa gusto mong gawin, ngunit karaniwang nila-log in ng mga customer ang kasalukuyang user sa iyong platform at iniuugnay ang user ID ng iyong platform sa Zealy User ID. Nasa ibaba ang isang halimbawa:

  /**
   * 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. Mag-redirect Pabalik sa Zealy

Ang huling hakbang ay i-redirect ang user pabalik sa Zealy kasama ang user ID ng iyong platform para payagan namin ang user na i-claim ang task, gamit ang callback query parameter na ibinibigay namin. Kailangan mo ring bumuo ng signature para ma-verify namin na ang tawag ay nagmumula sa iyo at hindi binago. Tingnan ang halimbawa sa ibaba:

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

Kapag natanggap namin ang callback, iva-validate namin ang signature at iimbak ang user ID ng iyong platform para maipadala namin ito bilang bahagi ng API task body.

Magagawa na ngayon ng user na i-claim ang task at anumang iba pang task na gumagamit ng Zealy Connect na may parehong redirect URL. Tatandaan namin ito para hindi na kailangang kumonekta ng user para sa bawat task.

Kung kailangan mong tanggalin ang Zealy Connect association ng isang user, maaari mong gamitin ang Delete Zealy Connect for Member API route. Pinapayagan ka ng route na ito na alisin ang Zealy Connect association para sa isang partikular na member. Pagkatapos tawagan ang route na ito, kakailanganin ng user na muling ikonekta ang kanilang account para magamit muli ang mga feature ng Zealy Connect.

FAQ