Browser SDK reference
A reference for the Browser SDK, window.sdk: how to offer a PWA install from the page,
subscribe the visitor to push, send events, and what settings that needs. For a general
introduction, see Browser SDK; to connect it to your own prelanding, see
SDK on your prelanding.
The window.pwaConfig settings
The SDK reads its settings from the window.pwaConfig object, which you set on the page
before the script tag. On pages served by Qubix the object is filled in automatically;
on your own prelanding you set it yourself.
| Field | Purpose |
|---|---|
pwaId | The PWA identifier. Required for install and for push |
domain | The page's domain. Required for the manifest and for push |
vapidKey | The key for push. Usually inlined automatically when /sdk.js loads — no need to set it by hand |
offerId | The offer (if you need to pass it explicitly) |
campaignId | The campaign (if you need to pass it explicitly) |
params | Extra tracking tags |
previewMode | Preview mode: events are not sent |
The PWA identifier (pwaId) is taken from the app card in the PWA Apps
section.
Subscribe to push
sdk.subscribePush() asks the browser for notification permission and creates a
subscription. You must call it explicitly — for example, on a button click. It does not
fire on its own.
const subscription = await sdk.subscribePush()
if (subscription) {
// the visitor allowed notifications and is subscribed
}
What happens inside:
- The browser's permission prompt is shown.
- If the visitor allows it, a subscription is created and sent to Qubix.
- Repeat calls are safe: if the visitor is already subscribed, the prompt is not shown again.
Installing the app is not required for push — a visitor can subscribe on an ordinary page.
Push works only over a secure connection (HTTPS) and on a domain that is set up in Qubix. More on this in SDK on your prelanding.
Install the PWA
If window.pwaConfig has a pwaId, the SDK exposes the sdk.pwa methods:
| Method | What it does |
|---|---|
sdk.pwa.init() | Preparation: registers the service worker and attaches the app manifest |
sdk.pwa.install() | Shows the system app-install prompt |
sdk.pwa.canInstall() | Whether install is available right now |
sdk.pwa.isInstalled() | Whether the app is already installed |
sdk.pwa.open() | Open the installed app |
init, install, and isInstalled are asynchronous — call them with await. canInstall and open return a value immediately.
if (sdk.pwa && sdk.pwa.canInstall()) {
await sdk.pwa.install()
}
The install prompt is shown by the browser itself, so its rules apply: HTTPS, an attached manifest (the SDK attaches it for you), and usually an action by the visitor on the page (a click, a scroll). That is why the install button is normally tied to an explicit tap.
Events
The SDK reports key moments to analytics on its own — they are visible in reports and in the event stream:
| Event | When |
|---|---|
campaign_visit | A visit to the page (sent automatically) |
push_prompt_shown | The push permission prompt was shown |
push_allow | The visitor allowed push |
push_deny | The visitor denied push |
push_ignored | The visitor dismissed the prompt without choosing |
install_accepted | The visitor agreed to install the app |
install_rejected | The visitor declined the install |
You can send your own event manually:
sdk.sendEvent('my_button_click', { place: 'hero' })
Traffic data
Helper methods to read the click context:
| Method | Returns |
|---|---|
sdk.getOffer() | The current offer (id and URL) |
sdk.getPwa() | The current PWA |
sdk.getPiuid() | The visitor id |
sdk.getTrackingParams() | The tracker tags that came with the click |
sdk.buildOfferUrl(url) | Build an offer URL with the tags carried over |
sdk.showStore() | Go to the PWA store card |
What the SDK does on its own
Without any calls from your side, on page load the SDK collects device data, parses the
tracking tags from the URL, attaches the app manifest (if pwaId is set), and sends the
campaign_visit event. Install and push subscription do not start on their own — you
trigger them from code.