Jak połączyć Bubble z Easytools - przewodnik krok po kroku
Obejrzyj tutorial o łączeniu Bubble z Easytools przygotowany przez Chrisa Rapacza, założyciela Sendby.io. Chris pokazuje w nim, jak zintegrował swoją aplikację Bubble z Easytools, aby przyjmować płatności i skutecznie zarządzać subskrypcjami oraz dostępem użytkowników.
Poniżej znajdziesz też opis z wszystkimi linkami i szczegółami, o których Chris wspomina w wideo.
1. Przygotuj bazę danych w Bubble
W typie danych User potrzebujesz kilku pól niestandardowych do śledzenia subskrypcji:
- easytools_customer_id - przypisywane po udanej transakcji
- renewal_date
- subscribed - najważniejsze; steruje dostępem
- subscription_date
- subscription_one_time
- subscription_type - np. „monthly”, „lifetime”
- trial_ends_at
Uwaga: kluczowe jest pole subscribed. Jeśli ma wartość yes, użytkownik może korzystać z aplikacji. Jeśli no - przekierujesz go do Easytools, aby wykupił subskrypcję.
2. Poznaj webhooki Easytools
Easytools wysyła różne typy webhooków, m.in.:
- subscription_created lub single_product_bought
- product_assigned
Każdy webhook ma inną strukturę JSON. Wszystkie zdarzenia trafiają na jeden adres URL, więc routing musisz obsłużyć w backendowym workflow w Bubble.
Pełną listę zdarzeń webhooków Easytools znajdziesz tutaj.
3. Skonfiguruj adres webhooka
W Easytools przejdź do Ustawienia API i webhooków i ustaw swój Webhook URL:
- easy_payments → nazwa Twojego backendowego workflow w Bubble
- api_token → wygenerujesz go w Bubble w Settings > API > Generate private key
Upewnij się, że używasz właściwej wersji adresu:
- Wersja deweloperska: zawiera version-test
- Wersja live: bez version-test
4. Dodaj weryfikację webhooka (opcjonalna, ale mocno zalecana)
Aby zabezpieczyć webhooka:
- Wygeneruj klucz podpisujący (Webhook Signing Key) w Easytools.
- Użyj wtyczki Toolbox w Bubble.
- W backendowym workflow (easy_payments) dodaj krok Server Script.
- Wklej klucz podpisujący i porównaj obliczony hash z nagłówkiem x-webhook-signature od Easytools.
Jeśli wartości się zgadzają, kontynuuj workflow. Jeśli nie - natychmiast go przerwij.
Uwaga: klucza podpisującego nie zobaczysz ponownie po wygenerowaniu, więc zapisz go w bezpiecznym miejscu.
5. Rozdziel zdarzenia webhooka na pod-workflow
Użyj głównego webhooka (easy_payments) jako routera. W zależności od typu zdarzenia przekieruj je do konkretnych backendowych workflow.
Przykłady:
- process_product_assigned
- process_subscription_expired
Publiczny powinien być tylko główny webhook. Pod-workflow zostaw prywatne.
6. Skonfiguruj pod-workflow
Dla process_product_assigned:
- Włącz „Ignore privacy rules”
- Ręcznie zdefiniuj parametry przyjmowane z webhooka:
- subscription_type
- subscription_one_time
- is_subscription
- price
- custom_id
- itd.
Kroki:
- (Opcjonalnie) Wyślij do siebie maila testowego.
- Zaktualizuj pasującego użytkownika w bazie:
- Ustaw subscribed = yes, jeśli subskrypcja jest aktywna.
- Zaktualizuj pozostałe pola, np. subscription_type, renewal_date, trial_ends_at.
- Użyj logiki warunkowej:
- Jeśli subscription_one_time = yes → subscribed = yes
- Jeśli subscription_one_time i is_subscription są no → subscribed = no
Dla process_subscription_expired:
- Zaktualizuj użytkownika:
- Ustaw subscribed = no
- Ustaw access_expired = yes
- Opcjonalnie wyślij do siebie maila z powiadomieniem
7. Obsłuż różne formaty JSON
Bubble oczekuje jednej, spójnej struktury JSON, a Easytools wysyła różne - w zależności od zdarzenia.
Aby to rozwiązać:
- Skopiuj wszystkie przykładowe JSON-y z dokumentacji Easytools.
- Połącz je w jeden wspólny JSON.
- Przejdź do workflow easy_payments w Bubble i kliknij „Detect data”.
- Wyślij połączony JSON przez Postmana:
- Metoda: POST
- Wklej adres webhooka
- Body: raw JSON
- Bubble rozpozna strukturę. Sprawdź typ każdego pola (np. number, text, date).
Gotowy, połączony plik JSON
Oto połączony schemat JSON przygotowany przez Chrisa - zawiera wszystkie klucze ze wszystkich zdarzeń webhooków Easytools. Możesz go użyć podczas wykrywania struktury w Bubble, aby poprawnie zainicjować endpoint webhooka.
Użyj tego pliku, wysyłając przez Postmana testowe żądanie do Bubble w kroku „Detect data”. Dzięki temu Bubble wychwyci każde możliwe pole ze wszystkich zdarzeń webhooków Easytools.
Aby użyć pliku:
- Otwórz załączony plik easytools_merged_webhook.json.
- Skopiuj jego zawartość do raw body żądania w Postmanie.
- Wyślij żądanie POST na adres wykrywania webhooka w Bubble.
Po wysłaniu:
- Bubble wyświetli wszystkie wykryte pola.
- Przejrzyj je i potwierdź, że typy danych się zgadzają:
- Daty powinny mieć typ date.
- Liczby - number.
- Pola tekstowe - text.
Gdy wszystko się zgadza, kliknij Save w Bubble, aby zakończyć konfigurację webhooka.
8. Dopasuj użytkowników po adresie email
Aby webhook trafił do właściwego użytkownika:
- Niech użytkownicy najpierw zakładają konto w Twojej aplikacji.
- Wstępnie uzupełnij formularz koszyka Easytools adresem Current User’s email.
- W workflow webhooka wyszukaj użytkownika przez:
Search for Users where email = request.body.customer_email
Jeśli adresy się nie zgadzają, Bubble nie przypisze zakupu do użytkownika. Zadbaj o spójność adresów email od samego początku.
9. Przetestuj cały proces
- Ustaw testowemu użytkownikowi pole subscribed na no w bazie Bubble.
- Spróbuj wejść w chronioną funkcję → użytkownik zostaje przekierowany do koszyka Easytools.
- Wykonaj płatność testową.
- Wróć do Bubble:
- Webhook został odebrany i zweryfikowany
- Pole subscribed użytkownika zostało zaktualizowane
- Aplikacja to wykrywa i odblokowuje dostęp
Uwaga: przetworzenie webhooka trwa zwykle 8-10 sekund.
Możesz:
- Dodać 20-sekundowe opóźnienie w przekierowaniu Easytools
- Pokazać ekran „przetwarzanie” i sprawdzać, aż subscribed = yes
Uwagi końcowe
- Backendowe workflow w Bubble są dostępne tylko w płatnych planach.
- Zawsze testuj zarówno płatności jednorazowe, jak i subskrypcje.
- Zadbaj o bezpieczeństwo logiki webhooków, zwłaszcza przy obsłudze płatności.