Tài liệu Zealy

Bản dịch tự động · Đọc bằng tiếng Anh

API

Tự động hóa các hành động trên nền tảng bên ngoài

Bởi Fredrika

API
Trên trang này

Tổng quan

Hướng dẫn này nói về nhiệm vụ API. Bạn có thể tìm tài liệu API đầy đủ của chúng tôi tại đây.

Nhiệm vụ API được dùng để tự động hóa các nhiệm vụ trên nền tảng bên ngoài. Bạn có thể dùng nó để xác nhận rằng người dùng đã đăng ký hoặc đã mua hàng, đã mở PR cho một issue trên Github hoặc để thêm hỗ trợ Reddit. Các khả năng là vô tận. Để bắt đầu và thử nghiệm chức năng, chúng tôi cung cấp một endpoint cơ bản mà bạn có thể dùng để hợp tác với các cộng đồng Zealy khác. Tìm hiểu thêm về cách thiết lập bên dưới.

Cơ bản

Tạo nhiệm vụ "API"

  1. Nhấp vào 'Add task'.
  2. Chọn 'Api'.
  3. Xác định endpoint cần gọi và API key nếu cần.
  4. Chọn cách người dùng có thể nhận diện. Bạn có thể chọn từ Email, Twitter, Discord, Địa chỉ ví, hoặc Zealy Connect.
  • Nếu chọn kết nối ví, bạn cũng có thể chọn mạng sử dụng.

Blockchain mới

  • Nếu chọn Zealy Connect, hãy làm theo các bước sau:

    1. Xác định URL chuyển hướng: URL này sẽ được dùng để xác thực. Chúng tôi sẽ chuyển hướng người dùng đến URL này để họ xác thực trong hệ thống của bạn.

    Nhiệm vụ API Zealy Connect

    1. Tạo community secret: Việc tạo community secret là bắt buộc để Zealy Connect hoạt động. Bạn có thể tạo secret từ cài đặt Zealy Connect trong mục Integrations trong cài đặt cộng đồng của bạn.

    Community Secret

Để biết thông tin chuyên sâu về cách API được kỳ vọng hoạt động, vui lòng xem tài liệu API và để được hướng dẫn về quản lý Zealy Connect, vui lòng tham khảo tài liệu Zealy Connect.

Tích hợp với Domino

Domino là Web3 Zapier. Nó cho phép bạn mở rộng khả năng của Zealy và tự động đánh giá các nhiệm vụ không được hỗ trợ gốc, chẳng hạn như:

  • Kiểm tra xem tên hoặc tiểu sử Twitter của người dùng có chứa một từ cụ thể không
  • Kiểm tra số dư NFT & token của người dùng
  • Xác minh rằng người dùng đã mời một số lượng người nhất định trên Discord
  • Và nhiều hơn nữa

Xem tài liệu của họ để biết cách tích hợp.

Kiểm thử endpoint

Khi cấu hình endpoint, chúng tôi sẽ tự động chạy các bài kiểm tra sau để đảm bảo endpoint hoạt động như mong đợi:

  1. Kiểm tra để cuộc gọi không mất quá 10 giây
  2. Xác minh rằng thông báo lỗi có đúng định dạng để chúng tôi có thể hiển thị cho người dùng
  3. Đảm bảo rằng không có mã trạng thái bất ngờ nào. Endpoint chỉ nên trả về 200 hoặc 400.

Tạo endpoint tùy chỉnh

Yêu cầu

Bạn có thể dùng nhiệm vụ API với một POST endpoint tùy chỉnh chấp nhận body sau:

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

Bạn có thể bảo vệ nó bằng API key được đặt khi tạo nhiệm vụ. API key sẽ được gửi trong headers như sau:

Headers
{
  "X-Api-Key": apiKey,
}

Phản hồi

Nếu hành động đã được người dùng thực hiện thành công, bạn nên trả về trạng thái 200 . Người dùng sau đó sẽ claim nhiệm vụ thành công.

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

Nếu không, trạng thái 400 nên được trả về trong phản hồi cùng với một thông báo trong body. Thông báo sẽ được hiển thị cùng với requestId được tạo để giúp bạn và người dùng gỡ lỗi mọi vấn đề. Hãy đảm bảo rằng nó mô tả càng chi tiết càng tốt.

RESPONSE 400
{
  "message": "We could not find a user with email kenny@zealy.io"
}

Ví dụ mã

// 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'));

Kiểm thử cục bộ với ngrok

Khi phát triển và kiểm thử endpoint tùy chỉnh của bạn cục bộ, bạn cần một cách để đưa máy chủ cục bộ của mình ra internet để Zealy có thể gửi yêu cầu API đến đó. ngrok là một công cụ tạo đường hầm bảo mật đến localhost và rất phù hợp cho mục đích này. Hãy làm theo các bước sau để thiết lập ngrok và kiểm thử endpoint của bạn:

Bước 1: Cài đặt ngrok Tải ngrok từ trang web của ngrok. Làm theo hướng dẫn cài đặt cho hệ điều hành của bạn.

Bước 2: Thiết lập ngrok Đăng ký tài khoản ngrok miễn phí và lấy authtoken từ bảng điều khiển ngrok. Kết nối tài khoản ngrok của bạn bằng cách chạy ngrok authtoken YOUR_AUTH_TOKEN trong terminal, thay YOUR_AUTH_TOKEN bằng token từ bảng điều khiển ngrok của bạn.

Bước 3: Khởi động máy chủ cục bộ của bạn Đảm bảo máy chủ cục bộ lưu trữ endpoint đang chạy. Ví dụ: nếu máy chủ của bạn là ứng dụng Node.js, bạn có thể chạy node server.js.

Bước 4: Đưa máy chủ cục bộ của bạn ra ngoài bằng ngrok Mở một cửa sổ terminal mới và khởi động đường hầm ngrok đến cổng của máy chủ cục bộ (ví dụ: 3000) bằng ngrok http http://127.0.0.1:3000. ngrok sẽ hiển thị một URL chuyển tiếp trong terminal (ví dụ: https://abc123.ngrok.io). Đây là URL công khai mà Zealy sẽ dùng để truy cập máy chủ cục bộ của bạn.

Bước 5: Cấu hình nhiệm vụ API của bạn trong Zealy Dùng URL chuyển tiếp của ngrok làm URL endpoint khi thiết lập nhiệm vụ API của bạn trong Zealy. Đảm bảo thêm bất kỳ đường dẫn cần thiết nào, ví dụ: https://abc123.ngrok.io/claim.

Lưu ý: Hãy nhớ rằng URL ngrok là tạm thời và thay đổi mỗi khi bạn khởi động lại ngrok, trừ khi bạn có gói đăng ký trả phí hỗ trợ tên miền phụ tùy chỉnh. Hãy đảm bảo cập nhật endpoint trong Zealy mỗi khi bạn khởi động lại ngrok.

Bằng cách làm theo các bước này, bạn có thể dễ dàng kiểm thử và gỡ lỗi endpoint tùy chỉnh của mình trong môi trường phát triển cục bộ trước khi triển khai lên máy chủ production.

Tích hợp Zealy Connect

Khi dùng Zealy Connect, chúng tôi sẽ chuyển hướng người dùng đến URL được chỉ định trong quá trình thiết lập nhiệm vụ. Chúng tôi sẽ bao gồm các query params sau:

  • zealyUserId: Một mã định danh duy nhất cho người dùng trong hệ thống Zealy được dùng để liên kết họ với nền tảng của bạn.
  • callback: URL để chuyển hướng người dùng trở lại sau khi hoàn tất xác thực để họ có thể claim nhiệm vụ.
  • signature: Một mã băm SHA-256 được dùng để xác minh tính xác thực của yêu cầu, đảm bảo rằng nó đến từ Zealy.

Dưới đây là một endpoint ví dụ đầy đủ mà bạn có thể dùng làm điểm khởi đầu:

 
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. Xác minh chữ ký

Điều đầu tiên ứng dụng của bạn nên làm là xác thực chữ ký bằng community secret của bạn. Việc xác thực này đảm bảo rằng cuộc gọi thực sự đến từ chúng tôi và chưa bị sửa đổi.

Chúng tôi sử dụng thuật toán băm SHA256 để tạo chữ ký. Để xác minh, bạn có thể sử dụng cách sau:

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. Sử dụng Zealy User ID

Bước tiếp theo phụ thuộc vào điều bạn muốn làm, nhưng khách hàng thường đăng nhập người dùng hiện tại trên nền tảng của bạn và liên kết user ID của nền tảng bạn với Zealy User ID. Dưới đây là ví dụ:

  /**
   * 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. Chuyển hướng trở lại Zealy

Bước cuối cùng là chuyển hướng người dùng trở lại Zealy với user ID của nền tảng bạn để chúng tôi có thể cho phép người dùng nhận nhiệm vụ, sử dụng tham số truy vấn callback mà chúng tôi cung cấp. Bạn cũng cần tạo chữ ký để chúng tôi có thể xác minh rằng cuộc gọi đến từ bạn và không bị sửa đổi. Xem ví dụ bên dưới:

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

Khi chúng tôi nhận được callback, chúng tôi sẽ xác thực chữ ký và lưu user ID của nền tảng bạn để có thể gửi nó như một phần của nội dung nhiệm vụ API.

Người dùng giờ đây sẽ có thể nhận nhiệm vụ này và bất kỳ nhiệm vụ nào khác sử dụng Zealy Connect với cùng URL chuyển hướng. Chúng tôi sẽ ghi nhớ điều này để người dùng không phải kết nối cho mỗi nhiệm vụ.

Nếu bạn cần xóa liên kết Zealy Connect của người dùng, bạn có thể sử dụng tuyến API Delete Zealy Connect for Member. Tuyến này cho phép bạn xóa liên kết Zealy Connect cho một thành viên cụ thể. Sau khi gọi tuyến này, người dùng sẽ cần kết nối lại tài khoản để sử dụng lại các tính năng của Zealy Connect.

Câu hỏi thường gặp