Event Tracking & Analytics

SharePush tracks the full notification funnel. Understanding which side fires each event explains why the numbers behave the way they do.

#The four events

Event	Fired by	When
`delivered`	Service worker	A push message is received by the device.
`clicked`	Service worker	The visitor clicks the notification.
`closed`	Service worker	The visitor dismisses the notification without clicking.
`viewed`	SDK (page)	The visitor lands on your page after clicking a notification, and the SDK attributes that visit to the campaign.

The first three fire inside the service worker using data carried in the push payload, so they're robust and fire regardless of what's on the page. viewed is different — it depends on the SDK running on the landing page and finding a valid attribution ticket (below). That's why viewed is typically lower than clicked: it only counts when the visitor actually reaches a page where the SDK is installed.

#Click-to-view attribution (how `viewed` works)

When a notification is clicked, the service worker writes a small attribution ticket into the browser's local database (IndexedDB), keyed by the destination page's path.
When the landing page loads, the SDK looks up that ticket, matches it to the campaign/dispatch, and fires the viewed event.
The ticket is consumed (deleted) so the same visit can't be counted twice, and a per-session guard prevents duplicate views of the same campaign/URL.

Because the ticket lives in the browser's per-origin storage, attribution works reliably as long as the notification's destination stays on the same host the visitor subscribed on. If you subscribe visitors on www.example.com, keep campaign links on www. (not the bare example.com) so the ticket is found.

#The ghost-referrer bounce (`useBounce`)

With useBounce: true (default), click-throughs are routed so that your destination page sees the visit as direct traffic rather than as coming from the push service. This keeps your analytics attribution clean (the push doesn't pollute your referrer reports) while SharePush still records the click and view internally.

Set useBounce: false to disable this behavior.

#Custom metadata: `props` and UTMs

props — any flat object you pass is attached to tracked events:

 1Sharepush.init({
 2  props: { article_id: '178523', author_id: '163221', sub_category: 'markets' }
 3});

UTMs — standard UTM parameters (utm_source, utm_medium, utm_campaign, utm_term, utm_content) present on the page URL are captured automatically and stored with events.

Also captured per event: device OS/platform/browser, country (via IP/Cloudflare), hostname, pathname, and referrer.

#Offline resilience

If an event can't be sent (network error, or the server returns an error status), the SDK saves it to an offline queue in the browser and retries on the next page load, draining the queue in order. A successful send (or a de-duplication response) removes it from the queue. This means transient failures don't silently lose events.

Reliability note: the viewed send treats any non-OK response (other than a de-dup status) as "retry later" and queues it, rather than assuming success. Combined with a short retry when reading the attribution ticket, this makes view tracking resilient to a cold service worker or a briefly failing server.

#Reading the data

Events land in the SharePush analytics store and surface in your dashboard. The SDK is the ingestion side; the dashboard is where you view delivery rates, click-through, and view counts per campaign.

Next: Triggers, Theming & Localization →