API

ទិដ្ឋភាពទូទៅ

ការណែនាំនេះនិយាយអំពីភារកិច្ច API។ អ្នកអាចរកឃើញឯកសារ API ពេញលេញរបស់យើង នៅទីនេះ.

ភារកិច្ច API ត្រូវបានប្រើដើម្បីស្វ័យប្រវត្តិកម្មភារកិច្ចនៅលើវេទិកាខាងក្រៅ។ អ្នកអាចប្រើវាដើម្បីបញ្ជាក់ថាអ្នកប្រើបានចុះឈ្មោះ ឬបានទិញទំនិញ បានបើក PR សម្រាប់បញ្ហានៅលើ Github ឬដើម្បីបន្ថែមការគាំទ្រ Reddit។ លទ្ធភាពគឺគ្មានដែនកំណត់។ ដើម្បីចាប់ផ្តើម និងសាកល្បងមុខងារដែលយើងផ្តល់ជូន យើងមាន endpoint មូលដ្ឋានដែលអ្នកអាចប្រើដើម្បីធ្វើដៃគូជាមួយសហគមន៍ Zealy ផ្សេងទៀត។ ស្វែងយល់បន្ថែមអំពីរបៀបដំឡើងវាខាងក្រោម។

មូលដ្ឋាន

ការបង្កើតភារកិច្ច "API"

1. ចុចលើ បន្ថែមភារកិច្ច.
2. ជ្រើសរើស Api.
3. កំណត់ចំណុចបញ្ចប់ដែលត្រូវហៅ និងសោ API ប្រសិនបើចាំបាច់។
4. ជ្រើសរើសរបៀបដែលអ្នកប្រើប្រាស់អាចកំណត់អត្តសញ្ញាណ។ អ្នកអាចជ្រើសរើសពី អ៊ីមែល, Twitter, Discord, អាសយដ្ឋានកាបូប, ឬ Zealy Connect.

• ប្រសិនបើជ្រើសរើស ការភ្ជាប់កាបូប, អ្នកក៏អាចជ្រើសរើសបណ្តាញដែលត្រូវប្រើបានផងដែរ។

• ប្រសិនបើជ្រើសរើស Zealy Connectសូមអនុវត្តតាមជំហានទាំងនេះ៖

  1. កំណត់ URL ប្តូរទិស៖ URL នេះនឹងត្រូវបានប្រើសម្រាប់ការផ្ទៀងផ្ទាត់អត្តសញ្ញាណ។ យើងនឹងប្តូរទិសអ្នកប្រើប្រាស់ទៅ URL នេះ ដើម្បីឱ្យពួកគេផ្ទៀងផ្ទាត់អត្តសញ្ញាណនៅក្នុងប្រព័ន្ធរបស់អ្នក។

  

  2. បង្កើតអាថ៌កំបាំងសហគមន៍៖ ការបង្កើតអាថ៌កំបាំងសហគមន៍គឺចាំបាច់សម្រាប់ Zealy Connect ដើម្បីដំណើរការ។ អ្នកអាចបង្កើតគន្លឹះសម្ងាត់ពី ការកំណត់ Zealy Connect ក្រោម ផ្នែក Integrations នៅក្នុងការកំណត់សហគមន៍របស់អ្នក។

  

សម្រាប់ព័ត៌មានលម្អិតអំពីរបៀបដែល API ត្រូវបានរំពឹងឱ្យដំណើរការ សូមមើល ឯកសារ API ហើយសម្រាប់ការណែនាំអំពីការគ្រប់គ្រង Zealy Connect សូមយោងទៅកាន់ ឯកសារ Zealy Connect.

ការភ្ជាប់ជាមួយ Domino

Domino គឺជា Web3 Zapier។ វាអនុញ្ញាតឱ្យអ្នកពង្រីកសមត្ថភាពរបស់ Zealy និងពិនិត្យភារកិច្ចដោយស្វ័យប្រវត្តិដែលមិនត្រូវបានគាំទ្រដោយដើម ដូចជា៖

• ពិនិត្យមើលថាតើឈ្មោះ ឬជីវប្រវត្តិ Twitter របស់អ្នកប្រើប្រាស់មានពាក្យជាក់លាក់ឬអត់
• ពិនិត្យមើលសមតុល្យ NFT និង token របស់អ្នកប្រើប្រាស់
• ផ្ទៀងផ្ទាត់ថាអ្នកប្រើប្រាស់បានអញ្ជើញមនុស្សចំនួនជាក់លាក់នៅលើ Discord
• និងច្រើនទៀត

ពិនិត្យមើល ឯកសារ សម្រាប់ការរួមបញ្ចូល។

ការសាកល្បងចំណុចបញ្ចប់

នៅពេលកំណត់រចនាសម្ព័ន្ធចំណុចបញ្ចប់ យើងនឹងដំណើរការការសាកល្បងខាងក្រោមដោយស្វ័យប្រវត្តិ ដើម្បីធានាថាចំណុចបញ្ចប់ដំណើរការដូចដែលបានរំពឹងទុក៖

1. ពិនិត្យមើលថាការហៅមិនចំណាយពេលលើសពី 10 វិនាទី
2. ផ្ទៀងផ្ទាត់ថាសារកំហុសមានទម្រង់ត្រឹមត្រូវ ដើម្បីឱ្យយើងអាចបង្ហាញវាទៅអ្នកប្រើប្រាស់
3. ត្រូវប្រាកដថាវាមិនមែនជាកូដស្ថានភាពដែលមិនបានរំពឹងទុកណាមួយឡើយ។ ចំណុចបញ្ចប់គួរតែត្រឡប់តែ 200 ឬ 400 ប៉ុណ្ណោះ។

ការបង្កើតចំណុចបញ្ចប់ផ្ទាល់ខ្លួន

សំណើ

អ្នកអាចប្រើភារកិច្ច API ជាមួយចំណុចបញ្ចប់ផ្ទាល់ខ្លួន POST ដែលទទួលយកតួខ្លឹមសារដូចខាងក្រោម៖

{
  /**
   * 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 នឹងត្រូវបានផ្ញើនៅក្នុងបឋមកថាដូចនេះ៖

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

ការឆ្លើយតប

ប្រសិនបើសកម្មភាពត្រូវបានអនុវត្តដោយជោគជ័យដោយអ្នកប្រើប្រាស់ អ្នកគួរតែត្រឡប់ 200 ស្ថានភាព។ បន្ទាប់មកអ្នកប្រើប្រាស់នឹងទាមទារកិច្ចការដោយជោគជ័យ។

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

បើមិនដូច្នេះទេ 400 ស្ថានភាពគួរត្រូវបានត្រឡប់ក្នុងការឆ្លើយតប រួមជាមួយសារមួយនៅក្នុងតួ។ សារនឹងត្រូវបានបង្ហាញជាមួយ requestId ដើម្បីជួយអ្នក និងអ្នកប្រើប្រាស់ក្នុងការដោះស្រាយបញ្ហាណាមួយ។ សូមប្រាកដថាវាមានការពិពណ៌នាឱ្យបានច្បាស់លាស់តាមដែលអាចធ្វើទៅបាន។

{
  "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 ឥតគិតថ្លៃ ហើយយក authtoken របស់អ្នកពីផ្ទាំងគ្រប់គ្រង ngrok។ ភ្ជាប់គណនី ngrok របស់អ្នកដោយដំណើរការ ngrok authtoken YOUR_AUTH_TOKEN ក្នុង terminal របស់អ្នក ដោយជំនួស YOUR_AUTH_TOKEN ដោយ token ពីផ្ទាំងគ្រប់គ្រង ngrok របស់អ្នក។

ជំហានទី 3៖ ចាប់ផ្តើម server មូលដ្ឋានរបស់អ្នក សូមប្រាកដថា server មូលដ្ឋានរបស់អ្នកដែលផ្ទុក endpoint កំពុងដំណើរការ។ ឧទាហរណ៍ ប្រសិនបើ server របស់អ្នកជា app Node.js អ្នកអាចដំណើរការ node server.js។

ជំហានទី 4៖ បង្ហាញ server មូលដ្ឋានរបស់អ្នកដោយ ngrok បើកផ្ទាំង terminal ថ្មី ហើយចាប់ផ្តើម tunnel ngrok ទៅកាន់ port របស់ server មូលដ្ឋានរបស់អ្នក (ឧ. 3000) ដោយប្រើ ngrok http http://127.0.0.1:3000. ngrok នឹងបង្ហាញ URL បញ្ជូនបន្តនៅក្នុង terminal (ឧ. https://abc123.ngrok.io)។ នេះជា URL សាធារណៈដែល Zealy នឹងប្រើដើម្បីភ្ជាប់ទៅ server មូលដ្ឋានរបស់អ្នក។

ជំហានទី 5៖ កំណត់រចនាសម្ព័ន្ធកិច្ចការ API របស់អ្នកក្នុង Zealy ប្រើ URL បញ្ជូនបន្ត ngrok ជា URL endpoint នៅពេលដំឡើងកិច្ចការ API របស់អ្នកក្នុង Zealy។ សូមបន្ថែម path ដែលត្រូវការ ឧទាហរណ៍ https://abc123.ngrok.io/claim.

ចំណាំ៖ សូមចងចាំថា URL របស់ ngrok គឺជាបណ្ដោះអាសន្ន ហើយផ្លាស់ប្ដូររាល់ពេលអ្នកចាប់ផ្ដើម ngrok ឡើងវិញ លុះត្រាតែអ្នកមានការជាវបង់ប្រាក់ដែលគាំទ្រដែនរងផ្ទាល់ខ្លួន។ សូមប្រាកដថាអ្នកធ្វើបច្ចុប្បន្នភាព endpoint ក្នុង Zealy រាល់ពេលអ្នកចាប់ផ្ដើម ngrok ឡើងវិញ។

ដោយអនុវត្តតាមជំហានទាំងនេះ អ្នកអាចសាកល្បង និងដោះស្រាយកំហុស endpoint ផ្ទាល់ខ្លួនរបស់អ្នកបានយ៉ាងងាយស្រួលនៅក្នុងបរិស្ថានអភិវឌ្ឍន៍មូលដ្ឋាន មុនពេលដាក់ឱ្យដំណើរការនៅលើម៉ាស៊ីនមេផលិតកម្ម។

ការរួមបញ្ចូល Zealy Connect

នៅពេលប្រើ Zealy Connect យើងនឹងបញ្ជូនអ្នកប្រើប្រាស់ទៅ URL ដែលបានបញ្ជាក់ក្នុងអំឡុងពេលដំឡើងភារកិច្ច។ យើងនឹងបញ្ចូល query params ដូចខាងក្រោម៖

• zealyUserId៖ អត្តសញ្ញាណតែមួយគត់សម្រាប់អ្នកប្រើប្រាស់នៅក្នុងប្រព័ន្ធ Zealy ដែលប្រើដើម្បីភ្ជាប់ពួកគេជាមួយវេទិការបស់អ្នក។
• callback៖ URL សម្រាប់បញ្ជូនអ្នកប្រើប្រាស់ត្រឡប់មកវិញបន្ទាប់ពីការផ្ទៀងផ្ទាត់អត្តសញ្ញាណបានបញ្ចប់ ដើម្បីឱ្យពួកគេអាចទាមទារភារកិច្ចបាន។
• signature៖ hash 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 នៃវេទិការបស់អ្នក ដើម្បីឱ្យយើងអាចឱ្យអ្នកប្រើប្រាស់ទាមទារកិច្ចការ ដោយប្រើប៉ារ៉ាម៉ែត្រ query callback ដែលយើងផ្តល់ជូន។ អ្នកក៏ត្រូវបង្កើតហត្ថលេខាផងដែរ ដើម្បីឱ្យយើងអាចផ្ទៀងផ្ទាត់ថាការហៅមកពីអ្នក ហើយមិនត្រូវបានកែប្រែ។ សូមមើលឧទាហរណ៍ខាងក្រោម៖

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 នៃវេទិការបស់អ្នក ដើម្បីឱ្យយើងអាចផ្ញើវាជាផ្នែកនៃតួ API task។

ឥឡូវនេះអ្នកប្រើប្រាស់នឹងអាចទាមទារកិច្ចការនេះ និងកិច្ចការផ្សេងទៀតដែលប្រើ Zealy Connect ជាមួយ redirect URL ដូចគ្នា។ យើងនឹងចងចាំរឿងនេះ ដើម្បីឱ្យអ្នកប្រើប្រាស់មិនចាំបាច់ភ្ជាប់សម្រាប់កិច្ចការនីមួយៗ។

ប្រសិនបើអ្នកត្រូវការលុបការភ្ជាប់ Zealy Connect របស់អ្នកប្រើប្រាស់ អ្នកអាចប្រើ ផ្លូវ API លុប Zealy Connect សម្រាប់សមាជិក. ផ្លូវនេះអនុញ្ញាតឱ្យអ្នកដកការភ្ជាប់ Zealy Connect សម្រាប់សមាជិកជាក់លាក់មួយ។ បន្ទាប់ពីហៅផ្លូវនេះ អ្នកប្រើប្រាស់នឹងត្រូវភ្ជាប់គណនីរបស់ពួកគេឡើងវិញ ដើម្បីប្រើមុខងារ Zealy Connect ម្តងទៀត។

សំណួរញឹកញាប់