Документация 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 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.

Выполнив эти шаги, вы сможете легко тестировать и отлаживать пользовательский эндпоинт в локальной среде разработки перед развёртыванием на production-сервере.

Интеграция Zealy Connect

При использовании Zealy Connect мы перенаправим пользователя на URL, указанный при настройке задания. Мы добавим следующие query-параметры:

  • 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

Следующий шаг зависит от того, что вы хотите сделать, но обычно клиенты выполняют вход текущего пользователя на вашей платформе и связывают 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 с ID пользователя вашей платформы, чтобы мы могли разрешить пользователю выполнить задание, используя параметр запроса 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, мы проверим подпись и сохраним ID пользователя вашей платформы, чтобы отправлять его в составе тела задачи API.

Теперь пользователь сможет выполнить задание и любое другое задание, использующее Zealy Connect с тем же redirect URL. Мы запомним это, чтобы пользователю не приходилось подключаться для каждого задания.

Если вам нужно удалить связь пользователя с Zealy Connect, вы можете использовать маршрут API Delete Zealy Connect for Member. Этот маршрут позволяет удалить связь Zealy Connect для конкретного участника. После вызова этого маршрута пользователю потребуется повторно подключить свой аккаунт, чтобы снова использовать функции Zealy Connect.

FAQ