API

Przegląd

Ten przewodnik dotyczy zadania API. Pełną dokumentację API znajdziesz tutaj.

Zadania API służą do automatyzacji zadań na zewnętrznych platformach. Możesz ich użyć, aby potwierdzić, że użytkownik zarejestrował się lub dokonał zakupu, otworzył PR do zgłoszenia na Githubie lub dodał wsparcie Reddit. Możliwości są nieograniczone. Aby zacząć i wypróbować funkcjonalność, oferujemy podstawowy endpoint, którego możesz użyć do nawiązania partnerstw z innymi społecznościami Zealy. Dowiedz się więcej o tym, jak go skonfigurować poniżej.

Podstawy

Tworzenie zadania "API"

1. Kliknij 'Dodaj zadanie'.
2. Wybierz 'Api'.
3. Zdefiniuj punkt końcowy do wywołania i klucz API, jeśli to konieczne.
4. Wybierz, jak użytkownicy mogą się identyfikować. Możesz wybrać spośród Email, Twitter, Discord, Adres portfela, lub Zealy Connect.

• Jeśli wybierzesz połączenie z portfelem, możesz także wybrać sieć do użycia.

• Jeśli wybierzesz Zealy Connect, wykonaj następujące kroki:

  1. Zdefiniuj adres URL przekierowania: Ten adres URL będzie używany do uwierzytelniania. Przekierujemy użytkowników na ten adres URL, aby uwierzytelnili się w Twoim systemie.

  

  2. Wygeneruj sekret społeczności: Wygenerowanie sekretu społeczności jest wymagane do Zealy Connect do działania. Możesz utworzyć sekret w Ustawienia Zealy Connect w sekcji Integracje w ustawieniach swojej społeczności.

  

Aby uzyskać szczegółowe informacje o tym, jak powinny działać interfejsy API, zobacz Dokumentacja API a wskazówki dotyczące zarządzania Zealy Connect znajdziesz w Dokumentacja Zealy Connect.

Integracja z Domino

Domino to Zapier Web3. Pozwala rozszerzyć możliwości Zealy i automatycznie weryfikować zadania, które nie są obsługiwane natywnie, takie jak:

• Sprawdzanie, czy nazwa lub bio użytkownika na Twitterze zawiera określone słowo
• Sprawdzanie salda NFT i tokenów użytkownika
• Weryfikacja, czy użytkownik zaprosił określoną liczbę osób na Discordzie
• I wiele więcej

Sprawdź ich dokumentację dotyczącą integracji.

Testowanie endpointu

Podczas konfigurowania endpointu automatycznie uruchomimy następujące testy, aby upewnić się, że endpoint działa zgodnie z oczekiwaniami:

1. Sprawdzanie, czy wywołanie nie trwa dłużej niż 10 sekund
2. Weryfikacja, czy komunikat o błędzie ma prawidłowy format, abyśmy mogli go wyświetlić użytkownikowi
3. Upewnij się, że nie jest to żaden z nieoczekiwanych kodów statusu. Endpoint powinien zwracać tylko 200 lub 400.

Tworzenie niestandardowego endpointu

Żądanie

Możesz używać zadań API z niestandardowym POST endpointem akceptującym następujące body:

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

Możesz go zabezpieczyć kluczem API ustawianym podczas tworzenia zadania. Klucz API będzie wysyłany w nagłówkach w ten sposób:

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

Odpowiedź

Jeśli akcja została pomyślnie wykonana przez użytkownika, powinieneś zwrócić 200 status. Użytkownik pomyślnie zgłosi zadanie.

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

W przeciwnym razie 400 status powinien zostać zwrócony w odpowiedzi wraz z komunikatem w treści. Komunikat zostanie wyświetlony z wygenerowanym requestId aby pomóc Tobie i użytkownikowi w debugowaniu problemów. Upewnij się, że jest jak najbardziej opisowy.

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

Przykład kodu

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

Testowanie lokalne z ngrok

Podczas tworzenia i testowania własnego endpointu lokalnie potrzebujesz sposobu na udostępnienie lokalnego serwera w internecie, aby Zealy mógł wysyłać do niego żądania API. ngrok to narzędzie tworzące bezpieczne tunele do localhost i idealnie nadaje się do tego celu. Wykonaj poniższe kroki, aby skonfigurować ngrok i przetestować endpoint:

Krok 1: Zainstaluj ngrok Pobierz ngrok ze strony ngrok. Postępuj zgodnie z instrukcjami instalacji dla swojego systemu operacyjnego.

Krok 2: Skonfiguruj ngrok Załóż darmowe konto ngrok i pobierz swój authtoken z panelu ngrok. Połącz swoje konto ngrok, uruchamiając w terminalu ngrok authtoken YOUR_AUTH_TOKEN, zastępując YOUR_AUTH_TOKEN tokenem z panelu ngrok.

Krok 3: Uruchom serwer lokalny Upewnij się, że serwer lokalny hostujący endpoint działa. Na przykład, jeśli serwer to aplikacja Node.js, możesz uruchomić node server.js.

Krok 4: Udostępnij serwer lokalny przez ngrok Otwórz nowe okno terminala i uruchom tunel ngrok do portu serwera lokalnego (np. 3000) za pomocą ngrok http http://127.0.0.1:3000. ngrok wyświetli w terminalu adres URL przekierowania (np. https://abc123.ngrok.io). To publiczny adres URL, którego Zealy użyje do połączenia z Twoim serwerem lokalnym.

Krok 5: Skonfiguruj zadanie API w Zealy Użyj adresu URL przekierowania ngrok jako adresu URL endpointu podczas konfigurowania zadania API w Zealy. Pamiętaj, aby dołączyć wymaganą ścieżkę, na przykład https://abc123.ngrok.io/claim.

Uwaga: Pamiętaj, że adresy URL ngrok są tymczasowe i zmieniają się przy każdym ponownym uruchomieniu ngrok, chyba że masz płatną subskrypcję obsługującą niestandardowe subdomeny. Pamiętaj, aby aktualizować endpoint w Zealy przy każdym ponownym uruchomieniu ngrok.

Wykonując te kroki, możesz łatwo testować i debugować swój niestandardowy endpoint w lokalnym środowisku programistycznym przed wdrożeniem go na serwer produkcyjny.

Integracja Zealy Connect

Podczas korzystania z Zealy Connect przekierujemy użytkownika na adres URL podany podczas konfiguracji zadania. Dołączymy następujące parametry zapytania:

• zealyUserId: Unikalny identyfikator użytkownika w systemie Zealy, używany do powiązania go z Twoją platformą.
• callback: Adres URL, na który użytkownik zostanie przekierowany po zakończeniu uwierzytelniania, aby mógł odebrać zadanie.
• signature: Skrót SHA-256 używany do weryfikacji autentyczności żądania, potwierdzający, że pochodzi ono z Zealy.

Oto pełny przykładowy endpoint, którego możesz użyć jako punktu wyjścia:

 
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. Zweryfikuj podpis

Pierwszą rzeczą, którą powinna zrobić Twoja aplikacja, jest weryfikacja podpisu przy użyciu Twojego sekretu społeczności. Ta weryfikacja zapewnia, że wywołanie rzeczywiście pochodzi od nas i nie zostało zmodyfikowane.

Używamy algorytmu skrótu SHA256 do generowania podpisu. Aby go zweryfikować, możesz użyć następującego podejścia:

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. Użyj Zealy User ID

Następny krok zależy od tego, co chcesz zrobić, ale klienci zwykle logują bieżącego użytkownika na swojej platformie i łączą identyfikator użytkownika swojej platformy z Zealy User ID. Poniżej znajduje się przykład:

  /**
   * 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. Przekieruj z powrotem do Zealy

Ostatnim krokiem jest przekierowanie użytkownika z powrotem do Zealy z identyfikatorem użytkownika Twojej platformy, abyśmy mogli umożliwić użytkownikowi odebranie zadania, używając parametru zapytania callback, który udostępniamy. Musisz także wygenerować podpis, abyśmy mogli zweryfikować, że wywołanie pochodzi od Ciebie i nie zostało zmodyfikowane. Zobacz przykład poniżej:

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

Po otrzymaniu callback zweryfikujemy podpis i zapiszemy identyfikator użytkownika Twojej platformy, abyśmy mogli go wysłać jako część treści zadania API.

Użytkownik będzie teraz mógł odebrać zadanie oraz każde inne zadanie, które korzysta z Zealy Connect z tym samym adresem URL przekierowania. Zapamiętamy to, aby użytkownik nie musiał łączyć się przy każdym zadaniu.

Jeśli chcesz usunąć powiązanie Zealy Connect użytkownika, możesz użyć Trasa API Delete Zealy Connect for Member. Ta trasa pozwala usunąć powiązanie Zealy Connect dla konkretnego członka. Po wywołaniu tej trasy użytkownik będzie musiał ponownie połączyć swoje konto, aby korzystać z funkcji Zealy Connect.

FAQ