Síntese

Este guia explica como implementar o Singular Web SDK usando o Google Tag Manager (GTM). Este método é ideal para equipas sem acesso direto ao código do site ou para aqueles que pretendem gerir o acompanhamento através do GTM.

Pré-requisitos

Antes de começar, verifique se você tem:

• SDK Key & SDK Secret:
  • Onde encontrá-los: Faça login na sua conta Singular e navegue até Ferramentas do desenvolvedor > Integração do SDK > Chaves do SDK.
• ID do produto:
  • O que é: Um nome exclusivo para seu site, de preferência usando o formato DNS reverso (por exemplo, com.website-name).
  • Por que é importante: Essa ID associa o site como um aplicativo no Singular e deve corresponder ao ID do pacote de aplicativos da Web listado na sua página de aplicativos no Singular.
• O Google Tag Manager foi configurado no seu site.
• Permissão no GTM para editar as tags, gatilhos e variáveis do seu site. Dependendo da personalização, talvez seja necessário saber como criar tags personalizadas e configurar a sequência de tags.
• Se não tiver permissão para publicar alterações no Google Tag Manager, precisará de pedir a alguém para publicar as alterações após o teste.
• Conhecimento sobre como pré-visualizar e depurar contentores e tags no GTM.
• Uma lista de eventos que pretende monitorizar. Veja nossos Eventos padrão Singular: Lista completa e Eventos recomendados por vertical para obter ideias.

Etapas de implementação

Etapa 1: Adicionar os modelos do Singular Web Tracking ao seu contêiner do GTM

1. Faça login na sua conta do Google Tag Manager e selecione o contêiner do seu site.
2. Vá para Tags > Novo.
3. Dê um nome para a tag: "Singular Init Tag"
4. Clique na caixa Configuração de tag para iniciar a configuração da tag.
5. Escolha Tipo de tag: e selecione "Descubra mais tipos de tag na Galeria de modelos da comunidade".
6. Procure por "Singular" e selecione "Singular Web Tracking". Clique no botão "Adicionar ao espaço de trabalho".

Etapa 2: Inicializar o SDK

1. Preencha os campos do formulário com o seguinte:
   • Defina o Tipo de rastreamento como Inicialização
   • Introduza a sua chave SDK real para o campo Chave Api
   • Introduza o seu SDK Secret atual para o campo Secret

   • Introduza o seu ID de produto real. Ela deve ser semelhante a: com.website-name e deve corresponder ao valor BundleID na página Apps na plataforma Singular.

     DICA: use uma ID de produto específica para testar com.website-name.dev e atualize-a antes de enviar para a produção. Isso mantém todos os seus dados de teste separados do aplicativo de produção nos relatórios do Singular.

   • Opcional:
     • Nível de log: A configuração do registro de depuração do SDK no console. O padrão é nenhum.
     • Tempo limite da sessão: O tempo que o utilizador tem de estar inativo antes de o SDK criar uma nova sessão. A Singular envia sessões de utilizador para calcular a retenção de utilizadores e permitir a atribuição de reengajamento. O valor padrão é 30 minutos.
     • Rastreamento entre subdomínios
2. Escolha Acionamento para configurar um acionador para fazer essa tag funcionar.
3. Escolha Novo e nomeie o gatilho: "Singular Init Trigger".
4. Clique na Configuração do acionador e escolha"Exibição de página - Janela carregada" e clique em"Salvar".
5. Clique em"Salvar" novamente para salvar a tag.
6. Clique em"Preview" (Pré-visualizar) na página da Tag e teste se a Tag de Inicialização Singular é activada.
   
   

Etapa 3: Acompanhamento de eventos

Depois de inicializar o SDK, você pode rastrear eventos personalizados quando os usuários realizam ações importantes no seu site.

Basic EventConversion EventRevenue Event

Rastreamento básico de eventos

Rastreie um evento simples ou adicione atributos personalizados usando JSON válido para fornecer mais contexto sobre o evento:

1. Crie uma nova tag para o seu evento personalizado usando o modelo Singular Web Tracking.

2. Dê um nome à tag de evento.

3. Escolha Tipo de rastreamento = Evento personalizado

4. Ajuste o campo "Nome do evento" ou defina a variável apropriada.

5. Ajuste o campo "Custom User Id" (ID do usuário personalizado) ou defina a variável apropriada.

6. Ajuste os "Atributos" se desejar passar pares Chave/Valor no Evento.

7. Configure um acionador adequado para disparar a etiqueta apenas quando esperado.

8. Guarde o acionador e a etiqueta e teste na pré-visualização.

Acompanhamento de eventos de conversão

Acompanhe um evento de conversão:

1. Crie uma nova Tag para o seu Evento personalizado utilizando o modelo Singular Web Tracking.

2. Dê um nome à tag de evento de conversão.

3. Selecione Tipo de seguimento = Evento de conversão

4. Ajuste o campo "Nome do evento" ou defina a variável apropriada.

5. Ajuste o campo "Custom User Id" ou defina a variável apropriada.

6. Ajuste os "Atributos" se desejar passar pares Chave/Valor no Evento.

7. Configure um acionador adequado para disparar a etiqueta apenas quando esperado.

8. Guarde o acionador e a etiqueta e teste-os na Pré-visualização.

Acompanhamento de eventos de receita

Rastreie eventos de conversão com informações de receita e adicione atributos opcionais para obter mais contexto:

1. Crie uma nova tag para o seu evento personalizado usando o modelo Singular Web Tracking.

2. Dê um nome à tag de evento de receita.

3. Escolha Tipo de rastreamento = Evento de receita

4. Ajuste o campo "Nome do evento" ou defina a variável apropriada.

5. Ajuste o campo "Custom User Id" (ID do utilizador personalizado) ou defina a variável adequada.

6. Ajuste o campo "Moeda" ou defina a variável apropriada. Passe a moeda da receita como um código de moeda ISO 4217 de três letras, como "USD", "EUR" ou "INR".

7. Ajuste o campo "Revenue" ou defina a variável adequada. A receita deve ser representada na moeda indicada.

8. Ajuste os "Atributos" se pretender passar pares Chave/Valor no Evento.

9. Configure um acionador adequado para disparar a etiqueta apenas quando esperado.

10. Guarde o Trigger e a Tag e teste na Pré-visualização.

Padrões comuns de implementação de eventos

Passo 4: Definir o ID de utilizador do cliente

O usuário pode enviar seu ID de usuário interno para a Singular usando um método do SDK da Singular.

Enquanto o usuário executa ações em seu site sem estar conectado, os eventos são enviados para a Singular com uma ID de usuário gerada pela Singular. Mas depois que o usuário se registra ou faz login, você pode ter eventos enviados para a Singular junto com o ID de usuário que é usado no seu site, por exemplo, um endereço de e-mail com hash.

A Singular usa a ID de usuário em exportações de dados no nível do usuário (consulte Exportando logs de atribuição), bem como em postbacks internos de BI, se você os tiver configurado (consulte Configurando postbacks internos de BI).

Há duas maneiras de enviar a ID de usuário para o Singular:

• Recomendado: Se você souber a ID do usuário quando o site for aberto, defina a ID do usuário no tipo de faixa Inicialização ao inicializar o SDK. Isso torna a ID de usuário disponível para a Singular desde a primeira visita à página.
• Como alternativa, é possível acionar uma Tag com Track Type = Login a qualquer momento, geralmente após a ocorrência de uma autenticação. Recomendamos chamá-la assim que o ID do usuário estiver disponível. Observação: chamar essa tag não aciona um evento. Apenas define o ID do utilizador para ser adicionado a quaisquer accionadores de eventos no futuro!

Para definir o ID de usuário com o Singular, adicione uma tag Singular com o tipo de rastreamento "Login":

1. Na sua conta do Google Tag Manager, clique em Tags > Novo.
2. Na janela Configuração de tag, clique em Configuração de tag e, no menu Tipo de tag, selecione "Singular Web Tracking".
3. Em Tipo de rastreio, selecione "Início de sessão".
4. Em ID de utilizador personalizado, introduza a variável do Google Tag Manager que contém o ID de utilizador.
5. Clique em Desencadeamento e adicione o evento de desencadeamento: início de sessão do utilizador ou registo.
6. Clique em Guardar.

Para anular o ID de utilizador, adicione uma etiqueta com o tipo de pista " Terminar sessão":

1. Na sua conta do Google Tag Manager, clique em Tags > Novo.
2. Na janela Configuração de tags, clique em Configuração de tags e, no menu Tipo de tag, selecione "Seguimento singular da Web".
3. Em Tipo de seguimento, selecione "Terminar sessão".
4. Clique em Desencadeamento e adicione o evento de desencadeamento: fim de sessão do utilizador.
5. Clique em Guardar.

Etapa 5: Evitar eventos duplicados

Como evitar eventos duplicados no Gerenciador de tags do Google

Por que ocorrem duplicatas no GTM

O Google Tag Manager avalia os accionadores em cada carregamento de página, fazendo com que as etiquetas sejam acionadas novamente quando os utilizadores actualizam as páginas de agradecimento, reenviam formulários ou navegam utilizando os botões de retrocesso/avanço do browser. Isso acontece porque o GTM não possui reconhecimento de sessão incorporado para eventos personalizados.

Métodos de deduplicação do GTM

Abordagem de armazenamento de sessão: Armazene identificadores de eventos exclusivos no sessionStorage do navegador para rastrear quais eventos já foram disparados durante a sessão do usuário.

Variáveis JavaScript personalizadas: Crie variáveis que verifiquem o localStorage em busca de eventos disparados anteriormente antes de permitir o disparo de novos eventos.

Condições de acionamento: Adicionar lógica condicional aos accionadores que evita o disparo quando estão presentes indicadores duplicados.

Etapas de implementação

Criar variável de armazenamento: Crie uma variável JavaScript personalizada que gere identificadores exclusivos para cada evento Singular com base nos parâmetros do evento e na sessão do usuário.

Criar variável de verificação: Crie outra variável JavaScript personalizada que verifica se o identificador de evento atual já existe no armazenamento do navegador.

Adicionar condições de acionamento: Modifique os acionadores do Singular Web SDK para incluir uma condição de que a variável "verificação duplicada" seja igual a "false".

Armazenar após disparar: Use o recurso Sequenciamento de tags do GTM para disparar uma tag HTML personalizada que armazena o identificador do evento no sessionStorage após o disparo bem-sucedido do evento Singular.

Considerações específicas do GTM

Sequenciamento de tags: Use o Sequenciamento de tags das Configurações avançadas para garantir que as tags de armazenamento sejam disparadas após a conclusão das principais tags Singular.

Avaliação de variáveis: Lembre-se de que as variáveis JavaScript personalizadas são avaliadas cada vez que são referenciadas, portanto, otimize o desempenho.

Limitações entre domínios: O SessionStorage é específico do domínio, portanto, implemente soluções baseadas em cookies para rastreamento entre domínios, se necessário.

Para uma implementação detalhada: Consulte os guias abrangentes de deduplicação do GTM:

• Impedir envios duplicados de formulários com o Google Tag Manager - Analytics Mania
• Impedir que as tags sejam disparadas após o recarregamento da página - Analytico Digital

Etapa 6: Testar sua implementação do GTM

1. Abra o modo de visualização do GTM e carregue seu site.
2. Verifique se:

• O SDK é carregado (solicitação de rede para singular-sdk.js)
• Os eventos são acionados como esperado e apenas uma vez por ação
• Não há erros no console do navegador relacionados a singular
• Os pedidos de rede são enviados para sdk-api-v1.singular.net

3. Utilize o separador Rede nas ferramentas de desenvolvimento do browser para verificar se o payload adequado é enviado

Passo 7: Implementar o reencaminhamento da Web para a aplicação

Encaminhamento de Atribuição Web-para-App

Use o Singular Web SDK para rastrear as jornadas do usuário do seu site para o seu aplicativo móvel, permitindo a atribuição precisa de campanhas da web a instalações e reengajamentos de aplicativos móveis. Siga estas etapas para configurar o encaminhamento da web para o aplicativo, incluindo o suporte a código QR para usuários de desktop.

1. Siga nosso Guia de Encaminhamento de Atribuição de Website para Aplicativo Móvelpara configurar o Singular Web SDK para atribuição de web móvel.
2. Para rastreamento Web-to-App para desktop:
   • Criar uma tag de limpeza do gerador de código QR
     1. Navegue até Tags > Novo no GTM e selecione HTML personalizado.
     2. Adicione código para:
        • Injetar a biblioteca QRCode que escolher
        • Recuperar o link Web-to-App em window.singularSdk.buildWebToAppLink(baselink);
        • Gerar o QRCode a partir do link retornado.
        • Atualizar a imagem QRCode na página.
     3. Nomear a etiqueta: "Singular - Gerador de código QR (Limpeza)"
     4. Não é necessário acionador: As tags de limpeza herdam os gatilhos da tag principal
     5. Configure a sua tag Singular Init:
        • Clique em Configuração de etiquetas
        • Aceda a Definições avançadas > Sequenciação de etiquetas
        • Selecione "Disparar uma etiqueta de limpeza após o disparo da [Etiqueta de inicialização singular]".
        • Selecione a sua etiqueta Gerador de código QR no menu pendente
        • Guarde a etiqueta e teste-a no modo de pré-visualização.

Tópicos avançados

Adição de propriedades globais

<script>
/**
 * Set a Singular global property before SDK initialization.
 * Allows up to 5 key/value pairs. Optionally overwrites existing value for a key.
 * 
 * @param {string} propertyKey - The property key to set.
 * @param {string} propertyValue - The property value to set.
 * @param {boolean} overrideExisting - Whether to overwrite the property if it already exists.
 */

// Example usage - customize these values for your implementation
window.singularSdk.setGlobalProperties('user_type', 'premium', true);
window.singularSdk.setGlobalProperties('app_version', '2.1.0', false);
</script>

<script>
// Get all global properties as a JSON object
var globalProps = window.singularSdk.getGlobalProperties();
console.log('Current global properties:', globalProps);
</script>

<script>
// Clears all Global Properties.

// Example usage
clearGlobalProperties();
</script>

Rastreamento de pesquisa orgânica

<script>
(function() {
    // singular-web-organic-search-tracking: setupOrganicSearchTracking.js
    // Tracks organic search referrals by appending wpsrc and wpcn to the URL if no campaign parameters exist and the referrer is a search engine.

    // Configuration for debugging (set to true to enable logs)
    var debug = true;

    // List of campaign parameters to check for exclusion
    var campaignParams = [
        'gclid', 'fbclid', 'ttclid', 'msclkid', 'twclid', 'li_fat_id',
        'utm_source', 'utm_medium', 'utm_campaign', 'utm_term', 'utm_content', 'wpsrc'
    ];

    // Whitelist of legitimate search engine domains (prevents false positives)
    var legitimateSearchEngines = new Set([
        // Google domains
        'google.com', 'google.co.uk', 'google.ca', 'google.com.au', 'google.de', 
        'google.fr', 'google.it', 'google.es', 'google.co.jp', 'google.co.kr',
        'google.com.br', 'google.com.mx', 'google.co.in', 'google.ru', 'google.com.sg',
        
        // Bing domains  
        'bing.com', 'bing.co.uk', 'bing.ca', 'bing.com.au', 'bing.de',
        
        // Yahoo domains
        'yahoo.com', 'yahoo.co.uk', 'yahoo.ca', 'yahoo.com.au', 'yahoo.de',
        'yahoo.fr', 'yahoo.it', 'yahoo.es', 'yahoo.co.jp',
        
        // Other search engines
        'baidu.com', 'duckduckgo.com', 'yandex.com', 'yandex.ru',
        'ask.com', 'aol.com', 'ecosia.org', 'startpage.com', 
        'qwant.com', 'seznam.cz', 'naver.com', 'daum.net'
    ]);

    // Extract main domain from hostname (removes subdomains)
    function getMainDomain(hostname) {
        if (!hostname) return '';
        
        var lowerHost = hostname.toLowerCase();
        
        // Handle special cases for known search engines with country codes
        var searchEnginePatterns = {
            'google': function(host) {
                // Match google.TLD patterns more precisely
                if (host.indexOf('google.co.') !== -1 || host.indexOf('google.com') !== -1) {
                    var parts = host.split('.');
                    for (var i = 0; i < parts.length - 1; i++) {
                        if (parts[i] === 'google') {
                            return parts.slice(i).join('.');
                        }
                    }
                }
                return null;
            },
            'bing': function(host) {
                if (host.indexOf('bing.co') !== -1 || host.indexOf('bing.com') !== -1) {
                    var parts = host.split('.');
                    for (var i = 0; i < parts.length - 1; i++) {
                        if (parts[i] === 'bing') {
                            return parts.slice(i).join('.');
                        }
                    }
                }
                return null;
            },
            'yahoo': function(host) {
                if (host.indexOf('yahoo.co') !== -1 || host.indexOf('yahoo.com') !== -1) {
                    var parts = host.split('.');
                    for (var i = 0; i < parts.length - 1; i++) {
                        if (parts[i] === 'yahoo') {
                            return parts.slice(i).join('.');
                        }
                    }
                }
                return null;
            }
        };
        
        // Try specific patterns for major search engines
        for (var engine in searchEnginePatterns) {
            if (lowerHost.indexOf(engine) !== -1) {
                var result = searchEnginePatterns[engine](lowerHost);
                if (result) return result;
            }
        }
        
        // Handle other known engines with simple mapping
        var otherEngines = {
            'baidu.com': 'baidu.com',
            'duckduckgo.com': 'duckduckgo.com', 
            'yandex.ru': 'yandex.ru',
            'yandex.com': 'yandex.com',
            'ask.com': 'ask.com',
            'aol.com': 'aol.com',
            'ecosia.org': 'ecosia.org',
            'startpage.com': 'startpage.com',
            'qwant.com': 'qwant.com',
            'seznam.cz': 'seznam.cz',
            'naver.com': 'naver.com',
            'daum.net': 'daum.net'
        };
        
        for (var domain in otherEngines) {
            if (lowerHost.indexOf(domain) !== -1) {
                return otherEngines[domain];
            }
        }
        
        // Fallback: Extract main domain by taking last 2 parts (for unknown domains)
        var parts = hostname.split('.');
        if (parts.length >= 2) {
            return parts[parts.length - 2] + '.' + parts[parts.length - 1];
        }
        
        return hostname;
    }

    // Get query parameter by name, using URL.searchParams with regex fallback for IE11
    function getParameterByName(name, url) {
        if (!url) url = window.location.href;
        try {
            return new URL(url).searchParams.get(name) || null;
        } catch (e) {
            if (debug) console.warn('URL API not supported, falling back to regex:', e);
            name = name.replace(/[\[\]]/g, '\\$&');
            var regex = new RegExp('[?&]' + name + '(=([^&#]*)|&|#|$)');
            var results = regex.exec(url);
            if (!results) return null;
            if (!results[2]) return '';
            return decodeURIComponent(results[2].replace(/\+/g, ' '));
        }
    }

    // Check if any campaign parameters exist in the URL
    function hasAnyParameter(url, params) {
        for (var i = 0; i < params.length; i++) {
            if (getParameterByName(params[i], url) !== null) {
                return true;
            }
        }
        return false;
    }

    // Improved search engine detection - only checks hostname, uses whitelist
    function isSearchEngineReferrer(referrer) {
        if (!referrer) return false;
        
        var hostname = '';
        try {
            hostname = new URL(referrer).hostname.toLowerCase();
        } catch (e) {
            // Fallback regex for hostname extraction (IE11 compatibility)
            var match = referrer.match(/^(?:https?:\/\/)?([^\/\?#]+)/i);
            hostname = match ? match[1].toLowerCase() : '';
        }
        
        if (!hostname) return false;
        
        // First check: exact match against whitelist
        if (legitimateSearchEngines.has(hostname)) {
            if (debug) console.log('Exact match found for:', hostname);
            return true;
        }
        
        // Second check: subdomain of legitimate search engine
        var hostParts = hostname.split('.');
        if (hostParts.length >= 3) {
            // Try domain.tld combination (e.g., google.com from www.google.com)
            var mainDomain = hostParts[hostParts.length - 2] + '.' + hostParts[hostParts.length - 1];
            if (legitimateSearchEngines.has(mainDomain)) {
                if (debug) console.log('Subdomain match found for:', hostname, '-> main domain:', mainDomain);
                return true;
            }
            
            // Try last 3 parts for country codes (e.g., google.co.uk from www.google.co.uk)
            if (hostParts.length >= 3) {
                var ccDomain = hostParts[hostParts.length - 3] + '.' + hostParts[hostParts.length - 2] + '.' + hostParts[hostParts.length - 1];
                if (legitimateSearchEngines.has(ccDomain)) {
                    if (debug) console.log('Country code domain match found for:', hostname, '-> cc domain:', ccDomain);
                    return true;
                }
            }
        }
        
        if (debug) {
            console.log('Hostname not recognized as legitimate search engine:', hostname);
        }
        
        return false;
    }

    // Main function to update URL with organic search tracking parameters
    function setupOrganicSearchTracking() {
        var url = window.location.href;
        var referrer = document.referrer || '';

        // Store URL and referrer in localStorage
        try {
            localStorage.setItem('sng_url', url);
            localStorage.setItem('sng_ref', referrer);
        } catch (e) {
            if (debug) console.warn('localStorage not available:', e);
        }

        if (debug) {
            console.log('Current URL:', url);
            console.log('Referrer:', referrer);
        }

        // Skip if campaign parameters exist or referrer is not a search engine
        var hasCampaignParams = hasAnyParameter(url, campaignParams);
        if (hasCampaignParams || !isSearchEngineReferrer(referrer)) {
            if (debug) console.log('Skipping URL update: Campaign params exist or referrer is not a legitimate search engine');
            return;
        }

        // Extract and validate referrer hostname
        var referrerHostname = '';
        try {
            referrerHostname = new URL(referrer).hostname;
        } catch (e) {
            if (debug) console.warn('Invalid referrer URL, falling back to regex:', e);
            var match = referrer.match(/^(?:https?:\/\/)?([^\/]+)/i);
            referrerHostname = match ? match[1] : '';
        }

        // Extract main domain from hostname
        var mainDomain = getMainDomain(referrerHostname);
        
        if (debug) {
            console.log('Full hostname:', referrerHostname);
            console.log('Main domain:', mainDomain);
        }

        // Only proceed if main domain is valid and contains safe characters
        if (!mainDomain || !/^[a-zA-Z0-9.-]+$/.test(mainDomain)) {
            if (debug) console.log('Skipping URL update: Invalid or unsafe main domain');
            return;
        }

        // Update URL with wpsrc and wpcn parameters
        var urlObj;
        try {
            urlObj = new URL(url);
        } catch (e) {
            if (debug) console.warn('URL API not supported, cannot modify URL:', e);
            return;
        }
        
        // Set wpsrc to the main domain (e.g., google.com instead of tagassistant.google.com)
        urlObj.searchParams.set('wpsrc', mainDomain);
        
        // Set wpcn to 'Organic Search' to identify the campaign type
        urlObj.searchParams.set('wpcn', 'Organic Search');

        // Update the URL without reloading (check if history API is available)
        if (window.history && window.history.replaceState) {
            try {
                window.history.replaceState({}, '', urlObj.toString());
                if (debug) console.log('Updated URL with organic search tracking:', urlObj.toString());
            } catch (e) {
                if (debug) console.warn('Failed to update URL:', e);
            }
        } else {
            if (debug) console.warn('History API not supported, cannot update URL');
        }
    }

    // Execute the function
    setupOrganicSearchTracking();
})();
</script>

Rastreamento entre subdomínios

Por predefinição, o Singular Website SDK gera uma ID de dispositivo Singular e persiste-a utilizando o armazenamento do browser. Como esse armazenamento não pode ser compartilhado entre subdomínios, o SDK acaba gerando uma nova ID para cada subdomínio.

Se quiser manter a ID de Dispositivo Singular em todos os subdomínios, pode usar uma das seguintes opções:

Problemas comuns de implementação do GTM

Práticas recomendadas

• Mantenha o GTM organizado: Nomeie claramente as tags e os acionadores e documente sua finalidade.
• Auditar regularmente as tags não utilizadas ou antigas.
• Minimize o número de accionadores para reduzir o risco de eventos duplicados.
• Após as alterações, sempre teste completamente no modo de visualização do GTM antes de colocar em produção.
• Se você usa rastreamento baseado em cookies(rastreamento entre subdomínios), atualize sua política de privacidadede acordo.

Artigos relacionados

• Guia de implementação do JavaScript nativo
• Guia de implementação do Google Tag Manager
• Solução de problemas e práticas recomendadas
• Perguntas frequentes sobre atribuição da Web