Dokumentasi Zealy

Terjemahan otomatis · Baca dalam bahasa Inggris

API

Otomatiskan tindakan di platform eksternal

Oleh Fredrika

API
Di halaman ini

Ikhtisar

Panduan ini membahas tentang tugas API. Anda dapat menemukan dokumentasi API lengkap kami di sini.

Tugas API digunakan untuk mengotomatiskan tugas di platform eksternal. Anda dapat menggunakannya untuk mengonfirmasi bahwa pengguna telah mendaftar atau melakukan pembelian, telah membuka PR untuk masalah di Github, atau untuk menambahkan dukungan Reddit. Kemungkinannya tidak terbatas. Untuk memulai dan mencoba fungsionalitasnya, kami menyediakan endpoint dasar yang dapat Anda gunakan untuk bermitra dengan komunitas Zealy lainnya. Pelajari lebih lanjut tentang cara mengaturnya di bawah ini.

Dasar-dasar

Membuat Tugas "API"

  1. Klik 'Tambahkan tugas'.
  2. Pilih 'Api'.
  3. Tentukan endpoint yang akan dipanggil dan kunci API jika diperlukan.
  4. Pilih bagaimana pengguna dapat mengidentifikasi. Anda dapat memilih dari Email, Twitter, Discord, Alamat dompet, atau Zealy Connect.
  • Jika memilih koneksi dompet, Anda juga dapat memilih jaringan yang akan digunakan.

Blockchain baru

  • Jika memilih Zealy Connect, ikuti langkah-langkah berikut:

    1. Tentukan URL pengalihan: URL ini akan digunakan untuk autentikasi. Kami akan mengalihkan pengguna ke URL ini agar mereka dapat mengautentikasi di sistem Anda.

    TUGAS API Zealy Connect

    1. Buat rahasia komunitas: Membuat rahasia komunitas diperlukan agar Zealy Connect berfungsi. Anda dapat membuat rahasia dari pengaturan Zealy Connect di bawah bagian Integrasi di pengaturan komunitas Anda.

    Rahasia Komunitas

Untuk informasi mendalam tentang cara kerja API, silakan lihat dokumentasi API dan untuk panduan tentang mengelola Zealy Connect, silakan merujuk ke dokumentasi Zealy Connect.

Integrasi dengan Domino

Domino adalah Zapier Web3. Ini memungkinkan Anda memperluas kemampuan Zealy dan secara otomatis meninjau tugas yang tidak didukung secara native, seperti:

  • Memeriksa apakah nama atau bio Twitter pengguna mengandung kata tertentu
  • Memeriksa saldo NFT & token pengguna
  • Memverifikasi bahwa pengguna telah mengundang sejumlah orang tertentu di Discord
  • Dan masih banyak lagi

Lihat dokumentasi mereka untuk integrasi.

Pengujian endpoint

Saat mengonfigurasi endpoint, kami akan secara otomatis menjalankan pengujian berikut untuk memastikan bahwa endpoint berfungsi seperti yang diharapkan:

  1. Memeriksa agar panggilan tidak memakan waktu lebih dari 10 detik
  2. Memverifikasi bahwa pesan kesalahan dalam format yang benar sehingga kami dapat menampilkannya kepada pengguna
  3. Memastikan bahwa tidak ada kode status yang tidak terduga. Endpoint hanya boleh mengembalikan 200 atau 400.

Membuat endpoint kustom

Permintaan

Anda dapat menggunakan tugas API dengan POST endpoint kustom yang menerima body berikut:

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

Anda dapat melindunginya dengan kunci API yang diatur saat membuat tugas. Kunci API akan dikirim dalam header seperti ini:

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

Respons

Jika tindakan telah berhasil dilakukan oleh pengguna, Anda harus mengembalikan 200 status. Pengguna kemudian akan berhasil mengklaim tugas.

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

Jika tidak, 400 status harus dikembalikan dalam respons bersama dengan pesan di body. Pesan akan ditampilkan dengan requestId yang dihasilkan untuk membantu Anda dan pengguna men-debug masalah. Pastikan pesan tersebut sedeskriptif mungkin.

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

Contoh kode

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

Pengujian lokal dengan ngrok

Saat mengembangkan dan menguji endpoint kustom Anda secara lokal, Anda memerlukan cara untuk mengekspos server lokal Anda ke internet agar Zealy dapat mengirim permintaan API ke sana. ngrok adalah alat yang membuat tunnel aman ke localhost dan sempurna untuk tujuan ini. Ikuti langkah-langkah berikut untuk menyiapkan ngrok dan menguji endpoint Anda:

Langkah 1: Instal ngrok Unduh ngrok dari situs web ngrok. Ikuti instruksi instalasi untuk sistem operasi Anda.

Langkah 2: Siapkan ngrok Daftar untuk akun ngrok gratis dan dapatkan authtoken Anda dari dasbor ngrok. Hubungkan akun ngrok Anda dengan menjalankan ngrok authtoken YOUR_AUTH_TOKEN di terminal Anda, ganti YOUR_AUTH_TOKEN dengan token dari dasbor ngrok Anda.

Langkah 3: Mulai server lokal Anda Pastikan server lokal Anda yang menghosting endpoint sedang berjalan. Misalnya, jika server Anda adalah aplikasi Node.js, Anda mungkin menjalankan node server.js.

Langkah 4: Ekspos server lokal Anda dengan ngrok Buka jendela terminal baru dan mulai tunnel ngrok ke port server lokal Anda (misalnya, 3000) menggunakan ngrok http http://127.0.0.1:3000. ngrok akan menampilkan URL penerusan di terminal (misalnya, https://abc123.ngrok.io). Ini adalah URL publik yang akan digunakan Zealy untuk menjangkau server lokal Anda.

Langkah 5: Konfigurasikan tugas API Anda di Zealy Gunakan URL penerusan ngrok sebagai URL endpoint saat menyiapkan tugas API Anda di Zealy. Pastikan untuk menambahkan path yang diperlukan, misalnya, https://abc123.ngrok.io/claim.

Catatan: Ingat, URL ngrok bersifat sementara dan berubah setiap kali Anda memulai ulang ngrok, kecuali Anda memiliki langganan berbayar yang mendukung subdomain kustom. Pastikan untuk memperbarui endpoint di Zealy setiap kali Anda memulai ulang ngrok.

Dengan mengikuti langkah-langkah ini, Anda dapat dengan mudah menguji dan men-debug endpoint kustom Anda di lingkungan pengembangan lokal sebelum menerapkannya ke server produksi.

Integrasi Zealy Connect

Saat menggunakan Zealy Connect, kami akan mengalihkan pengguna ke URL yang ditentukan selama penyiapan tugas. Kami akan menyertakan parameter kueri berikut:

  • zealyUserId: Pengenal unik untuk pengguna dalam sistem Zealy yang digunakan untuk menautkan mereka dengan platform Anda.
  • callback: URL untuk mengalihkan pengguna kembali setelah autentikasi selesai sehingga mereka dapat mengklaim tugas.
  • signature: Hash SHA-256 yang digunakan untuk memverifikasi keaslian permintaan, memastikan bahwa permintaan tersebut berasal dari Zealy.

Berikut adalah contoh endpoint lengkap yang dapat Anda gunakan sebagai titik awal:

 
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. Verifikasi Tanda Tangan

Hal pertama yang harus dilakukan aplikasi Anda adalah memvalidasi tanda tangan menggunakan rahasia komunitas Anda. Validasi ini memastikan bahwa panggilan benar-benar berasal dari kami dan belum dimodifikasi.

Kami menggunakan algoritma hash SHA256 untuk menghasilkan signature. Untuk memverifikasinya, Anda dapat menggunakan pendekatan berikut:

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. Gunakan Zealy User ID

Langkah berikutnya bergantung pada apa yang ingin Anda lakukan, tetapi pelanggan biasanya melakukan login pengguna saat ini di platform Anda dan menautkan user ID platform Anda dengan Zealy User ID. Berikut adalah contohnya:

  /**
   * 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. Alihkan Kembali ke Zealy

Langkah terakhir adalah mengalihkan pengguna kembali ke Zealy dengan user ID platform Anda agar kami dapat mengizinkan pengguna untuk claim task, menggunakan parameter query callback yang kami sediakan. Anda juga perlu menghasilkan signature agar kami dapat memverifikasi bahwa panggilan tersebut berasal dari Anda dan belum dimodifikasi. Lihat contoh di bawah ini:

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

Setelah kami menerima callback, kami akan memvalidasi signature dan menyimpan user ID platform Anda agar kami dapat mengirimkannya sebagai bagian dari body task API.

Pengguna sekarang dapat claim task tersebut dan task lain yang menggunakan Zealy Connect dengan redirect URL yang sama. Kami akan mengingatnya sehingga pengguna tidak perlu menghubungkan ulang untuk setiap task.

Jika Anda perlu menghapus asosiasi Zealy Connect pengguna, Anda dapat menggunakan rute API Delete Zealy Connect for Member. Rute ini memungkinkan Anda menghapus asosiasi Zealy Connect untuk member tertentu. Setelah memanggil rute ini, pengguna perlu menghubungkan kembali akunnya untuk menggunakan fitur Zealy Connect lagi.

FAQ