> ## Documentation Index
> Fetch the complete documentation index at: https://docs.sagepilot.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Shopify Web Push setup

> Enable Sagepilot Web Push on a Shopify Online Store through the app embed and Theme App Extension.

Shopify Online Stores use the Sagepilot app embed and Theme App Extension for Web Push. The extension supplies the signed Shopify customer identity, installs the storefront worker and shows the notification-consent button. Do not install `@sagepilot-ai/web-push-addon` or paste a service-worker script into your Liquid theme.

<Note>
  Use the npm [Web Push integration](/sdks/web/push-notifications) only for custom or headless storefronts where your application owns authentication and public service-worker assets.
</Note>

## Prerequisites

* The Sagepilot Shopify app is installed and connected under **Settings** > **Integrations**.
* A Website Widget channel is active and connected to the Shopify store.
* An active Push Notifications channel has **Web Push**, a complete VAPID configuration and an **Identity signing secret** under **SDK & delivery**.
* The test shopper can log in to the Online Store and exists as a synced Sagepilot customer.
* The published storefront uses HTTPS and a browser that supports Web Push.

If the workspace has multiple active Web Push channels, confirm with Sagepilot which Push channel is bound to the Shopify store before testing. An ambiguous channel selection prevents the extension from offering registration.

## 1. Connect the storefront widget

1. In Sagepilot, open **Channels**.
2. Create or open the Website Widget channel used by this store.
3. Open the **Shopify** section.
4. Select the store and click **Connect channel**. If another widget channel is connected, click **Use this channel** only when you intend to replace it.
5. Click **Open theme editor**.

The channel should show **Widget enabled** after the app embed is active and the published theme has been saved. Use **Refresh status** after returning from Shopify.

## 2. Enable Web Push in the Shopify theme

In the Shopify theme editor:

1. Open **App embeds**.
2. Turn on **Sagepilot widget**.
3. Turn on **Enable customer notifications** in the embed settings.
4. Keep the notification button label explicit about marketing, for example **Enable marketing notifications**.
5. Click **Save**.

The Shopify extension currently enables both marketing and support Push preferences after the shopper accepts. The visible button and disclosure therefore need to mention marketing notifications clearly.

<Warning>
  The theme-editor preview does not initialize Web Push. Save the theme, then test from the published storefront as a real logged-in shopper.
</Warning>

## 3. Register a shopper

1. Open the published storefront in a supported browser.
2. Log in through the store's customer-account flow.
3. Navigate to a storefront page and locate the **Enable marketing notifications** button.
4. Click the button and allow the browser notification prompt.

Sagepilot registers the browser only after the shopper clicks. The extension does not request browser permission during page load, login or theme preview.

The button is not shown to guests. The signed-in Shopify customer must also resolve to exactly one synced Sagepilot customer and an eligible Push channel. If browser permission was already denied, the shopper must change the site's notification permission in browser settings.

## 4. Send a real test notification

1. In Sagepilot, create a test list or segment containing only the registered Shopify customer.
2. Create a Push template with a same-origin storefront destination, such as a product, collection or customer-account URL.
3. Send it through a Campaign or Journey Push node.
4. Confirm the notification arrives with the storefront in the foreground, background and closed.
5. Click the notification and confirm the destination opens.

Do not use the Push channel **Test Send** form to validate Shopify Web Push; that form currently targets Android/FCM. A Campaign or Journey exercises the real customer and endpoint selection flow.

## 5. Verify analytics independently

Check each lifecycle stage separately:

| Stage | What it proves |
| - | - |
| Queued | Sagepilot accepted the send into its delivery pipeline. |
| Provider accepted | The Web Push provider accepted the request. |
| Received | The Shopify service worker received the payload. |
| Presentation requested | The browser accepted the request to display it. |
| Opened | The shopper clicked the notification. |
| Destination opened | The same-origin storefront destination loaded successfully. |

The extension stores signed observations if no storefront page is open and uploads them on the next identified shopper session. A queued send alone does not prove browser receipt or presentation.

## Disable Shopify Web Push

To stop offering registration, clear **Enable customer notifications** in the app embed settings and save the theme. Returning storefront sessions can then clean up their local subscription.

To stop Web Push sends immediately for every Shopify shopper, disable **Web Push** on the Push Notifications channel or make those endpoints ineligible through your notification preferences. Turning off the app embed alone prevents its script from running and is not an immediate global endpoint revocation.

## Troubleshooting

| Symptom | What to check |
| - | - |
| Notification button is missing | Test the saved, published storefront rather than theme preview. Confirm the shopper is logged in, synced to Sagepilot, the app embed and **Enable customer notifications** are on, and the Push channel is eligible. |
| **Widget enabled** does not appear | Confirm the correct published theme was saved, then click **Refresh status** in the channel's **Shopify** section. |
| Browser prompt does not appear | Check whether notification permission is already granted or denied for the storefront origin. Browsers do not allow the extension to override a denial. |
| Registration reports that Push is not configured | Confirm the Push channel is active, has both VAPID keys and contact email, and has an identity signing secret. Resolve multiple eligible Push channels with Sagepilot. |
| Registered shopper receives nothing | Confirm the Campaign or Journey targets the synced customer, Web marketing consent is enabled and analytics progress beyond queued/provider accepted. Also check browser and operating-system settings. |
| Opened exists but destination opened is missing | Use a same-origin storefront URL and revisit the storefront while signed in so retained observations can upload. |

For payload behavior and analytics definitions, see [Web Push integration](/sdks/web/push-notifications#8-deep-links-images-and-analytics).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.