Overview & Quick Start

#What the SDK does

The SharePush Web SDK is a drop-in script that turns any website into a web-push channel. Once installed it:

Registers a service worker on your site so the browser can receive push messages in the background.
Shows an opt-in prompt inviting visitors to allow notifications (fully customizable, optional two-step "are you sure?" flow).
Optionally invites visitors to install your site as an app (PWA), which is required for push on iOS.
Detects unsupported environments (in-app browsers, old iOS, privacy browsers) and either shows a helpful "open in Safari/Chrome" bridge or stays silent. It never shows a broken prompt.
Tracks the full funnel (delivered, clicked, closed, and viewed) and attributes landing-page views back to the campaign that drove them.

Everything renders in a Shadow DOM, so the SDK's UI can't clash with your site's CSS.

#Minimum installation

#1. Add the script and initialize

Place this near the end of your <body> (or in <head>, it's async-safe):

 1<script src="https://api.sharepush.io/api/v1/sdk.js"></script>
 2<script>
 3  Sharepush.init({
 4    apiUrl: 'https://api.sharepush.io',
 5    apiKey: 'st_your_site_token_here',
 6    autoPrompt: true            // show the push opt-in automatically
 7  });
 8</script>

Only apiUrl and apiKey are required. (A vapidPublicKey is also required, but it's injected automatically by /api/v1/sdk.js; you don't set it.) If any required value is missing, the SDK logs a clear [Sharepush] Configuration missing: error and stops.

#2. Host the service worker file

The SDK registers a service worker from your own origin, by default /sharepush-sw.js. This small file pulls in the SharePush service-worker logic. It must be served from your site root (or the path you set via serviceWorkerPath) so its scope covers your whole site.

#3. (Recommended) Add a Web App Manifest

For the PWA install prompt to appear (and for push to work on iOS at all), your page needs a valid manifest:

 1<link rel="manifest" href="/manifest.json">

Without a manifest, push still works on desktop/Android, but the "install app" prompt is skipped and iOS push is unavailable.

#A fuller, real-world example

 1<script src="https://api.sharepush.io/api/v1/sdk.js"></script>
 2<script>
 3Sharepush.init({
 4  apiUrl: 'https://api.sharepush.io',
 5  apiKey: 'st_your_site_token_here',
 6  serviceWorkerPath: '/sharepush-sw.js',
 7  autoPrompt: true,
 8  useBounce: true,
 9
10  category: 'news',                 // segment subscribers
11  language: 'it',
12  theme: 'glass-light',
13  customKey: 'Guest',               // your identifier for this visitor
14
15  promptTitle: 'Stay updated with Example.com',
16  promptMessage: 'Turn on notifications for breaking news in real time.',
17  promptButtonAllow: 'Yes, notify me',
18  promptButtonDeny: 'No thanks',
19  promptBrandColor: '#00913F',
20  promptIcon: 'https://example.com/logo.svg',
21  delay: 3000,
22  useSecondStep: false,
23
24  props: {                          // custom metadata attached to events
25    article_id: '178523',
26    author_id: '163221'
27  }
28});
29</script>

#How the pieces fit together

 1Visitor lands ─▶ SDK boots ─▶ registers service worker
 2                     │
 3                     ├─▶ unsupported browser/webview? ─▶ show bridge or stay silent
 4                     │
 5                     ├─▶ show PWA install prompt (if eligible)  ┐ coordinated:
 6                     └─▶ show push opt-in prompt                ┘ never both at once
 7                                    │
 8                          user Allows ─▶ subscription created
 9                                    │
10        You send a campaign ─▶ delivered ─▶ clicked ─▶ viewed (on your landing page)

Continue to the Configuration Reference for every available option.