เอกสารประกอบ Zealy

แปลอัตโนมัติ · อ่านเป็นภาษาอังกฤษ

API

ทำให้การดำเนินการบนแพลตฟอร์มภายนอกเป็นอัตโนมัติ

โดย Fredrika

API
ในหน้านี้

ภาพรวม

คู่มือนี้เกี่ยวกับงาน API คุณสามารถดูเอกสาร API ฉบับเต็มได้ ที่นี่.

งาน API ใช้เพื่อทำให้งานบนแพลตฟอร์มภายนอกเป็นอัตโนมัติ คุณอาจใช้เพื่อยืนยันว่าผู้ใช้ได้ลงทะเบียนหรือซื้อแล้ว ได้เปิด PR สำหรับปัญหาบน Github หรือเพื่อเพิ่มการสนับสนุน Reddit ความเป็นไปได้ไม่มีที่สิ้นสุด ในการเริ่มต้นและลองใช้ฟังก์ชันการทำงาน เราเสนอ endpoint พื้นฐานที่คุณอาจใช้เพื่อสร้างความร่วมมือกับชุมชน Zealy อื่นๆ เรียนรู้เพิ่มเติมเกี่ยวกับวิธีการตั้งค่าด้านล่าง

พื้นฐาน

การสร้างงาน "API"

  1. คลิกที่ 'เพิ่มงาน'.
  2. เลือก 'Api'.
  3. กำหนด endpoint ที่จะเรียกและคีย์ API หากจำเป็น
  4. เลือกวิธีที่ผู้ใช้สามารถระบุตัวตนได้ คุณสามารถเลือกจาก อีเมล, 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
  • และอื่นๆ อีกมากมาย

ดู เอกสาร ของพวกเขาสำหรับการผสานรวม

การทดสอบ endpoint

เมื่อกำหนดค่า endpoint เราจะทำการทดสอบต่อไปนี้โดยอัตโนมัติเพื่อให้แน่ใจว่า endpoint ทำงานตามที่คาดไว้:

  1. ตรวจสอบว่าการเรียกใช้ใช้เวลาไม่เกิน 10 วินาที
  2. ตรวจสอบว่าข้อความแสดงข้อผิดพลาดอยู่ในรูปแบบที่ถูกต้องเพื่อให้เราแสดงให้ผู้ใช้เห็นได้
  3. ตรวจสอบว่าไม่ใช่รหัสสถานะที่ไม่คาดคิด endpoint ควรส่งคืนเฉพาะ 200 หรือ 400

การสร้าง endpoint ที่กำหนดเอง

คำขอ

คุณสามารถใช้งาน API ได้ด้วย POST endpoint ที่กำหนดเองซึ่งรับเนื้อหาต่อไปนี้:

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

เมื่อพัฒนาและทดสอบ endpoint ที่กำหนดเองในเครื่อง คุณต้องมีวิธีเปิดเผยเซิร์ฟเวอร์ในเครื่องของคุณสู่อินเทอร์เน็ตเพื่อให้ Zealy สามารถส่งคำขอ API ไปยังเซิร์ฟเวอร์นั้นได้ ngrok เป็นเครื่องมือที่สร้างอุโมงค์ที่ปลอดภัยไปยัง localhost และเหมาะสำหรับจุดประสงค์นี้ ทำตามขั้นตอนเหล่านี้เพื่อตั้งค่า ngrok และทดสอบ endpoint ของคุณ:

ขั้นตอนที่ 1: ติดตั้ง ngrok ดาวน์โหลด ngrok จากเว็บไซต์ของ ngrok ทำตามคำแนะนำการติดตั้งสำหรับระบบปฏิบัติการของคุณ

ขั้นตอนที่ 2: ตั้งค่า ngrok สมัครบัญชี ngrok ฟรีและรับ authtoken จากแดชบอร์ด ngrok เชื่อมต่อบัญชี ngrok ของคุณโดยรัน ngrok authtoken YOUR_AUTH_TOKEN ในเทอร์มินัลของคุณ แทนที่ YOUR_AUTH_TOKEN ด้วยโทเค็นจากแดชบอร์ด ngrok ของคุณ

ขั้นตอนที่ 3: เริ่มเซิร์ฟเวอร์ในเครื่องของคุณ ตรวจสอบให้แน่ใจว่าเซิร์ฟเวอร์ในเครื่องของคุณที่โฮสต์ endpoint กำลังทำงานอยู่ ตัวอย่างเช่น หากเซิร์ฟเวอร์ของคุณเป็นแอป 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 ของ endpoint เมื่อตั้งค่างาน API ของคุณใน Zealy ตรวจสอบให้แน่ใจว่าได้เพิ่มพาธที่จำเป็น เช่น https://abc123.ngrok.io/claim.

หมายเหตุ: โปรดจำไว้ว่า URL ของ ngrok เป็นแบบชั่วคราวและเปลี่ยนแปลงทุกครั้งที่คุณรีสตาร์ท ngrok เว้นแต่คุณจะมีสมาชิกแบบชำระเงินที่รองรับโดเมนย่อยที่กำหนดเอง ตรวจสอบให้แน่ใจว่าได้อัปเดต endpoint ใน Zealy ทุกครั้งที่คุณรีสตาร์ท ngrok

เมื่อทำตามขั้นตอนเหล่านี้ คุณสามารถทดสอบและแก้ไขข้อบกพร่องของ endpoint ที่กำหนดเองในสภาพแวดล้อมการพัฒนาในเครื่องได้อย่างง่ายดายก่อนที่จะนำไปใช้กับเซิร์ฟเวอร์การผลิต

การผสานรวม Zealy Connect

เมื่อใช้ Zealy Connect เราจะเปลี่ยนเส้นทางผู้ใช้ไปยัง URL ที่ระบุระหว่างการตั้งค่างาน เราจะรวมพารามิเตอร์คิวรีต่อไปนี้:

  • zealyUserId: ตัวระบุที่ไม่ซ้ำกันสำหรับผู้ใช้ในระบบ Zealy ที่ใช้เชื่อมโยงกับแพลตฟอร์มของคุณ
  • callback: URL ที่จะเปลี่ยนเส้นทางผู้ใช้กลับหลังจากเสร็จสิ้นการรับรองความถูกต้องเพื่อให้พวกเขาสามารถเคลมงานได้
  • signature: แฮช SHA-256 ที่ใช้ตรวจสอบความถูกต้องของคำขอ เพื่อให้แน่ใจว่ามาจาก Zealy

นี่คือตัวอย่าง endpoint แบบเต็มที่คุณสามารถใช้เป็นจุดเริ่มต้น:

 
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

ขั้นตอนถัดไปขึ้นอยู่กับสิ่งที่คุณต้องการทำ แต่โดยปกติแล้วลูกค้าจะล็อกอินผู้ใช้ปัจจุบันบนแพลตฟอร์มของคุณและเชื่อมโยง 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 พร้อมกับ User ID ของแพลตฟอร์มคุณ เพื่อให้เราอนุญาตให้ผู้ใช้เคลมงาน โดยใช้พารามิเตอร์ callback query ที่เราให้ไว้ คุณยังต้องสร้างลายเซ็นเพื่อให้เราตรวจสอบได้ว่าการเรียกนั้นมาจากคุณและไม่ถูกแก้ไข ดูตัวอย่างด้านล่าง:

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 เราจะตรวจสอบลายเซ็นและจัดเก็บ User ID ของแพลตฟอร์มคุณ เพื่อให้เราส่งเป็นส่วนหนึ่งของ body ของงาน API ได้

ตอนนี้ผู้ใช้จะสามารถเคลมงานและงานอื่น ๆ ที่ใช้ Zealy Connect กับ redirect URL เดียวกันได้ เราจะจดจำข้อมูลนี้ไว้เพื่อให้ผู้ใช้ไม่ต้องเชื่อมต่อใหม่สำหรับทุกงาน

หากคุณต้องการลบการเชื่อมโยง Zealy Connect ของผู้ใช้ คุณสามารถใช้ เส้นทาง API Delete Zealy Connect for Memberเส้นทางนี้ช่วยให้คุณลบการเชื่อมโยง Zealy Connect สำหรับสมาชิกที่ระบุได้ หลังจากเรียกเส้นทางนี้ ผู้ใช้จะต้องเชื่อมต่อบัญชีใหม่เพื่อใช้ฟีเจอร์ Zealy Connect อีกครั้ง

คำถามที่พบบ่อย