API

在外部平臺上自動執行操作

作者 Fredrika

本頁內容

概述

本指南介紹 API 任務。您可以在這裡找到完整的 API 文件這裡.

API 任務用於在外部平臺上自動化任務。您可以使用它來確認使用者已註冊或已購買、已為 GitHub 上的問題開啟 PR，或新增 Reddit 支援。可能性無窮無盡。為了開始並試用我們提供的功能，我們提供了一個基本端點，您可以用來與其他 Zealy 社群進行合作。請在下方瞭解如何設定。

基礎

建立「API」任務

點擊 「新增任務」.
選擇 「Api」.
定義要呼叫的端點，以及必要的 API 金鑰。
選擇使用者如何識別。您可以從以下選項中選擇： 電子郵件, Twitter, Discord, 錢包地址，或 Zealy Connect.

如果選擇 錢包連接，您還可以選擇要使用的網路。

新的區塊鏈

如果選擇 Zealy Connect，請按照以下步驟操作：
1. 定義重新導向 URL： 此 URL 將用於驗證。我們會將使用者重新導向至此 URL，以便他們在您的系統中進行驗證。
1. 產生社群密鑰： 產生社群密鑰是 Zealy Connect 運作所必需的。您可以在社群設定的 Zealy Connect 設定 中的 整合區段 建立密鑰。

如需深入瞭解 API 的預期運作方式，請參閱 API 文件，如需管理 Zealy Connect 的指引，請參閱 Zealy Connect 文件.

與 Domino 整合

Domino 是 Web3 的 Zapier。它允許您擴展 Zealy 的功能，並自動審查原生不支援的任務，例如：

檢查使用者的 Twitter 名稱或簡介是否包含特定詞彙
檢查使用者的 NFT 與代幣餘額
驗證使用者在 Discord 上已邀請一定數量的人
以及更多

查看他們的文件以進行整合。

端點測試

設定端點時，我們會自動執行以下測試，以確保端點如預期運作：

檢查呼叫時間不超過 10 秒
驗證錯誤訊息格式正確，以便我們向使用者顯示
確保沒有意外的狀態碼。端點應僅傳回 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 帳戶，並從 ngrok 儀錶板取得您的 authtoken。在終端機中執行 ngrok authtoken YOUR_AUTH_TOKEN 來連接您的 ngrok 帳戶，將 YOUR_AUTH_TOKEN 替換為您 ngrok 儀錶板中的權杖。

步驟 3：啟動本機伺服器確保託管端點的本機伺服器正在執行。例如，如果您的伺服器是 Node.js 應用程式，您可能會執行 node server.js。

步驟 4：使用 ngrok 暴露本機伺服器開啟新的終端機視窗，並使用以下命令啟動到本機伺服器連接埠（例如 3000）的 ngrok 通道： ngrok http http://127.0.0.1:3000。 ngrok 將在終端機中顯示轉發 URL（例如 https://abc123.ngrok.io）。這是 Zealy 將用來連線到您本機伺服器的公開 URL。

步驟 5：在 Zealy 中設定您的 API 任務在 Zealy 中設定 API 任務時，使用 ngrok 轉發 URL 作為端點 URL。確保附加任何必要的路徑，例如 https://abc123.ngrok.io/claim.

注意：請記住，ngrok URL 是暫時的，每次重新啟動 ngrok 時都會變更，除非您有支援自訂子網域的付費訂閱。每次重新啟動 ngrok 時，請務必更新 Zealy 中的端點。

按照這些步驟，您可以在部署到生產伺服器之前，輕鬆在本機開發環境中測試和偵錯您的自訂端點。

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

下一步取決於你想做什麼，但客戶通常會在你的平臺上登入目前使用者，並將你平臺的使用者 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

最後一步是使用我們提供的 callback 查詢參數，將使用者重新導向回 Zealy，並附上你平臺的使用者 ID，以便我們允許該使用者領取任務。你還需要產生簽章，讓我們能驗證此呼叫來自你且未被修改。請參閱以下範例：

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 任務 body 中一併傳送。

使用者現在將能領取該任務，以及任何使用相同重新導向 URL 的 Zealy Connect 任務。我們會記住這點，讓使用者不必為每個任務重新連結。

如果你需要刪除使用者的 Zealy Connect 關聯，可以使用 Delete Zealy Connect for Member API 路由。此路由可讓你移除特定成員的 Zealy Connect 關聯。呼叫此路由後，使用者需要重新連結帳戶才能再次使用 Zealy Connect 功能。

概述

基礎