Dokumentacja Browser SDK
Dokumentacja Browser SDK, window.sdk: jak zaproponować instalację PWA ze strony,
zapisać odwiedzającego do powiadomień push, wysyłać zdarzenia i jakich ustawień to wymaga. Ogólne
wprowadzenie — zob. Browser SDK; podłączenie na własnym prelanderze — zob.
SDK na prelanderze.
Ustawienia window.pwaConfig
SDK odczytuje ustawienia z obiektu window.pwaConfig, który należy ustawić na stronie
przed tagiem skryptu. Na stronach serwowanych przez Qubix obiekt jest wypełniany automatycznie;
na własnym prelanderze ustawia go Pan/Pani samodzielnie.
| Pole | Przeznaczenie |
|---|---|
pwaId | Identyfikator PWA. Wymagany do instalacji i do push |
domain | Domena strony. Wymagana do manifestu i do push |
vapidKey | Klucz do push. Zwykle jest wstawiany automatycznie podczas ładowania /sdk.js — nie trzeba go ustawiać ręcznie |
offerId | Oferta (jeśli trzeba ją przekazać jawnie) |
campaignId | Kampania (jeśli trzeba ją przekazać jawnie) |
params | Dodatkowe tagi trackingowe |
previewMode | Tryb podglądu: zdarzenia nie są wysyłane |
Identyfikator PWA (pwaId) pochodzi z karty aplikacji w sekcji Aplikacje PWA.
Subskrypcja push
sdk.subscribePush() prosi przeglądarkę o zgodę na powiadomienia i tworzy
subskrypcję. Należy wywołać tę metodę jawnie — na przykład przy kliknięciu przycisku. Nie uruchamia się sama.
const subscription = await sdk.subscribePush()
if (subscription) {
// odwiedzający zezwolił na powiadomienia i jest zapisany
}
Co dzieje się wewnątrz:
- Wyświetlany jest monit uprawnień przeglądarki.
- Jeśli odwiedzający wyrazi zgodę, subskrypcja jest tworzona i wysyłana do Qubix.
- Kolejne wywołania są bezpieczne: jeśli odwiedzający jest już zapisany, monit nie jest wyświetlany ponownie.
Instalacja aplikacji nie jest wymagana do push — odwiedzający może zapisać się na zwykłej stronie.
Push działa tylko przez bezpieczne połączenie (HTTPS) oraz na domenie skonfigurowanej w Qubix. Więcej na ten temat w artykule SDK na prelanderze.
Instalacja PWA
Jeśli window.pwaConfig zawiera pwaId, SDK udostępnia metody sdk.pwa:
| Metoda | Co robi |
|---|---|
sdk.pwa.init() | Przygotowanie: rejestruje service worker i dołącza manifest aplikacji |
sdk.pwa.install() | Wyświetla systemowy monit instalacji aplikacji |
sdk.pwa.canInstall() | Czy instalacja jest dostępna w tej chwili |
sdk.pwa.isInstalled() | Czy aplikacja jest już zainstalowana |
sdk.pwa.open() | Otwiera zainstalowaną aplikację |
init, install i isInstalled są asynchroniczne — należy je wywoływać z await. canInstall i open zwracają wartość natychmiast.
if (sdk.pwa && sdk.pwa.canInstall()) {
await sdk.pwa.install()
}
Monit instalacji jest wyświetlany przez samą przeglądarkę, dlatego obowiązują jej zasady: HTTPS, dołączony manifest (SDK dołącza go za Pana/Panią) oraz zazwyczaj akcja odwiedzającego na stronie (kliknięcie, przewinięcie). Dlatego przycisk instalacji jest zwykle powiązany z jawnym dotknięciem.
Zdarzenia
SDK raportuje do analityki kluczowe momenty samodzielnie — są widoczne w raportach i w strumieniu zdarzeń:
| Zdarzenie | Kiedy |
|---|---|
campaign_visit | Odwiedzenie strony (wysyłane automatycznie) |
push_prompt_shown | Wyświetlono monit zgody na push |
push_allow | Odwiedzający zezwolił na push |
push_deny | Odwiedzający odmówił push |
push_ignored | Odwiedzający zamknął monit bez wyboru |
install_accepted | Odwiedzający zgodził się zainstalować aplikację |
install_rejected | Odwiedzający odmówił instalacji |
Własne zdarzenie można wysłać ręcznie:
sdk.sendEvent('my_button_click', { place: 'hero' })
Dane o ruchu
Metody pomocnicze do odczytu kontekstu kliknięcia:
| Metoda | Zwraca |
|---|---|
sdk.getOffer() | Bieżącą ofertę (identyfikator i adres URL) |
sdk.getPwa() | Bieżące PWA |
sdk.getPiuid() | Identyfikator odwiedzającego |
sdk.getTrackingParams() | Tagi trackingowe przesłane przy kliknięciu |
sdk.buildOfferUrl(url) | Tworzy adres URL oferty z przeniesieniem tagów |
sdk.showStore() | Przechodzi do karty sklepu PWA |
Co SDK robi samodzielnie
Bez żadnych wywołań z Pańskiej/Pani strony SDK przy ładowaniu strony zbiera dane urządzenia, parsuje
tagi trackingowe z adresu URL, dołącza manifest aplikacji (jeśli ustawiono pwaId) i wysyła zdarzenie
campaign_visit. Instalacja i subskrypcja push nie uruchamiają się samodzielnie — wyzwala je Pan/Pani z kodu.