Zealy दस्तऐवजीकरण

स्वयंचलितपणे भाषांतरित · इंग्रजीत वाचा

API

बाह्य प्लॅटफॉर्मवर क्रिया स्वयंचलित करा

द्वारे Fredrika

API
या पृष्ठावर

आढावा

हा मार्गदर्शक API कार्याबद्दल आहे. आमचे संपूर्ण API दस्तऐवजीकरण तुम्हाला येथे.

API क्वेस्ट्स बाह्य प्लॅटफॉर्मवरील क्वेस्ट्स स्वयंचलित करण्यासाठी वापरल्या जातात. वापरकर्त्याने नोंदणी केली आहे किंवा खरेदी केली आहे, Github वरील एखाद्या इश्यूसाठी PR उघडला आहे किंवा Reddit सपोर्ट जोडला आहे याची पुष्टी करण्यासाठी तुम्ही ते वापरू शकता. शक्यता अमर्याद आहेत. सुरुवात करण्यासाठी आणि आम्ही देऊ करत असलेली कार्यक्षमता वापरून पाहण्यासाठी आम्ही एक मूलभूत एंडपॉइंट देऊ करतो जो तुम्ही इतर Zealy समुदायांसोबत भागीदारी करण्यासाठी वापरू शकता. ते कसे सेट करायचे याबद्दल खाली अधिक जाणून घ्या.

मूलभूत गोष्टी

"API" कार्य तयार करणे

  1. वर क्लिक करा 'कार्य जोडा'.
  2. निवडा 'Api'.
  3. कॉल करण्यासाठी एंडपॉइंट आणि आवश्यक असल्यास API की निश्चित करा.
  4. वापरकर्ते कसे ओळखू शकतात ते निवडा. तुम्ही यामधून निवडू शकता ईमेल, Twitter, Discord, वॉलेट पत्ता, किंवा Zealy Connect.
  • निवडल्यास वॉलेट कनेक्शन, तुम्ही कोणते नेटवर्क वापरायचे ते देखील निवडू शकता.

नवीन ब्लॉकचेन

  • निवडल्यास Zealy Connect, हे चरण अनुसरा:

    1. रीडायरेक्ट URL परिभाषित करा: हा URL प्रमाणीकरणासाठी वापरला जाईल. तुमच्या सिस्टीममध्ये प्रमाणीकरण करण्यासाठी आम्ही वापरकर्त्यांना या URL वर रीडायरेक्ट करू.

    Zealy Connect API TASK

    1. कम्युनिटी सीक्रेट तयार करा: कम्युनिटी सीक्रेट तयार करणे यासाठी आवश्यक आहे Zealy Connect कार्य करण्यासाठी. तुम्ही हे गुपित येथून तयार करू शकता: Zealy Connect सेटिंग्ज या अंतर्गत Integrations विभाग तुमच्या समुदाय सेटिंग्जमध्ये.

    Community Secret

API कशा प्रकारे कार्य करतील याबद्दल सविस्तर माहितीसाठी, कृपया पहा API दस्तऐवजीकरण आणि Zealy Connect व्यवस्थापित करण्याबाबत मार्गदर्शनासाठी, कृपया पहा Zealy Connect दस्तऐवजीकरण.

Domino सह एकत्रीकरण

Domino हे Web3 Zapier आहे. हे तुम्हाला Zealy ची क्षमता वाढवण्यास आणि मूळतः समर्थित नसलेल्या कार्यांचे स्वयंचलितपणे पुनरावलोकन करण्यास अनुमती देते, जसे की:

  • वापरकर्त्याच्या Twitter नावात किंवा बायोमध्ये विशिष्ट शब्द आहे का हे तपासणे
  • वापरकर्त्याची NFT आणि टोकन शिल्लक तपासणे
  • वापरकर्त्याने Discord वर विशिष्ट संख्येने लोकांना आमंत्रित केले आहे याची पडताळणी करणे
  • आणि बरेच काही

त्यांचे पहा दस्तऐवजीकरण एकत्रीकरणासाठी.

एंडपॉइंट चाचणी

एंडपॉइंट कॉन्फिगर करताना एंडपॉइंट अपेक्षेप्रमाणे कार्यरत आहे याची खात्री करण्यासाठी आम्ही खालील चाचण्या स्वयंचलितपणे चालवू:

  1. कॉल 10 सेकंदांपेक्षा जास्त काळ घेत नाही याची तपासणी करणे
  2. त्रुटी संदेश योग्य स्वरूपात आहे याची पडताळणी करणे जेणेकरून आम्ही तो वापरकर्त्याला दाखवू शकू
  3. हे कोणत्याही अनपेक्षित स्थिती कोडपैकी नाही याची खात्री करा. एंडपॉइंटने फक्त 200 किंवा 400 परत करावे.

सानुकूल एंडपॉइंट तयार करणे

विनंती

तुम्ही API कार्ये सानुकूल POST एंडपॉइंटसह वापरू शकता जे खालील बॉडी स्वीकारते:

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
  };
}

कार्य तयार करताना सेट केलेल्या API की ने तुम्ही ते संरक्षित करू शकता. API की हेडरमध्ये अशा प्रकारे पाठवली जाईल:

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

प्रतिसाद

वापरकर्त्याने कृती यशस्वीरित्या पूर्ण केली असल्यास तुम्ही परत करावे 200 स्थिती. वापरकर्ता नंतर कार्य यशस्वीरित्या दावा करेल.

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

अन्यथा, 400 स्थिती प्रतिसादात बॉडीमधील संदेशासह परत केली पाहिजे. संदेश व्युत्पन्न केलेल्या सह प्रदर्शित केला जाईल requestId तुम्हाला आणि वापरकर्त्याला कोणत्याही समस्या डीबग करण्यात मदत करण्यासाठी. ते शक्य तितके वर्णनात्मक असल्याची खात्री करा.

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

कोड उदाहरण

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

ngrok सह स्थानिक चाचणी

तुमचा सानुकूल एंडपॉइंट स्थानिकरित्या विकसित आणि चाचणी करताना, Zealy त्यावर API विनंत्या पाठवू शकेल यासाठी तुमचा स्थानिक सर्व्हर इंटरनेटवर उघड करण्याचा मार्ग तुम्हाला आवश्यक आहे. ngrok हे एक साधन आहे जे localhost वर सुरक्षित बोगदे तयार करते आणि या उद्देशासाठी योग्य आहे. ngrok सेट करण्यासाठी आणि तुमचा एंडपॉइंट चाचणी करण्यासाठी या पायऱ्या अनुसरा:

पायरी 1: ngrok स्थापित करा ngrok च्या वेबसाइटवरून ngrok डाउनलोड करा. तुमच्या ऑपरेटिंग सिस्टमसाठी स्थापना सूचना अनुसरा.

पायरी 2: ngrok सेट करा विनामूल्य ngrok खात्यासाठी साइन अप करा आणि ngrok डॅशबोर्डवरून तुमचा authtoken मिळवा. तुमच्या टर्मिनलमध्ये ngrok authtoken YOUR_AUTH_TOKEN चालवून तुमचे ngrok खाते जोडा, YOUR_AUTH_TOKEN च्या जागी तुमच्या ngrok डॅशबोर्डमधील टोकन टाका.

पायरी 3: तुमचा स्थानिक सर्व्हर सुरू करा एंडपॉइंट होस्ट करणारा तुमचा स्थानिक सर्व्हर सुरू असल्याची खात्री करा. उदाहरणार्थ, तुमचा सर्व्हर Node.js अॅप असल्यास, तुम्ही node server.js चालवू शकता.

पायरी 4: ngrok वापरून तुमचा स्थानिक सर्व्हर उघडा नवीन टर्मिनल विंडो उघडा आणि तुमच्या स्थानिक सर्व्हरच्या पोर्टवर (उदा., 3000) ngrok टनेल सुरू करा: ngrok http http://127.0.0.1:3000. ngrok टर्मिनलमध्ये फॉरवर्डिंग URL दाखवेल (उदा., https://abc123.ngrok.io). ही सार्वजनिक URL आहे जी Zealy तुमच्या स्थानिक सर्व्हरपर्यंत पोहोचण्यासाठी वापरेल.

पायरी 5: Zealy मध्ये तुमचे API कार्य कॉन्फिगर करा Zealy मध्ये तुमचे API कार्य सेट करताना एंडपॉइंट URL म्हणून ngrok फॉरवर्डिंग URL वापरा. आवश्यक असल्यास पथ जोडण्याची खात्री करा, उदाहरणार्थ, https://abc123.ngrok.io/claim.

टीप: लक्षात ठेवा, ngrok URLs तात्पुरत्या असतात आणि तुम्ही ngrok पुन्हा सुरू केल्यावर प्रत्येक वेळी बदलतात, जोपर्यंत तुमच्याकडे कस्टम सबडोमेनला समर्थन देणारी सशुल्क सदस्यता नाही. तुम्ही ngrok पुन्हा सुरू केल्यावर प्रत्येक वेळी Zealy मधील endpoint अपडेट करण्याची खात्री करा.

या पायऱ्यांचे पालन करून, तुम्ही तुमचा कस्टम endpoint प्रोडक्शन सर्व्हरवर डिप्लॉय करण्यापूर्वी स्थानिक विकास वातावरणात सहजपणे चाचणी आणि डीबग करू शकता.

Zealy Connect एकत्रीकरण

Zealy Connect वापरताना, आम्ही वापरकर्त्याला टास्क सेटअप दरम्यान निर्दिष्ट केलेल्या URL वर पुनर्निर्देशित करू. आम्ही खालील query params समाविष्ट करू:

  • zealyUserId: Zealy सिस्टममधील वापरकर्त्यासाठी एक अद्वितीय ओळखकर्ता, जो त्यांना तुमच्या प्लॅटफॉर्मशी जोडण्यासाठी वापरला जातो.
  • callback: प्रमाणीकरण पूर्ण झाल्यानंतर वापरकर्त्याला परत पुनर्निर्देशित करण्यासाठीचा URL, जेणेकरून ते टास्क क्लेम करू शकतील.
  • signature: विनंतीची सत्यता पडताळण्यासाठी वापरला जाणारा SHA-256 हॅश, ज्यामुळे ती Zealy कडून आली आहे याची खात्री होते.

सुरुवातीचा बिंदू म्हणून तुम्ही वापरू शकता असा संपूर्ण उदाहरण endpoint येथे आहे:

 
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. स्वाक्षरी सत्यापित करा

तुमच्या अॅप्लिकेशनने पहिली गोष्ट म्हणजे तुमच्या community secret वापरून स्वाक्षरी सत्यापित करणे. हे सत्यापन सुनिश्चित करते की कॉल खरोखर आमच्याकडून आला आहे आणि त्यात बदल केलेला नाही.

आम्ही सही तयार करण्यासाठी SHA256 हॅश अल्गोरिदम वापरतो. ती पडताळण्यासाठी तुम्ही खालील पद्धत वापरू शकता:

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. Zealy User ID वापरा

पुढील पायरी तुम्हाला काय करायचे आहे यावर अवलंबून आहे, परंतु ग्राहक सहसा तुमच्या प्लॅटफॉर्मवर वर्तमान वापरकर्ता लॉग इन करतात आणि तुमच्या प्लॅटफॉर्मचा वापरकर्ता ID Zealy User ID शी जोडतात. खाली एक उदाहरण आहे:

  /**
   * 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. Zealy कडे परत रीडायरेक्ट करा

शेवटची पायरी म्हणजे वापरकर्त्याला तुमच्या प्लॅटफॉर्मच्या वापरकर्ता ID सह Zealy कडे परत रीडायरेक्ट करणे, जेणेकरून आम्ही वापरकर्त्याला क्वेस्ट क्लेम करण्याची परवानगी देऊ शकतो, आम्ही देतो त्या callback क्वेरी पॅरामीटरचा वापर करून. कॉल तुमच्याकडून येत आहे आणि त्यात बदल केलेला नाही हे आम्ही पडताळू शकावे यासाठी तुम्हाला सही देखील तयार करावी लागेल. खालील उदाहरण पहा:

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

आम्हाला callback मिळाल्यावर आम्ही सही पडताळू आणि तुमच्या प्लॅटफॉर्मचा वापरकर्ता ID साठवू, जेणेकरून आम्ही तो API क्वेस्ट बॉडीचा भाग म्हणून पाठवू शकू.

वापरकर्ता आता ही क्वेस्ट आणि त्याच रीडायरेक्ट URL सह Zealy Connect वापरणारी इतर कोणतीही क्वेस्ट क्लेम करू शकेल. आम्ही हे लक्षात ठेवू, जेणेकरून वापरकर्त्याला प्रत्येक क्वेस्टसाठी कनेक्ट करावे लागणार नाही.

जर तुम्हाला वापरकर्त्याचे Zealy Connect संलग्नीकरण हटवायचे असेल, तर तुम्ही वापरू शकता सदस्यासाठी Zealy Connect हटवा API मार्ग. हा मार्ग तुम्हाला विशिष्ट सदस्यासाठी Zealy Connect संलग्नीकरण काढण्याची परवानगी देतो. हा मार्ग कॉल केल्यानंतर, वापरकर्त्याला Zealy Connect वैशिष्ट्ये पुन्हा वापरण्यासाठी त्यांचे खाते पुन्हा जोडावे लागेल.

सामान्य प्रश्न