API

Genel Bakış

Bu kılavuz API görevi hakkındadır. Tam API belgelerimizi burada bulabilirsiniz burada.

API görevleri, harici platformlardaki görevleri otomatikleştirmek için kullanılır. Kullanıcının kayıt olup olmadığını veya bir satın alma yapıp yapmadığını, Github'da bir sorun için PR açıp açmadığını onaylamak veya Reddit desteği eklemek için kullanabilirsiniz. Olasılıklar sonsuzdur. Başlamak ve işlevselliği denemek için, diğer Zealy topluluklarıyla ortaklık yapmak üzere kullanabileceğiniz temel bir uç nokta sunuyoruz. Nasıl kurulacağı hakkında daha fazla bilgiyi aşağıda bulabilirsiniz.

Temel Bilgiler

Bir "API" Görevi Oluşturma

1. Tıklayın 'Görev ekle'.
2. Seçin 'Api'.
3. Çağrılacak uç noktayı ve gerekirse bir API anahtarı tanımlayın.
4. Kullanıcıların nasıl tanımlanacağını seçin. Şunlardan seçim yapabilirsiniz: E-posta, Twitter, Discord, Cüzdan adresi veya Zealy Connect.

• Eğer cüzdan bağlantısı seçerseniz, hangi ağın kullanılacağını da seçebilirsiniz.

• Eğer Zealy Connect seçerseniz, şu adımları izleyin:

  1. Yönlendirme URL'sini tanımlayın: Bu URL kimlik doğrulama için kullanılacaktır. Kullanıcıları sisteminizde kimlik doğrulamaları için bu URL'ye yönlendireceğiz.

  

  2. Bir topluluk sırrı oluşturun: Zealy Connect'in çalışması için bir topluluk sırrı oluşturmak gereklidir. Sırrı, topluluk ayarlarınızdaki Zealy Connect için oluşturabilirsiniz. Zealy Connect ayarları altındaki Entegrasyonlar bölümü içinden oluşturabilirsiniz.

  

API'lerin nasıl çalışması beklendiği hakkında ayrıntılı bilgi için lütfen API belgelerine bakın ve Zealy Connect yönetimi hakkında rehberlik için lütfen Zealy Connect belgelerine.

Domino ile Entegrasyon

Domino, Web3 Zapier'dir. Zealy'nin yeteneklerini genişletmenize ve yerel olarak desteklenmeyen görevleri otomatik olarak incelemenize olanak tanır, örneğin:

• Bir kullanıcının Twitter adının veya biyografisinin belirli bir kelime içerip içermediğini kontrol etme
• Bir kullanıcının NFT ve token bakiyesini kontrol etme
• Bir kullanıcının Discord'da belirli sayıda kişiyi davet ettiğini doğrulama
• Ve daha fazlası

Entegrasyon için belgelerine göz atın.

Uç nokta testi

Uç noktayı yapılandırırken, uç noktanın beklendiği gibi çalıştığından emin olmak için otomatik olarak aşağıdaki testleri çalıştıracağız:

1. Çağrının 10 saniyeden uzun sürmediğini kontrol etme
2. Hata mesajının doğru formatta olduğunu ve kullanıcıya gösterebileceğimiz şekilde olduğunu doğrulama
3. Beklenmeyen durum kodlarından herhangi biri olmadığından emin olma. Uç nokta yalnızca 200 veya 400 döndürmelidir.

Özel bir uç nokta oluşturma

İstek

API görevlerini, aşağıdaki gövdeyi kabul eden özel bir POST uç nokta ile kullanabilirsiniz:

{
  /**
   * 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
  };
}

Görev oluşturulurken ayarlanan bir API anahtarı ile koruyabilirsiniz. API anahtarı başlıklarda şu şekilde gönderilecektir:

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

Yanıt

Eylem kullanıcı tarafından başarıyla gerçekleştirildiyse, bir 200 durumu döndürmelisiniz. Kullanıcı daha sonra görevi başarıyla talep edecektir.

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

Aksi takdirde, yanıtla birlikte gövdede bir mesaj ile 400 durumu döndürülmelidir. Mesaj, sizin ve kullanıcının sorunları ayıklamasına yardımcı olmak için oluşturulan requestId ile birlikte görüntülenecektir. Mümkün olduğunca açıklayıcı olduğundan emin olun.

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

Kod örneği

// 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 ile yerel test

Özel uç noktanızı yerel olarak geliştirirken ve test ederken, Zealy'nin API istekleri gönderebilmesi için yerel sunucunuzu internete açmanın bir yoluna ihtiyacınız vardır. ngrok, localhost'a güvenli tüneller oluşturan bir araçtır ve bu amaç için mükemmeldir. ngrok'u kurmak ve uç noktanızı test etmek için şu adımları izleyin:

Adım 1: ngrok'u yükleyin ngrok'u ngrok'un web sitesinden indirin. İşletim sisteminiz için kurulum talimatlarını izleyin.

Adım 2: ngrok'u ayarlayın Ücretsiz bir ngrok hesabına kaydolun ve ngrok kontrol panelinden authtoken'ınızı alın. Terminalinizde ngrok authtoken YOUR_AUTH_TOKEN komutunu çalıştırarak ngrok hesabınızı bağlayın, YOUR_AUTH_TOKEN'ı ngrok kontrol panelinizdeki token ile değiştirin.

Adım 3: Yerel sunucunuzu başlatın Uç noktayı barındıran yerel sunucunuzun çalıştığından emin olun. Örneğin, sunucunuz bir Node.js uygulamasıysa, node server.js komutunu çalıştırabilirsiniz.

Adım 4: Yerel sunucunuzu ngrok ile açın Yeni bir terminal penceresi açın ve yerel sunucunuzun portuna (örneğin, 3000) bir ngrok tüneli başlatın: ngrok http http://127.0.0.1:3000. ngrok terminalde bir yönlendirme URL'si gösterecektir (örneğin, https://abc123.ngrok.io). Bu, Zealy'nin yerel sunucunuza ulaşmak için kullanacağı genel URL'dir.

Adım 5: Zealy'de API görevinizi yapılandırın Zealy'de API görevinizi ayarlarken uç nokta URL'si olarak ngrok yönlendirme URL'sini kullanın. Gerekli yolu eklediğinizden emin olun, örneğin, https://abc123.ngrok.io/claim.

Not: Unutmayın, ngrok URL'leri geçicidir ve özel alt alan adlarını destekleyen ücretli bir aboneliğiniz yoksa ngrok'u her yeniden başlattığınızda değişir. ngrok'u her yeniden başlattığınızda Zealy'deki uç noktayı güncellediğinizden emin olun.

Bu adımları izleyerek, özel uç noktanızı üretim sunucusuna dağıtmadan önce yerel bir geliştirme ortamında kolayca test edebilir ve hata ayıklayabilirsiniz.

Zealy Connect Entegrasyonu

Zealy Connect kullanırken, kullanıcıyı görev kurulumu sırasında belirtilen URL'ye yönlendireceğiz. Aşağıdaki sorgu parametrelerini ekleyeceğiz:

• zealyUserId: Kullanıcıyı platformunuzla ilişkilendirmek için kullanılan Zealy sistemindeki benzersiz tanımlayıcı.
• callback: Kimlik doğrulama tamamlandıktan sonra kullanıcıyı görevi talep edebilmesi için geri yönlendirilecek URL.
• signature: İsteğin gerçekliğini doğrulamak ve Zealy'den geldiğinden emin olmak için kullanılan SHA-256 karması.

Başlangıç noktası olarak kullanabileceğiniz tam bir örnek uç nokta:

 
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. İmzayı Doğrulayın

Uygulamanızın yapması gereken ilk şey, topluluk sırrınızı kullanarak imzayı doğrulamaktır. Bu doğrulama, çağrının gerçekten bizden geldiğinden ve değiştirilmediğinden emin olur.

İmzayı oluşturmak için SHA256 hash algoritmasını kullanıyoruz. Doğrulamak için aşağıdaki yaklaşımı kullanabilirsiniz:

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 Kullanıcı Kimliğini kullanın

Sonraki adım ne yapmak istediğinize bağlıdır, ancak müşteriler genellikle mevcut kullanıcıyı platformunuzda oturum açtırır ve platformunuzun kullanıcı kimliğini Zealy Kullanıcı Kimliği ile ilişkilendirir. Aşağıda bir örnek verilmiştir:

  /**
   * 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'ye Geri Yönlendirin

Son adım, kullanıcının görevi talep etmesine izin verebilmemiz için kullanıcıyı sağladığımız callback sorgu parametresini kullanarak platformunuzun kullanıcı kimliğiyle Zealy'ye geri yönlendirmektir. Ayrıca çağrının sizden geldiğini ve değiştirilmediğini doğrulayabilmemiz için bir imza oluşturmanız gerekir. Aşağıdaki örneğe bakın:

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'i aldığımızda imzayı doğrular ve platformunuzun kullanıcı kimliğini saklarız, böylece bunu API görev gövdesinin bir parçası olarak gönderebiliriz.

Kullanıcı artık görevi ve aynı yönlendirme URL'sini kullanan Zealy Connect kullanan diğer görevleri talep edebilecektir. Kullanıcının her görev için bağlanması gerekmemesi için bunu hatırlayacağız.

Bir kullanıcının Zealy Connect ilişkilendirmesini silmeniz gerekirse, Üye API rotası için Zealy Connect'i Silrotasını kullanabilirsiniz. Bu rota, belirli bir üye için Zealy Connect ilişkilendirmesini kaldırmanıza olanak tanır. Bu rotayı çağırdıktan sonra kullanıcının Zealy Connect özelliklerini tekrar kullanabilmesi için hesabını yeniden bağlaması gerekecektir.

SSS