Web SDK - Resolução de problemas e melhores práticas

Seguir
Avatar
Jared Ornstead
Updated
Documento

Descrição geral

Este guia abrange problemas comuns de implementação, melhores práticas e soluções para o ajudar a evitar problemas de rastreio e garantir a exatidão dos dados.

Erros comuns de implementação

Erro 1: Implementação duplicada (Nativo + GTM)

Problema: o erro mais comum é implementar simultaneamente o SDK JavaScript nativo e o SDK do Google Tag Manager. Isso faz com que todas as sessões e eventos sejam rastreados duas vezes, aumentando todas as métricas em 200%.

IMPORTANTE! O Singular não desduplica eventos automaticamente. O uso de ambos os métodos de implementação duplicará a contagem de todos os seus dados.

Como identificar esse problema:

  • Verifique o código-fonte do seu site para o script Singular SDK
  • Verifique se há tags Singular no Gerenciador de tags do Google
  • Nas ferramentas de desenvolvimento do navegador, filtre as solicitações de rede por singular e conte quantas solicitações são disparadas no carregamento da página (deve ser 1, não 2)

Solução:

  1. Decidir qual o método de implementação que pretende utilizar(recomenda-se JS nativo)
  2. Remover completamente a outra implementação
  3. Teste para verificar se apenas um pedido é disparado por evento
  4. Monitorize os seus dados durante 24-48 horas para garantir que as métricas voltam ao normal

Erro 2: Formato incorreto da ID do produto

Problema: Usando o formato incorreto para sua ID do produto. A ID do produto deve ser consistente para o aplicativo da Web em todos os subdomínios.

Erros comuns:

  • Usar um URL de site: www.mycompany.com ❌
  • Usar traços: my-company-store ❌
  • Utilização de DNS avançado: mycompany.com.store ❌
  • Utilização de espaços: my company store ❌

Formato correto (notação de DNS inverso):

  • com.mycompany ✓

DICA! Pense na sua ID de produto como um identificador de pacote de aplicativo móvel. Use letras minúsculas, comece com seu domínio ao contrário e use pontos para separar componentes.

Como identificar esse problema:

  • Verifique os pedidos de rede nas ferramentas do programador - procure erros 400 ou 403
  • Verifique o parâmetro i na carga útil do pedido nas ferramentas de desenvolvimento do navegador.
  • Verifique se há erros na consola do browser

Solução:

  1. Obtenha o valor correto da sua Página de Aplicações Singulares (BundleId)
  2. Atualize sua implementação com o formato correto
  3. Teste e verifique os códigos de status 200 nas solicitações de rede

Erro 3: Eventos disparados várias vezes

Problema: Os eventos são disparados várias vezes devido a recarregamentos de página, cliques rápidos do utilizador ou falta de lógica de deduplicação. Isso aumenta a contagem de eventos e os números de conversão.

Causas comuns:

  • O usuário clica em um botão várias vezes rapidamente
  • O código do evento é executado em cada renderização de página (React, Vue, aplicações Angular)
  • Envios de formulários que não impedem o comportamento padrão
  • Atualizações de página ou navegação pelo botão Voltar
  • Gatilhos do Google Tag Manager disparados várias vezes

IMPORTANTE! Ao contrário de algumas plataformas de análise, o Singular não desduplica eventos automaticamente. É sua responsabilidade implementar mecanismos de segurança para evitar o rastreamento duplicado.

Estratégias de solução:

Analise as estratégias nos guias de implementação para obter mais detalhes. JS nativo, GTM

Erro 4: SDK não está carregando

Problema: O script Singular SDK não é carregado, impedindo qualquer rastreamento.

Causas comuns:

  • Script bloqueado por bloqueadores de anúncios (afeta principalmente o GTM)
  • Restrições da Política de Segurança de Conteúdo (CSP)
  • Script colocado numa localização incorrecta na página
  • Erros de sintaxe no código de implementação
  • Problemas de conetividade de rede

Como diagnosticar:

  1. Abrir o separador Consola das ferramentas de programação do browser
  2. Procure erros que mencionem "singular" ou "sdk"
  3. Escreva typeof singularSdk na consola - deve devolver "função" e não "indefinido"
  4. Verifique o separador Rede para ver se há falhas no carregamento de scripts
  5. Desativar os bloqueadores de anúncios e testar novamente

Soluções:

  • Bloqueadores de anúncios: Mudar para a implementação de JavaScript nativo (menos provável de ser bloqueado)
  • Problemas de CSP: Adicionar domínios Singular à sua Política de segurança de conteúdo
  • Colocação de scripts: Certifique-se de que o script SDK está na tag <head>
  • Erros de sintaxe: Valide o seu código JavaScript

Configuração da política de segurança de conteúdo

Se o seu site usa cabeçalhos CSP, adicione estas diretivas:

Content-Security-Policy: 
  script-src 'self' https://web-sdk-v1.singular.net;
  connect-src 'self' https://sdk-api-v1.singular.net;

Melhores práticas

Gestão do ID do produto

  • Utilizar um ID de produto por site ou aplicação Web
  • Mantenha as IDs de produto consistentes em todas as páginas e subdomínios
  • Documentar as IDs de produto na base de conhecimentos da sua equipa
  • Use IDs de produto separadas para ambientes de desenvolvimento, teste e produção

Convenções de nomenclatura de eventos

Boas práticas de nomenclatura:

  • Use nomes claros e descritivos: Purchase, Signup_Completed, Video_Play
  • Usar capitalização consistente (recomendar Title_Case)
  • Utilizar sublinhados em vez de espaços
  • Manter os nomes com menos de 32 caracteres
  • Evitar caracteres especiais e emojis

Maus exemplos:

  • Purchase!!!🎉 (caracteres especiais e emojis)
  • user clicked the purchase button on the checkout page (demasiado longo, espaços)
  • evt_123 (não descritivo)

DICA! Crie um documento de nomeação de eventos partilhado entre as equipas de marketing, produto e engenharia para manter a consistência.

Práticas recomendadas de parâmetros de eventos

  • Receita: Envie sempre como um número, não como uma cadeia de caracteres: revenue: 49.99 e não revenue: "$49.99"
  • Moeda: Use códigos de moeda ISO de 3 letras: USD, EUR, GBP
  • IDs: Enviar como cadeias de caracteres, mesmo que sejam numéricas: product_id: "12345"
  • Nomes de parâmetros: Usar snake_case para consistência
  • Valores: Manter os valores das cadeias de caracteres com menos de 100 caracteres

Estratégia de teste

Siga esta lista de verificação de testes antes do lançamento:

Tabela

Teste Como verificar Resultado esperado
O SDK é carregado Consola: typeof singularSdk Retorna "function" (função)
Init/PageVisit rastreado Separador Rede: Filtro "__PAGE_VISIT__" 1 pedido no carregamento da página com o estado 200
Eventos disparados Desencadear o evento, verificar o separador Rede, validar o nome do evento (parâmetro "n") na carga útil. Novo pedido por evento com o estado 200
ID do produto correta Verificar a carga útil do pedido, validar o nome do evento (parâmetro "i") na carga útil. Formato DNS invertido
Sem duplicados Acionar o mesmo evento 3 vezes rapidamente Apenas 1 pedido enviado
Receita controlada Verificar a carga útil do evento de compra A receita aparece como um número
Várias páginas Navegar para páginas diferentes O rastreio funciona em todas as páginas
Dispositivos móveis Teste em navegadores iOS e Android O rastreio funciona no telemóvel

Otimização do desempenho

  • Coloque o script SDK em <head> tag para carregamento antecipado
  • Minimize o número de eventos rastreados por página (concentre-se em acções significativas, eventos de marketing)
  • Evitar o rastreio de cada toque de tecla (utilizar o debouncing)

Privacidade e conformidade

Divulgação de cookies

Se você ativar o rastreamento de domínios cruzados na sua configuração, o Singular definirá um cookie primário. Você deve divulgar isso em sua política de privacidade.

Linguagem recomendada para a política de privacidade:

Utilizamos cookies para rastrear o comportamento do utilizador e melhorar a sua experiência no website. Especificamente, usamos os seguintes cookies:

singular_device_id - Este cookie atribui um ID único aos utilizadores que visitam o nosso website. Este ID ajuda-nos a seguir as actividades e interações dos utilizadores durante a sua visita sem recolher informações pessoais. Permite-nos diferenciar entre utilizadores e monitorizar o comportamento dos visitantes em diferentes sessões.

  • Duração: 1 ano
  • Tipo: Cookie de primeira parte
  • Provedor: Singular (https://www.singular.net/privacy-policy/)

Conformidade com o RGPD e a privacidade

Para conformidade com o GDPR:

  • Definir persistentIdentifier: false por predefinição
  • Ativar os cookies apenas após o consentimento do utilizador
  • Fornecer aos utilizadores a possibilidade de optarem por não seguir o rastreio
  • Incluir o Singular no seu banner de consentimento de cookies

Ferramentas e técnicas de depuração

Ferramentas de desenvolvimento do navegador

Comandos de consola para depuração:

// Check if SDK is loaded
typeof singularSdk
// Should return: "function"

// Test firing an event manually
window.singularSdk.event("test");

Lista de verificação de migração

Se estiver a mudar de outra plataforma de análise ou a atualizar a sua implementação:

  1. Auditar a implementação atual
    • Documentar todos os eventos atualmente rastreados
    • Identificar todas as páginas com código de rastreamento
    • Anotar quaisquer parâmetros personalizados ou IDs de utilizador
  2. Planear a nova implementação
    • Mapear nomes de eventos antigos para a nova convenção de nomes
    • Decidir sobre JS nativo ou GTM
    • Criar um plano de testes
  3. Implementar por fases
    • Começar com um ambiente de teste/preparação
    • Testar exaustivamente (mínimo de 1 semana)
    • Implementar na produção durante um período de pouco tráfego
    • Executar em paralelo com o sistema antigo durante 1-2 semanas
  4. Validar os dados
    • Comparar as métricas entre os sistemas antigo e novo
    • Verificar se há rastreamento duplicado
    • Verificar se todos os eventos estão a disparar corretamente
    • Monitorizar durante 2-4 semanas
  5. Desativar o sistema antigo
    • Remover o código de rastreio antigo
    • Atualizar a documentação
    • Formar a equipa no novo sistema

Obter ajuda

Se você encontrar problemas não abordados neste guia:

  • Entre em contato com o gerente de sucesso do cliente da Singular.
  • Envie um tíquete de suporte através do painel de controle da Singular.
  • Inclua logs do console do navegador e capturas de tela da solicitação de rede.
  • Forneça o URL do seu site e etapas detalhadas para replicar qualquer problema.

Artigos relacionados