OneSignal Web Push Setup

This guide shows how to set up OneSignal web push notifications for your Shopify store with Vendo.

Prerequisites

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

Step 1: Create a OneSignal App

1. Log in to OneSignal 
2. Click New App/Website
3. Enter your app name (for example, your store name)
4. Select Web as the platform
5. Choose Custom Code as the integration type

Important: You must pick Custom Code. The Typical Site option does not let you customize the service worker path. Shopify does not serve OneSignal’s default service worker from the site root. Vendo routes the service worker through the Shopify App Proxy at /apps/vendo/, which only the Custom Code flow supports.

If you already created the app under Typical Site, switch it to Custom Code (or recreate the app) before you continue.

Step 2: Configure Web Push Platform

In the OneSignal setup wizard:

1. Site Name: your store name
2. Site URL: your Shopify store URL (for example, https://yourstore.myshopify.com)
3. Default Icon URL: upload your store icon (recommended: 256x256 PNG)

Service Worker Configuration

This setting is critical for Shopify stores. Shopify does not allow files to be served from the site root, so the service worker must use a custom path. In OneSignal, expand Advanced Push Settings and turn on Customize service worker paths and filenames. Then enter these values:

The OneSignal Web push tab in the Vendo Shopify app shows these exact values with click-to-copy. You do not need to type them again.

4. Click Save to complete the web platform setup

Step 3: Get Your Credentials

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

• App ID: your OneSignal application ID
• REST API Key: required. Vendo uses it to verify your credentials and to send events to OneSignal.

Step 4: Configure in Vendo

1. In the Vendo Shopify app, go to Destinations and click Add destination
2. Select OneSignal
3. On the Credentials step, enter your App ID
4. Enter your REST API Key
5. Click Complete Setup

To change the credentials later, open the OneSignal Settings tab and click Save in the save bar.

Step 5: Enable the Theme Block

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

The Vendo theme block loads the OneSignal SDK on your storefront. It 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

Before you enable any Vendo push setting, remove the dashboard prompts:

1. In the OneSignal dashboard, go to Web Push > Permission Prompt Setup
2. Delete all prompts listed there

The Vendo admin is then the only source of truth for what your storefront shows.

In the Vendo app, open OneSignal > Web push. It has four prompt sections, each with its own toggle:

For Push Slide and Native, you set triggers: how many page views and how many seconds to wait before the prompt shows. Vendo fills in defaults: 1 page view, 10 seconds for the slide prompt and 20 seconds for the native prompt.

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

All four are off by default. Enable only the ones that you want. Click Save in the save bar. Changes take effect on the next storefront load (no theme redeploy required).

How Vendo and OneSignal interact

OneSignal’s Web SDK reference  says that storefront init options can add prompts to what the dashboard already serves. They cannot remove prompts. Vendo uses only documented init keys (appId, safari_web_id, serviceWorkerPath, serviceWorkerParam, allowLocalhostAsSecureOrigin, notifyButton, promptOptions, welcomeNotification). For the native prompt, it uses the documented OneSignal.Notifications.requestPermission() method.

Effect:

• Subscription Bell: Vendo controls whether the bell shows (notifyButton.enable). You still set the bell appearance (position, color, size) in OneSignal.
• Push Slide: Vendo adds it when the Vendo toggle is on. When the toggle is off, Vendo sends nothing. Any slidedown that is still configured in your OneSignal dashboard shows on top.
• Native Browser Prompt: when this toggle is on and Push Slide is off, Vendo calls requestPermission() on a timer. It does not depend on the OneSignal dashboard settings.
• Welcome Notification: when it is on, Vendo passes welcomeNotification.title/message. When it is off in Vendo, the OneSignal dashboard welcome notification (if set) still sends.

What still lives in OneSignal’s dashboard

The Vendo admin controls prompt visibility and triggers. Everything after the subscription stays in OneSignal. This includes composing and sending the push notifications:

• Default notification icon (Site Settings → Default Icon URL): OneSignal applies it to every push that it sends. You set it once for each app.
• Notification content and campaigns: compose messages, upload images and schedule sends
• Segments: audience targeting rules (by tag, subscription date, country and other attributes)
• Journeys: trigger-based sends (for example, a welcome series or cart abandonment follow-ups)
• A/B testing of sent notifications: split test message variants when you send a campaign
• Analytics: delivery, click-through and opt-in funnels

Vendo does not support prompt-level copy (accept and cancel button labels, action message), category opt-ins or prompt localization at this time. Vendo’s init uses the SDK default text for the slide prompt and uses only type: "push" prompts. If you need these features, contact us and we will add them to the Vendo admin.

On the Vendo app’s Web push tab, click Open OneSignal Dashboard to go to your app in OneSignal. Use it to compose campaigns and manage your audience. Do not use it to add prompts (add prompts in the Vendo admin).

Step 7: Verify Setup

Check Service Worker

Visit your store and open browser DevTools (F12):

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

Test Notifications

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

Verify in OneSignal Dashboard

1. Go to Audience > All Users
2. Confirm your test subscription appears
3. Check that user tags are synced (for example, email and name)

Verify live settings with the console diagnostic

To confirm which push settings are actually live on your storefront (compared to what you saved in the Vendo admin), paste this script into the browser DevTools console on your storefront. Open the console with F12 or Cmd+Option+I, select the Console tab, paste the script and press Enter. The script prints the current metafield, theme extension version, OneSignal dashboard state and browser subscription state. It also prints a short verdict with the next action if something looks wrong.

(async () => {
  const r = {};
 
  const h = await (await fetch(location.origin + '/?_d=' + Date.now())).text();
 
  const meta = h.match(/"onesignal":\{[^}]+\}/);
 
  r.metafield = meta ? meta[0] : 'MISSING';
 
  r.hasNewInitCode = {
    requestPermission: h.includes('OneSignal.Notifications.requestPermission'),
    noEnabledFalseHack: !h.includes('enabled: false, autoPrompt: false'),
    safariWiring: h.includes('os.safari_web_id'),
  };
 
  const appId = meta ? meta[0].match(/"app_id":"([^"]+)"/)?.[1] : null;
 
  if (appId) {
    try {
      const cfg = await (
        await fetch(
          'https://onesignal.com/api/v1/sync/' + appId + '/web?t=' + Date.now()
        )
      ).json();
 
      r.onesignalDashboard = {
        bellConfigured: 'bell' in cfg.config.prompts,
        nativeConfigured: 'native' in cfg.config.prompts,
        slidedownPromptCount:
          cfg.config.prompts.slidedown?.prompts?.length || 0,
        slidedownPromptTypes: (cfg.config.prompts.slidedown?.prompts || []).map(
          (p) => ({
            type: p.type,
            autoPrompt: p.autoPrompt,
            delay: p.delay,
          })
        ),
      };
    } catch (e) {
      r.onesignalDashboard = 'fetch failed: ' + e.message;
    }
  }
 
  const regs = await navigator.serviceWorker.getRegistrations();
 
  r.browser = {
    serviceWorkers: regs.map((g) => ({
      scope: g.scope,
      script: g.active?.scriptURL,
    })),
    notificationPermission: Notification.permission,
    oneSignalPermission: window.OneSignal?.Notifications?.permission,
    optedIn: window.OneSignal?.User?.PushSubscription?.optedIn,
    onesignalId:
      window.OneSignal?.User?.onesignalId ||
      window.OneSignal?.User?.PushSubscription?.id,
    nativePromptPageViews: parseInt(
      localStorage.getItem('_vendo_onesignal_native_pv') || '0',
      10
    ),
  };
 
  console.log('=== VENDO x ONESIGNAL DIAGNOSTIC ===');
  console.log('1. METAFIELD:', r.metafield);
  console.log(
    '2. THEME EXTENSION VERSION (expect all true):',
    r.hasNewInitCode
  );
  console.log(
    '3. ONESIGNAL DASHBOARD (cleared if all false/0):',
    r.onesignalDashboard
  );
  console.log('4. BROWSER STATE:', r.browser);
 
  const v = [];
 
  if (!r.hasNewInitCode.requestPermission) {
    v.push('THEME EXTENSION IS OLD - redeploy needed');
  } else {
    v.push('Theme extension has latest init code');
  }
 
  if (
    typeof r.onesignalDashboard === 'object' &&
    (r.onesignalDashboard.bellConfigured ||
      r.onesignalDashboard.nativeConfigured ||
      r.onesignalDashboard.slidedownPromptCount > 0)
  ) {
    v.push(
      'ONESIGNAL DASHBOARD still has prompts - clear Permission Prompt Setup'
    );
  } else if (typeof r.onesignalDashboard === 'object') {
    v.push('OneSignal dashboard is clean');
  }
 
  if (r.browser.notificationPermission === 'denied') {
    v.push('BROWSER permission DENIED - reset via lock icon');
  } else if (r.browser.notificationPermission === 'granted') {
    v.push('Already subscribed - test in fresh incognito');
  } else {
    v.push('Browser permission is default (ready)');
  }
 
  console.log('5. VERDICT:');
  v.forEach((x) => console.log(' - ' + x));
})();

What the verdict tells you:

• “THEME EXTENSION IS OLD” → contact Vendo support. The theme extension needs to be redeployed.
• “ONESIGNAL DASHBOARD still has prompts” → go to OneSignal → Web Push → Permission Prompt Setup and delete the entries listed there. Vendo’s init options can only add prompts, not suppress dashboard prompts (per OneSignal’s Web SDK reference ).
• “BROWSER permission DENIED” → your test browser blocked notifications before. Click the lock icon in the URL bar → Site settings → Notifications → Ask.
• “Already subscribed” → prompts do not show again in this browser profile. Test in a fresh incognito window.

Quick check: which App ID is the storefront using?

After you save credentials in Vendo, the storefront page HTML includes your OneSignal App ID. The fastest way to confirm that a credential change reached the storefront (and is not stuck in Shopify’s page cache) is to paste this in the DevTools Console on any storefront page:

const m = document.documentElement.innerHTML.match(
  /"onesignal":\{[^}]*"app_id":"([^"]*)"/
);
console.log('app_id rendered into page:', m?.[1] || 'MISSING');

If the printed App ID matches what you saved in the Vendo app, the metafield reached the storefront. If it shows an old value, Shopify’s page cache still serves the old page. See Storefront still shows old App ID below.

Troubleshooting

OneSignal init warning: “Can only be used on…”

With debug mode on (?vendo_debug=1), the storefront DevTools console shows:

[Vendo] OneSignal init warning: Can only be used on: https://<some-other-store>.myshopify.com

The OneSignal app whose App ID is configured in Vendo has a Site URL set to a different store. OneSignal binds each Web Push app to a single origin and rejects initialization from any other origin.

This almost always happens when someone copied an App ID from a sister store instead of creating a dedicated OneSignal app. It also happens in a less obvious case: an app with multiple Site URLs configured. The OneSignal SDK loads its config through JSONP (no Origin header), so it gets back the primary/default Site URL. Even adding your new store URL as a secondary URL does not fix it.

Fix: create a dedicated OneSignal app for this store:

1. OneSignal → + New App/Website → Web Push → Site URL = your store’s https://<store>.myshopify.com
2. Use Custom Code with the service worker paths from Step 2
3. Copy the new App ID + REST API Key into the OneSignal Settings tab in the Vendo app and click Save
4. Wait about 1–2 minutes for the Shopify storefront cache to refresh (or follow the next entry to force it)

Storefront still shows old App ID after changing credentials

You updated the OneSignal credentials in the Vendo app and verified that the new App ID is in the metafield. But the storefront diagnostic still shows the old App ID, and OneSignal init still warns about the old Site URL.

This is Shopify’s storefront page cache. The Vendo theme block writes the OneSignal config from the Vendo app metafield directly into the page HTML. Shopify caches that HTML at its edge. The cached version stays even with ?cachebust= query strings.

Force a refresh. Any one of these works:

• Re-save the page you are testing on: Online Store → Pages → click the page → Save (no changes needed). Saving clears the edge cache for that page.
• Toggle the Vendo theme block: Online Store → Themes → Customize → App embeds → toggle Vendo off → Save → toggle on → Save. This clears the cache for every page.
• Wait: the Shopify storefront cache usually refreshes within 1–10 minutes.

After the cache clears, paste the Quick check snippet again. The App ID should match the App ID in the Vendo admin.

Settings changed in OneSignal dashboard haven’t taken effect

You changed the Site URL, prompt config or service worker paths in the OneSignal dashboard. But the storefront still behaves as if the old values are in place.

OneSignal caches its SDK config response (/sync/<app-id>/web) at the CDN for up to 1 hour. The OneSignal SDK loads this config through a JSONP <script> tag, which does not send an Origin header. The response varies based on the request, so a curl with an Origin header may show fresh data while the browser sees stale data. Two layers can lag independently:

If both layers still look stuck after the lag times above, run the diagnostic script and compare the four sections. Any mismatch tells you which layer is stale.

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 are accessing the store through its primary domain
• In the OneSignal dashboard, Customize service worker paths and filenames is on with the four values from Step 2. If this section is collapsed or off, OneSignal falls back to the root path and Shopify rejects the request

”Typical Site” was selected during OneSignal setup

Vendo requires the Custom Code integration type. Typical Site does not show the service worker path settings. So the SDK tries to load /OneSignalSDKWorker.js from your store root. Shopify blocks that request and push subscription fails silently.

To fix this, do one of these in the OneSignal dashboard:

• Switch the app’s integration type to Custom Code (Settings > Platforms > Web)
• 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 > Web push, confirm that at least one prompt toggle (Subscription Bell, Push Slide Prompt or Native Browser Prompt) is on. All four are off by default.
• Check the trigger delay. For example, a Push Slide set to 3 page views does not show on the first page load
• Make sure that your browser allows notifications (check browser settings)
• Verify that you have not 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