OneSignal Integration

Vendo’s OneSignal integration enables powerful push notification capabilities by syncing your Shopify customer data and e-commerce events to OneSignal. This allows you to create targeted push notification campaigns based on customer behavior and purchase history.

Overview

The OneSignal integration provides:

• User Tag Sync: Customer properties synced as OneSignal tags for segmentation
• E-commerce Events: Order and cart events for behavioral targeting
• Automated Campaigns: Trigger push notifications based on customer actions
• Cross-channel Engagement: Reach customers via web push, mobile push, and in-app messages

Key Benefits

• Send abandoned cart recovery notifications
• Notify customers of order fulfillment and delivery
• Create customer segments based on purchase behavior
• Personalize notifications with customer data

Web Push Setup (OneSignal Dashboard)

Before configuring Vendo, you need to set up your OneSignal app for web push. Follow these steps in order.

Prerequisites

• A OneSignal account  (free tier works)
• Admin access to your Shopify store
• The Vendo app installed on your Shopify store
• The Vendo theme block enabled (Online Store > Themes > Customize > App embeds > Vendo)

Step 1: Create a OneSignal App

1. Log in to your OneSignal dashboard 
2. Click New App/Website
3. Enter your app name (e.g., your store name)
4. Select Web as the platform
5. Click Next

Step 2: Configure Web Push Platform

1. Choose Custom Code as the integration type (not Shopify or WordPress)
2. Fill in the Site Settings:
   • Site Name: Your store name (shown in the notification prompt)
   • Site URL: Your Shopify store URL (e.g., https://yourstore.myshopify.com)
   • Default Icon URL: Upload a square icon (recommended: 256x256 PNG) — this appears in the notification prompt and on push notifications your customers receive
3. Under Permission Prompt Setup, you can keep the defaults or customize later
4. Click Save

Step 3: Get Your Credentials

1. Go to Settings > Keys & IDs
2. Note down:
   • App ID: Your unique OneSignal App ID (UUID format, e.g., 580acc63-36bf-43b0-8db1-56be18dac368)
   • REST API Key: Required for server-side events (starts with OS...)

Step 4: Configure the Service Worker Path

Shopify doesn’t allow serving files from the store’s root URL. Vendo works around this by automatically serving the required OneSignal service worker file through the Shopify App Proxy at /apps/vendo/. You need to tell OneSignal where to find it.

1. In OneSignal, go to Settings > Push & In-App > Web Settings
2. Scroll down to Advanced Push Settings and expand it
3. Toggle on “Customize service workers paths and filenames”
4. Fill in the following fields:

5. Click Save

Why is this needed? OneSignal requires a service worker file (OneSignalSDKWorker.js) on your store’s domain to receive push notifications. Vendo automatically serves this file at https://yourstore.myshopify.com/apps/vendo/OneSignalSDKWorker.js — no manual file uploads required. These settings tell OneSignal where to find it.

Note: The Updater Filename and Service Worker Filename are the same file. OneSignal v16 uses a single service worker for both purposes.

Vendo App Configuration

Step 5: Enter Credentials in Vendo

1. Open the Vendo app in your Shopify admin
2. Navigate to Integrations > OneSignal
3. Enter your credentials:
   • App ID: Your OneSignal App ID (from Step 3)
   • REST API Key: Your OneSignal REST API Key (from Step 3)
4. Click Save

Step 6: Enable the Vendo Theme Block

The theme block loads the OneSignal SDK on your storefront. Without it, the notification prompt won’t appear.

1. In Shopify admin, go to Online Store > Themes
2. Click Customize on your active theme
3. Click App embeds (puzzle piece icon in the left sidebar)
4. Toggle Vendo on
5. Click Save

Step 7: Select Events to Enable

In the Vendo app under OneSignal settings, choose which events to sync:

• Customer tags/properties (for segmentation)
• Order events (order received, fulfilled, delivered, refunded)
• Abandoned checkout notifications
• Fulfillment and delivery events

Step 8: Historical Data Sync

Vendo will automatically backfill your existing customers and recent order history to OneSignal. This happens in the background after you save your credentials.

Verification & Testing

After completing setup, verify everything is working:

1. Verify the Service Worker URL

Visit this URL in your browser (replace with your store domain):

https://yourstore.myshopify.com/apps/vendo/OneSignalSDKWorker.js

You should see a single line of JavaScript code. If you get a 404, ensure the Vendo app is installed.

2. Check the Notification Prompt

1. Open your storefront in a browser (use an incognito/private window or a fresh browser profile for clean testing)
2. You should see the OneSignal notification permission prompt (bell icon or slide-down prompt, depending on your OneSignal settings)
3. Click Allow to subscribe

3. Verify Service Worker Registration

1. Open DevTools (F12) on your storefront
2. Go to Application tab > Service Workers
3. You should see a service worker from OneSignalSDKWorker.js with status “activated and is running”
4. The scope should show https://yourstore.myshopify.com/apps/vendo/

4. Send a Test Push Notification

1. In the OneSignal dashboard , go to Messages > Push
2. Click New Message
3. Write a test message and select your test subscriber
4. Send the notification
5. You should see a browser notification appear on your device

5. Verify in OneSignal Dashboard

Go to Audience > Subscriptions and confirm your test subscription appears with the correct device type (Web Push - Chrome/Firefox/etc.).

Events Tracked

OneSignal events are tracked to enable behavioral segmentation and automated notifications.

Event Properties

All events include these properties (as strings, per OneSignal requirements):

User Tags (Properties)

OneSignal uses “tags” instead of properties. All values are converted to strings.

Customer Tags

User Identification

Vendo uses an identified-only approach — anonymous visitors are not tracked in OneSignal. This prevents duplicate users and ensures clean data.

Four Ways Users Are Identified

How It Works

1. Anonymous visitors browse the store — events are sent to other destinations but not to OneSignal
2. When a visitor is identified (via any of the four methods above), their identifier is stored in the browser
3. From that point on, all client-side events are sent to OneSignal with the correct identifier
4. If a push subscriber later logs in or purchases, OneSignal automatically merges the identities

Identity Priority

When multiple identifiers are available, Vendo uses this priority:

1. external_id (Shopify Customer ID or Email) — from login, checkout, or newsletter
2. onesignal_id — from push subscription only

Once an external_id is set, it takes precedence. This ensures server-side events (orders from the pipeline) match the same user.

Why No Anonymous Tracking?

Previous versions tracked anonymous visitors using Shopify’s session cookie. This created duplicate OneSignal users that could never be properly merged. The identified-only approach ensures every OneSignal user is real and actionable.

Example Payloads

User Tags Update

When customer data is synced to OneSignal:

{
  "external_id": "6359703453860",
  "email": "customer@email.com",
  "phone": "+14155551234",
  "tags": {
    "email": "customer@email.com",
    "first_name": "John",
    "last_name": "Smith",
    "total_spent": "1523.50",
    "order_count": "12",
    "verified_email": "true",
    "marketing_state": "enabled",
    "tax_exempt": "false",
    "first_order_date": "2023-06-20T14:20:00Z",
    "last_order_date": "2024-01-10T09:15:00Z",
    "customer_created_at": "2023-06-15T10:30:00Z",
    "customer_tags": "VIP,repeat-buyer,newsletter",
    "email_marketing_consent": "subscribed"
  }
}

Order Received Event

{
  "external_id": "6359703453860",
  "name": "order_received",
  "properties": {
    "order_id": "1001",
    "shopify_order_id": "5363269534010",
    "email": "customer@email.com",
    "currency": "USD",
    "cart_total_amount": "162.49",
    "cart_subtotal_amount": "149.99",
    "total_discounts": "15.00",
    "tax_amount": "12.50",
    "shipping_amount": "10.00",
    "product_count": "2",
    "payment_gateway": "shopify_payments",
    "source": "Vendo - Shopify App",
    "version": "2.1.0"
  },
  "idempotency_key": "order_received_5363269534010"
}

Cart Abandoned Event

{
  "external_id": "6359703453860",
  "name": "cart_abandoned",
  "properties": {
    "checkout_id": "29563359395886",
    "email": "customer@email.com",
    "currency": "USD",
    "cart_total_amount": "97.49",
    "cart_subtotal_amount": "89.99",
    "total_discounts": "0",
    "product_count": "1",
    "checkout_url": "https://mystore.com/checkouts/abc123/recover",
    "source": "Vendo - Shopify App",
    "version": "2.1.0"
  },
  "idempotency_key": "cart_abandoned_29563359395886"
}

Order Fulfilled Event

{
  "external_id": "6359703453860",
  "name": "order_fulfilled",
  "properties": {
    "order_id": "1001",
    "shopify_order_id": "5363269534010",
    "fulfillment_id": "4751610282298",
    "email": "customer@email.com",
    "fulfillment_status": "success",
    "fulfillment_service": "manual",
    "tracking_number": "1Z999AA10123456784",
    "fulfillment_speed_days": "2",
    "source": "Vendo - Shopify App",
    "version": "2.1.0"
  },
  "idempotency_key": "order_fulfilled_4751610282298"
}

Order Delivered Event

{
  "external_id": "6359703453860",
  "name": "order_delivered",
  "properties": {
    "order_id": "1001",
    "shopify_order_id": "5363269534010",
    "fulfillment_id": "4751610282298",
    "email": "customer@email.com",
    "fulfillment_status": "delivered",
    "delivery_date": "2024-01-17T14:30:00Z",
    "delivery_speed_days": "3",
    "source": "Vendo - Shopify App",
    "version": "2.1.0"
  },
  "idempotency_key": "order_delivered_4751610282298"
}

Order Refunded Event

{
  "external_id": "6359703453860",
  "name": "order_refunded",
  "properties": {
    "order_id": "1001",
    "shopify_order_id": "5363269534010",
    "refund_id": "789456123",
    "email": "customer@email.com",
    "currency": "USD",
    "refund_amount": "162.49",
    "cart_total_amount": "162.49",
    "cancel_reason": "customer",
    "source": "Vendo - Shopify App",
    "version": "2.1.0"
  },
  "idempotency_key": "order_refunded_789456123"
}

Client-Side Event Payloads

Client-side events are tracked via the Shopify Web Pixel and sent to OneSignal’s Custom Events API. All property values are converted to strings per OneSignal requirements.

Page Viewed Event (Client-Side)

{
  "events": [{
    "name": "page_viewed",
    "external_id": "shop_client_abc123",
    "properties": {
      "timestamp": "2024-01-15T10:30:00.000Z",
      "page_title": "Summer Collection – My Store",
      "page_type": "collection",
      "url": "https://mystore.com/collections/summer",
      "utm_source": "google",
      "utm_medium": "cpc",
      "utm_campaign": "summer-sale"
    },
    "idempotency_key": "page_viewed_shop_client_abc123_1705314600000"
  }]
}

Product Viewed Event (Client-Side)

{
  "events": [{
    "name": "product_viewed",
    "external_id": "6359703453860",
    "properties": {
      "timestamp": "2024-01-15T10:32:00.000Z",
      "product_id": "gid://shopify/Product/7894561230",
      "product_title": "Classic T-Shirt",
      "product_type": "Apparel",
      "product_vendor": "My Brand",
      "product_price": "29.99",
      "product_sku": "TSHIRT-BLK-M",
      "utm_source": "google",
      "utm_medium": "cpc"
    },
    "idempotency_key": "product_viewed_6359703453860_1705314720000"
  }]
}

Product Added To Cart Event (Client-Side)

{
  "events": [{
    "name": "product_added_to_cart",
    "external_id": "6359703453860",
    "properties": {
      "timestamp": "2024-01-15T10:35:00.000Z",
      "product_id": "gid://shopify/Product/7894561230",
      "product_title": "Classic T-Shirt",
      "product_price": "29.99",
      "quantity": "2",
      "currency": "USD",
      "cart_total_amount": "59.98"
    },
    "idempotency_key": "product_added_to_cart_6359703453860_1705314900000"
  }]
}

Product Removed From Cart Event (Client-Side)

{
  "events": [{
    "name": "product_removed_from_cart",
    "external_id": "6359703453860",
    "properties": {
      "timestamp": "2024-01-15T10:36:00.000Z",
      "product_id": "gid://shopify/Product/7894561230",
      "product_title": "Classic T-Shirt",
      "quantity": "1"
    },
    "idempotency_key": "product_removed_from_cart_6359703453860_1705314960000"
  }]
}

Collection Viewed Event (Client-Side)

{
  "events": [{
    "name": "collection_viewed",
    "external_id": "6359703453860",
    "properties": {
      "timestamp": "2024-01-15T10:28:00.000Z",
      "collection_title": "Summer Collection",
      "collection_id": "gid://shopify/Collection/123456789",
      "utm_source": "google",
      "utm_medium": "cpc"
    },
    "idempotency_key": "collection_viewed_6359703453860_1705314480000"
  }]
}

Search Submitted Event (Client-Side)

{
  "events": [{
    "name": "search_submitted",
    "external_id": "6359703453860",
    "properties": {
      "timestamp": "2024-01-15T10:25:00.000Z",
      "search_query": "t-shirt"
    },
    "idempotency_key": "search_submitted_6359703453860_1705314300000"
  }]
}

Checkout Started Event (Client-Side)

{
  "events": [{
    "name": "checkout_started",
    "external_id": "6359703453860",
    "properties": {
      "timestamp": "2024-01-15T10:40:00.000Z",
      "checkout_token": "abc123def456",
      "order_id": "gid://shopify/Order/5363269534010",
      "currency": "USD",
      "cart_total_amount": "162.49",
      "cart_subtotal_amount": "149.97",
      "total_discounts": "0",
      "tax_amount": "12.52",
      "shipping_amount": "0",
      "product_count": "3",
      "utm_source": "google",
      "utm_medium": "cpc"
    },
    "idempotency_key": "checkout_started_6359703453860_1705315200000"
  }]
}

Checkout Completed Event (Client-Side)

{
  "events": [{
    "name": "checkout_completed",
    "external_id": "6359703453860",
    "properties": {
      "timestamp": "2024-01-15T10:45:00.000Z",
      "checkout_token": "abc123def456",
      "order_id": "gid://shopify/Order/5363269534010",
      "currency": "USD",
      "cart_total_amount": "162.49",
      "cart_subtotal_amount": "149.97",
      "total_discounts": "0",
      "tax_amount": "12.52",
      "shipping_amount": "10.00",
      "product_count": "3",
      "utm_source": "google",
      "utm_medium": "cpc"
    },
    "idempotency_key": "checkout_completed_6359703453860_1705315500000"
  }]
}

User Tags from Client-Side (on Checkout Completed)

When a customer completes checkout, their profile tags are also updated:

{
  "properties": {
    "tags": {
      "email": "customer@email.com",
      "phone": "+14155551234",
      "first_name": "John",
      "last_name": "Smith",
      "shopify_customer_id": "6359703453860",
      "utm_source": "google",
      "utm_medium": "cpc",
      "utm_campaign": "summer-sale",
      "gclid": "CjwKCAjw...",
      "initial_utm_source": "facebook",
      "initial_utm_medium": "social",
      "first_seen": "2024-01-01T08:00:00.000Z"
    }
  },
  "subscriptions": [
    {
      "type": "Email",
      "token": "customer@email.com",
      "enabled": true
    },
    {
      "type": "SMS",
      "token": "+14155551234",
      "enabled": true
    }
  ]
}

What to Expect in OneSignal

After Setup

1. User Tags Appear: Within hours, customer tags will sync to matching OneSignal users
2. Events Flow: E-commerce events will appear in user activity
3. Segments Available: You can create segments using synced tags

Creating Segments

Use synced tags to create powerful segments:

Automated Messages

Set up automated push notifications:

1. Abandoned Cart Recovery

   • Trigger: cart_abandoned event
   • Timing: 1 hour after abandonment
   • Message: “You left items in your cart! Complete your purchase now.”

2. Order Shipped

   • Trigger: order_fulfilled event
   • Message: “Your order #{{order_id}} has been shipped! Track it here.”

3. Delivery Confirmation

   • Trigger: order_delivered event
   • Message: “Your order has been delivered! We hope you love it.”

Use Cases

1. Abandoned Cart Recovery

Setup:

1. Create a Journey in OneSignal triggered by cart_abandoned event
2. Wait 1 hour
3. Send push notification with recovery link
4. Include the checkout_url property in the notification

Example Notification:

Title: Don't forget your items!
Body: You left {{product_count}} item(s) worth ${{cart_total_amount}} in your cart.
URL: {{checkout_url}}

2. Order Status Updates

Setup:

1. Create separate Journeys for order_fulfilled and order_delivered
2. Send immediate notifications
3. Include tracking information

Fulfilled Notification:

Title: Your order is on the way!
Body: Order #{{order_id}} has been shipped. Tracking: {{tracking_number}}

3. VIP Customer Engagement

Setup:

1. Create a segment where total_spent > “1000”
2. Send exclusive offers to this segment
3. Use first_name tag for personalization

VIP Notification:

Title: Exclusive offer for you, {{first_name}}!
Body: As a valued customer, enjoy 20% off your next order.

4. Re-engagement Campaigns

Setup:

1. Create a segment where last_order_date is more than 90 days ago
2. Target inactive customers with win-back campaigns

Data Sync Frequency

Troubleshooting

Service Worker 404 Error

Symptom: Console shows Failed to register a ServiceWorker ... A bad HTTP response code (404) was received when fetching the script.

Check the URL in the error message:

• If the URL is https://yourstore.myshopify.com/OneSignalSDKWorker.js (root path) — the OneSignal dashboard service worker path is not configured. Follow Step 4 to set the path to /apps/vendo/.
• If the URL is https://yourstore.myshopify.com/apps/vendo/OneSignalSDKWorker.js — the Vendo app proxy is not working. Verify the Vendo app is installed and try visiting the URL directly in your browser.

Notification Prompt Not Appearing

1. Check the Vendo theme block: Go to Online Store > Themes > Customize > App embeds and make sure the Vendo block is toggled on
2. Check OneSignal credentials: In the Vendo app, verify the App ID is correct
3. Try incognito mode: The prompt may have been previously dismissed. Open a private/incognito window to test with a clean state
4. Check browser permissions: Click the lock icon in the browser address bar and make sure Notifications are not set to “Block”

OneSignal Shows “Delivered” but No Notification Appears

This means the integration is working correctly — the issue is with your browser or OS notification settings.

1. Check macOS notification settings: Go to System Settings > Notifications > find your browser (Chrome, Firefox, etc.) and ensure notifications are enabled and the alert style is not set to “None”
2. Check Do Not Disturb: Make sure Focus/DND mode is not active (check the Control Center in the macOS menu bar)
3. Check browser-level permissions: Go to chrome://settings/content/notifications (Chrome) and ensure your store’s domain is in the “Allowed” list
4. Clear site data and re-subscribe: If notifications worked before but stopped:
   • Go to chrome://settings/content/all
   • Find your store’s domain and click Clear data
   • Revisit the storefront and re-subscribe when prompted
5. Try a different browser profile: If the above steps don’t help, test with a fresh browser profile to rule out profile-level corruption. If notifications work in the new profile, clear all site data for the store domain in your main profile

Tags Not Appearing

1. User must be identified: Tags only sync for identified users (push subscribers, logged-in customers, newsletter signups, or checkout completions). Anonymous visitors are not tracked.
2. Verify external_id match: If using server-side tags, the user must have been identified with a Shopify Customer ID or email
3. Allow sync time: Initial sync can take several hours

Events Not Triggering

1. User must be identified: Client-side events are only sent to OneSignal after the user is identified via push subscription, login, newsletter, or checkout
2. Verify API key: Ensure REST API Key has correct permissions
3. Review idempotency: Duplicate events are ignored via idempotency_key
4. Check the Vendo theme block: Login and newsletter detection require the theme block to be enabled

Push Notifications Not Sending

1. Check segment criteria: Ensure segment filters match user tags
2. Verify subscription: User must have active push subscription
3. Review notification settings: Check OneSignal delivery settings
4. Check OneSignal dashboard: Go to Messages > Delivery and check if the message shows as “Delivered” — if so, the issue is on the device side (see “OneSignal Shows Delivered but No Notification Appears” above)

Related

• OneSignal Destination Overview — General OneSignal destination setup and capabilities
• OneSignal Web Push Setup — Detailed web push configuration
• OneSignal Events & Properties — Complete event reference
• Shopify Source Overview — Full Shopify integration documentation

Support

For assistance with your OneSignal integration:

• Email: support@vendodata.com
• Documentation: https://docs.vendodata.com 
• OneSignal Help: https://documentation.onesignal.com