API

अवलोकन

यो गाइड API कार्यको बारेमा हो। तपाईंले हाम्रो पूर्ण API कागजात यहाँ फेला पार्न सक्नुहुन्छ यहाँ.

API क्वेस्टहरू बाह्य प्लेटफर्महरूमा क्वेस्टहरू स्वचालित गर्न प्रयोग गरिन्छ। तपाईंले यसलाई प्रयोगकर्ताले दर्ता गरेको वा खरिद गरेको पुष्टि गर्न, Github मा कुनै समस्याको लागि PR खोलेको छ वा Reddit समर्थन थप्न प्रयोग गर्न सक्नुहुन्छ। सम्भावनाहरू असीमित छन्। सुरु गर्न र हामीले प्रदान गर्ने कार्यक्षमता प्रयास गर्न, हामी एउटा आधारभूत endpoint प्रदान गर्छौं जुन तपाईंले अन्य Zealy समुदायहरूसँग साझेदारी गर्न प्रयोग गर्न सक्नुहुन्छ। यसलाई कसरी सेट अप गर्ने भनेर तल थप जान्नुहोस्।

आधारभूत कुराहरू

"API" कार्य सिर्जना गर्नुहोस्

1. क्लिक गर्नुहोस् 'कार्य थप्नुहोस्'.
2. चयन गर्नुहोस् 'Api'.
3. कल गर्ने endpoint र आवश्यक भएमा API key परिभाषित गर्नुहोस्।
4. प्रयोगकर्ताहरूले कसरी पहिचान गर्न सक्छन् छान्नुहोस्। तपाईं यसबाट चयन गर्न सक्नुहुन्छ इमेल, Twitter, Discord, वallet ठेगाना, वा Zealy Connect.

• यदि छनोट गर्दा वallet जडान, तपाईंले कुन नेटवर्क प्रयोग गर्ने भन्ने पनि छनोट गर्न सक्नुहुन्छ।

• यदि छनोट गर्दै Zealy Connect, यी चरणहरू पालना गर्नुहोस्:

  1. रिडाइरेक्ट URL परिभाषित गर्नुहोस्: यो URL प्रमाणीकरणका लागि प्रयोग गरिनेछ। तपाईंको प्रणालीमा प्रमाणीकरण गर्न हामी प्रयोगकर्ताहरूलाई यो URL मा रिडाइरेक्ट गर्नेछौं।

  

  2. समुदाय गोप्य सिर्जना गर्नुहोस्: समुदाय गोप्य सिर्जना गर्नु आवश्यक छ Zealy Connect काम गर्न। तपाईं यो secret यहाँबाट सिर्जना गर्न सक्नुहुन्छ: Zealy Connect सेटिङहरू अन्तर्गत Integrations खण्ड तपाईंको समुदाय सेटिङहरूमा।

  

API हरूले कसरी काम गर्ने अपेक्षा गरिन्छ भन्ने विस्तृत जानकारीका लागि, कृपया हेर्नुहोस् API documentation र Zealy Connect व्यवस्थापनसम्बन्धी मार्गदर्शनका लागि, कृपया हेर्नुहोस् Zealy Connect documentation.

Domino सँग एकीकरण

Domino Web3 Zapier हो। यसले तपाईंलाई Zealy का क्षमताहरू विस्तार गर्न र नेटिभ रूपमा समर्थित नभएका कार्यहरू स्वचालित रूपमा समीक्षा गर्न अनुमति दिन्छ, जस्तै:

• प्रयोगकर्ताको Twitter नाम वा बायोमा कुनै विशेष शब्द छ कि छैन जाँच गर्ने
• प्रयोगकर्ताको NFT र टोकन ब्यालेन्स जाँच गर्ने
• प्रयोगकर्ताले Discord मा निश्चित संख्यामा व्यक्तिहरूलाई निमन्त्रणा गरेको छ कि छैन प्रमाणित गर्ने
• र थप धेरै

तिनीहरूको हेर्नुहोस् कागजात एकीकरणका लागि।

एन्डपोइन्ट परीक्षण

एन्डपोइन्ट कन्फिगर गर्दा एन्डपोइन्ट अपेक्षाअनुसार काम गरिरहेको छ भनी सुनिश्चित गर्न हामी स्वचालित रूपमा निम्न परीक्षणहरू चलाउनेछौं:

1. कल १० सेकेन्डभन्दा लामो नहुने सुनिश्चित गर्दै
2. त्रुटि सन्देश सही ढाँचामा छ कि छैन भनी प्रमाणित गर्दै ताकि हामी यसलाई प्रयोगकर्तालाई देखाउन सकौं
3. यो कुनै पनि अप्रत्याशित स्टेटस कोड नभएको सुनिश्चित गर्दै। इन्डपोइन्टले 200 वा 400 मात्र फर्काउनुपर्छ।

कस्टम इन्डपोइन्ट सिर्जना गर्दै

अनुरोध

तपाईं API कार्यहरू कस्टम POST इन्डपोइन्टसँग प्रयोग गर्न सक्नुहुन्छ जसले निम्न बडी स्वीकार गर्छ:

{
  /**
   * 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 कुञ्जी हेडरहरूमा यसरी पठाइनेछ:

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

प्रतिक्रिया

यदि प्रयोगकर्ताले कार्य सफलतापूर्वक सम्पन्न गरेको छ भने तपाईंले 200 स्थिति। प्रयोगकर्ताले त्यसपछि कार्य सफलतापूर्वक दाबी गर्नेछ।

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

अन्यथा, 400 स्थिति प्रतिक्रियामा शरीरमा सन्देशसँगै फर्काइनुपर्छ। सन्देश सिर्जित सँग देखाइनेछ requestId तपाईं र प्रयोगकर्तालाई कुनै पनि समस्या डिबग गर्न मद्दत गर्न। यो सकेसम्म वर्णनात्मक छ भनी सुनिश्चित गर्नुहोस्।

{
  "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 डाउनलोड गर्नुहोस्। तपाईंको अपरेटिङ सिस्टमका लागि स्थापना निर्देशनहरू पालना गर्नुहोस्।

चरण २: ngrok सेट अप गर्नुहोस् निःशुल्क ngrok खातामा साइन अप गर्नुहोस् र ngrok ड्यासबोर्डबाट आफ्नो authtoken प्राप्त गर्नुहोस्। टर्मिनलमा ngrok authtoken YOUR_AUTH_TOKEN चलाएर आफ्नो ngrok खाता जोड्नुहोस्, YOUR_AUTH_TOKEN लाई ngrok ड्यासबोर्डको टोकनले प्रतिस्थापन गर्दै।

चरण ३: आफ्नो स्थानीय सर्भर सुरु गर्नुहोस् एन्डपोइन्ट होस्ट गर्ने तपाईंको स्थानीय सर्भर चलिरहेको छ भनी सुनिश्चित गर्नुहोस्। उदाहरणका लागि, यदि तपाईंको सर्भर Node.js एप हो भने, तपाईंले node server.js चलाउन सक्नुहुन्छ।

चरण ४: ngrok प्रयोग गरी आफ्नो स्थानीय सर्भर एक्सपोज गर्नुहोस् नयाँ टर्मिनल विन्डो खोल्नुहोस् र आफ्नो स्थानीय सर्भरको पोर्ट (जस्तै, 3000) मा ngrok टनेल सुरु गर्नुहोस् ngrok http http://127.0.0.1:3000. ngrok ले टर्मिनलमा फर्वार्डिङ URL देखाउनेछ (जस्तै, https://abc123.ngrok.io)। यो सार्वजनिक URL हो जुन Zealy ले तपाईंको स्थानीय सर्भरमा पुग्न प्रयोग गर्नेछ।

चरण ५: Zealy मा आफ्नो API कार्य कन्फिगर गर्नुहोस् Zealy मा आफ्नो API कार्य सेट अप गर्दा ngrok फर्वार्डिङ URL लाई एन्डपोइन्ट URL का रूपमा प्रयोग गर्नुहोस्। आवश्यक पथ थप्न नबिर्सनुहोस्, उदाहरणका लागि, https://abc123.ngrok.io/claim.

नोट: याद राख्नुहोस्, ngrok URL हरू अस्थायी हुन्छन् र तपाईंले ngrok पुनः सुरु गर्दा हरेक पटक परिवर्तन हुन्छन्, जबसम्म तपाईंसँग कस्टम सबडोमेन समर्थन गर्ने सशुल्क सदस्यता छैन। तपाईंले ngrok पुनः सुरु गर्दा हरेक पटक Zealy मा endpoint अद्यावधिक गर्न निश्चित गर्नुहोस्।

यी चरणहरू पालना गरेर, तपाईंले उत्पादन सर्भरमा तैनाथ गर्नु अघि स्थानीय विकास वातावरणमा आफ्नो कस्टम endpoint सजिलै परीक्षण र डिबग गर्न सक्नुहुन्छ।

Zealy Connect एकीकरण

Zealy Connect प्रयोग गर्दा, हामी प्रयोगकर्तालाई कार्य सेटअपको क्रममा निर्दिष्ट गरिएको URL मा रिडिरेक्ट गर्नेछौं। हामी निम्न क्वेरी प्यारामहरू समावेश गर्नेछौं:

• 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. हस्ताक्षर प्रमाणित गर्नुहोस्

तपाईंको एप्लिकेसनले सबैभन्दा पहिले तपाईंको समुदायको गोप्य कुञ्जी प्रयोग गरेर हस्ताक्षर प्रमाणित गर्नुपर्छ। यो प्रमाणीकरणले कल साँच्चै हामीबाट आएको हो र परिवर्तन गरिएको छैन भन्ने सुनिश्चित गर्छ।

हामी हस्ताक्षर उत्पन्न गर्न 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 कार्य बडीको भागको रूपमा पठाउन सकौं।

प्रयोगकर्ताले अब यो कार्य र उही redirect URL प्रयोग गर्ने Zealy Connect प्रयोग गर्ने अन्य कुनै पनि कार्य दाबी गर्न सक्नेछ। हामी यो सम्झनेछौं ताकि प्रयोगकर्ताले प्रत्येक कार्यका लागि जोडिनु नपर्ने हो।

यदि तपाईंले प्रयोगकर्ताको Zealy Connect सम्बन्ध मेटाउनु पर्ने भयो भने, तपाईं प्रयोग गर्न सक्नुहुन्छ सदस्यका लागि Zealy Connect मेटाउने API मार्ग। यो मार्गले तपाईंलाई एक विशेष सदस्यको Zealy Connect सम्बन्ध हटाउन अनुमति दिन्छ। यो मार्ग कल गरेपछि, प्रयोगकर्ताले Zealy Connect सुविधाहरू फेरि प्रयोग गर्न आफ्नो खाता पुनः जोड्नुपर्नेछ।

प्रश्नोत्तर