How OneSignal Identification Works

Vendo uses an identified-only approach for OneSignal. Anonymous visitors are not tracked — users must be identified through one of four methods before any events are sent. This prevents duplicate users and ensures clean data.

The Four Identification Methods

1. Web Push Subscription

When a visitor subscribes to push notifications:

The visitor clicks “Allow” on the push notification prompt
OneSignal automatically creates a user with an internal OneSignal ID
Vendo’s theme extension captures this OneSignal ID
The ID is stored in the browser’s localStorage
Future client-side events (page views, product views, etc.) are sent to OneSignal using this ID

This is the earliest identification point — it happens before the visitor logs in or makes a purchase.

When a visitor submits a newsletter or email signup form:

Vendo’s theme extension listens for form submissions on common newsletter form patterns
When detected, the email address is captured
Vendo calls OneSignal.login(email) to create or identify the user
Future events are sent using the email as the external_id

Supported form patterns:

Shopify default newsletter forms (/contact#contact_form)
Forms with newsletter in the ID or class
Klaviyo forms
Custom forms with email inputs

When a customer logs in to their Shopify account:

Vendo’s theme extension detects the logged-in customer using Shopify’s Liquid template variables
The customer’s Shopify ID and email are available immediately on page load
Vendo calls OneSignal.login() with the configured identifier (Shopify Customer ID or email)
All events during this session are sent with the identified user

The identifier used (Customer ID vs email) is configured in the Vendo app under Settings > Customer Identifier.

4. Checkout Completed

When a customer completes a purchase:

Shopify’s web pixel fires the checkout_completed event with customer details
Vendo stores the customer’s identifier in localStorage
The theme extension picks up this identifier and calls OneSignal.login()
The checkout_completed event itself is also sent to OneSignal with the correct identifier

Identity Merging

A common scenario: a visitor subscribes to push first (getting an OneSignal ID), then later logs in or makes a purchase.

What happens:

Push subscription → User exists in OneSignal with onesignal_id
Login/checkout → Vendo calls OneSignal.login(shopify_customer_id)
OneSignal links the push subscription to the identified user
The user now has both an onesignal_id and an external_id
Server-side events (orders, etc.) sent via external_id reach the correct user

Result: No duplicate users. The push subscription, client-side events, and server-side events all point to the same user.

Data Flow Diagram


Visitor arrives on store
  │
  ├─ Anonymous browsing
  │  └─ Events sent to other destinations (Mixpanel, GA4, etc.)
  │     OneSignal events are NOT sent yet
  │
  ├─ Path A: Subscribes to push
  │  └─ OneSignal creates user → onesignal_id captured
  │     └─ Events now sent to OneSignal via onesignal_id
  │
  ├─ Path B: Signs up for newsletter
  │  └─ Email captured → OneSignal.login(email)
  │     └─ Events now sent via external_id (email)
  │
  ├─ Path C: Logs in
  │  └─ Shopify customer detected → OneSignal.login(identifier)
  │     └─ Events now sent via external_id
  │
  └─ Path D: Completes checkout
     └─ Customer ID captured → OneSignal.login(identifier)
        └─ Events now sent via external_id

If Path A happened first, then Path C/D later:
  └─ OneSignal merges: push subscription linked to external_id
     └─ Server-side events (pipeline) reach the same user

Edge Cases

Push subscriber who never logs in

Tracked via onesignal_id only
Client-side events (page views, product views) are sent to OneSignal
No server-side events (no orders to export)
You can still send push notifications to this user
If they later log in, their identity merges

Returning identified user

localStorage persists the identifier across sessions
On return visits, the user is immediately identified — no need to re-identify
Events start flowing to OneSignal from the first page view

User logs in on a different device

A new push subscription is created on the new device
The same external_id is set via OneSignal.login()
OneSignal merges both devices under the same user
Push notifications can be sent to all their devices

If a visitor signs up with personal@email.com but logs in as Shopify customer 123
The first identification uses the email
On login, Vendo updates the identifier to the Shopify customer ID
OneSignal may create a separate user if the email doesn’t match — this is expected and handled by OneSignal’s identity system

Theme extension not installed

Push settings, login detection, and newsletter capture won’t work
Only checkout identification (from the web pixel) will function
We recommend always enabling the Vendo theme block

Multiple tabs open

localStorage is shared across tabs
Identification in one tab is immediately available to others
No duplicate identifications occur

Server-Side Events (Pipeline)

Server-side events (orders, fulfillments, etc.) are exported from Shopify to BigQuery and then forwarded to OneSignal by the Vendo pipeline. These always use the Shopify Customer ID as the external_id.

For this to work, the OneSignal user must have an external_id set (via login, checkout, or newsletter). Push-only subscribers without an external_id won’t receive server-side events — which is correct since they don’t have orders.

Configuration

Customer Identifier

In the Vendo app under Settings > Customer Identifier, choose how customers are identified:

Option	When to Use
Shopify Customer ID (default)	Most stores — provides a stable, unique identifier
Email	When you want to match customers across systems using email

This setting affects all destinations, not just OneSignal.