Treści i cele przycisków w aplikacji mobilnej

Banery, karuzela, aktualności i paski z wezwaniem do działania w aplikacji to te same treści co w portalu klienta. Marka przygotowuje je w panelu i przy każdej treści wybiera kanał: portal, aplikacja albo oba (Treści w portalu i aplikacji). Ten przewodnik opisuje, jak aplikacja je pobiera, dokąd prowadzi przycisk i jak zgłaszać pokazania. Zasady ustalono z zespołem aplikacji w listopadzie 2026 (decyzje A1-A6, tabela na końcu).

Pobieranie treści#

API zwraca wyłącznie treści z kanałem „Aplikacja mobilna”, które działają w tej chwili dla widza: w swoim okresie i harmonogramie, dla gościa, zalogowanego albo segmentu. Sekcja treści nie ma przełącznika - marka bez treści daje puste sloty, a nie FEATURE_DISABLED.

GET content/home zwraca cztery sloty startu jednym żądaniem, GET content?placement=... - jeden slot, GET news/{uuid} - pełny wpis aktualności. Obrazy to oryginały: animowany GIF zostaje animacją (image.animated). Pole image może być null - pokaż wtedy treść w barwach marki z brand/config.

Obiekt link#

Przycisk treści (cta) ma label i link:

{
  "type": "shop_product",
  "params": { "uuid": "...", "category_uuid": "...", "localization_uuid": "..." },
  "url": "https://...",
  "deep_link": "shop/products/...",
  "requires_login": false
}

• Ekran wybieraj wyłącznie po type i params. Nie parsuj url ani deep_link. params jest zawsze obiektem; każdy cel z obiektem (offer_category, shop_category, shop_product, news_item) ma params.uuid.
• deep_link to tylko informacyjna podpowiedź (np. do logów). Nie buduj z niego nawigacji.
• url jest zawsze https: ten sam cel w portalu klienta albo adres zewnętrzny, z parametrami UTM. To zapas dla ekranu, którego aplikacja jeszcze nie ma - otwórz go w przeglądarce w aplikacji. Linków uniwersalnych nie ma, bo każda marka ma własną domenę.
• requires_login = true - ekran konta. Gościa najpierw przeprowadź przez logowanie.
• Brak cta oznacza treść bez przycisku albo cel, którego już nie ma (sekcja wyłączona, produkt usunięty).

Oferta, kategoria oferty i pomoc w przeglądarce w aplikacji to stan tymczasowy. Docelowo dostaną ekrany natywne (wytyczna Apple 4.2) - zmieni się wtedy tylko ekran w tabeli, obiekt link zostanie ten sam.

Pomiar pokazań i kliknięć#

Pokazanie liczy się według standardu IAB: co najmniej połowa elementu widoczna przez co najmniej 1 sekundę. Jedno pokazanie danej treści na jedno wejście na ekran - przewinięcie z powrotem nie jest nowym pokazaniem. Slajd karuzeli przewijanej automatycznie liczy się tak samo. Otwarcie wpisu aktualności to pokazanie wpisu. Dotknięcie przycisku albo karty aktualności to kliknięcie. Samo pobranie treści (GET) niczego nie liczy.

Wynik przychodzi dla każdego zdarzenia w kolejności paczki: counted, duplicate (już policzone w tej sesji, dla tej treści, rodzaju i dnia) albo rejected z powodem (invalid_event, invalid_occurred_at, occurred_in_future, too_old, content_not_found, content_not_live). Odrzucenie jest ostateczne. 422 VALIDATION_ERROR dotyczy tylko złej koperty: brak events, pusta lista albo ponad 100 elementów.

Okno czasu: occurred_at najwyżej 5 minut w przód i 24 godziny wstecz. Dzień zdarzenia liczy się w strefie Europe/Warsaw. Ponowna wysyłka tej samej paczki jest bezpieczna - da duplicate. Idempotency-Key nie jest tu potrzebny. Pojedyncze POST content/{uuid}/impression i click zostały dla zgodności; click zwraca też bieżący link celu.

Sesja i X-Device-Id#

Serwer liczy pokazanie raz na sesję aplikacji, treść, rodzaj i dzień. Sesją zalogowanego jest token. Sesją gościa jest nagłówek X-Device-Id - losowy identyfikator instalacji (np. UUID v4); bez niego serwer używa skrótu IP i przeglądarki.

X-Device-Id jest osobny od device_id z logowania. Serwer ich nie łączy i nie przenosi pokazań gościa na konto: po zalogowaniu nagłówek jest pomijany, a ta sama treść liczy się w nowej sesji. Nie jest to identyfikator reklamowy. Nie przechowuj go w iOS Keychain - Keychain przeżywa odinstalowanie aplikacji, a identyfikator ma opisywać instalację.

Tryb gościa i powrót po logowaniu#

Cel jest niedostępny, gdy click zwrócił link: null albo ekran celu odpowiedział 404 lub FEATURE_DISABLED. Po zalogowaniu pobierz content/home ponownie - z tokenem dochodzą treści dla zalogowanych i segmentu.

Ustalenia z zespołem aplikacji (A1-A6)#