API

نمای کلی

این راهنما دربارهٔ تسک API است. مستندات کامل API ما را می‌توانید اینجا.

کوئست‌های API برای خودکارسازی کوئست‌ها در پلتفرم‌های خارجی استفاده می‌شوند. ممکن است از آن برای تأیید ثبت‌نام یا خرید کاربر، باز کردن PR برای یک ایشو در Github یا افزودن پشتیبانی Reddit استفاده کنید. امکانات بی‌پایان است. برای شروع و آزمایش قابلیت‌ها، یک اندپوینت پایه ارائه می‌دهیم که می‌توانید از آن برای همکاری با سایر جوامع Zealy استفاده کنید. در ادامه دربارهٔ نحوهٔ راه‌اندازی آن بیشتر بدانید.

مبانی

ایجاد یک تسک «API»

1. کلیک کنید روی افزودن وظیفه.
2. انتخاب کنید API.
3. نقطه پایانی (endpoint) برای فراخوانی و در صورت نیاز یک کلید API را تعریف کنید.
4. نحوه شناسایی کاربران را انتخاب کنید. می‌توانید از میان موارد زیر انتخاب کنید ایمیل, توییتر, Discord, آدرس کیف پول، یا Zealy Connect.

• اگر انتخاب کنید اتصال کیف پول، می‌توانید شبکه مورد استفاده را نیز انتخاب کنید.

• اگر انتخاب می‌کنید Zealy Connect، این مراحل را دنبال کنید:

  1. URL تغییرمسیر را تعریف کنید: این URL برای احراز هویت استفاده می‌شود. کاربران را به این URL هدایت می‌کنیم تا در سیستم شما احراز هویت کنند.

  

  2. یک رمز محرمانه جامعه تولید کنید: تولید یک رمز محرمانه جامعه برای Zealy Connect کار کند. می‌توانید رمز را از تنظیمات Zealy Connect در بخش Integrations در تنظیمات کامیونیتی خود بسازید.

  

برای اطلاعات کامل درباره نحوه کار مورد انتظار APIها، لطفاً مستندات API و برای راهنمایی در مورد مدیریت Zealy Connect، لطفاً به مستندات Zealy Connect.

یکپارچه‌سازی با Domino

Domino همان Zapier وب۳ است. این ابزار به شما امکان می‌دهد قابلیت‌های Zealy را گسترش دهید و به‌طور خودکار وظایفی را که به‌صورت بومی پشتیبانی نمی‌شوند بررسی کنید، مانند:

• بررسی اینکه نام یا بیو توییتر کاربر شامل یک کلمه مشخص است یا خیر
• بررسی موجودی NFT و توکن کاربر
• تأیید اینکه کاربر تعداد مشخصی از افراد را در Discord دعوت کرده است
• و موارد دیگر

مشاهده کنید مستندات برای یکپارچه‌سازی.

آزمایش نقطه پایانی

هنگام پیکربندی نقطه پایانی، به‌طور خودکار آزمایش‌های زیر را اجرا می‌کنیم تا مطمئن شویم نقطه پایانی همان‌طور که انتظار می‌رود کار می‌کند:

1. بررسی می‌کنیم که فراخوانی بیش از 10 ثانیه طول نکشد
2. بررسی می‌کنیم که پیام خطا در قالب درست باشد تا بتوانیم آن را به کاربر نمایش دهیم
3. اطمینان حاصل کنید که هیچ‌یک از کدهای وضعیت غیرمنتظره نباشد. endpoint باید فقط 200 یا 400 برگرداند.

ساخت یک endpoint سفارشی

درخواست

می‌توانید از تسک‌های API با یک POST 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 key که هنگام ساخت تسک تنظیم می‌شود محافظت کنید. API key به این صورت در هدرها ارسال می‌شود:

{
  "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 و تست نقطه پایانی خود این مراحل را دنبال کنید:

مرحله ۱: نصب ngrok ngrok را از وب‌سایت ngrok دانلود کنید. دستورالعمل‌های نصب را برای سیستم‌عامل خود دنبال کنید.

مرحله ۲: راه‌اندازی ngrok یک حساب رایگان ngrok ثبت‌نام کنید و authtoken خود را از داشبورد ngrok دریافت کنید. حساب ngrok خود را با اجرای ngrok authtoken YOUR_AUTH_TOKEN در ترمینال متصل کنید و YOUR_AUTH_TOKEN را با توکن داشبورد ngrok خود جایگزین کنید.

مرحله ۳: سرور محلی خود را راه‌اندازی کنید مطمئن شوید سرور محلی‌ای که endpoint را میزبانی می‌کند در حال اجراست. برای مثال، اگر سرور شما یک اپ Node.js است، ممکن است node server.js را اجرا کنید.

مرحله ۴: سرور محلی خود را با ngrok در دسترس قرار دهید یک پنجره ترمینال جدید باز کنید و یک تونل ngrok به پورت سرور محلی خود (مثلاً 3000) با استفاده از ngrok http http://127.0.0.1:3000. ngrok یک URL ارجاع‌دهنده در ترمینال نمایش می‌دهد (مثلاً https://abc123.ngrok.io). این همان URL عمومی است که Zealy برای دسترسی به سرور محلی شما استفاده می‌کند.

مرحله ۵: وظیفه API خود را در Zealy پیکربندی کنید هنگام راه‌اندازی وظیفه API خود در Zealy، از URL ارجاع‌دهنده ngrok به‌عنوان URL endpoint استفاده کنید. مطمئن شوید مسیر موردنیاز را اضافه می‌کنید، برای مثال، https://abc123.ngrok.io/claim.

توجه: به یاد داشته باشید، URLهای ngrok موقتی هستند و هر بار که ngrok را دوباره راه‌اندازی می‌کنید تغییر می‌کنند، مگر اینکه اشتراک پرداختی داشته باشید که از زیردامنه‌های سفارشی پشتیبانی کند. هر بار که ngrok را دوباره راه‌اندازی می‌کنید، مطمئن شوید که endpoint را در Zealy به‌روزرسانی کنید.

با دنبال کردن این مراحل، می‌توانید به‌راحتی endpoint سفارشی خود را در یک محیط توسعه محلی قبل از استقرار در سرور تولید تست و اشکال‌زدایی کنید.

یکپارچه‌سازی Zealy Connect

هنگام استفاده از Zealy Connect، کاربر را به URL مشخص‌شده در هنگام تنظیم تسک هدایت می‌کنیم. پارامترهای query زیر را شامل می‌شویم:

• 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;

2. از شناسه کاربری Zealy استفاده کنید

مرحله بعدی به کاری که می‌خواهید انجام دهید بستگی دارد، اما مشتریان معمولاً کاربر فعلی را در پلتفرم شما وارد می‌کنند و شناسه کاربری پلتفرم خود را با شناسه کاربری Zealy پیوند می‌دهند. در زیر یک نمونه آمده است:

  /**
   * 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

آخرین مرحله این است که کاربر را با شناسه کاربری پلتفرم خود به 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، امضا را اعتبارسنجی می‌کنیم و شناسه کاربری پلتفرم شما را ذخیره می‌کنیم تا بتوانیم آن را به‌عنوان بخشی از بدنه کوئست API ارسال کنیم.

اکنون کاربر می‌تواند این کوئست و هر کوئست دیگری را که از Zealy Connect با همان URL بازگشت استفاده می‌کند، دریافت کند. ما این را به خاطر می‌سپاریم تا کاربر مجبور نباشد برای هر کوئست متصل شود.

اگر نیاز دارید ارتباط Zealy Connect یک کاربر را حذف کنید، می‌توانید از مسیر API حذف Zealy Connect برای عضواستفاده کنید. این مسیر به شما امکان می‌دهد ارتباط Zealy Connect یک عضو مشخص را حذف کنید. پس از فراخوانی این مسیر، کاربر باید حساب خود را دوباره متصل کند تا بتواند از قابلیت‌های Zealy Connect استفاده کند.

پرسش‌های متداول