10 gru 2025·7 min
Projekt katalogu integracji, który skaluje się od 3 do 30 aplikacji
Zaprojektuj katalog integracji skalowalny od 3 do 30 integracji z prostym modelem danych, czytelnymi statusami, uprawnieniami i UI postępu konfiguracji.
Zaprojektuj katalog integracji skalowalny od 3 do 30 integracji z prostym modelem danych, czytelnymi statusami, uprawnieniami i UI postępu konfiguracji.
Ludzie otwierają katalog integracji z jednego powodu: żeby połączyć narzędzia i utrzymać je działające bez codziennego myślenia. Jeśli ekran każe użytkownikom zgadywać, co jest połączone, co jest zepsute albo co kliknąć dalej, zaufanie szybko spada.
Przy 3 integracjach prosta siatka logotypów może działać. Przy 30 to się rozpada: ludzie przestają skanować, liczba zgłoszeń do supportu rośnie, a przycisk „Connect” staje się pułapką, bo każda integracja może być w innym stanie.
Każda karta integracji (lub wiersz) powinna odpowiadać na trzy pytania na pierwszy rzut oka:
Większość nieporozumień bierze się z przypadków brzegowych, które występują cały czas w zespołach. Ktoś łączy Google z kontem prywatnym zamiast firmowego. Token Stripe wygasa i płatności przestają się synchronizować. Workspace Slacka jest podłączony, ale nigdy nie nadano zakresu wymaganego dla kanału, więc konfiguracja jest „pół gotowa”, choć UI wygląda poprawnie.
Dobry ekran czyni te sytuacje oczywistymi. Zamiast po prostu „Connected”, pokaż np. „Connected (potrzebne uprawnienia)” lub „Connected to: [email protected]” i umieść kolejne kroki bezpośrednio na karcie. To trzyma ludzi z dala od zgadywania i utrzymuje listę w ryzach, gdy rośnie.
Najprostszy sposób na skalowanie katalogu integracji to rozdzielenie:
To pozostaje czytelne przy 3 integracjach i działa również przy 30.
Integration to wpis w katalogu. Jest globalny, nie powiązany z konkretnym workspace.
Install reprezentuje włączenie danej Integration w workspace (np. „Slack jest włączony dla Workspace A”).
Connection reprezentuje faktyczne zewnętrzne konto lub poświadczenie (np. „workspace Slack X przez OAuth” albo „konto Stripe Y przez klucz API”). Jedna Install może mieć wiele Connections.
Minimalny zestaw pól, który dobrze skaluje:
Przechowuj widoczne dla użytkownika ustawienia (wybrany kanał, alias URL webhooka, włączone zdarzenia) na Install lub Connection jako zwykłe dane. Sekrety (refresh tokeny OAuth, klucze API, signing secrets) trzymaj wyłącznie w magazynie sekretów lub w zaszyfrowanym polu z restrykcyjnymi kontrolami dostępu.
Nie umieszczaj sekretów, pełnych kodów autoryzacyjnych ani surowych payloadów webhooków w logach. Jeśli musisz coś logować, zapisuj odniesienia (connection_id) oraz bezpieczne metadane (HTTP status, kod błędu).
Aby pozostać elastycznym względem OAuth, kluczy API i webhooków, trzymaj pola specyficzne dla autoryzacji wewnątrz Connection (metadane tokena vs odcisk palca klucza vs status weryfikacji webhooka). Stan widoczny w UI (włączone i postęp konfiguracji) trzymaj na Install.
Ludzie otwierają katalog integracji, by szybko odpowiedzieć na trzy rzeczy: czy to działa, jak daleko posunęła się konfiguracja i co powinienem zrobić dalej. Jeśli słowa statusu są niejasne, zgłoszenia do supportu rosną, a zaufanie spada.
Zacznij od małego zestawu statusów, którymi możesz zarządzać latami:
Wol preferować status pochodny zamiast przechowywanego. Przechowywane etykiety dryfują: ktoś naprawia błąd, a odznaka zostaje czerwona. Status pochodny jest obliczany z faktów, które już śledzisz, jak czy tokeny są ważne, czy wymagane kroki konfiguracji są zakończone oraz czy administrator wstrzymał integrację. Jeśli coś przechowujesz, to przechowuj podstawowe fakty (ostatnia udana synchronizacja, ostatni kod błędu), a nie końcową etykietę.
Postęp konfiguracji najlepiej działa jako krótka lista kontrolna, z wyraźnym podziałem na wymagane i opcjonalne. Modeluj ją jako definicje kroków (statyczne, per integration) plus wyniki kroków (per install).
Przykład: Slack może wymagać „Authorize workspace” i „Select channels”, z opcjonalnym krokiem „Enable message previews”. UI może pokazać „2 z 3 wymaganych kroków ukończone”, jednocześnie utrzymując opcjonalne elementy widoczne bez blokowania.
Wiele połączeń pod jedną integracją może zamienić katalog w bałagan, jeśli tego nie zaplanujesz. Trzymaj jedną kartę na integrację, pokaż liczbę połączeń i zwijaj status uczciwie. Jeśli choć jedno połączenie jest uszkodzone, pokaż „Needs attention” z informacją typu „1 z 4 workspace’ów wymaga ponownej autoryzacji”. Przegląd pozostaje czytelny, ale odzwierciedla rzeczywistość.
Uprawnienia integracji robią się złożone, gdy wszystko traktuje się jako jeden przełącznik. Klarowniej jest oddzielić:
Zacznij od lekkiego sprawdzenia roli, które działa wszędzie. Dla wielu aplikacji trzy role wystarczą: Admin, Manager i Member. Admini mogą wszystko. Managerowie mogą skonfigurować większość integracji dla swojego zespołu. Członkowie mogą korzystać z już włączonych integracji, ale nie mogą zmieniać ustawień.
Dodawaj flagi uprawnień per integration tylko tam, gdzie to ma znaczenie. Większość integracji (kalendarze, czat) może trzymać się domyślnych reguł ról. Wrażliwe (płatności, kadry, exporty) powinny wymagać dodatkowego sprawdzenia, np. „Payments admin” lub „Billing manager”. Trzymaj to jako prosty boolean na install, a nie nowy system ról.
Mapa, która pozostaje czytelna:
Audyt nie musi być ciężki, ale powinien istnieć. Śledź wystarczająco, by szybko odpowiedzieć na pytania supportu i bezpieczeństwa: kto połączył, kiedy zmieniono poświadczenia i kto wyłączył integrację. Panel „Activity” na stronie szczegółów z 5–20 ostatnimi zdarzeniami zwykle wystarcza.
Przykład: Stripe może być widoczny dla wszystkich, ale tylko Admini (lub użytkownicy z rolą „Billing manager”) mogą go podłączyć, rotować klucze lub wyłączyć wypłaty. Slack może pozwalać Managerom na podłączenie, podczas gdy Członkowie nadal otrzymują powiadomienia po włączeniu.
Przy 3 integracjach możesz pokazać wszystko. Przy 30 katalog musi szybko odpowiadać na jedno pytanie: „Które działają i co powinienem zrobić dalej?”. Najczystsze podejście to oddzielenie skanowania od działania.
Trzymaj widok katalogu skupiony na szybkich decyzjach. Cięższe sterowanie przenieś na stronę szczegółów za jednym przyciskiem „Manage”.
Na liście pokaż tylko to, co wspiera następne kliknięcie:
Anatomia karty ma znaczenie, bo buduje nawyk. Akcja główna zawsze powinna znaczyć „następny krok” w zależności od stanu: Connect dla nowych, Continue setup dla częściowo skonfigurowanych, Reconnect gdy auth wygasł i Manage gdy wszystko jest zdrowe. Unikaj dwóch równie agresywnych przycisków na każdej karcie — sprawiają, że strona jest hałaśliwa.
Przykłady:
Stany pustego widoku powinny prowadzić, bez rzucania podręcznika na ekran:
To utrzymuje spokój na stronie przy 30 integracjach, bo każda karta odpowiada: co to jest, czy działa i co teraz.
Lista katalogu prowadzi ludzi do właściwej integracji. Strona szczegółów to miejsce, gdzie podejmują decyzję: skonfigurować, naprawić czy wyłączyć. Zachowaj spójną strukturę strony dla każdej integracji, nawet jeśli backend różni się pracą.
Zacznij od zwartego przeglądu: nazwa integracji, jednolinijkowy opis i czytelne etykiety statusu (Connected, Needs attention, Disabled). Dodaj mały pasek „Setup progress”, żeby użytkownik wiedział, czy jest o krok od zakończenia, czy dopiero na początku.
Prosty kreator świetnie się sprawdza: 3–6 kroków, jeden ekran na raz, z zawsze dostępnym „Back”. Nazwij kroki prostym językiem (Połącz konto, Wybierz workspace, Wybierz dane do synchronizacji, Potwierdź). Jeśli krok ma opcjonalne wybory, oznacz je jako opcjonalne zamiast ukrywać.
Jeśli konfiguracja może być wstrzymana, powiedz to jasno: „Możesz dokończyć później. Zachowamy Twoje wybory.” To zmniejsza lęk przed utratą postępu.
Pokaż Connections jako małą tabelę: nazwa konta, połączone przez (użytkownik), data utworzenia i ostatnia synchronizacja.
Dla „następnej synchronizacji” unikaj obietnic, których nie możesz dotrzymać (dokładnych godzin). Używaj sformułowań, które możesz udźwignąć, np. „Next sync: scheduled soon” lub „Next sync: w ciągu najbliższej godziny”, w zależności od tego, co system naprawdę może zagwarantować.
Trzymaj ryzykowne akcje z dala od głównej ścieżki. Umieść akcje główne na górze (Continue setup, Reconnect). Przenieś Disable i Disconnect do osobnej sekcji „Danger zone” na dole z krótkim wyjaśnieniem skutków. Jeśli wspierasz role, powiedz to jednym zdaniem (np. „Only admins can disconnect”).
Dodaj mały log aktywności: ostatnie zdarzenia (połączono, token odświeżony, synchronizacja nie powiodła się), znaczniki czasu i krótki komunikat błędu, który użytkownik może skopiować do zgłoszenia do supportu.
Dodawanie integracji jest łatwiejsze, gdy traktujesz to jak mały produkt. Potrzebuje wpisu w katalogu, metody połączenia, miejsca do przechowywania połączenia i jasnych rezultatów sukcesu lub porażki.
Dodaj integrację do katalogu, aby pojawiła się w katalogu jeszcze zanim ktoś ją połączy. Uwzględnij jasną nazwę, krótki opis, ikonę i jedną lub dwie kategorie (Messaging, Payments). Napisz oczekiwania konfiguracji prostym językiem, np. „Połącz konto” i „Wybierz workspace”. Tu też definiujesz, czego integracja będzie potrzebować później (zakresy OAuth, wymagane pola, wspierane funkcje).
Wybierz najprostszy sposób połączenia pasujący do dostawcy:
Gdy użytkownik zakończy flow, stwórz Connection powiązane z workspace lub kontem, a nie tylko z użytkownikiem. Przechowuj poświadczenia bezpiecznie (szyfruj dane i unikaj ponownego pokazywania pełnego sekretu). Zapisz podstawy potrzebne do wsparcia: ID konta u dostawcy, czas utworzenia, kto połączył i jakie uprawnienia zostały przyznane.
Uruchom prosty test od razu (dla Stripe: pobierz szczegóły konta). Jeśli przejdzie, pokaż Connected i oznacz postęp jako ukończony. Jeśli częściowo przejdzie (połączono, ale brakuje uprawnień), oznacz Needs attention i skieruj do dokładnej naprawy.
Pokaż jeden jasny komunikat, jedną zalecaną akcję i bezpieczny fallback. Na przykład: „Nie udało się połączyć ze Stripe. Sprawdź klucz API lub spróbuj ponownie.” Utrzymuj katalog użyteczny nawet przy jednej uszkodzonej integracji.
Jeśli budujesz na Koder.ai (koder.ai), możesz najpierw opracować katalog, flow konfiguracji i reguły statusów w Planning Mode, a potem wygenerować UI i backend z tego planu.
Integracje zawodzą z nudnych powodów. Jeśli katalog nie potrafi wyjaśnić tych powodów jasno, użytkownicy obwiniają twoją aplikację, a support nie ma nic do roboty.
Grupuj awarie w kubełki odpowiadające realnym naprawom: wygasłe logowanie, brak uprawnień, awaria dostawcy lub limit zapytań. Wewnętrzne kody błędów trzymaj szczegółowe, ale użytkownikom pokazuj krótką, zrozumiałą etykietę.
Gdy coś się psuje, komunikat powinien odpowiedzieć na trzy rzeczy: co się stało, co użytkownik powinien zrobić i co system zrobi dalej. Przykład: „Połączenie Slack wygasło. Ponownie autoryzuj, aby kontynuować synchronizację. Będziemy automatycznie retryować po twojej ponownej autoryzacji.” To jest spokojniejsze i bardziej użyteczne niż surowy błąd z API.
Auto-retry tylko wtedy, gdy użytkownik nie może tego naprawić sam. Prosty zestaw reguł wystarczy:
Statusy starzeją się, jeśli ich nie odświeżać. Dodaj lekki job health-check, który okresowo potwierdza, czy tokeny nadal działają, czy ostatnia synchronizacja się odbyła i czy odznaka w katalogu odpowiada rzeczywistości.
Przechowuj krótką historię zdarzeń per install. Nie potrzebujesz pełnych logów, tylko wystarczające breadcrumbs: timestamp, zdarzenie („token refreshed”, „sync failed”), krótka przyczyna i kto to wywołał (użytkownik lub system). Dodaj pole notatek widoczne tylko wewnętrznie, aby support mógł zapisać, co zmienił i dlaczego.
Katalog robi się szybko chaotyczny po przekroczeniu kilku aplikacji. Cel jest prosty: pomóc ludziom znaleźć to, czego potrzebują w kilka sekund i pozwolić im zauważyć problemy bez otwierania każdej karty.
Zacznij od podstawowego wyszukiwania po nazwie integracji i kategorii. Większość użytkowników wpisuje to, co już zna („Slack”, „Stripe”), więc dopasowanie nazw jest ważniejsze niż zaawansowane rankingi. Wyszukiwanie po kategorii pomaga, gdy znają tylko funkcję (payments, messaging).
Filtry powinny odzwierciedlać realne intencje. Te trzy zwykle wystarczają:
Do organizacji listy wybierz jedno główne pogrupowanie i trzymaj się go. Grupowanie po kategorii dobrze działa przy większej liczbie (CRM, Payments, Messaging). Popularność może być przydatna, ale tylko jeśli odzwierciedla twoją bazę użytkowników, a nie marketing. Praktyczny domyślny układ: pokaż najczęściej używane najpierw, a resztę pogrupuj według kategorii.
Potrzebny jest też plan dla „nie każdy powinien widzieć wszystko”. Jeśli integracja jest za feature flagą lub planem taryfowym, albo ją ukryj dla większości użytkowników, albo pokaż jako wyłączoną z krótkim powodem typu „Business plan”. Unikaj ekranu pełnego wyszarzonych kart — wygląda jak błąd.
Utrzymuj wydajność przez rozdzielenie ładowania listy i szczegółów. Paginate lub wirtualizuj listę, aby nie renderować 30 ciężkich kart naraz, i leniwie ładuj szczegóły tylko po otwarciu integracji. Katalog może pokazywać pola streszczenia (Slack: Connected, Google: Needs attention, Stripe: Not set up), podczas gdy strona szczegółów pobiera pełną historię połączeń.
Wyobraź sobie aplikację zespołową o nazwie Pinework. Ma dwie role: Admin i Member. Admini mogą podłączać narzędzia i zmieniać ustawienia. Członkowie mogą używać podłączonych narzędzi, ale nie mogą ich dodawać ani usuwać.
W katalogu integracji Pinework każda karta pokazuje czytelną etykietę (Connected, Needs setup, Error), krótki opis „co robi” oraz postęp konfiguracji jak „2 z 3 kroków”. Ludzie widzą, co działa, a co czeka na dokończenie bez klikania.
Slack służy do powiadomień. Admin otwiera Slack i widzi: Status: Connected, Setup: „3 z 3 kroków.” Członkowie też widzą Slack, ale główna akcja jest zablokowana i brzmi „Poproś Admina o zarządzanie.” Jeśli Slack się rozłączy, Członkowie nadal widzą, co się zepsuło, ale nie mają kontroli do ponownego połączenia.
Google używany jest do kalendarzy. Pinework wspiera dwa działy, więc pozwala na wiele połączeń. Karta Google pokazuje: Status: Connected (2 konta). Pod spodem krótka linia wymienia „Marketing Calendar” i „Support Calendar”. Konfiguracja może być kompletna, a strona szczegółów pokazuje dwa oddzielne Connections, żeby Admin mógł odłączyć tylko jedno z nich.
Stripe służy do bilingów. Typowa częściowa konfiguracja to: konto połączone, ale webhooki nie są ukończone. Karta pokazuje: Status: Needs setup, Progress: „2 z 3 kroków”, z ostrzeżeniem „Płatności mogą nie synchronizować się.” Widok szczegółów precyzuje brakujący krok:
To unika bolesnej sytuacji „wygląda na połączone, ale nic nie działa”.
Katalog integracji zwykle się psuje, gdy aplikacja rośnie od kilku integracji do kilkudziesięciu. Problemy rzadko są „wielkie technologicznie”. To małe błędy w etykietowaniu i modelowaniu, które codziennie mylą ludzi.
Częsty problem to mieszanie „installed” i „connected”. Installed zwykle znaczy „dostępne w workspace”, a connected znaczy, że istnieją realne poświadczenia i dane mogą płynąć. Gdy to się miesza, użytkownicy klikają integrację, która wygląda na gotową i trafiają na martwy punkt.
Inny błąd to wymyślanie zbyt wielu stanów statusu. Zespoły zaczynają od prostej odznaki, potem dodają przypadki brzegowe: pending, verifying, partial, paused, degraded, blocked, expiring i więcej. Z czasem etykiety te dryfują, bo nikt ich nie trzyma spójnych. Trzymaj mały zestaw powiązany z rzeczywistymi kontrolami: Not connected, Connected, Needs attention.
Ukryte uprawnienia też sprawiają problemy. Ktoś łączy konto, a potem odkrywa, że integracja miała szerszy dostęp niż się spodziewał. Uczyń zakres oczywistym przed końcowym krokiem „Connect” i pokaż go ponownie na stronie szczegółów, aby Admini mogli to audytować.
Wiele aplikacji potrzebuje wielu połączeń: dwa workspace Slack, kilka kont Stripe albo wspólne konto Google plus konta prywatne. Jeśli na stałe założysz „jedna integracja = jedno połączenie”, po pewnym czasie pojawią się brzydkie obejścia.
Planuj na:
Trzymaj widok listy lekki. Gdy upychasz w nim logi, mapowania pól i długie opisy, skanowanie zwalnia. Użyj listy do nazwy, krótkiego celu i postępu konfiguracji. Historię i zaawansowane ustawienia przenieś na stronę szczegółów.
Skalowalny katalog integracji sprowadza się do prostego modelu i uczciwego UI. Jeśli użytkownicy potrafią szybko odpowiedzieć na trzy pytania, system wydaje się przewidywalny: co jest połączone, co jest zepsute i co robić dalej?
Lista kontrolna przed wdrożeniem:
Następnie wybierz trzy integracje, które dobrze znasz i zamodeluj je end-to-end: narzędzie czatu (OAuth), połączenie w stylu Google (OAuth z zakresami) i narzędzie płatnicze (klucz API + webhooki). Jeśli twój model potrafi wyrazić wszystkie trzy bez wyjątków, zwykle wystarczy, żeby skalować do 30.
Traktuj katalog jako panel sterowania, a nie stronę marketingową. Każda karta powinna szybko pokazać, do czego służy integracja, czy teraz działa oraz jedną, najważniejszą akcję, którą użytkownik powinien wykonać. Jeśli użytkownicy muszą kliknąć tylko po to, by dowiedzieć się „czy to jest połączone?”, katalog stanie się niewiarygodny wraz ze wzrostem liczby integracji.
Proste zasady: karta powinna odpowiadać na „co to jest”, „czy jest zdrowe” i „co teraz”. Zazwyczaj oznacza to nazwę i jednowierszowy opis, status z ostatnim znacznikiem czasu (ostatnia synchronizacja lub ostatnie sprawdzenie) oraz jeden główny przycisk, który zmienia się w zależności od stanu. Wszystko inne trzymaj za przyciskiem „Manage”, aby skanowanie było szybkie.
Aby oddzielić ofertę od stanu użycia: Integration jako wpis w katalogu (globalny), Install jako włączenie integracji w danym workspace, oraz Connection jako faktyczne konto zewnętrzne (OAuth, klucz API, webhook). Taka separacja zapobiega chaosowi, gdy „zainstalowane” i „połączone” zaczynają się mieszać.
Rzeczywiste zespoły często potrzebują więcej niż jednego konta u tego samego dostawcy. Marketing i Support mogą podpiąć różne kalendarze Google, firma może mieć kilka kont Stripe. Model wielokrotnych Connections pod jednym Install pozwala utrzymać porządek i jednocześnie zarządzać kontami pojedynczo na stronie szczegółów.
Używaj małego zestawu etykiet, które da się utrzymać w czasie: Not set up, In progress, Connected, Needs attention i Disabled. Wyprowadzaj te etykiety z faktów, które możesz sprawdzić (ważność tokena, ukończone kroki konfiguracji, ostatnia udana synchronizacja). Dzięki temu unikniesz przestarzałych odznak, które pozostają czerwone po naprawie problemu.
Zrób postęp konfiguracji jako krótką listę kontrolną z wyraźnym rozróżnieniem na kroki wymagane i opcjonalne. Definicje kroków przechowuj per integration (statycznie), a wyniki kroków per install. UI może wtedy pokazać np. „2 z 3 wymaganych kroków ukończone”. Użytkownik zawsze powinien widzieć następny brakujący wymagany krok bez głębszego grzebania.
Zacznij od prostego reguły ról, która działa wszędzie, a dodatkowe sprawdzenia dodawaj tylko dla wrażliwych integracji. W wielu produktach Admini mogą konfigurować, Managerowie mogą ustawić większość narzędzi, a Członkowie mogą korzystać z włączonych integracji, ale nie mogą ich podłączać ani edytować. Dla płatności lub kadr dodaj pojedynczy znacznik "billing/payments admin" zamiast tworzenia nowego systemu ról.
Konfiguracje widoczne dla użytkownika trzymaj jako zwykłe dane, ale sekrety (refresh tokeny OAuth, klucze API) przechowuj w magazynie sekretów lub w zaszyfrowanym polu z rygorystycznymi zasadami dostępu. Nie loguj surowych sekretów, kodów autoryzacyjnych ani pełnych payloadów webhooków — loguj odniesienia (connection_id) i bezpieczne metadane (HTTP status, kod błędu).
Pokaż komunikat, który mówi, co się stało, co użytkownik powinien zrobić i co system zrobi automatycznie. Powtórki powinny być ciche i ograniczone do przypadków, których użytkownik nie naprawi sam (awarie dostawcy, sieci). Przy wygasłym auth lub brakujących uprawnieniach przerwij automatyczne retry i uczyn "Reconnect" albo "Fix permissions" główną akcją.
Utrzymuj wyszukiwanie proste i skupione na tym, jak myślą użytkownicy: najpierw nazwa dostawcy, potem kategoria. Dodaj filtry odzwierciedlające intencje: Connected, Needs attention i Not set up, żeby łatwo znaleźć problemy. Jeśli używasz Koder.ai, najpierw zaprojektuj pola katalogu, reguły statusów i kroki konfiguracji w Planning Mode, aby wygenerowany UI i backend były spójne przy rozszerzaniu listy integracji.