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

APIs ఎలా పని చేయాలని ఆశించబడుతుంది అనే దానిపై లోతైన సమాచారం కోసం, దయచేసి చూడండి 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). ఇది మీ లోకల్ సర్వర్‌ను చేరుకోవడానికి Zealy ఉపయోగించే పబ్లిక్ URL.

దశ 5: Zealyలో మీ API టాస్క్‌ను కాన్ఫిగర్ చేయండి Zealyలో మీ API టాస్క్‌ను సెటప్ చేసేటప్పుడు ఎండ్‌పాయింట్ URLగా ngrok ఫార్వార్డింగ్ URLను ఉపయోగించండి. అవసరమైన పాత్‌ను జోడించాలని నిర్ధారించుకోండి, ఉదాహరణకు, https://abc123.ngrok.io/claim.

గమనిక: గుర్తుంచుకోండి, మీకు కస్టమ్ సబ్‌డొమైన్‌లకు మద్దతు ఇచ్చే చెల్లింపు సబ్‌స్క్రిప్షన్ లేకపోతే, ngrok URLలు తాత్కాలికమైనవి మరియు మీరు ప్రతిసారీ ngrokని పునఃప్రారంభించినప్పుడు మారుతాయి. మీరు ప్రతిసారీ ngrokని పునఃప్రారంభించినప్పుడు Zealyలో ఎండ్‌పాయింట్‌ను తప్పనిసరిగా అప్‌డేట్ చేయండి.

ఈ దశలను అనుసరించడం ద్వారా, మీరు ఉత్పత్తి సర్వర్‌కు డిప్లాయ్ చేయడానికి ముందు స్థానిక అభివృద్ధి వాతావరణంలో మీ కస్టమ్ ఎండ్‌పాయింట్‌ను సులభంగా పరీక్షించవచ్చు మరియు డీబగ్ చేయవచ్చు.

Zealy Connect ఇంటిగ్రేషన్

Zealy Connectని ఉపయోగిస్తున్నప్పుడు, టాస్క్ సెటప్ సమయంలో పేర్కొన్న URLకి మేము వినియోగదారుని రీడైరెక్ట్ చేస్తాము. మేము ఈ క్వెరీ పారామ్‌లను చేర్చుతాము:

  • zealyUserId: మీ ప్లాట్‌ఫారమ్‌తో వారిని లింక్ చేయడానికి ఉపయోగించే Zealy సిస్టమ్‌లోని వినియోగదారు కోసం ప్రత్యేక గుర్తింపు.
  • callback: ప్రామాణీకరణ పూర్తయిన తర్వాత వినియోగదారు టాస్క్‌ను క్లెయిమ్ చేయగలిగేలా వారిని తిరిగి రీడైరెక్ట్ చేయడానికి URL.
  • signature: అభ్యర్థన Zealy నుండి వచ్చిందని నిర్ధారించడానికి దాని ప్రామాణికతను ధృవీకరించడానికి ఉపయోగించే SHA-256 హాష్.

మీరు ప్రారంభ స్థానంగా ఉపయోగించగల పూర్తి ఉదాహరణ ఎండ్‌పాయింట్ ఇక్కడ ఉంది:

 
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కి రీడైరెక్ట్ చేయండి

చివరి దశ, వినియోగదారు టాస్క్‌ను క్లెయిమ్ చేయడానికి అనుమతించేందుకు, మేము అందించే callback క్వెరీ పరామితిని ఉపయోగించి, మీ ప్లాట్‌ఫారమ్ యొక్క వినియోగదారు IDతో వినియోగదారుని తిరిగి Zealyకి రీడైరెక్ట్ చేయడం. కాల్ మీ నుండి వస్తోందని మరియు మార్చబడలేదని ధృవీకరించగలిగేందుకు మీరు సంతకాన్ని కూడా రూపొందించాలి. క్రింద ఉదాహరణ చూడండి:

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ని స్వీకరించిన తర్వాత, సంతకాన్ని ధృవీకరించి, API టాస్క్ బాడీలో భాగంగా పంపగలిగేందుకు మీ ప్లాట్‌ఫారమ్ యొక్క వినియోగదారు IDని నిల్వ చేస్తాము.

ఇప్పుడు వినియోగదారు ఈ టాస్క్‌ను మరియు అదే రీడైరెక్ట్ URLతో Zealy Connectని ఉపయోగించే ఇతర టాస్క్‌లను క్లెయిమ్ చేయగలరు. ప్రతి టాస్క్‌కు వినియోగదారు కనెక్ట్ అవ్వాల్సిన అవసరం లేకుండా మేము దీన్ని గుర్తుంచుకుంటాము.

మీరు వినియోగదారు యొక్క Zealy Connect అనుబంధాన్ని తొలగించాల్సి వస్తే, మీరు దీన్ని ఉపయోగించవచ్చు సభ్యుని కోసం Zealy Connect తొలగించే API మార్గం. ఈ మార్గం నిర్దిష్ట సభ్యుని కోసం Zealy Connect అనుబంధాన్ని తొలగించడానికి మిమ్మల్ని అనుమతిస్తుంది. ఈ మార్గాన్ని పిలిచిన తర్వాత, Zealy Connect ఫీచర్లను మళ్లీ ఉపయోగించడానికి వినియోగదారు తమ ఖాతాను మళ్లీ కనెక్ట్ చేయాలి.

తరచుగా అడిగే ప్రశ్నలు