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

# Shopify

> Conecta Shopify a OneSignal a través de la integración Vendo para notificaciones push web, etiquetas de clientes, eventos de comercio y segmentación por comportamiento.

OneSignal se ha asociado con Vendo para crear una integración de Shopify perfecta. Vendo despliega el SDK de OneSignal en tu tienda de Shopify con un solo clic — sin necesidad de editar manualmente el código del tema. Sincroniza etiquetas de clientes, eventos de navegación del lado del cliente y eventos de comercio del lado del servidor a OneSignal para que puedas crear segmentos y desencadenar campañas push basadas en comportamiento real e historial de compras.

Para la documentación de Vendo, consulta [Vendo OneSignal Destination](https://docs.vendodata.com/destinations/onesignal/overview).

## Requisitos previos

Antes de comenzar, asegúrate de tener:

* Una tienda Shopify con la [aplicación Vendo](https://apps.shopify.com/) instalada
* Una cuenta y aplicación OneSignal (plataforma Web)
* Tu **App ID** de OneSignal (obligatorio)
* Tu **REST API Key** de OneSignal (obligatoria para eventos del lado del servidor como sincronización de pedidos y etiquetado de usuarios)

## Configuración de OneSignal

<Steps>
  <Step title="Crear una aplicación OneSignal">
    Inicia sesión en [onesignal.com](https://onesignal.com) y crea o selecciona una aplicación. Elige **Web** como plataforma y selecciona **Custom Code** como tipo de integración.
  </Step>

  <Step title="Configurar los ajustes de push web">
    En tu aplicación OneSignal, navega a **Settings > Push & In-App > Web Settings** o sigue la guía de [configuración de push web](./web-push-setup).

    **Configuración del sitio**

    * **Site Name**: El nombre de tu tienda, usado como título de notificación predeterminado.
    * **Site URL**: La URL accesible públicamente de tu tienda Shopify (p. ej., `https://yourstore.com`).
      * Debe ser el [origen](https://developer.mozilla.org/en-US/docs/Web/Security/Same-origin_policy) exacto de tu sitio.
      * No uses `https://your-site.myshopify.com/` si los clientes acceden a tu sitio a través de un dominio personalizado como `https://your-site.com/`.
    * **Default Icon URL**: Sube una imagen PNG o JPG cuadrada de 256x256px para los prompts y mensajes de notificación. Si no se configura, se usa un ícono de campana.
  </Step>

  <Step title="Configurar la ruta del service worker">
    Shopify no permite servir archivos desde la raíz del sitio, por lo que debes indicarle a OneSignal dónde sirve Vendo el archivo service worker.

    En OneSignal, ve a **Settings > Push & In-App > Web Settings**, desplázate hasta **Advanced Push Settings** y configura:

    | Ajuste                            | Valor                   |
    | --------------------------------- | ----------------------- |
    | Service Worker Path               | `/apps/vendo/`          |
    | Service Worker Filename           | `OneSignalSDKWorker.js` |
    | Updater Filename                  | `OneSignalSDKWorker.js` |
    | Service Worker Registration Scope | `/apps/vendo/`          |

    <Frame caption="Configuración del service worker para tiendas Shopify que usan Vendo.">
      <img src="https://mintcdn.com/onesignal/N_-d1DtCTRgGPN4l/images/integrations/shopify/vendo-service-worker-configuration.png?fit=max&auto=format&n=N_-d1DtCTRgGPN4l&q=85&s=b7bc1794445e002bd3427c94a6ec6ccf" alt="OneSignal Advanced Push Settings showing service worker paths configured for Vendo" width="3038" height="1108" data-path="images/integrations/shopify/vendo-service-worker-configuration.png" />
    </Frame>

    Vendo sirve automáticamente el archivo `OneSignalSDKWorker.js` requerido en `https://yourstore.myshopify.com/apps/vendo/OneSignalSDKWorker.js` — no se necesitan cargas manuales de archivos.

    <Note>
      El Updater Filename y el Service Worker Filename son el mismo archivo. OneSignal v16+ usa un único service worker para ambos propósitos.
    </Note>
  </Step>

  <Step title="Copiar tus credenciales">
    En OneSignal, ve a [**Settings > Keys & IDs**](./keys-and-ids) y copia tu **App ID** y **REST API Key**. Los ingresarás en Vendo.
  </Step>
</Steps>

## Configuración de Vendo

<Steps>
  <Step title="Instalar la aplicación Vendo">
    Instala la aplicación Vendo desde el Shopify App Store.
  </Step>

  <Step title="Agregar la integración OneSignal">
    En Vendo, navega a **Integrations > Add Integration > OneSignal** (o **Destinations > OneSignal**).

    <Frame caption="Agregar la integración OneSignal en Vendo.">
      <img src="https://mintcdn.com/onesignal/PoskQI_qr0DD8jDV/images/integrations/shopify/vendo-onesignal-integrations.png?fit=max&auto=format&n=PoskQI_qr0DD8jDV&q=85&s=13acfaf4e6b01f77535f1a1386c4212d" alt="Vendo Integrations page showing the OneSignal integration option" width="2520" height="1756" data-path="images/integrations/shopify/vendo-onesignal-integrations.png" />
    </Frame>
  </Step>

  <Step title="Ingresar tus credenciales de OneSignal">
    Ingresa tu **App ID** y **REST API Key** de OneSignal de la sección anterior, luego haz clic en **Save**.
  </Step>

  <Step title="Activar el bloque de tema Vendo">
    El bloque de tema Vendo carga el SDK de OneSignal en tu tienda. Sin él, el prompt de push no aparecerá y el seguimiento del lado del cliente no funcionará.

    1. En tu administrador de Shopify, ve a **Online Store > Themes > Customize**.
    2. Haz clic en **App embeds** (ícono de pieza de rompecabezas en la barra lateral izquierda).
    3. Activa **Vendo**.
    4. Haz clic en **Save**.

    El bloque de tema gestiona la inicialización del SDK, el registro del service worker, la visualización del prompt push, la identificación de usuarios (suscripción push, inicio de sesión, registro en newsletter) y la sincronización de etiquetas.
  </Step>

  <Step title="Seleccionar eventos a sincronizar">
    En la aplicación Vendo bajo **OneSignal > Events**, activa los eventos del lado del cliente y del servidor que deseas enviar a OneSignal. Consulta [Seguimiento](#tracking) a continuación para la lista completa de eventos.
  </Step>

  <Step title="Sincronización de datos históricos (opcional)">
    Vendo puede rellenar retroactivamente clientes existentes e historial de pedidos recientes en OneSignal. Esto ocurre automáticamente en segundo plano después de guardar tus credenciales.

    <Frame caption="Opciones de sincronización de datos históricos en Vendo.">
      <img src="https://mintcdn.com/onesignal/dknFSNQuQfw5IM0j/images/integrations/shopify/vendo-historical-data.png?fit=max&auto=format&n=dknFSNQuQfw5IM0j&q=85&s=4eb61a384a7ac3f4596661348f98ac48" alt="Vendo historical data settings showing sync options for Shopify data" width="1724" height="762" data-path="images/integrations/shopify/vendo-historical-data.png" />
    </Frame>
  </Step>
</Steps>

## Seguimiento

### Identificación de usuarios

Vendo utiliza un enfoque **solo para usuarios identificados** — los visitantes anónimos no se rastrean en OneSignal. Los usuarios deben identificarse a través de uno de cuatro métodos antes de que se envíen los eventos. Esto evita usuarios duplicados y garantiza datos limpios y accionables.

| Método                           | Cómo funciona                                                                                                                         | Identificador usado         |
| -------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------- | --------------------------- |
| **Suscripción push web**         | El visitante hace clic en "Permitir" en el prompt push. OneSignal crea un usuario automáticamente y Vendo captura el ID de OneSignal. | OneSignal ID                |
| **Registro en newsletter**       | El visitante envía un formulario de newsletter o correo electrónico. Vendo captura el email y llama a `OneSignal.login(email)`.       | Email                       |
| **Inicio de sesión del cliente** | El cliente inicia sesión en su cuenta de Shopify. Vendo lo detecta y llama a `OneSignal.login()` con el identificador configurado.    | Shopify Customer ID o Email |
| **Compra completada**            | El cliente completa una compra. Vendo almacena el identificador y llama a `OneSignal.login()`.                                        | Shopify Customer ID o Email |

<Warning>
  Si tienes una aplicación móvil o conexiones de terceros, selecciona el identificador (Shopify Customer ID vs. Email) que coincida con tus otras herramientas para que los perfiles de usuario permanezcan consistentes entre plataformas. Configúralo en la aplicación Vendo bajo **Settings > Customer Identifier**.
</Warning>

#### Fusión de identidades

Si un suscriptor push (identificado por el ID de OneSignal) luego inicia sesión o completa una compra, Vendo llama a `OneSignal.login()` con su Shopify Customer ID o email. OneSignal vincula la suscripción push al usuario identificado — no se crean usuarios duplicados. Todas las suscripciones push anteriores se conservan, y los eventos del lado del servidor (pedidos, cumplimientos) llegan al perfil de usuario correcto.

### Etiquetas de clientes

Vendo sincroniza las propiedades del cliente como [etiquetas](./add-user-data-tags) en OneSignal para segmentación. Todos los valores se almacenan como cadenas (formato nativo de OneSignal).

| Etiqueta                  | Descripción                              |
| ------------------------- | ---------------------------------------- |
| `email`                   | Email del cliente                        |
| `first_name`              | Nombre                                   |
| `last_name`               | Apellido                                 |
| `total_spent`             | Gasto total de por vida                  |
| `order_count`             | Total de pedidos                         |
| `verified_email`          | `"true"` o `"false"`                     |
| `tax_exempt`              | `"true"` o `"false"`                     |
| `marketing_state`         | Estado de consentimiento de marketing    |
| `first_order_date`        | Fecha del primer pedido (ISO 8601)       |
| `last_order_date`         | Fecha del pedido más reciente (ISO 8601) |
| `customer_created_at`     | Fecha de creación del cliente            |
| `customer_tags`           | Etiquetas de Shopify separadas por comas |
| `email_marketing_consent` | Estado de opt-in de marketing            |

### Eventos del lado del cliente

Vendo rastrea [eventos personalizados](./custom-events) del lado del cliente en tu tienda a través del Shopify Web Pixel y los envía a OneSignal. Estos eventos solo se envían después de que un usuario es identificado.

| Evento                             | Descripción                                                        |
| ---------------------------------- | ------------------------------------------------------------------ |
| `page_viewed`                      | El cliente visita una página (tienda, checkout o estado de pedido) |
| `product_viewed`                   | El cliente ve una página de detalles de producto                   |
| `collection_viewed`                | El cliente ve una página de colección de productos                 |
| `search_submitted`                 | El cliente realiza una búsqueda en la tienda                       |
| `product_added_to_cart`            | Un producto se agrega al carrito                                   |
| `product_removed_from_cart`        | Un producto se elimina del carrito                                 |
| `cart_viewed`                      | El cliente ve la página del carrito                                |
| `checkout_started`                 | El cliente inicia el proceso de pago                               |
| `checkout_contact_info_submitted`  | Paso de información de contacto enviado                            |
| `checkout_address_info_submitted`  | Paso de información de dirección enviado                           |
| `checkout_shipping_info_submitted` | Método de envío seleccionado                                       |
| `payment_info_submitted`           | Detalles de pago enviados                                          |
| `checkout_completed`               | Pago completado exitosamente                                       |

<Frame caption="Configuración de eventos del lado del cliente en Vendo.">
  <img src="https://mintcdn.com/onesignal/dknFSNQuQfw5IM0j/images/integrations/shopify/vendo-client-side-events.png?fit=max&auto=format&n=dknFSNQuQfw5IM0j&q=85&s=c94b99465b8c200ebb1bb475e492f8a1" alt="Vendo client-side events settings showing available custom events" width="865" height="726" data-path="images/integrations/shopify/vendo-client-side-events.png" />
</Frame>

### Eventos del lado del servidor

Los eventos de comercio de Shopify se exportan y reenvían a OneSignal a través del pipeline de Vendo. Estos siempre usan el Shopify Customer ID como `external_id`.

| Evento                      | Descripción                              |
| --------------------------- | ---------------------------------------- |
| `received_orders`           | Se crea un nuevo pedido                  |
| `fulfilled_orders`          | El pedido está cumplido/enviado          |
| `delivered_orders`          | El pedido está entregado                 |
| `refunded_orders`           | El pedido está completamente reembolsado |
| `partially_refunded_orders` | El pedido está parcialmente reembolsado  |
| `abandoned_checkouts`       | El checkout es abandonado                |

<Frame caption="Configuración de eventos del lado del servidor en Vendo.">
  <img src="https://mintcdn.com/onesignal/dknFSNQuQfw5IM0j/images/integrations/shopify/vendo-server-side-events.png?fit=max&auto=format&n=dknFSNQuQfw5IM0j&q=85&s=c9bed30c26b0bec3b8a53eb8cde8098d" alt="Vendo server-side events settings showing available Shopify webhook events" width="865" height="394" data-path="images/integrations/shopify/vendo-server-side-events.png" />
</Frame>

### Propiedades comunes de eventos

Todos los eventos incluyen estas propiedades (como cadenas):

| Propiedad          | Descripción                      |
| ------------------ | -------------------------------- |
| `order_id`         | Identificador de pedido mostrado |
| `shopify_order_id` | ID de pedido interno de Shopify  |
| `email`            | Email del cliente                |
| `currency`         | Moneda del pedido                |
| `source`           | Fuente del evento                |
| `version`          | Versión de la integración        |

### Frecuencia de sincronización de datos

| Tipo de datos           | Frecuencia de sincronización     |
| ----------------------- | -------------------------------- |
| Etiquetas de clientes   | Cada 4–6 horas                   |
| Eventos de pedidos      | Casi en tiempo real (en minutos) |
| Carritos abandonados    | Cada 1–2 horas                   |
| Eventos de cumplimiento | Casi en tiempo real              |

## Detalles de la plataforma

| Ajuste                   | Valor                                      |
| ------------------------ | ------------------------------------------ |
| Método de sincronización | Cliente + lado del servidor vía Vendo      |
| Identidad                | Shopify Customer ID, Email u OneSignal ID  |
| Deduplicación            | Hash UUID v5 por evento                    |
| Tamaño del lote          | 1,000 eventos por solicitud                |
| Formato de datos         | Todos los valores almacenados como cadenas |

## Casos de uso

### Recuperación de carrito abandonado

Crea un [Journey](./journeys-overview) desencadenado por el evento `abandoned_checkouts`. Espera 1 hora después del abandono, luego envía una notificación push con el enlace de recuperación usando la propiedad `checkout_url`.

### Actualizaciones del estado del pedido

Crea Journeys para `fulfilled_orders` y `delivered_orders` para enviar notificaciones push inmediatas con información de seguimiento cuando los pedidos se envían y llegan.

### Engagement de clientes VIP

Crea un [segmento](./segmentation) donde `total_spent` sea mayor que un umbral, luego envía ofertas exclusivas personalizadas con la etiqueta `first_name`.

### Campañas de reactivación

Dirige a clientes inactivos creando un segmento donde `last_order_date` sea hace más de 90 días y envía campañas de reconquista.

## Fuentes compatibles

OneSignal funciona con las siguientes fuentes de datos de Vendo:

| Fuente    | Eventos | Etiquetas de usuario | Audiencias |
| --------- | ------- | -------------------- | ---------- |
| Shopify   | Sí      | Sí                   | Sí         |
| Stripe    | Sí      | Sí                   | Sí         |
| Mixpanel  | —       | —                    | Sí         |
| Segment   | —       | —                    | Sí         |
| Amplitude | —       | —                    | Sí         |

Los eventos y etiquetas de usuario requieren Shopify o Stripe como fuente de datos. Los segmentos de audiencia se pueden construir a partir de cualquier dato fuente en tu conjunto de datos de BigQuery.

***

## Pruebas

<Steps>
  <Step title="Verificar el service worker">
    Visita `https://yourstore.myshopify.com/apps/vendo/OneSignalSDKWorker.js` en tu navegador. Deberías ver código JavaScript. Si obtienes un 404, verifica que la aplicación Vendo esté instalada.

    También puedes abrir el DevTools del navegador (**F12**), ir a **Application > Service Workers** y confirmar que `OneSignalSDKWorker.js` está registrado con un scope de `/apps/vendo/`.
  </Step>

  <Step title="Probar el prompt push">
    Abre tu tienda en una ventana de navegación incógnito/privada. Deberías ver el prompt de permiso de notificación de OneSignal. Haz clic en **Permitir** para suscribirte.
  </Step>

  <Step title="Enviar una notificación de prueba">
    En el panel de OneSignal, ve a **Messages > Push > New Message**. Envía una notificación de prueba a tu suscriptor y verifica que aparezca.
  </Step>

  <Step title="Verificar datos de usuario en OneSignal">
    Ve a **Audience > Subscriptions** y confirma que tu suscripción de prueba aparece. Verifica que las etiquetas de usuario (email, nombre, etc.) se están sincronizando para usuarios identificados.
  </Step>

  <Step title="Desencadenar un evento de prueba">
    Navega por un producto o completa un checkout de prueba en tu tienda. Confirma que el evento aparece en la actividad del usuario en el panel de OneSignal.
  </Step>
</Steps>

***

## Solución de problemas

### El service worker devuelve 404

El service worker debe estar en `/apps/vendo/OneSignalSDKWorker.js`. Si ves un error 404 en la ruta raíz (`/OneSignalSDKWorker.js`), la ruta del service worker no está configurada en OneSignal — sigue el [paso de configuración del service worker](#configure-the-service-worker-path). Si el 404 está en la ruta `/apps/vendo/`, verifica que la aplicación Vendo esté instalada y el bloque de tema esté habilitado.

### El prompt push no aparece

Verifica que el bloque de tema Vendo esté habilitado en **App embeds**. Comprueba que tu navegador permita notificaciones (haz clic en el ícono de candado en la barra de direcciones). Prueba en una ventana de navegación privada por si el prompt fue rechazado previamente.

### Las etiquetas no aparecen en OneSignal

Las etiquetas solo se sincronizan para usuarios identificados — los visitantes anónimos no se rastrean. Asegúrate de que el usuario haya sido identificado mediante suscripción push, inicio de sesión, registro en newsletter o checkout. Las sincronizaciones iniciales de etiquetas pueden tardar varias horas.

### Los eventos no se disparan

Verifica que los eventos estén habilitados en la aplicación Vendo bajo **OneSignal > Events**. Los eventos del lado del cliente requieren que el Shopify Web Pixel esté activo y el usuario esté identificado. Los eventos del lado del servidor requieren que la REST API Key esté configurada.

### Las notificaciones muestran "Entregado" pero no aparecen

La integración está funcionando — el problema está en la configuración de notificaciones de tu navegador o sistema operativo. Revisa la configuración de notificaciones de tu sistema operativo para tu navegador, asegúrate de que el modo No molestar / Concentración esté desactivado y verifica los permisos de notificación a nivel del navegador.

***

## Preguntas frecuentes

### ¿Puedo cambiar el identificador de cliente después de la configuración?

Sí. Actualiza el ajuste en la aplicación Vendo bajo **Settings > Customer Identifier**. Cambiar el identificador puede crear perfiles de usuario separados si los usuarios existentes ya fueron identificados con el método anterior.

### ¿La integración Vendo admite aplicaciones móviles?

La integración Vendo se enfoca en las tiendas Shopify y el push web. Si también tienes una aplicación móvil, asegúrate de que el identificador que seleccionas en Vendo coincida con el que usas en tu aplicación móvil para que los perfiles de usuario permanezcan consistentes.

### ¿Qué pasa si un visitante nunca es identificado?

Los eventos de visitantes no identificados no se envían a OneSignal. Una vez que el visitante se identifica (suscribiéndose al push, iniciando sesión, registrándose en una newsletter o completando el checkout), Vendo comienza a enviar eventos. Este enfoque solo para usuarios identificados evita usuarios duplicados y garantiza datos limpios.

### ¿Por qué Vendo usa un enfoque solo para usuarios identificados?

Las versiones anteriores rastreaban visitantes anónimos usando la cookie de sesión de Shopify como identificador. Esto creaba usuarios duplicados de OneSignal que nunca podían fusionarse correctamente, llevando a conteos inflados de usuarios y datos fragmentados. El enfoque solo para usuarios identificados garantiza que cada usuario de OneSignal sea real y accionable.

***

## Páginas relacionadas

<Columns cols={2}>
  <Card title="Keys & IDs" icon="key" href="./keys-and-ids">
    Encuentra tu App ID de OneSignal y clave REST API.
  </Card>

  <Card title="Eventos personalizados" icon="bolt" href="./custom-events">
    Rastrea el comportamiento del usuario y desencadena automatizaciones basadas en eventos de Shopify.
  </Card>

  <Card title="Configuración push web" icon="globe" href="./web-push-setup">
    Configura notificaciones push web para tu tienda Shopify.
  </Card>

  <Card title="Prompts de permiso web" icon="bell" href="./permission-requests">
    Configura cómo y cuándo solicitar a los visitantes permiso para push web.
  </Card>
</Columns>