Visão geral

Este guia explica como implementar o SDK da Singular Web usando o Google Tag Manager (GTM). Esse método é ideal para equipes sem acesso direto ao código do site ou que desejam gerenciar o rastreamento por meio do GTM.

Pré-requisitos

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

• Chave SDK e Segredo SDK: 
  • 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 o seu site, idealmente usando o formato DNS reverso (por exemplo, com.website-name).
  • Por que é importante: esse ID associa o site como um aplicativo no Singular e deve corresponder ao bundleID do aplicativo web listado na sua página de aplicativos no Singular. 
• O Google Tag Managerfoi 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 você não tiver permissão para publicar alterações no Google Tag Manager, será necessário pedir a alguém para publicar as alterações após o teste.
• Conhecimento sobre como visualizar e depurar contêineres e tags no GTM. 
• Uma lista de eventos que você deseja rastrear. Veja nossos Eventos Padrão Singular: Lista Completa e Eventos Recomendados por Vertical para obter ideias.

Etapas de implementação

Etapa 1: adicione os modelos de rastreamento da web Singular ao seu contêiner 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. Nomeie a tag: "Singular Init Tag"
4. Clique na caixa Configuração da tag para iniciar a configuração da tag.
5. Escolha o tipo de tag: e selecione "Descubra mais tipos de tags na Galeria de modelos da comunidade".
6. Pesquise por "Singular" e selecione "Rastreamento da Web Singular". 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
   • Insira sua chave SDK real no campo Chave API
   • Insira seu segredo SDK real no campo Segredo .

   • Insira seu ID do produto real. Ele deve parecer com: com.website-name e deve corresponder ao valor BundleID na página Apps na plataforma Singular.

     DICA! Use um ID do produto específico para testes com.website-name.dev e atualize-o antes de enviar para 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 SDK debug logging para o console. O padrão é nenhum.
     • Desduplicação de eventos
     • Definição de propriedades globais
     • Ativação de banners inteligentes (somente para empresas)
     • Definição do ID do usuário do cliente
     • Tempo limite da sessão: quanto tempo o usuário deve ficar inativo antes que o SDK crie uma nova sessão. O Singular envia sessões do usuário para calcular a retenção do usuário e habilitar a atribuição de reengajamento. O valor padrão é 30 minutos.
     • Rastreamento entre subdomínios
2. Selecione Triggering para configurar um gatilho para fazer esta tag funcionar.
3. Selecione Novo e nomeie o acionador: "Singular Init Trigger".
4. Clique em Trigger Configuration (Configuração do gatilho) e escolha "Page View - Window Loaded" (Visualização da página - Janela carregada) e clique em "Save" (Salvar).
5. Clique em "Salvar" novamente para salvar a tag.
6. Clique em "Visualizar" na página Tag e teste se a Singular Initialization Tag é acionada.
   
   

Etapa 3: Rastreamento de eventos

Após inicializar o SDK, você pode rastrear eventos personalizados quando os usuários realizam ações importantes em 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 seu evento personalizado usando o modelo de rastreamento da web da Singular . Dê um nome à tag do evento.

2. Nomeie a tag do 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 "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 gatilho adequado para disparar a tag apenas quando esperado.

8. Salve o Gatilho e a Tag e teste na Visualização.

Rastreamento de eventos de conversão

Rastreie um evento de conversão:

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

2. Nomeie a tag do evento de conversão.

3. Escolha o tipo de rastreamento = Evento de conversão

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

5. Ajuste o campo "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 gatilho adequado para disparar a tag apenas quando esperado.

8. Salve o gatilho e a tag e teste na visualização.

Rastreamento 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 seu evento personalizado usando o modelo Singular Web Tracking.

2. Nomeie a 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 "ID do usuário personalizado" ou defina a variável apropriada .

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 "Receita" ou defina a variável apropriada. A receita deve ser representada na moeda indicada.

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

9. Configure um gatilho adequado para disparar a tag apenas quando esperado.

10. Salve o gatilho e a tag e teste na visualização.

Padrões comuns de implementação de eventos

Etapa 4: Definir o ID do usuário do cliente

Você pode enviar sua ID de usuário interna para a Singular usando um método SDK da Singular.

Enquanto o usuário realizar ações em seu site sem estar conectado , os eventos serão enviados para a Singular com um ID de usuário gerado pela Singular. Mas depois que o usuário se registrar ou fizer login, você poderá enviar eventos para a Singular junto com o ID de usuário usado em seu site, por exemplo, um endereço de e-mail com hash.

O Singular usa o ID do 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 configurados (consulte Configurando postbacks internos de BI).

Existem duas maneiras de enviar o ID do usuário para o Singular:

• Recomendado: se você souber a ID do usuário quando o site abrir, defina a ID do usuário no tipo de rastreamento Inicialização ao inicializar o SDK. Isso torna a ID do usuário disponível para o Singular desde a primeira visita à página.
• Como alternativa, você pode acionar uma tag com o tipo de rastreamento = Login a qualquer momento, geralmente após a autenticação ocorrer. Recomendamos chamá-la assim que a ID do usuário estiver disponível. Observação: chamar essa tag não aciona um evento. Ela apenas define a ID do usuário a ser adicionada a quaisquer acionadores de evento daqui em diante!

Para definir o ID do 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 da tag, clique em Configuração da tag e, no menu Tipo de tag , selecione "Rastreamento da Web Singular".
3. Em Tipo de rastreamento, selecione "Login".
4. Em ID de usuário personalizada, insira a variável do Gerenciador de tags do Google que contém a ID do usuário.
5. Clique em Acionamento e adicione o evento de acionamento: login ou registro do usuário .
6. Clique em Salvar.

Para desativar a ID do usuário, adicione uma tag com o tipo de rastreamento "Logout":

1. Na sua conta do Google Tag Manager, clique em Tags > Novo.
2. Na janela Tag Configuration (Configuração da tag ), clique em Tag Configuration(Configuração da tag) e, no menu Tag Type(Tipo de tag) , selecione "Singular Web Tracking" (Rastreamento único da Web).
3. Em Tipo de rastreamento, selecione "Logout".
4. Clique em Acionamento e adicione o evento de acionamento: logout do usuário.
5. Clique em Salvar.

Etapa 5: Desduplicação de eventos (opcional)

Deduplicação de eventos no Google Tag Manager

Por que ocorrem duplicatas no GTM

O GTM pode avaliar e disparar tags várias vezes para a mesma ação do usuário (por exemplo, condições de disparo repetidas ou vários ouvintes de eventos), o que pode levar à duplicação das exportações de eventos do Singular.

Método de deduplicação do GTM (recomendado)

Desduplicação de eventos do SDK do Singular: habilite a desduplicação no modelo GTM do SDK da Web do Singular para descartar eventos duplicados que correspondam aos mesmos parâmetros de desduplicação dentro de uma janela de tempo configurável.

Etapas de implementação

Habilite a deduplicação de eventos: Na sua tag/modelo de inicialização do SDK da Web Singular , habilite a opção Deduplicação de eventos.

Definir a janela de tempo (opcional): Configure a janela de tempo máxima (em milissegundos) usada para considerar dois eventos duplicados (padrão: 1000 ms / 1 segundo).

Como funciona a deduplicação

Quando ativado, o SDK suprime eventos (excluindo visitas à página) quando o mesmo evento ocorre novamente dentro da janela de tempo usando um hash desses parâmetros: EventName , EventProductName, IsRevenueEvent , CustomUserId, GlobalProperties , MatchId e WebUrl (além da carga útil "extra" do evento, como receita e argumentos personalizados).

Etapa 6: Testando sua implementação do GTM

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

• O SDK carregue (solicitação de rede para singular-sdk.js)
• Os eventos são acionados conforme o esperado e apenas uma vez por ação
• Não há erros no console do navegador relacionados a singular
• As solicitações de rede são enviadas para sdk-api-v1.singular.net

3. Use a guia Rede nas ferramentas de desenvolvedor do navegador para verificar se a carga útil correta é enviada

Etapa 7: Implemente o encaminhamento da Web para o aplicativo

Encaminhamento de atribuição Web-to-App

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

1. Siga nosso Guia de encaminhamento de atribuição do site para o aplicativo móvel para configurar o SDK da Singular Web para atribuição da web móvel.
2. Para rastreamento de Web para aplicativo móvel:
   • Adicione a tag Abrir aplicativo e defina o gatilho de disparo no clique do botão para abrir ou instalar seu aplicativo.

     1. Ao configurar a tag Abrir aplicativo, especifique seu link base da Web móvel para aplicativo na página Gerenciar links do Singular.

        

3. Para rastreamento de Web para aplicativo em desktop:
   • Crie uma tag de limpeza do gerador de código QR
     1. Navegue até Tags > Novo no GTM e selecione HTML personalizado.
     2. Adicione o código a:
        • Injetar a biblioteca QRCode que você escolher
        • Recupere o link Web-to-App de window.singularSdk.buildWebToAppLink(baselink);
        • Gere o QRCode a partir do link retornado.
        • Atualize a imagem do QRCode na página.
     3. Nomeie a tag: "Singular - Gerador de QR Code (Limpeza)"
     4. Não é necessário nenhum gatilho: as tags de limpeza herdam os gatilhos da tag principal
     5. Configure sua tag Singular Init:
        • Clique em Configuração da tag
        • Vá para Configurações avançadas > Sequência de tags
        • Marque "Disparar uma tag de limpeza após o disparo da [Tag Singular Init]"
        • Selecione sua tag QR Code Generator no menu suspenso
        • Salve a tag e teste no modo Visualizar.

Tópicos avançados

Banners Singular

Adicionando propriedades globais

Track Type: setGlobalProperties
propertyKey: user_type
value: premium

Track Type: getGlobalProperties

Track Type: unsetGlobalProperty
propertyKey: user_type

Track Type: clearGlobalProperties

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 padrão, o SDK do site Singular gera um ID de dispositivo Singular e o mantém usando o armazenamento do navegador. Como esse armazenamento não pode ser compartilhado entre subdomínios, o SDK acaba gerando um novo ID para cada subdomínio.

Se você deseja manter o ID de dispositivo Singular entre subdomínios, pode usar uma das seguintes opções:

Problemas comuns de implementação do GTM

Melhores práticas

• Mantenha o GTM organizado: nomeie as tags e os gatilhos de forma clara e documente sua finalidade.
• Audite regularmente as tags não utilizadas ou legadas.
• Minimize o número de gatilhos para reduzir o risco de eventos duplicados.
• Após as alterações, sempre teste exaustivamente no Modo de Visualização do GTM antes de publicar ao vivo.
• Se você usar rastreamento baseado em cookies (Rastreamento entre subdomínios), atualize sua política de privacidade de acordo.

Artigos relacionados

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