API

بیرونی پلیٹ فارمز پر اقدامات خودکار بنائیں

بذریعہ Fredrika

اس صفحے پر

جائزہ

یہ گائیڈ API ٹاسک کے بارے میں ہے۔ ہماری مکمل API دستاویزات آپ یہاں تلاش کر سکتے ہیں یہاں.

API کوئسٹس بیرونی پلیٹ فارمز پر کوئسٹس کو خودکار بنانے کے لیے استعمال ہوتے ہیں۔ آپ اسے اس بات کی تصدیق کے لیے استعمال کر سکتے ہیں کہ صارف نے رجسٹر کیا ہے یا خریداری کی ہے، Github پر کسی ایشو کے لیے PR کھولا ہے یا Reddit پر سپورٹ شامل کی ہے۔ امکانات لامحدود ہیں۔ شروع کرنے اور فعالیت آزمانے کے لیے ہم ایک بنیادی اینڈ پوائنٹ پیش کرتے ہیں جسے آپ دیگر Zealy کمیونٹیز کے ساتھ شراکت داری کے لیے استعمال کر سکتے ہیں۔ اسے ترتیب دینے کے بارے میں مزید جانیں نیچے۔

بنیادی باتیں

"API" ٹاسک بنانا

پر کلک کریں 'Add task'.
منتخب کریں 'Api'.
کال کرنے کے لیے اینڈ پوائنٹ اور اگر ضرورت ہو تو API کلید متعین کریں۔
منتخب کریں کہ صارفین کیسے شناخت ہو سکتے ہیں۔ آپ منتخب کر سکتے ہیں ای میل, Twitter, Discord, Wallet address, یا Zealy Connect.

اگر منتخب کریں wallet connection, آپ یہ بھی منتخب کر سکتے ہیں کہ کون سا نیٹ ورک استعمال کرنا ہے۔

نئی بلاک چینز

اگر منتخب کر رہے ہیں Zealy Connect, تو یہ مراحل پر عمل کریں:
1. ری ڈائریکٹ URL کی تعریف کریں: یہ URL تصدیق کے لیے استعمال ہوگا۔ ہم صارفین کو آپ کے سسٹم میں تصدیق کے لیے اس URL پر ری ڈائریکٹ کریں گے۔
1. کمیونٹی سیکرٹ بنائیں: کمیونٹی سیکرٹ بنانا درکار ہے برائے Zealy Connect کام کرنے کے لیے۔ آپ سیکرٹ یہاں سے بنا سکتے ہیں: Zealy Connect کی ترتیبات کے تحت Integrations سیکشن اپنی کمیونٹی کی ترتیبات میں۔

APIs کے متوقع طریقۂ کار کے بارے میں تفصیلی معلومات کے لیے، براہ کرم دیکھیں API دستاویزات اور Zealy Connect کے انتظام کے لیے رہنمائی کے لیے، براہ کرم ملاحظہ کریں Zealy Connect دستاویزات.

Domino کے ساتھ انضمام

Domino ایک Web3 Zapier ہے۔ یہ آپ کو Zealy کی صلاحیتوں کو بڑھانے اور ان کاموں کا خودکار جائزہ لینے کی اجازت دیتا ہے جو قدرتی طور پر معاون نہیں ہیں، جیسے:

یہ جانچنا کہ آیا صارف کے Twitter نام یا بائیو میں کوئی مخصوص لفظ موجود ہے
صارف کے NFT اور ٹوکن بیلنس کی جانچ کرنا
یہ تصدیق کرنا کہ صارف نے Discord پر ایک مخصوص تعداد میں لوگوں کو مدعو کیا ہے
اور بہت کچھ

ان کی دستاویزات کو انٹیگریشن کے لیے دیکھیں۔

اینڈ پوائنٹ ٹیسٹنگ

اینڈ پوائنٹ کنفیگر کرتے وقت ہم درج ذیل ٹیسٹ خودکار طور پر چلائیں گے تاکہ یقینی بنایا جا سکے کہ اینڈ پوائنٹ توقع کے مطابق کام کر رہا ہے:

جانچنا کہ کال میں 10 سیکنڈ سے زیادہ وقت نہ لگے
تصدیق کرنا کہ غلطی کا پیغام درست فارمیٹ میں ہے تاکہ ہم اسے صارف کو دکھا سکیں
یقینی بنائیں کہ یہ کوئی غیر متوقع اسٹیٹس کوڈ نہیں ہے۔ اینڈ پوائنٹ کو صرف 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 status۔ اس کے بعد صارف کامیابی سے ٹاسک کلیم کر لے گا۔

RESPONSE 200

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

بصورت دیگر، 400 status جواب میں واپس کیا جانا چاہیے، ساتھ ہی باڈی میں ایک پیغام بھی۔ یہ پیغام تیار کردہ 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: اپنا لوکل سرور شروع کریں یقینی بنائیں کہ آپ کا لوکل سرور جو endpoint کی میزبانی کرتا ہے چل رہا ہے۔ مثال کے طور پر، اگر آپ کا سرور 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 کو endpoint URL کے طور پر استعمال کریں۔ کسی بھی مطلوبہ پاتھ کو شامل کرنا یقینی بنائیں، مثال کے طور پر، https://abc123.ngrok.io/claim.

نوٹ: یاد رکھیں، ngrok URLs عارضی ہوتی ہیں اور ہر بار ngrok دوبارہ شروع کرنے پر تبدیل ہو جاتی ہیں، الا یہ کہ آپ کے پاس بامعاوضہ سبسکرپشن ہو جو حسبِ ضرورت ذیلی ڈومینز کی سہولت دیتی ہو۔ ہر بار ngrok دوبارہ شروع کرنے پر Zealy میں endpoint کو ضرور اپ ڈیٹ کریں۔

ان مراحل پر عمل کر کے، آپ اپنے حسبِ ضرورت endpoint کو production سرور پر تعینات کرنے سے پہلے مقامی ڈویلپمنٹ ماحول میں آسانی سے جانچ اور ڈی بگ کر سکتے ہیں۔

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. دستخط کی تصدیق کریں

آپ کی ایپلیکیشن کو سب سے پہلے اپنی کمیونٹی سیکرٹ کا استعمال کرتے ہوئے دستخط کی توثیق کرنی چاہیے۔ یہ توثیق یقینی بناتی ہے کہ کال واقعی ہماری طرف سے آئی ہے اور اس میں تبدیلی نہیں کی گئی۔

ہم دستخط بنانے کے لیے 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 استعمال کریں

اگلا مرحلہ اس پر منحصر ہے کہ آپ کیا کرنا چاہتے ہیں، لیکن گاہک عموماً موجودہ صارف کو آپ کے پلیٹ فارم پر لاگ اِن کرواتے ہیں اور اپنے پلیٹ فارم کی 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 });

3. Zealy پر واپس ری ڈائریکٹ کریں

آخری مرحلہ یہ ہے کہ صارف کو آپ کے پلیٹ فارم کی user ID کے ساتھ Zealy پر واپس ری ڈائریکٹ کیا جائے تاکہ ہم صارف کو ٹاسک claim کرنے کی اجازت دے سکیں، اس کے لیے ہماری فراہم کردہ 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());

4. Zealy

callback موصول ہونے کے بعد، ہم دستخط کی تصدیق کریں گے اور آپ کے پلیٹ فارم کی user ID محفوظ کریں گے تاکہ ہم اسے API ٹاسک باڈی کے حصے کے طور پر بھیج سکیں۔

صارف اب اس ٹاسک اور Zealy Connect استعمال کرنے والے کسی بھی دوسرے ٹاسک کو اسی redirect URL کے ساتھ claim کر سکے گا۔ ہم یہ یاد رکھیں گے تاکہ صارف کو ہر ٹاسک کے لیے دوبارہ connect نہ کرنا پڑے۔

اگر آپ کو کسی صارف کی Zealy Connect ایسوسی ایشن حذف کرنی ہو، تو آپ Delete Zealy Connect for Member API routeاستعمال کر سکتے ہیں۔ یہ route آپ کو کسی مخصوص member کے لیے Zealy Connect ایسوسی ایشن ہٹانے کی اجازت دیتا ہے۔ یہ route کال کرنے کے بعد، صارف کو Zealy Connect کی خصوصیات دوبارہ استعمال کرنے کے لیے اپنا اکاؤنٹ دوبارہ connect کرنا ہوگا۔