Dokumentasi Zealy

Diterjemah secara automatik · Baca dalam bahasa Inggeris

API

Automatkan tindakan pada platform luaran

Oleh Fredrika

API
Pada halaman ini

Gambaran keseluruhan

Panduan ini adalah tentang tugasan API. Anda boleh menemui dokumentasi API penuh kami di sini.

Quest API digunakan untuk mengautomasikan quest pada platform luaran. Anda mungkin menggunakannya untuk mengesahkan bahawa pengguna telah mendaftar atau membuat pembelian, telah membuka PR untuk isu di Github atau untuk menambah sokongan Reddit. Kemungkinannya tidak terhad. Untuk bermula dan mencuba fungsi yang kami tawarkan, kami menyediakan endpoint asas yang boleh anda gunakan untuk menjalin kerjasama dengan komuniti Zealy lain. Ketahui lebih lanjut tentang cara menyediakannya di bawah.

Asas

Mencipta Tugasan "API"

  1. Klik pada 'Tambah tugasan'.
  2. Pilih 'Api'.
  3. Tentukan endpoint untuk dipanggil dan kunci API jika perlu.
  4. Pilih cara pengguna boleh dikenal pasti. Anda boleh memilih daripada E-mel, Twitter, Discord, Alamat dompet, atau Zealy Connect.
  • Jika memilih sambungan dompet, anda juga boleh memilih rangkaian yang hendak digunakan.

Rangkaian blok baharu

  • Jika memilih Zealy Connect, ikuti langkah berikut:

    1. Tentukan URL ubah hala: URL ini akan digunakan untuk pengesahan. Kami akan mengubah hala pengguna ke URL ini untuk mereka sahkan dalam sistem anda.

    TUGAS API Zealy Connect

    1. Jana rahsia komuniti: Menjana rahsia komuniti diperlukan untuk Zealy Connect untuk berfungsi. Anda boleh mencipta rahsia daripada tetapan Zealy Connect di bawah bahagian Integrasi dalam tetapan komuniti anda.

    Rahsia Komuniti

Untuk maklumat mendalam tentang cara API dijangka berfungsi, sila lihat Dokumentasi API dan untuk panduan mengurus Zealy Connect, sila rujuk Dokumentasi Zealy Connect.

Integrasi dengan Domino

Domino ialah Zapier Web3. Ia membolehkan anda meluaskan keupayaan Zealy dan menyemak secara automatik tugasan yang tidak disokong secara asli, seperti:

  • Menyemak sama ada nama atau bio Twitter pengguna mengandungi perkataan tertentu
  • Menyemak baki NFT & token pengguna
  • Mengesahkan bahawa pengguna telah menjemput sebilangan orang tertentu di Discord
  • Dan banyak lagi

Lihat dokumentasi mereka untuk integrasi.

Ujian titik akhir

Semasa mengkonfigurasi titik akhir, kami akan menjalankan ujian berikut secara automatik untuk memastikan titik akhir berfungsi seperti yang dijangka:

  1. Menyemak supaya panggilan tidak mengambil masa lebih daripada 10 saat
  2. Mengesahkan bahawa mesej ralat berada dalam format yang betul supaya kami boleh memaparkannya kepada pengguna
  3. Pastikan ia bukan mana-mana kod status yang tidak dijangka. Endpoint sepatutnya hanya mengembalikan 200 atau 400.

Mencipta endpoint tersuai

Permintaan

Anda boleh menggunakan tugasan API dengan POST endpoint tersuai 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 boleh melindunginya dengan kunci API yang ditetapkan semasa mencipta tugasan. Kunci API akan dihantar dalam pengepala seperti ini:

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

Respons

Jika tindakan telah berjaya dilakukan oleh pengguna, anda harus mengembalikan 200 status. Pengguna kemudian akan berjaya menuntut tugasan itu.

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

Jika tidak, 400 status harus dikembalikan dalam respons bersama mesej dalam badan. Mesej itu akan dipaparkan dengan requestId untuk membantu anda dan pengguna menyahpepijat sebarang isu. Pastikan ia sekata mungkin deskriptif.

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

Contoh kod

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

Ujian setempat dengan ngrok

Apabila membangun dan menguji titik akhir tersuai anda secara setempat, anda memerlukan cara untuk mendedahkan pelayan setempat anda kepada internet supaya Zealy boleh menghantar permintaan API kepadanya. ngrok ialah alat yang mencipta terowong selamat ke localhost dan sesuai untuk tujuan ini. Ikuti langkah ini untuk menyediakan ngrok dan menguji titik akhir anda:

Langkah 1: Pasang ngrok Muat turun ngrok dari laman web ngrok. Ikuti arahan pemasangan untuk sistem pengendalian anda.

Langkah 2: Sediakan ngrok Daftar akaun ngrok percuma dan dapatkan authtoken anda daripada papan pemuka ngrok. Sambungkan akaun ngrok anda dengan menjalankan ngrok authtoken YOUR_AUTH_TOKEN dalam terminal anda, gantikan YOUR_AUTH_TOKEN dengan token daripada papan pemuka ngrok anda.

Langkah 3: Mulakan pelayan tempatan anda Pastikan pelayan tempatan anda yang menghoskan titik akhir sedang berjalan. Contohnya, jika pelayan anda ialah aplikasi Node.js, anda mungkin menjalankan node server.js.

Langkah 4: Dedahkan pelayan tempatan anda dengan ngrok Buka tetingkap terminal baharu dan mulakan terowong ngrok ke port pelayan tempatan anda (cth., 3000) menggunakan ngrok http http://127.0.0.1:3000. ngrok akan memaparkan URL pemajuan dalam terminal (cth., https://abc123.ngrok.io). Ini ialah URL awam yang akan digunakan oleh Zealy untuk mencapai pelayan tempatan anda.

Langkah 5: Konfigurasikan tugas API anda dalam Zealy Gunakan URL pemajuan ngrok sebagai URL titik akhir semasa menyediakan tugas API anda dalam Zealy. Pastikan anda menambahkan sebarang laluan yang diperlukan, contohnya, https://abc123.ngrok.io/claim.

Nota: Ingat, URL ngrok adalah sementara dan berubah setiap kali anda memulakan semula ngrok, melainkan anda mempunyai langganan berbayar yang menyokong subdomain tersuai. Pastikan anda mengemas kini titik akhir dalam Zealy setiap kali anda memulakan semula ngrok.

Dengan mengikuti langkah-langkah ini, anda boleh menguji dan menyahpepijat titik akhir tersuai anda dengan mudah dalam persekitaran pembangunan setempat sebelum menggunakannya pada pelayan pengeluaran.

Integrasi Zealy Connect

Apabila menggunakan Zealy Connect, kami akan mengalihkan pengguna ke URL yang dinyatakan semasa persediaan tugasan. Kami akan menyertakan parameter pertanyaan berikut:

  • zealyUserId: Pengecam unik untuk pengguna dalam sistem Zealy yang digunakan untuk memautkan mereka dengan platform anda.
  • callback: URL untuk mengalihkan pengguna kembali selepas pengesahan selesai supaya mereka boleh menuntut tugasan.
  • signature: Hash SHA-256 yang digunakan untuk mengesahkan ketulenan permintaan, memastikan ia berasal daripada Zealy.

Berikut ialah contoh titik akhir penuh yang boleh anda gunakan sebagai titik permulaan:

 
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. Sahkan Tandatangan

Perkara pertama yang perlu dilakukan oleh aplikasi anda ialah mengesahkan tandatangan menggunakan rahsia komuniti anda. Pengesahan ini memastikan bahawa panggilan itu benar-benar datang daripada kami dan tidak diubah suai.

Kami menggunakan algoritma hash SHA256 untuk menjana tandatangan. Untuk mengesahkannya, anda boleh 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 ID Pengguna Zealy

Langkah seterusnya bergantung pada apa yang anda mahu lakukan, tetapi pelanggan biasanya log masuk pengguna semasa pada platform anda dan memautkan ID pengguna platform anda dengan ID Pengguna Zealy. Berikut ialah contoh:

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

Langkah terakhir ialah mengubah hala pengguna kembali ke Zealy dengan ID pengguna platform anda supaya kami boleh membenarkan pengguna menuntut tugasan, menggunakan parameter pertanyaan callback yang kami sediakan. Anda juga perlu menjana tandatangan supaya kami boleh mengesahkan bahawa panggilan itu datang daripada anda dan tidak diubah suai. Lihat contoh di bawah:

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

Sebaik sahaja kami menerima callback, kami akan mengesahkan tandatangan dan menyimpan ID pengguna platform anda supaya kami boleh menghantarnya sebagai sebahagian daripada badan tugasan API.

Pengguna kini boleh menuntut tugasan ini dan mana-mana tugasan lain yang menggunakan Zealy Connect dengan URL ubah hala yang sama. Kami akan mengingati perkara ini supaya pengguna tidak perlu menyambung untuk setiap tugasan.

Jika anda perlu memadamkan persatuan Zealy Connect pengguna, anda boleh menggunakan Laluan API Padam Zealy Connect untuk Ahli. Laluan ini membolehkan anda mengalih keluar persatuan Zealy Connect untuk ahli tertentu. Selepas memanggil laluan ini, pengguna perlu menyambung semula akaun mereka untuk menggunakan ciri Zealy Connect sekali lagi.

Soalan Lazim