Deep linki dla aplikacji natywnych: trasy, tokeny, otwórz w aplikacji

Co powinien robić deep link, prostym językiem

Gdy ktoś stuknie link na telefonie, spodziewa się jednego rezultatu: trafia od razu we właściwe miejsce. Nie „coś w tym kierunku”. Nie ekran główny z paskiem wyszukiwania. Nie ekran logowania, który zapomina, po co przyszedł użytkownik.

Dobre doświadczenie z deep linkami wygląda tak:

• Jeśli aplikacja jest zainstalowana, otwiera się dokładnie ten ekran, który sugeruje link.
• Jeśli aplikacji nie ma, kliknięcie i tak pomaga (np. otwiera fallback webowy lub stronę sklepu i pozwala wrócić do tego samego miejsca po instalacji).
• Jeśli trzeba się zalogować, robi się to raz i użytkownik trafia na zamierzony ekran, nie na domyślny start aplikacji.
• Jeśli link niesie ze sobą akcję (zaakceptuj zaproszenie, zobacz zamówienie, potwierdź email), akcja jest jasna i bezpieczna.

Większość frustracji pochodzi od linków, które „trochę działają”, ale psują flow. Użytkownicy widzą zły ekran, tracą kontekst albo wpadają w pętlę: klik — logowanie — dashboard — klik ponownie — logowanie. Nawet jeden dodatkowy krok może zniechęcić, szczególnie przy jednorazowych akcjach jak zaproszenia czy reset hasła.

Zanim napiszesz jakikolwiek kod w Kotlin lub SwiftUI, zdecyduj, co znaczy dany link. Które ekrany można otworzyć z zewnątrz? Co się zmienia, gdy aplikacja jest zamknięta vs już działa? Co zrobić, gdy użytkownik nie jest zalogowany?

To planowanie zapobiega większości problemów później: jasne trasy, przewidywalne zachowanie „otwórz w aplikacji” i bezpieczny sposób przekazywania jednorazowych kodów bez wrzucania sekretów do URL-a.

Typy deep linków i gdzie „otwórz w aplikacji” zawodzi

Nie każdy „link otwierający aplikację” zachowuje się tak samo. Traktowanie ich zamiennie prowadzi do typowych błędów: link otwiera złe miejsce, otwiera przeglądarkę zamiast aplikacji albo działa tylko na jednej platformie.

Trzy popularne kategorie:

• Schematy niestandardowe (np. myapp:). Łatwe w konfiguracji, ale wiele aplikacji i przeglądarek traktuje je ostrożnie.
• Universal Links (iOS) i App Links (Android). To zwykłe linki webowe, które otwierają aplikację, gdy jest zainstalowana, albo robią fallback na stronę, gdy jej nie ma.
• Linki otwierane w wbudowanej przeglądarce aplikacji. Linki kliknięte w aplikacji pocztowej lub komunikatorze często zachowują się inaczej niż w Safari czy Chrome.

„Otwórz w aplikacji” może znaczyć coś innego w zależności od miejsca tapnięcia. Link w Safari może przenieść od razu do aplikacji. Ten sam link w emailu może otworzyć najpierw wbudowaną przeglądarkę, a osoba musi stuknąć dodatkowy przycisk „otwórz w aplikacji” (albo go w ogóle nie zobaczy). Na Androidzie Chrome może respektować App Links, podczas gdy wbudowana przeglądarka aplikacji społecznościowej może je ignorować.

Cold start vs aplikacja już uruchomiona to kolejna pułapka.

• Cold start: system uruchamia aplikację, aplikacja się inicjalizuje i dopiero potem otrzymujesz deep link. Jeśli podczas startu pokazujesz splash, sprawdzasz auth lub ładujesz konfigurację, link może się zgubić, chyba że go zapiszesz i odtworzysz po gotowości.
• Już uruchomiona: otrzymujesz link, gdy użytkownik jest w trakcie sesji. Stos nawigacji istnieje, więc to samo miejsce może wymagać innego podejścia (push ekranu vs reset stosu).

Prosty przykład: zaproszenie kliknięte w Telegramie często otwiera się w wbudowanej przeglądarce. Jeśli twoja aplikacja zakłada, że OS zawsze przekaże bezpośrednio, użytkownik zobaczy stronę webową i pomyśli, że link nie działa. Zaplanuj te środowiska wcześniej i napiszesz mniej platformowego kleju później.

Zaplanuj trasy, zanim zaczniesz implementować

Większość błędów z deep linkami to nie problemy Kotlin/SwiftUI, tylko planowania. Link nie mapuje się jednoznacznie na ekran, albo niesie zbyt wiele „może”.

Zacznij od jednego spójnego wzorca tras, który pasuje do tego, jak użytkownicy myślą o aplikacji: lista, szczegóły, ustawienia, checkout, zaproszenie. Niech będzie czytelny i stabilny — będziesz go używać w emailach, kodach QR i na stronach web.

Prosty zestaw tras może zawierać:

• Strona główna
• Lista zamówień i szczegóły zamówienia (orderId)
• Ustawienia konta
• Akceptacja zaproszenia (inviteId)
• Wyszukiwanie (query, tab)

Następnie zdefiniuj parametry:

• Używaj ID dla pojedynczych obiektów (orderId).
• Używaj parametrów opcjonalnych dla stanu UI (tab, filter).
• Zdecyduj o domyślnych wartościach, by każdy link miał jedno najlepsze miejsce docelowe.

Zdecyduj też, co zrobić, gdy link jest błędny: brak danych, nieprawidłowe ID lub treść, do której użytkownik nie ma dostępu. Najbezpieczniejszy domyślny krok to otworzyć najbliższy stabilny ekran (np. listę) i pokazać krótką wiadomość. Unikaj wrzucania ludzi na pusty ekran lub ekran logowania bez kontekstu.

Planuj też według źródła. Kod QR zwykle potrzebuje krótkiej trasy, która otwiera się szybko i toleruje słabe łącze. Link w emailu może być dłuższy i zawierać dodatkowy kontekst. Strona web powinna degradować się łagodnie: jeśli aplikacja nie jest zainstalowana, osoba nadal powinna trafić na stronę wyjaśniającą, co zrobić dalej.

Jeśli używasz podejścia backend-driven (np. generując endpointy i ekrany za pomocą platformy takiej jak AppMaster), plan tras staje się wspólnym kontraktem: aplikacja wie, dokąd iść, a backend wie, które ID i stany są poprawne.

Bezpieczne przekazywanie tokenów bez wrzucania sekretów do URL-a

Deep link często traktowany jest jak bezpieczna koperta. Nie jest. Wszystko w URL może trafić do historii przeglądarki, zrzutów ekranu, podglądów udostępnionych, logów analitycznych lub zostać skopiowane do czatu.

Unikaj umieszczania sekretów w linku. To obejmuje długotrwałe tokeny dostępu, tokeny odświeżające, hasła, dane osobowe lub cokolwiek, co pozwoli komuś występować jako użytkownik, jeśli link zostanie przekazany.

Bezpieczniejszy wzorzec to krótki, jednorazowy kod. Link zawiera tylko ten kod, a aplikacja wymienia go na prawdziwą sesję po otwarciu. Jeśli ktoś przechwyci link, kod powinien być bezużyteczny po minucie lub dwóch albo po pierwszym zrealizowaniu.

Prosty przepływ:

• Link zawiera jednorazowy kod, nie token sesji.
• Aplikacja otwiera się i woła backend, by zrealizować kod.
• Backend sprawdza wygaśnięcie, czy kod nie był użyty, i oznacza go jako użyty.
• Backend zwraca normalną, uwierzytelnioną sesję dla aplikacji.
• Aplikacja czyści kod z pamięci po zrealizowaniu.

Nawet po pomyślnym zrealizowaniu, potwierdź tożsamość wewnątrz aplikacji przed wykonaniem czegoś wrażliwego. Jeśli link ma zatwierdzić płatność, zmienić email lub wyeksportować dane, wymagać szybkiego potwierdzenia jak biometryka lub świeże logowanie.

Przechowuj sesję bezpiecznie. Na iOS zwykle Keychain. Na Androidzie używaj magazynu zabezpieczonego przez Keystore. Przechowuj tylko to, co potrzebne, i czyść przy wylogowaniu, usunięciu konta lub wykryciu podejrzanego ponownego użycia.

Konkretny przykład: wysyłasz link zaproszenia do przestrzeni roboczej. Link ma jednorazowy kod ważny 10 minut. Aplikacja realizuje go, a potem pokazuje ekran jasno informujący, co się stanie (do której przestrzeni dołączasz). Dopiero po potwierdzeniu przez użytkownika aplikacja kończy dołączenie.

Jeśli budujesz z AppMaster, mapuje się to prosto na endpoint realizujący kody i zwracający sesję, podczas gdy UI mobilne zajmuje się krokiem potwierdzenia przed akcją o dużym znaczeniu.

Uwierzytelnianie i „kontynuuj tam, gdzie przerwałeś”

Deep linki często prowadzą do ekranów z prywatnymi danymi. Zacznij od decyzji, co jest publiczne, a co wymaga zalogowania. Ta jedna decyzja zapobiega większości niespodzianek typu „zadziałało w testach”.

Prosta reguła: najpierw prowadź do bezpiecznego stanu docelowego, a dopiero potem nawiguj do chronionego ekranu po potwierdzeniu, że użytkownik jest uwierzytelniony.

Zdecyduj, co jest publiczne, a co chronione

Traktuj deep linki jak coś, co może być przekazane niewłaściwej osobie.

• Publiczne: strony marketingowe, artykuły pomocy, rozpoczęcie resetu hasła, rozpoczęcie akceptacji zaproszenia (bez pokazywania danych)
• Chronione: szczegóły zamówień, wiadomości, ustawienia konta, ekrany admina
• Mieszane: ekran podglądu może być ok, ale pokazuj tylko nie-wrażliwe widżety do momentu zalogowania

„Kontynuuj po logowaniu”, które wraca we właściwe miejsce

Niezawodne podejście: parsuj link, zapisz zamierzone miejsce, potem route zależnie od stanu auth.

Przykład: użytkownik stuknął link do konkretnego zgłoszenia wsparcia będąc wylogowanym. Twoja aplikacja powinna otworzyć neutralny ekran, poprosić o logowanie, a potem automatycznie przenieść go do zgłoszenia.

By to utrzymać, zapisz mały „return target” lokalnie (nazwa trasy plus ID zgłoszenia) z krótkim czasem życia. Po zakończeniu logowania odczytaj go raz, nawiguj i skasuj. Jeśli logowanie się nie powiedzie lub cel wygaśnie, wróć do bezpiecznego ekranu głównego.

Obsługuj edge case’y z szacunkiem:

• Wygasła sesja: pokaż krótką wiadomość, ponów auth, potem kontynuuj.
• Cofnięty dostęp: otwórz szkielety docelowe, potem pokaż „Nie masz już dostępu” i zaproponuj bezpieczny następny krok.

Unikaj też pokazywania prywatnych danych w podglądach na ekranie blokady, podglądach w menedżerze aplikacji czy powiadomieniach. Trzymaj wrażliwe ekrany puste, dopóki dane nie zostaną załadowane i sesja nie zostanie potwierdzona.

Podejście do routingu, które unika spaghetti nawigacyjnego

Deep linki robią się chaotyczne, gdy każdy ekran parsuje URL po swojemu. To rozsiewa drobne decyzje (co jest opcjonalne, co wymagane, co ważne) po całej aplikacji i trudno to potem bezpiecznie zmienić.

Traktuj routing jak wspólną instalację hydrauliczną. Miej jedną tabelę tras i jednego parsera, a UI niech otrzymuje już oczyszczone dane.

Użyj jednej wspólnej tabeli tras

Niech iOS i Android zgadzają się co do jednej, czytelnej listy tras. Myśl o tym jak o kontrakcie.

Każda trasa mapuje się na:

1. ekran,
2. mały model wejściowy.

Na przykład „Szczegóły zamówienia” mapują się na ekran Order z wejściem OrderRouteInput(id). Jeśli trasa potrzebuje dodatkowych wartości (np. źródło ref), należą one do modelu wejściowego, a nie rozsiane po kodzie widoku.

Centralizuj parsowanie i walidację

Trzymaj parsowanie, dekodowanie i walidację w jednym miejscu. UI nie powinno pytać „czy ten token jest obecny?” albo „czy ten ID jest prawidłowy?” Powinien otrzymać albo poprawny model trasy, albo jasny stan błędu.

Praktyczny przepływ:

• Odbierz URL (tap, skan, share sheet)
• Sparsuj go do znanej trasy
• Zwaliduj wymagane pola i formaty
• Wyprodukuj docelowy ekran i model wejściowy
• Nawiguj przez jeden punkt wejścia

Dodaj ekran fallback dla „nieznanego linku”. Zrób go użytecznym, nie martwym końcem: pokaż, czego nie da się otworzyć, wyjaśnij prostym językiem i zaproponuj akcje: przejdź do Strony Głównej, wyszukaj, zaloguj się.

Krok po kroku: projektuj deep linki i zachowanie „otwórz w aplikacji”

Dobre deep linki są nudne — i to dobrze. Ludzie stukają i trafiają we właściwe miejsce, niezależnie od tego, czy aplikacja jest zainstalowana.

Krok 1: wybierz punkty wejścia, które naprawdę się liczą

Wypisz pierwsze ~10 typów linków, których ludzie faktycznie używają: zaproszenia, reset hasła, potwierdzenia zamówień, „zobacz zgłoszenie”, linki promocyjne. Celowo trzymaj listę krótką.

Krok 2: zapisz wzorce jako kontrakt

Dla każdego punktu wejścia określ wzorzec canonical i minimalne dane potrzebne do otwarcia właściwego ekranu. Preferuj stabilne ID zamiast nazw. Zdecyduj, co jest wymagane, a co opcjonalne.

Przydatne zasady:

• Jedna intencja na trasę (invite, reset, receipt).
• Parametry wymagane zawsze obecne; opcjonalne mają bezpieczne domyślne.
• Używaj tych samych wzorców na iOS (SwiftUI) i Android (Kotlin).
• Jeśli spodziewasz się zmian, zarezerwuj prosty prefix wersji (np. v1).
• Określ zachowanie przy brakujących parametrach (ekran błędu, nie pusty ekran).

Krok 3: ustal zachowanie logowania i cel post-login

Spisz dla każdego typu linku, czy wymaga logowania. Jeśli tak, pamiętaj, by po logowaniu wrócić do punktu docelowego.

Przykład: link do paragonu może pokazać podgląd bez logowania, ale „Pobierz fakturę” wymaga logowania i po nim użytkownik powinien wrócić do tego samego paragonu.

Krok 4: ustal zasady przekazywania tokenów (nie wrzucaj sekretów do URL)

Jeśli link potrzebuje jednorazowego tokena (akceptacja zaproszenia, reset, magic sign-in), określ jak długo jest ważny i jak można go wykorzystać.

Praktyczne podejście: URL niesie krótko-ważny, jednorazowy kod, aplikacja wymienia go z backendem na sesję.

Krok 5: testuj trzy stany z życia

Deep linki zawodzą na brzegach. Testuj każdy typ linku w:

• Cold start (aplikacja zamknięta)
• Warm start (aplikacja w pamięci)
• Brak aplikacji zainstalowanej (link wciąż powinien prowadzić gdzieś sensownie)

Jeśli trzymasz trasy, sprawdzenia auth i reguły wymiany tokenów w jednym miejscu, unikniesz rozproszonej logiki w Kotlin i SwiftUI.

Typowe błędy, które psują deep linki (i jak ich unikać)

Deep linki zawodzą z nudnych powodów: drobne założenie, przemianowany ekran czy „tymczasowy” token, który trafił wszędzie.

Błędy, które zobaczysz i ich naprawy

• Wrzucanie tokenów dostępu do URL (i ich wyciek do logów). Parametry zapytania są kopiowane, udostępniane, zapisywane w historii i przechwytywane przez analitykę. Naprawa: tylko jednorazowy, krótko-ważny kod w linku, realizuj go w aplikacji i szybko wygaszaj.

• Zakładanie, że aplikacja jest zainstalowana (brak fallbacku). Link prowadzący do błędu albo nic nie robi sprawia, że użytkownicy rezygnują. Naprawa: przygotuj fallback webowy, który wyjaśnia, co się dzieje i oferuje normalną ścieżkę instalacji.

• Brak obsługi wielu kont na jednym urządzeniu. Otworzenie odpowiedniego ekranu dla niewłaściwego użytkownika jest gorsze niż błąd. Naprawa: po otrzymaniu linku sprawdź aktywne konto, poproś o potwierdzenie lub przełączenie, potem kontynuuj. Jeśli akcja wymaga konkretnego workspace, dołącz identyfikator workspace (nie sekret) i go zweryfikuj.

• Łamanie linków po zmianach w ekranach lub trasach. Jeśli trasa jest powiązana z nazwami UI, stare linki umierają po zmianie nazwy. Naprawa: projektuj stabilne, intencyjne trasy (invite, ticket, order) i utrzymuj wsparcie dla starszych wersji.

• Brak śledzenia, gdy coś idzie nie tak. Bez możliwości odtworzenia zdarzeń dział pomocy tylko zgaduje. Naprawa: dodaj niesensytywny request ID w linku, loguj go na serwerze i w aplikacji oraz pokazuj komunikat błędu z tym ID.

Krótki test rzeczywistości: wyobraź sobie link zaproszenia wysłany na czat grupowy. Ktoś otwiera go na służbowym telefonie z dwoma kontami, aplikacja nie jest zainstalowana na tablecie, a link został przekazany dalej. Jeśli link zawiera tylko kod zaproszenia, ma fallback, prosi o wybór konta i loguje request ID, to ten sam link może zadziałać we wszystkich tych sytuacjach bez ujawniania sekretów.

Przykład: link zaproszenia, który zawsze otwiera właściwy ekran

Zaproszenia to klasyczny deep link: ktoś wysyła link koleżance w komunikatorze i oczekuje jednego kliknięcia, które prowadzi do ekranu akceptacji, a nie do ogólnej strony głównej.

Scenariusz: manager zaprasza nowego agenta do workspace „Support Team”. Agent klika zaproszenie w Telegramie.

Jeśli aplikacja jest zainstalowana, system powinien otworzyć aplikację i przekazać szczegóły zaproszenia. Jeśli aplikacji nie ma, użytkownik powinien trafić na prostą stronę wyjaśniającą zaproszenie i ze ścieżką instalacji. Po instalacji i pierwszym uruchomieniu aplikacja powinna móc dokończyć przepływ zaproszenia, żeby użytkownik nie musiał szukać linku ponownie.

W aplikacji przepływ wygląda tak samo w Kotlin i SwiftUI:

• Odczytaj kod zaproszenia z przychodzącego linku.
• Sprawdź, czy użytkownik jest zalogowany.
• Zweryfikuj zaproszenie przez backend, potem przekieruj na właściwy ekran.

Weryfikacja jest kluczowa. Link nie powinien zawierać sekretów jak długotrwały token sesji. Powinien mieć krótki kod zaproszenia, który jest użyteczny dopiero po walidacji na serwerze.

Doświadczenie użytkownika powinno być przewidywalne:

• Niezalogowany: zobaczy ekran logowania, a po nim wróci do akceptacji zaproszenia.
• Zalogowany: zobaczy jedno potwierdzenie „Dołącz do workspace”, a potem trafi do właściwej przestrzeni.

Jeśli zaproszenie wygasło lub zostało już użyte, nie rzucaj użytkownika na pusty ekran z błędem. Pokaż jasną wiadomość i kolejne kroki: poproś o nowe zaproszenie, przełącz konto lub skontaktuj się z administratorem. „To zaproszenie zostało już zaakceptowane” jest lepsze niż „Nieprawidłowy token.”

Szybka checklista i kolejne kroki

Deep linki wydają się „gotowe”, gdy zachowują się tak samo wszędzie: cold start, warm start i gdy użytkownik jest już zalogowany.

Szybka checklista

Przed wypuszczeniem przetestuj na prawdziwych urządzeniach i wersjach OS:

• Link otwiera właściwy ekran przy cold start i warm start.
• W URL nie ma nic wrażliwego. Jeśli musisz przekazać token, niech będzie jednorazowy i krótkotrwały.
• Nieznane, wygasłe lub użyte linki robią fallback do przejrzystego ekranu z instrukcją i propozycją następnego kroku.
• Działa z aplikacji pocztowych, przeglądarek, skanerów QR i podglądów komunikatorów (niektóre je wstępnie otwierają).
• Logowanie mówi ci, co się stało (otrzymano link, sparsowano trasę, auth wymagany, powód sukcesu lub porażki).

Prosty sposób na walidację: wybierz kilka krytycznych linków (zaproszenie, reset hasła, szczegóły zamówienia, zgłoszenie wsparcia, promo) i przetestuj je z tego samego procesu: klik z emaila, klik z czatu, skan QR, otwarcie po reinstalacji.

Kolejne kroki (by utrzymać porządek)

Jeśli obsługa deep linków zaczyna rozprzestrzeniać się po ekranach, traktuj routing i auth jako wspólną infrastrukturę, a nie kod każego ekranu. Centralizuj parsowanie tras w jednym miejscu i spraw, by każdy ekran przyjmował czyste parametry (nie surowe URL-e). To samo z auth: jeden gate decydujący „kontynuuj teraz” vs „zaloguj się, a potem kontynuuj”.

Jeśli chcesz ograniczyć ilość własnego kleju, warto budować backend, auth i aplikacje mobilne razem. AppMaster (appmaster.io) to platforma no-code, która generuje produkcyjne backendy i natywne aplikacje mobilne, co ułatwia utrzymanie zgodności nazw tras i endpointów realizujących jednorazowe kody w miarę zmian wymagań.

Jeśli zrobisz jedną rzecz w następnym tygodniu: spisz canonical routes i dokładne fallbacki dla każdego przypadku błędu, a potem zaimplementuj te reguły w jednej warstwie routingu.