API

সংক্ষিপ্ত বিবরণ

এই গাইডটি API টাস্ক সম্পর্কে। আমাদের সম্পূর্ণ API ডকুমেন্টেশন পাবেন এখানে.

API কোয়েস্ট বাহ্যিক প্ল্যাটফর্মে কোয়েস্ট স্বয়ংক্রিয় করতে ব্যবহৃত হয়। ব্যবহারকারী নিবন্ধন করেছে বা কেনাকাটা করেছে, Github-এ কোনো ইস্যুর জন্য PR খুলেছে বা Reddit সাপোর্ট যোগ করেছে তা নিশ্চিত করতে আপনি এটি ব্যবহার করতে পারেন। সম্ভাবনার শেষ নেই। শুরু করতে এবং কার্যকারিতা পরীক্ষা করতে আমরা একটি বেসিক এন্ডপয়েন্ট অফার করি, যা আপনি অন্য Zealy কমিউনিটির সাথে পার্টনারশিপ করতে ব্যবহার করতে পারেন। এটি কীভাবে সেট আপ করবেন তা নিচে আরও জানুন।

মৌলিক বিষয়

একটি "API" টাস্ক তৈরি করা

1. ক্লিক করুন 'Add task'.
2. নির্বাচন করুন 'Api'.
3. কল করার এন্ডপয়েন্ট এবং প্রয়োজনে একটি API key নির্ধারণ করুন।
4. ব্যবহারকারীরা কীভাবে শনাক্ত হবে তা বেছে নিন। আপনি এখান থেকে নির্বাচন করতে পারেন Email, Twitter, Discord, Wallet address, বা Zealy Connect.

• যদি বেছে নেন wallet connection, আপনি কোন নেটওয়ার্ক ব্যবহার করবেন তাও বেছে নিতে পারেন।

• যদি বেছে নেন Zealy Connect, এই ধাপগুলো অনুসরণ করুন:

  1. রিডাইরেক্ট URL নির্ধারণ করুন: এই URL প্রমাণীকরণের জন্য ব্যবহৃত হবে। আপনার সিস্টেমে প্রমাণীকরণের জন্য আমরা ব্যবহারকারীদের এই URL-এ রিডাইরেক্ট করব।

  

  2. একটি কমিউনিটি সিক্রেট তৈরি করুন: এর জন্য একটি কমিউনিটি সিক্রেট তৈরি করা প্রয়োজন Zealy Connect কাজ করার জন্য। আপনি সিক্রেটটি এখান থেকে তৈরি করতে পারেন Zealy Connect সেটিংস এর অধীনে Integrations বিভাগ আপনার কমিউনিটি সেটিংসে।

  

API-গুলো কীভাবে কাজ করবে সে সম্পর্কে বিস্তারিত তথ্যের জন্য, দেখুন API ডকুমেন্টেশন এবং Zealy Connect পরিচালনার নির্দেশনার জন্য, দেখুন Zealy Connect ডকুমেন্টেশন.

Domino-এর সাথে ইন্টিগ্রেশন

Domino হলো Web3 Zapier। এটি আপনাকে Zealy-এর সক্ষমতা বাড়াতে এবং নেটিভভাবে সমর্থিত নয় এমন কাজ স্বয়ংক্রিয়ভাবে পর্যালোচনা করতে দেয়, যেমন:

• কোনো ব্যবহারকারীর Twitter নাম বা বায়োতে নির্দিষ্ট শব্দ আছে কিনা তা যাচাই করা
• ব্যবহারকারীর NFT ও টোকেন ব্যালেন্স যাচাই করা
• কোনো ব্যবহারকারী Discord-এ নির্দিষ্ট সংখ্যক মানুষকে আমন্ত্রণ জানিয়েছেন কিনা তা যাচাই করা
• আরও অনেক কিছু

তাদের দেখুন ডকুমেন্টেশন ইন্টিগ্রেশনের জন্য।

এন্ডপয়েন্ট পরীক্ষা

এন্ডপয়েন্ট কনফিগার করার সময় আমরা স্বয়ংক্রিয়ভাবে নিম্নলিখিত পরীক্ষাগুলো চালাব যাতে এন্ডপয়েন্টটি প্রত্যাশিতভাবে কাজ করছে কিনা তা নিশ্চিত করা যায়:

1. কলটি 10 সেকেন্ডের বেশি সময় নিচ্ছে কিনা তা পরীক্ষা করা হচ্ছে
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 status। এরপর ব্যবহারকারী সফলভাবে টাস্কটি ক্লেইম করবে।

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

অন্যথায়, 400 status রেসপন্সে ফেরত দিতে হবে এবং সাথে বডিতে একটি মেসেজ দিতে হবে। মেসেজটি জেনারেট করা 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 টাস্ক সেট আপ করার সময় এন্ডপয়েন্ট URL হিসেবে ngrok ফরওয়ার্ডিং URL ব্যবহার করুন। প্রয়োজনীয় যেকোনো পাথ যোগ করতে ভুলবেন না, উদাহরণস্বরূপ, https://abc123.ngrok.io/claim.

Note: মনে রাখবেন, ngrok URL গুলো অস্থায়ী এবং প্রতিবার ngrok রিস্টার্ট করলে পরিবর্তিত হয়, যদি না আপনার কাস্টম সাবডোমেইন সমর্থনকারী পেইড সাবস্ক্রিপশন থাকে। প্রতিবার ngrok রিস্টার্ট করার সময় Zealy-তে endpoint আপডেট করতে ভুলবেন না।

এই ধাপগুলো অনুসরণ করে, প্রোডাকশন সার্ভারে ডিপ্লয় করার আগে আপনি সহজেই লোকাল ডেভেলপমেন্ট এনভায়রনমেন্টে আপনার কাস্টম endpoint পরীক্ষা ও ডিবাগ করতে পারেন।

Zealy Connect ইন্টিগ্রেশন

Zealy Connect ব্যবহার করার সময়, আমরা ব্যবহারকারীকে টাস্ক সেটআপের সময় নির্দিষ্ট করা URL-এ রিডাইরেক্ট করব। আমরা নিম্নলিখিত query params অন্তর্ভুক্ত করব:

• zealyUserId: Zealy সিস্টেমে ব্যবহারকারীর একটি অনন্য শনাক্তকারী, যা তাদের আপনার প্ল্যাটফর্মের সাথে লিঙ্ক করতে ব্যবহৃত হয়।
• callback: প্রমাণীকরণ সম্পন্ন হওয়ার পর ব্যবহারকারীকে ফিরিয়ে আনার URL, যাতে তারা টাস্কটি claim করতে পারে।
• 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());
});

১. স্বাক্ষর যাচাই করুন

আপনার অ্যাপ্লিকেশনের প্রথম কাজ হলো আপনার কমিউনিটি সিক্রেট ব্যবহার করে স্বাক্ষরটি যাচাই করা। এই যাচাই নিশ্চিত করে যে কলটি সত্যিই আমাদের কাছ থেকে এসেছে এবং এটি পরিবর্তন করা হয়নি।

আমরা সিগনেচার তৈরি করতে 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;

২. Zealy User ID ব্যবহার করুন

পরবর্তী ধাপটি নির্ভর করে আপনি কী করতে চান তার উপর, তবে সাধারণত কাস্টমাররা আপনার প্ল্যাটফর্মে বর্তমান ব্যবহারকারীকে লগইন করায় এবং আপনার প্ল্যাটফর্মের user 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 });
 

৩. Zealy-তে ফিরে রিডাইরেক্ট করুন

শেষ ধাপ হলো আপনার প্ল্যাটফর্মের user ID সহ ব্যবহারকারীকে Zealy-তে ফিরে রিডাইরেক্ট করা, যাতে আমরা ব্যবহারকারীকে টাস্কটি ক্লেইম করতে দিতে পারি, আমাদের দেওয়া callback query প্যারামিটার ব্যবহার করে। আপনাকে একটি সিগনেচারও তৈরি করতে হবে যাতে আমরা যাচাই করতে পারি যে কলটি আপনার কাছ থেকে আসছে এবং পরিবর্তন করা হয়নি। নিচের উদাহরণ দেখুন:

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());

৪. Zealy

আমরা callback পেলে সিগনেচার যাচাই করব এবং আপনার প্ল্যাটফর্মের user ID সংরক্ষণ করব যাতে আমরা এটি API টাস্কের বডির অংশ হিসেবে পাঠাতে পারি।

ব্যবহারকারী এখন টাস্কটি এবং একই redirect URL ব্যবহার করে Zealy Connect ব্যবহার করা অন্য যেকোনো টাস্ক ক্লেইম করতে পারবেন। আমরা এটি মনে রাখব যাতে ব্যবহারকারীকে প্রতিটি টাস্কের জন্য কানেক্ট করতে না হয়।

আপনার যদি কোনো ব্যবহারকারীর Zealy Connect অ্যাসোসিয়েশন মুছে ফেলার প্রয়োজন হয়, আপনি Delete Zealy Connect for Member API রুটব্যবহার করতে পারেন। এই রুটটি আপনাকে নির্দিষ্ট একজন সদস্যের Zealy Connect অ্যাসোসিয়েশন সরাতে দেয়। এই রুটটি কল করার পর, ব্যবহারকারীকে আবার Zealy Connect ফিচার ব্যবহার করতে তাদের অ্যাকাউন্ট পুনরায় কানেক্ট করতে হবে।

সাধারণ প্রশ্নোত্তর