Web Push Setup

This guide walks through configuring OneSignal web push notifications for your Shopify store using Vendo.

Prerequisites

A Shopify store with the Vendo app installed
A OneSignal account (free tier available)

Step 1: Create a OneSignal App

Log in to OneSignal
Click New App/Website
Enter your app name (e.g., your store name)
Select Web as the platform
Choose Custom Code as the integration type

Important: You must pick Custom Code. The Typical Site option does not let you customise the service worker path, and Shopify will not allow OneSignal’s default root-path service worker to be served. Vendo routes the service worker through the Shopify App Proxy at /apps/vendo/, which only the Custom Code flow supports. If you’ve already created the app under Typical Site, switch it to Custom Code (or recreate the app) before continuing.

Step 2: Configure Web Push Platform

In the OneSignal setup wizard:

Site Name — Your store name
Site URL — Your Shopify store URL (e.g., https://yourstore.myshopify.com)
Default Icon URL — Upload your store icon (recommended: 256x256 PNG)

Service Worker Configuration

This is critical for Shopify stores. Shopify does not allow serving files from the site root, so the service worker must use a custom path. In OneSignal, expand Advanced Push Settings and toggle on “Customize service worker paths and filenames”, then enter:

Field	Value
Path to service worker files	`/apps/vendo/`
Main service worker filename	`OneSignalSDKWorker.js`
Updater service worker filename	`OneSignalSDKWorker.js`
Service worker registration scope	`/apps/vendo/`

Vendo’s OneSignal Push Settings page in the Shopify app displays these exact values with click-to-copy — no need to retype them.

Click Save to complete the web platform setup

Step 3: Get Your Credentials

From the OneSignal dashboard, navigate to Settings > Keys & IDs:

App ID — Your OneSignal application ID
REST API Key — Used for server-side event syncing (optional but recommended)

Step 4: Configure in Vendo

In the Vendo Shopify app, navigate to Destinations > OneSignal
Enter your OneSignal App ID
Optionally enter your REST API Key for server-side events
Click Save

Step 5: Enable the Theme Block

In your Shopify admin, go to Online Store > Themes > Customize
Click App embeds (in the left sidebar)
Enable the Vendo theme block
Save the theme

The Vendo theme block loads the OneSignal SDK on your storefront and handles:

SDK initialization with your App ID
Service worker registration at the correct path
Push prompt display based on your settings
User identification (push subscription, login, newsletter signup)
Tag syncing for identified users

Step 6: Configure Push Prompts in the Vendo App

Whether each prompt shows on your storefront, and when it shows, is controlled from the Vendo app — not OneSignal’s dashboard. This keeps all storefront-visible decisions in one place and avoids OneSignal’s default-on behaviour for the Subscription Bell.

In the Vendo app, open OneSignal > Push Settings. You’ll see four sections, each with its own toggle:

Section	What it does	When you’d use it
Subscription Bell	Floating bell icon visitors can click to subscribe	A persistent subscribe affordance — useful for always-visible opt-in
Push Slide Prompt	Branded slide-in banner asking for push permission	The default for most stores — less intrusive than the native dialog alone
Native Browser Prompt	Triggers the browser’s built-in permission dialog directly	If you want to skip the slide prompt and ask immediately
Welcome Notification	Push notification sent automatically the moment a visitor subscribes	Confirms the subscription and sets expectations

For Push Slide and Native, you set triggers — how many page views and how many seconds to wait before the prompt fires. Sensible defaults (1 page view, 10s for slide, 20s for native) are pre-filled.

For Welcome, you set the title and message shown in the push notification.

All four are off by default — enable only the ones you want. Save once at the bottom of the page; changes take effect on the next storefront load (no theme redeploy required).

What still lives in OneSignal’s dashboard

Things Vendo intentionally doesn’t mirror — OneSignal’s dashboard has a richer editor for these:

Prompt button copy (accept/cancel labels), action message, confirmation text
Default icon shown in prompts and notifications
Email & Phone Capture prompts (opt-in form variants)
Category opt-ins (let visitors pick notification topics)
A/B tests and localization

From the Vendo app’s Push Settings, click Open OneSignal Dashboard — it deep-links straight to your app’s Permission Prompt Setup page.

Tip: If you configure a prompt in OneSignal’s dashboard but its Vendo toggle is off, the prompt won’t render. Vendo’s admin toggle is the source of truth for visibility; OneSignal’s dashboard is the source of truth for the copy/icons of prompts that are visible.

Step 7: Verify Setup

Check Service Worker

Visit your store and open browser DevTools (F12):

Go to Application > Service Workers
Verify OneSignalSDKWorker.js is registered
The scope should show /apps/vendo/

Test Notifications

Subscribe to push notifications on your store
In the OneSignal dashboard, go to Messages > New Push
Send a test notification to yourself
Verify the notification appears

Verify in OneSignal Dashboard

Go to Audience > All Users
Confirm your test subscription appears
Check that user tags are being synced (email, name, etc.)

Troubleshooting

Service Worker Returns 404

The service worker path must be /apps/vendo/OneSignalSDKWorker.js. Verify:

The Vendo theme block is enabled in your Shopify theme
You’re accessing the store via its primary domain
In the OneSignal dashboard, Customize service worker paths and filenames is toggled on with the four values from Step 2 — if this section is collapsed or disabled, OneSignal falls back to the root path and Shopify will reject the request

”Typical Site” was selected during OneSignal setup

Vendo requires the Custom Code integration type. Typical Site does not expose the service-worker path settings, so the SDK will try to load /OneSignalSDKWorker.js from your store root — Shopify blocks that and push subscription will silently fail.

Fix: in the OneSignal dashboard, either switch the app’s integration type to Custom Code (Settings > Platforms > Web), or delete the app and recreate it with Custom Code from the start.

Push Prompt Not Appearing

Check that the Vendo theme block is enabled in App embeds
In the Vendo app under OneSignal > Push Settings, confirm at least one prompt toggle (Subscription Bell, Push Slide Prompt, or Native Browser Prompt) is turned on — all four default to off
Check the trigger delay — a Push Slide set to e.g. 3 page views won’t fire on the first page load
Ensure your browser allows notifications (check browser settings)
Verify you haven’t already dismissed or subscribed
Try an incognito/private window

Notifications Show “Delivered” But Don’t Appear

Check your OS notification settings (System Preferences > Notifications)
Verify the browser has notification permissions
Some browsers require the site to be served over HTTPS

Tags Not Appearing in OneSignal

Tags sync only for identified users (logged in, subscribed to push, signed up for newsletter, or completed a purchase)
Anonymous visitors are not tracked in OneSignal
Check the Vendo app logs for sync errors

Events Not Triggering

Verify the events are enabled in OneSignal > Events in the Vendo app
Client-side events require the Web Pixel to be active and the user to be identified
Server-side events require the REST API Key to be configured
See How It Works for details on user identification