API
बाहरी प्लेटफ़ॉर्म पर क्रियाएँ स्वचालित करें
द्वारा Fredrika
इस पेज पर
अवलोकन
यह गाइड API टास्क के बारे में है। हमारा पूरा API दस्तावेज़ीकरण आप यहाँ पा सकते हैं यहाँ.
API क्वेस्ट का उपयोग बाहरी प्लेटफ़ॉर्म पर क्वेस्ट स्वचालित करने के लिए किया जाता है। आप इसका उपयोग यह पुष्टि करने के लिए कर सकते हैं कि उपयोगकर्ता ने पंजीकरण किया है या खरीदारी की है, Github पर किसी issue के लिए PR खोला है या Reddit सपोर्ट जोड़ा है। संभावनाएँ अनंत हैं। शुरुआत करने और हमारी सुविधाओं को आज़माने के लिए हम एक बेसिक endpoint प्रदान करते हैं जिसका उपयोग आप अन्य Zealy कम्युनिटीज़ के साथ पार्टनरशिप करने के लिए कर सकते हैं। इसे सेट अप करने का तरीका नीचे जानें।
मूल बातें
"API" टास्क बनाना
- पर क्लिक करें 'Add task'.
- चुनें 'Api'.
- कॉल करने के लिए endpoint और यदि आवश्यक हो तो API key परिभाषित करें।
- चुनें कि उपयोगकर्ता कैसे पहचाने जाएं। आप इनमें से चुन सकते हैं Email, Twitter, Discord, वॉलेट पता, या Zealy Connect.
- यदि चुनते हैं वॉलेट कनेक्शन, तो आप यह भी चुन सकते हैं कि कौन सा नेटवर्क उपयोग करना है।
-
यदि चुनते हैं Zealy Connect, तो इन चरणों का पालन करें:
- रीडायरेक्ट URL परिभाषित करें: इस URL का उपयोग प्रमाणीकरण के लिए किया जाएगा। हम उपयोगकर्ताओं को आपके सिस्टम में प्रमाणीकृत करने के लिए इस URL पर रीडायरेक्ट करेंगे।
- कम्युनिटी सीक्रेट जनरेट करें: कम्युनिटी सीक्रेट जनरेट करना आवश्यक है इसके लिए Zealy Connect काम करने के लिए। आप इससे secret बना सकते हैं Zealy Connect सेटिंग्स under the Integrations अनुभाग अपनी कम्युनिटी सेटिंग्स में।
API कैसे काम करते हैं, इसकी विस्तृत जानकारी के लिए कृपया देखें API दस्तावेज़ीकरण और Zealy Connect के प्रबंधन के मार्गदर्शन के लिए, कृपया देखें Zealy Connect दस्तावेज़ीकरण.
Domino के साथ एकीकरण
Domino Web3 Zapier है। यह आपको Zealy की क्षमताओं का विस्तार करने और उन कार्यों की स्वचालित रूप से समीक्षा करने की अनुमति देता है जो मूल रूप से समर्थित नहीं हैं, जैसे:
- जाँचना कि क्या किसी उपयोगकर्ता के Twitter नाम या बायो में कोई विशिष्ट शब्द है
- किसी उपयोगकर्ता का NFT और टोकन बैलेंस जाँचना
- सत्यापित करना कि किसी उपयोगकर्ता ने Discord पर एक निश्चित संख्या में लोगों को आमंत्रित किया है
- और भी बहुत कुछ
उनका दस्तावेज़ इंटीग्रेशन के लिए देखें।
एंडपॉइंट परीक्षण
एंडपॉइंट कॉन्फ़िगर करते समय हम यह सुनिश्चित करने के लिए स्वचालित रूप से निम्नलिखित परीक्षण चलाएंगे कि एंडपॉइंट अपेक्षा के अनुसार काम कर रहा है:
- यह जाँचना कि कॉल में 10 सेकंड से अधिक समय न लगे
- यह सत्यापित करना कि त्रुटि संदेश सही प्रारूप में है ताकि हम इसे उपयोगकर्ता को दिखा सकें
- यह सुनिश्चित करना कि यह किसी भी अप्रत्याशित स्टेटस कोड में से न हो। एंडपॉइंट को केवल 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 डाउनलोड करें। अपने ऑपरेटिंग सिस्टम के लिए इंस्टॉलेशन निर्देशों का पालन करें।
चरण 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 टास्क सेट करते समय ngrok फ़ॉरवर्डिंग URL को एंडपॉइंट URL के रूप में उपयोग करें। किसी भी आवश्यक पथ को जोड़ना सुनिश्चित करें, उदाहरण के लिए, https://abc123.ngrok.io/claim.
नोट: याद रखें, ngrok URLs अस्थायी होते हैं और हर बार ngrok रीस्टार्ट करने पर बदल जाते हैं, जब तक कि आपके पास पेड सब्सक्रिप्शन न हो जो कस्टम सबडोमेन सपोर्ट करता हो। हर बार ngrok रीस्टार्ट करने पर Zealy में endpoint अपडेट करना सुनिश्चित करें।
इन चरणों का पालन करके, आप प्रोडक्शन सर्वर पर डिप्लॉय करने से पहले लोकल डेवलपमेंट एनवायरनमेंट में अपने कस्टम endpoint को आसानी से टेस्ट और डीबग कर सकते हैं।
Zealy Connect इंटीग्रेशन
Zealy Connect का उपयोग करते समय, हम उपयोगकर्ता को टास्क सेटअप के दौरान निर्दिष्ट URL पर रीडायरेक्ट करेंगे। हम निम्नलिखित query params शामिल करेंगे:
zealyUserId: Zealy सिस्टम में उपयोगकर्ता के लिए एक यूनिक आइडेंटिफायर, जिसका उपयोग उन्हें आपके प्लेटफ़ॉर्म से लिंक करने के लिए किया जाता है।callback: ऑथेंटिकेशन पूरा होने के बाद उपयोगकर्ता को वापस रीडायरेक्ट करने के लिए URL, ताकि वे टास्क claim कर सकें।signature: अनुरोध की प्रामाणिकता सत्यापित करने के लिए उपयोग किया जाने वाला SHA-256 hash, यह सुनिश्चित करने के लिए कि यह 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 कार्य बॉडी के भाग के रूप में भेज सकें।
अब उपयोगकर्ता इस कार्य और उसी रीडायरेक्ट URL के साथ Zealy Connect का उपयोग करने वाले किसी भी अन्य कार्य को क्लेम कर सकेगा। हम इसे याद रखेंगे ताकि उपयोगकर्ता को हर कार्य के लिए कनेक्ट न करना पड़े।
यदि आपको किसी उपयोगकर्ता का Zealy Connect संबंध हटाना है, तो आप Delete Zealy Connect for Member API रूटका उपयोग कर सकते हैं। यह रूट आपको किसी विशिष्ट सदस्य के लिए Zealy Connect संबंध हटाने की अनुमति देता है। इस रूट को कॉल करने के बाद, उपयोगकर्ता को Zealy Connect सुविधाओं का फिर से उपयोग करने के लिए अपना खाता दोबारा कनेक्ट करना होगा।