API

نظرة عامة

هذا الدليل يتعلق بمهمة API. يمكنك العثور على وثائق API الكاملة لدينا هنا.

تُستخدم مهام API لأتمتة المهام على المنصات الخارجية. يمكنك استخدامها للتأكد من أن المستخدم قد سجل أو قام بعملية شراء، أو فتح PR لمشكلة على Github أو لإضافة دعم Reddit. الاحتمالات لا حصر لها. للبدء وتجربة الوظائف، نقدم نقطة نهاية أساسية يمكنك استخدامها لإجراء شراكات مع مجتمعات Zealy الأخرى. تعرف على كيفية إعدادها أدناه.

الأساسيات

إنشاء مهمة "API"

1. انقر على 'إضافة مهمة'.
2. اختر 'Api'.
3. حدد نقطة النهاية للاتصال ومفتاح API إذا لزم الأمر.
4. اختر كيف يمكن للمستخدمين التعريف عن أنفسهم. يمكنك الاختيار من البريد الإلكتروني, تويتر, ديسكورد, عنوان المحفظة، أو Zealy Connect.

• إذا اخترت اتصال المحفظة، يمكنك أيضًا اختيار الشبكة التي تريد استخدامها.

• إذا اخترت Zealy Connect، اتبع هذه الخطوات:

  1. حدد عنوان URL لإعادة التوجيه: سيتم استخدام عنوان URL هذا للمصادقة. سنعيد توجيه المستخدمين إلى عنوان URL هذا ليتمكنوا من المصادقة في نظامك.

  

  2. أنشئ سر المجتمع: إنشاء سر المجتمع مطلوب لكي يعمل Zealy Connect . يمكنك إنشاء السر من إعدادات Zealy Connect ضمن قسم التكاملات في إعدادات مجتمعك.

  

للحصول على معلومات متعمقة حول كيفية عمل واجهات برمجة التطبيقات، يرجى الاطلاع على وثائق API وللحصول على إرشادات حول إدارة Zealy Connect، يرجى الرجوع إلى وثائق Zealy Connect.

التكامل مع Domino

Domino هو Zapier للويب 3. يسمح لك بتوسيع قدرات Zealy ومراجعة المهام غير المدعومة أصلاً تلقائيًا، مثل:

• التحقق مما إذا كان اسم تويتر أو السيرة الذاتية للمستخدم تحتوي على كلمة معينة
• التحقق من رصيد NFT والرموز للمستخدم
• التحقق من أن المستخدم قد دعا عددًا معينًا من الأشخاص على ديسكورد
• والمزيد

اطلع على وثائقهم للتكامل.

اختبار نقطة النهاية

عند تكوين نقطة النهاية، سنقوم تلقائيًا بتشغيل الاختبارات التالية للتأكد من أن نقطة النهاية تعمل كما هو متوقع:

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 . سيتمكن المستخدم بعد ذلك من المطالبة بالمهمة بنجاح.

{
  "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. قم بتوصيل حساب ngrok الخاص بك عن طريق تشغيل ngrok authtoken YOUR_AUTH_TOKEN في terminal، مع استبدال YOUR_AUTH_TOKEN بالرمز من لوحة تحكم ngrok.

الخطوة 3: بدء خادمك المحلي تأكد من أن خادمك المحلي الذي يستضيف نقطة النهاية قيد التشغيل. على سبيل المثال، إذا كان خادمك تطبيق Node.js، فقد تشغل node server.js.

الخطوة 4: كشف خادمك المحلي باستخدام ngrok افتح نافذة terminal جديدة وابدأ نفق ngrok إلى منفذ خادمك المحلي (مثل 3000) باستخدام ngrok http http://127.0.0.1:3000. سيعرض ngrok عنوان URL لإعادة التوجيه في terminal (مثل https://abc123.ngrok.io). هذا هو عنوان URL العام الذي ستستخدمه Zealy للوصول إلى خادمك المحلي.

الخطوة 5: تكوين مهمة API في Zealy استخدم عنوان URL لإعادة التوجيه من ngrok كعنوان URL لنقطة النهاية عند إعداد مهمة API في Zealy. تأكد من إضافة أي مسار مطلوب، على سبيل المثال https://abc123.ngrok.io/claim.

ملاحظة: تذكر أن عناوين URL الخاصة بـ ngrok مؤقتة وتتغير في كل مرة تعيد تشغيل ngrok، ما لم يكن لديك اشتراك مدفوع يدعم النطاقات الفرعية المخصصة. تأكد من تحديث نقطة النهاية في Zealy في كل مرة تعيد تشغيل ngrok.

باتباع هذه الخطوات، يمكنك بسهولة اختبار وتصحيح نقطة النهاية المخصصة في بيئة تطوير محلية قبل نشرها على خادم إنتاج.

تكامل Zealy Connect

عند استخدام Zealy Connect، سنعيد توجيه المستخدم إلى عنوان URL المحدد أثناء إعداد المهمة. سنقوم بتضمين معلمات الاستعلام التالية:

• zealyUserId: معرف فريد للمستخدم في نظام Zealy يُستخدم لربطه بمنصتك.
• callback: عنوان URL لإعادة توجيه المستخدم بعد اكتمال المصادقة حتى يتمكن من المطالبة بالمهمة.
• signature: تجزئة SHA-256 تُستخدم للتحقق من صحة الطلب، مما يضمن أنه نشأ من Zealy.

إليك مثال كامل لنقطة نهاية يمكنك استخدامه كنقطة بداية:

 
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

تعتمد الخطوة التالية على ما تريد فعله، لكن العملاء عادةً يسجّلون دخول المستخدم الحالي على منصتك ويربطون معرّف مستخدم منصتك بمعرّف مستخدم 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 مرة أخرى.

الأسئلة الشائعة