> ## 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

> Conecte o Shopify ao OneSignal através da integração Vendo para notificações web push, tags de clientes, eventos de comércio e segmentação comportamental.

O OneSignal fez parceria com a Vendo para criar uma integração perfeita com o Shopify. A Vendo implanta o SDK do OneSignal na sua loja Shopify com um clique — sem necessidade de editar manualmente o código do tema. Ela sincroniza tags de clientes, eventos de navegação do lado do cliente e eventos de comércio do lado do servidor para o OneSignal, permitindo que você construa segmentos e acione campanhas push a partir de comportamento real e histórico de compras.

Para a documentação da Vendo, consulte [Vendo OneSignal Destination](https://docs.vendodata.com/destinations/onesignal/overview).

## Pré-requisitos

Antes de começar, certifique-se de ter:

* Uma loja Shopify com o [aplicativo Vendo](https://apps.shopify.com/) instalado
* Uma conta e app OneSignal (plataforma Web)
* Seu **App ID** do OneSignal (obrigatório)
* Sua **REST API Key** do OneSignal (necessária para eventos do lado do servidor como sincronização de pedidos e marcação de usuários)

## Configuração do OneSignal

<Steps>
  <Step title="Criar um app OneSignal">
    Faça login em [onesignal.com](https://onesignal.com) e crie ou selecione um app. Escolha **Web** como plataforma e selecione **Custom Code** como tipo de integração.
  </Step>

  <Step title="Configurar as definições de push web">
    No seu app OneSignal, navegue até **Settings > Push & In-App > Web Settings** ou siga o guia de [configuração de push web](./web-push-setup).

    **Configuração do site**

    * **Site Name**: O nome da sua loja, usado como título de notificação padrão.
    * **Site URL**: A URL acessível publicamente da sua loja Shopify (ex.: `https://yourstore.com`).
      * Deve ser a [origem](https://developer.mozilla.org/en-US/docs/Web/Security/Same-origin_policy) exata do seu site.
      * Não use `https://your-site.myshopify.com/` se os clientes acessam seu site através de um domínio personalizado como `https://your-site.com/`.
    * **Default Icon URL**: Faça upload de uma imagem PNG ou JPG quadrada de 256x256px para prompts e mensagens de notificação. Se não definida, um ícone de sino é usado.
  </Step>

  <Step title="Configurar o caminho do service worker">
    O Shopify não permite servir arquivos da raiz do site, então você deve informar ao OneSignal onde a Vendo serve o arquivo service worker.

    No OneSignal, vá para **Settings > Push & In-App > Web Settings**, role até **Advanced Push Settings** e configure:

    | Configuração                      | Valor                   |
    | --------------------------------- | ----------------------- |
    | Service Worker Path               | `/apps/vendo/`          |
    | Service Worker Filename           | `OneSignalSDKWorker.js` |
    | Updater Filename                  | `OneSignalSDKWorker.js` |
    | Service Worker Registration Scope | `/apps/vendo/`          |

    <Frame caption="Configuração do service worker para lojas Shopify usando a 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>

    A Vendo serve automaticamente o arquivo `OneSignalSDKWorker.js` necessário em `https://yourstore.myshopify.com/apps/vendo/OneSignalSDKWorker.js` — sem uploads manuais de arquivos.

    <Note>
      O Updater Filename e o Service Worker Filename são o mesmo arquivo. O OneSignal v16+ usa um único service worker para ambos os propósitos.
    </Note>
  </Step>

  <Step title="Copiar suas credenciais">
    No OneSignal, vá para [**Settings > Keys & IDs**](./keys-and-ids) e copie seu **App ID** e **REST API Key**. Você os inserirá na Vendo.
  </Step>
</Steps>

## Configuração da Vendo

<Steps>
  <Step title="Instalar o aplicativo Vendo">
    Instale o aplicativo Vendo da Shopify App Store.
  </Step>

  <Step title="Adicionar a integração OneSignal">
    Na Vendo, navegue até **Integrations > Add Integration > OneSignal** (ou **Destinations > OneSignal**).

    <Frame caption="Adicionar a integração OneSignal na 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="Inserir suas credenciais OneSignal">
    Insira seu **App ID** e **REST API Key** do OneSignal da seção anterior, depois clique em **Save**.
  </Step>

  <Step title="Ativar o bloco de tema Vendo">
    O bloco de tema Vendo carrega o SDK do OneSignal na sua loja. Sem ele, o prompt de push não aparecerá e o rastreamento do lado do cliente não funcionará.

    1. No administrador do Shopify, vá para **Online Store > Themes > Customize**.
    2. Clique em **App embeds** (ícone de peça de quebra-cabeça na barra lateral esquerda).
    3. Ative **Vendo**.
    4. Clique em **Save**.

    O bloco de tema gerencia a inicialização do SDK, o registro do service worker, a exibição do prompt push, a identificação do usuário (inscrição push, login, cadastro em newsletter) e a sincronização de tags.
  </Step>

  <Step title="Selecionar eventos para sincronizar">
    No aplicativo Vendo em **OneSignal > Events**, ative os eventos do lado do cliente e do servidor que deseja enviar ao OneSignal. Consulte [Rastreamento](#tracking) abaixo para a lista completa de eventos.
  </Step>

  <Step title="Sincronização de dados históricos (opcional)">
    A Vendo pode preencher retroativamente clientes existentes e histórico de pedidos recentes para o OneSignal. Isso acontece automaticamente em segundo plano após salvar suas credenciais.

    <Frame caption="Opções de sincronização de dados históricos na 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>

## Rastreamento

### Identificação de usuários

A Vendo usa uma abordagem **somente para usuários identificados** — visitantes anônimos não são rastreados no OneSignal. Os usuários devem ser identificados por um dos quatro métodos antes que os eventos sejam enviados. Isso evita usuários duplicados e garante dados limpos e acionáveis.

| Método                     | Como funciona                                                                                                                    | Identificador usado          |
| -------------------------- | -------------------------------------------------------------------------------------------------------------------------------- | ---------------------------- |
| **Inscrição push web**     | O visitante clica em "Permitir" no prompt push. O OneSignal cria um usuário automaticamente e a Vendo captura o ID do OneSignal. | OneSignal ID                 |
| **Cadastro em newsletter** | O visitante envia um formulário de newsletter ou e-mail. A Vendo captura o e-mail e chama `OneSignal.login(email)`.              | Email                        |
| **Login do cliente**       | O cliente faz login na sua conta Shopify. A Vendo detecta isso e chama `OneSignal.login()` com o identificador configurado.      | Shopify Customer ID ou Email |
| **Checkout concluído**     | O cliente conclui uma compra. A Vendo armazena o identificador e chama `OneSignal.login()`.                                      | Shopify Customer ID ou Email |

<Warning>
  Se você tem um app mobile ou conexões de terceiros, selecione o identificador (Shopify Customer ID vs. Email) que corresponde às suas outras ferramentas para que os perfis de usuário permaneçam consistentes entre plataformas. Configure isso no aplicativo Vendo em **Settings > Customer Identifier**.
</Warning>

#### Fusão de identidades

Se um assinante push (identificado pelo ID do OneSignal) fizer login ou concluir uma compra posteriormente, a Vendo chama `OneSignal.login()` com seu Shopify Customer ID ou e-mail. O OneSignal vincula a inscrição push ao usuário identificado — nenhum usuário duplicado é criado. Todas as inscrições push anteriores são preservadas, e os eventos do lado do servidor (pedidos, cumprimentos) chegam ao perfil de usuário correto.

### Tags de clientes

A Vendo sincroniza as propriedades do cliente como [tags](./add-user-data-tags) no OneSignal para segmentação. Todos os valores são armazenados como strings (formato nativo do OneSignal).

| Tag                       | Descrição                              |
| ------------------------- | -------------------------------------- |
| `email`                   | E-mail do cliente                      |
| `first_name`              | Nome                                   |
| `last_name`               | Sobrenome                              |
| `total_spent`             | Gasto total acumulado                  |
| `order_count`             | Total de pedidos                       |
| `verified_email`          | `"true"` ou `"false"`                  |
| `tax_exempt`              | `"true"` ou `"false"`                  |
| `marketing_state`         | Estado de consentimento de marketing   |
| `first_order_date`        | Data do primeiro pedido (ISO 8601)     |
| `last_order_date`         | Data do pedido mais recente (ISO 8601) |
| `customer_created_at`     | Data de criação do cliente             |
| `customer_tags`           | Tags do Shopify separadas por vírgulas |
| `email_marketing_consent` | Estado de opt-in de marketing          |

### Eventos do lado do cliente

A Vendo rastreia [eventos personalizados](./custom-events) do lado do cliente na sua loja através do Shopify Web Pixel e os envia ao OneSignal. Esses eventos só são enviados após um usuário ser identificado.

| Evento                             | Descrição                                                        |
| ---------------------------------- | ---------------------------------------------------------------- |
| `page_viewed`                      | O cliente visita uma página (loja, checkout ou status do pedido) |
| `product_viewed`                   | O cliente visualiza uma página de detalhes do produto            |
| `collection_viewed`                | O cliente visualiza uma página de coleção de produtos            |
| `search_submitted`                 | O cliente realiza uma busca na loja                              |
| `product_added_to_cart`            | Um produto é adicionado ao carrinho                              |
| `product_removed_from_cart`        | Um produto é removido do carrinho                                |
| `cart_viewed`                      | O cliente visualiza a página do carrinho                         |
| `checkout_started`                 | O cliente inicia o checkout                                      |
| `checkout_contact_info_submitted`  | Etapa de informações de contato enviada                          |
| `checkout_address_info_submitted`  | Etapa de informações de endereço enviada                         |
| `checkout_shipping_info_submitted` | Método de envio selecionado                                      |
| `payment_info_submitted`           | Detalhes de pagamento enviados                                   |
| `checkout_completed`               | Checkout concluído com sucesso                                   |

<Frame caption="Configuração de eventos do lado do cliente na 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 do lado do servidor

Os eventos de comércio do Shopify são exportados e encaminhados ao OneSignal pelo pipeline da Vendo. Eles sempre usam o Shopify Customer ID como `external_id`.

| Evento                      | Descrição                           |
| --------------------------- | ----------------------------------- |
| `received_orders`           | Um novo pedido é criado             |
| `fulfilled_orders`          | O pedido é cumprido/enviado         |
| `delivered_orders`          | O pedido é entregue                 |
| `refunded_orders`           | O pedido é totalmente reembolsado   |
| `partially_refunded_orders` | O pedido é parcialmente reembolsado |
| `abandoned_checkouts`       | O checkout é abandonado             |

<Frame caption="Configuração de eventos do lado do servidor na 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>

### Propriedades comuns de eventos

Todos os eventos incluem estas propriedades (como strings):

| Propriedade        | Descrição                       |
| ------------------ | ------------------------------- |
| `order_id`         | Identificador de pedido exibido |
| `shopify_order_id` | ID de pedido interno do Shopify |
| `email`            | E-mail do cliente               |
| `currency`         | Moeda do pedido                 |
| `source`           | Fonte do evento                 |
| `version`          | Versão da integração            |

### Frequência de sincronização de dados

| Tipo de dados          | Frequência de sincronização      |
| ---------------------- | -------------------------------- |
| Tags de clientes       | A cada 4–6 horas                 |
| Eventos de pedidos     | Quase em tempo real (em minutos) |
| Carrinhos abandonados  | A cada 1–2 horas                 |
| Eventos de cumprimento | Quase em tempo real              |

## Detalhes da plataforma

| Configuração            | Valor                                      |
| ----------------------- | ------------------------------------------ |
| Método de sincronização | Cliente + lado do servidor via Vendo       |
| Identidade              | Shopify Customer ID, Email ou OneSignal ID |
| Deduplicação            | Hash UUID v5 por evento                    |
| Tamanho do lote         | 1.000 eventos por requisição               |
| Formato de dados        | Todos os valores armazenados como strings  |

## Casos de uso

### Recuperação de carrinho abandonado

Crie um [Journey](./journeys-overview) acionado pelo evento `abandoned_checkouts`. Aguarde 1 hora após o abandono, depois envie uma notificação push com o link de recuperação usando a propriedade `checkout_url`.

### Atualizações de status do pedido

Crie Journeys para `fulfilled_orders` e `delivered_orders` para enviar notificações push imediatas com informações de rastreamento quando os pedidos são enviados e chegam.

### Engajamento de clientes VIP

Crie um [segmento](./segmentation) onde `total_spent` seja maior que um limite, depois envie ofertas exclusivas personalizadas com a tag `first_name`.

### Campanhas de reengajamento

Direcione clientes inativos criando um segmento onde `last_order_date` seja há mais de 90 dias e envie campanhas de reconquista.

## Fontes compatíveis

O OneSignal funciona com as seguintes fontes de dados da Vendo:

| Fonte     | Eventos | Tags de usuário | Audiências |
| --------- | ------- | --------------- | ---------- |
| Shopify   | Sim     | Sim             | Sim        |
| Stripe    | Sim     | Sim             | Sim        |
| Mixpanel  | —       | —               | Sim        |
| Segment   | —       | —               | Sim        |
| Amplitude | —       | —               | Sim        |

Eventos e tags de usuário requerem Shopify ou Stripe como fonte de dados. Segmentos de audiência podem ser construídos a partir de qualquer dado fonte no seu conjunto de dados do BigQuery.

***

## Testes

<Steps>
  <Step title="Verificar o service worker">
    Visite `https://yourstore.myshopify.com/apps/vendo/OneSignalSDKWorker.js` no seu navegador. Você deve ver código JavaScript. Se receber um 404, verifique se o aplicativo Vendo está instalado.

    Você também pode abrir o DevTools do navegador (**F12**), ir para **Application > Service Workers** e confirmar que `OneSignalSDKWorker.js` está registrado com um scope de `/apps/vendo/`.
  </Step>

  <Step title="Testar o prompt push">
    Abra sua loja em uma janela de navegação anônima/privada. Você deve ver o prompt de permissão de notificação do OneSignal. Clique em **Permitir** para se inscrever.
  </Step>

  <Step title="Enviar uma notificação de teste">
    No dashboard do OneSignal, vá para **Messages > Push > New Message**. Envie uma notificação de teste para seu assinante e verifique se ela aparece.
  </Step>

  <Step title="Verificar dados do usuário no OneSignal">
    Vá para **Audience > Subscriptions** e confirme que sua inscrição de teste aparece. Verifique se as tags de usuário (e-mail, nome, etc.) estão sincronizando para usuários identificados.
  </Step>

  <Step title="Acionar um evento de teste">
    Navegue por um produto ou conclua um checkout de teste na sua loja. Confirme que o evento aparece na atividade do usuário no dashboard do OneSignal.
  </Step>
</Steps>

***

## Solução de problemas

### O service worker retorna 404

O service worker deve estar em `/apps/vendo/OneSignalSDKWorker.js`. Se você vir um erro 404 no caminho raiz (`/OneSignalSDKWorker.js`), o caminho do service worker não está configurado no OneSignal — siga a [etapa de configuração do service worker](#configure-the-service-worker-path). Se o 404 estiver no caminho `/apps/vendo/`, verifique se o aplicativo Vendo está instalado e o bloco de tema está ativado.

### O prompt push não aparece

Verifique se o bloco de tema Vendo está ativado em **App embeds**. Confirme que seu navegador permite notificações (clique no ícone de cadeado na barra de endereços). Tente uma janela de navegação privada caso o prompt tenha sido descartado anteriormente.

### As tags não aparecem no OneSignal

As tags só sincronizam para usuários identificados — visitantes anônimos não são rastreados. Certifique-se de que o usuário foi identificado via inscrição push, login, cadastro em newsletter ou checkout. As sincronizações iniciais de tags podem levar várias horas.

### Os eventos não estão sendo disparados

Verifique se os eventos estão habilitados no aplicativo Vendo em **OneSignal > Events**. Eventos do lado do cliente requerem que o Shopify Web Pixel esteja ativo e o usuário esteja identificado. Eventos do lado do servidor requerem que a REST API Key esteja configurada.

### As notificações mostram "Entregue" mas não aparecem

A integração está funcionando — o problema está nas configurações de notificação do seu navegador ou sistema operacional. Verifique as configurações de notificação do seu sistema operacional para o seu navegador, certifique-se de que o modo Não Perturbe / Foco está desativado e verifique as permissões de notificação no nível do navegador.

***

## Perguntas frequentes

### Posso alterar o identificador de cliente após a configuração?

Sim. Atualize a configuração no aplicativo Vendo em **Settings > Customer Identifier**. Alterar o identificador pode criar perfis de usuário separados se os usuários existentes já foram identificados com o método anterior.

### A integração Vendo suporta apps móveis?

A integração Vendo foca em lojas Shopify e push web. Se você também tem um app móvel, certifique-se de que o identificador selecionado na Vendo corresponde ao usado no seu app móvel para que os perfis de usuário permaneçam consistentes.

### O que acontece se um visitante nunca for identificado?

Eventos de visitantes não identificados não são enviados ao OneSignal. Assim que o visitante se identifica (inscrevendo-se no push, fazendo login, cadastrando-se em uma newsletter ou concluindo o checkout), a Vendo começa a enviar eventos. Essa abordagem somente para usuários identificados evita usuários duplicados e garante dados limpos.

### Por que a Vendo usa uma abordagem somente para usuários identificados?

Versões anteriores rastreavam visitantes anônimos usando o cookie de sessão do Shopify como identificador. Isso criava usuários duplicados do OneSignal que nunca podiam ser mesclados adequadamente, levando a contagens infladas de usuários e dados fragmentados. A abordagem somente para usuários identificados garante que cada usuário do OneSignal seja real e acionável.

***

## Páginas relacionadas

<Columns cols={2}>
  <Card title="Keys & IDs" icon="key" href="./keys-and-ids">
    Encontre seu App ID do OneSignal e chave REST API.
  </Card>

  <Card title="Eventos personalizados" icon="bolt" href="./custom-events">
    Rastreie o comportamento do usuário e acione automações baseadas em eventos do Shopify.
  </Card>

  <Card title="Configuração de push web" icon="globe" href="./web-push-setup">
    Configure notificações web push para sua loja Shopify.
  </Card>

  <Card title="Prompts de permissão web" icon="bell" href="./permission-requests">
    Configure como e quando solicitar permissão de push web aos visitantes.
  </Card>
</Columns>