Документація Zealy

Автоматичний переклад · Читати англійською

API

Автоматизуйте дії на зовнішніх платформах

Автор Fredrika

API
На цій сторінці

Огляд

Цей посібник присвячено завданню API. Повну документацію API можна знайти тут.

Завдання API використовуються для автоматизації завдань на зовнішніх платформах. Ви можете використовувати їх, щоб підтвердити, що користувач зареєструвався або здійснив покупку, відкрив PR для issue на Github, або додати підтримку Reddit. Можливості безмежні. Щоб почати та випробувати функціонал, ми пропонуємо базовий ендпоінт, який ви можете використовувати для партнерства з іншими спільнотами Zealy. Дізнайтеся більше про те, як його налаштувати, нижче.

Основи

Створення завдання "API"

  1. Натисніть 'Додати завдання'.
  2. Виберіть 'Api'.
  3. Визначте ендпоінт для виклику та API-ключ, якщо потрібно.
  4. Виберіть, як користувачі можуть ідентифікуватися. Ви можете вибрати з Email, Twitter, Discord, Адреса гаманця, або Zealy Connect.
  • Якщо вибрати підключення гаманця, ви також можете вибрати, яку мережу використовувати.

Нові блокчейни

  • Якщо вибрати Zealy Connect, виконайте такі кроки:

    1. Визначте URL перенаправлення: Цей URL буде використовуватися для автентифікації. Ми перенаправимо користувачів на цей URL, щоб вони автентифікувалися у вашій системі.

    API TASK Zealy Connect

    1. Згенеруйте секрет спільноти: Генерація секрету спільноти потрібна для роботи Zealy Connect . Ви можете створити секрет у налаштуваннях Zealy Connect у розділі Інтеграції у налаштуваннях вашої спільноти.

    Секрет спільноти

Для детальної інформації про те, як мають працювати API, дивіться документацію 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 і отримайте свій authtoken з панелі керування ngrok. Підключіть свій обліковий запис ngrok, виконавши ngrok authtoken YOUR_AUTH_TOKEN у терміналі, замінивши YOUR_AUTH_TOKEN на токен з панелі керування ngrok.

Крок 3: Запустіть локальний сервер Переконайтеся, що ваш локальний сервер, який розміщує ендпоінт, працює. Наприклад, якщо ваш сервер — це Node.js-додаток, ви можете виконати node server.js.

Крок 4: Відкрийте локальний сервер через ngrok Відкрийте нове вікно терміналу та запустіть тунель ngrok до порту вашого локального сервера (наприклад, 3000) за допомогою ngrok http http://127.0.0.1:3000. ngrok відобразить URL перенаправлення в терміналі (наприклад, 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 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

Останній крок — перенаправити користувача назад до 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 з тим самим redirect URL. Ми це запам'ятаємо, щоб користувачу не доводилося підключатися для кожного завдання.

Якщо вам потрібно видалити зв'язок користувача із Zealy Connect, ви можете скористатися маршрутом API Delete Zealy Connect for Member. Цей маршрут дозволяє видалити зв'язок із Zealy Connect для конкретного учасника. Після виклику цього маршруту користувачу потрібно буде повторно підключити свій акаунт, щоб знову використовувати функції Zealy Connect.

Часті запитання