Guia de início rápido sobre modelos personalizados

Com modelos personalizados, você pode criar suas próprias definições de tags e variáveis para que outras pessoas na organização possam usá-las com os modelos integrados de tags e variáveis. A natureza dos modelos personalizados, que se baseia em permissões e em sandbox, possibilita a criação de tags e variáveis personalizadas de maneira mais eficiente e segura do que com a personalização de tags HTML e variáveis JavaScript.

Os modelos personalizados de variáveis e tags são definidos na seção Modelos do Gerenciador de tags do Google. Na tela principal "Modelos", você encontra uma lista de todos aqueles que já foram definidos no seu contêiner e também poderá criar outros.

É possível exportar um modelo e compartilhar com outras pessoas na sua organização, e os modelos podem ser desenvolvidos para uma distribuição mais ampla na Galeria de modelos da comunidade.

Editor de modelos

Com o editor de modelos, é possível criar, visualizar e testar modelos personalizados. Ele tem quatro áreas principais de entrada para ajudar você a definir seu modelo de tag:

  • Informações: define propriedades básicas do modelo, como nome da tag ou variável e ícone.
  • Campos: é um editor visual para adicionar campos de entrada ao seu modelo de tag.
  • Código: acessa o JavaScript em modo sandbox para definir como sua tag ou variável se comportará.
  • Permissões: exibe e define limites de atividade para sua tag ou variável.

Criar seu primeiro modelo de tag personalizado

Neste exemplo, vamos mostrar como criar uma tag de pixel básica. Quando essa tag é disparada em uma página da Web, ela envia um hit com as informações certas da conta para os servidores do provedor de tags.

1. Para começar seu primeiro modelo, clique em "Modelos" na navegação à esquerda e no botão Novo da seção Modelos de tag.

2. Clique em Informações e defina o Nome (obrigatório), a Descrição e o Ícone da tag.

O nome vai aparecer para os usuários quando eles implementarem essa tag usando a IU do Gerenciador de tags.

A descrição é uma breve explicação da função da tag em, no máximo, 200 caracteres.

O ícone permite escolher a imagem mostrada quando a tag aparece em listas compatíveis com a propriedade do ícone. As imagens do ícone precisam ser arquivos quadrados no formato PNG, JPEG ou GIF com, no máximo, 50 kB e 64 x 64 pixels pelo menos.

3. Clique em Atualizar para visualizar seu modelo.

À direita dos campos de entrada, há uma janela Visualização do modelo. Sempre que uma alteração é feita no editor, o botão Atualizar é exibido. Clique nele para ver os resultados das suas alterações na aparência da tag.

4. Clique em Campos para adicionar campos ao modelo de tag.

A guia Campos do editor de modelos permite criar e editar campos no modelo de tag. Os campos são usados para inserir dados personalizados, como um ID da conta. Você pode adicionar elementos de formulário padrão, como campos de texto, menus suspensos, botões de opção e caixas de seleção.

5. Clique em Adicionar campo e selecione Entrada de texto. Substitua o nome padrão (por exemplo: "text1") por "accountId". Em Visualização do modelo, clique em Atualizar.

Ao lado do campo, há um ícone de seletor de variável (ícone de seletor de variável). Os usuários do modelo podem clicar nesse ícone para escolher as variáveis que estão ativas no contêiner.

Em seguida, adicione uma etiqueta ao campo:

6. Clique no ícone de expansão (ícone de expansão) ao lado do campo de texto para abrir mais opções. Insira ID da conta no campo Nome de exibição. Em Visualização do modelo, clique em Atualizar.

Um rótulo de texto chamado ID da conta vai aparecer acima do campo.

7. Clique na guia Código e insira o JavaScript no modo sandbox no editor:

// require relevant API
const sendPixel = require('sendPixel');
const encodeUriComponent = require('encodeUriComponent');

// capture values of template fields
const account = data.accountId;

// use the provided APIs to do things like send pixels
const url = 'https://endpoint.example.com/?account=' + encodeUriComponent(account);
sendPixel(url, data.gtmOnSuccess, data.gtmOnFailure);

A primeira linha de código, const sendPixel = require('sendPixel'), importa a API sendPixel.

A segunda linha de código, const encodeUriComponent = require('encodeUriComponent'), importa a API encodeUriComponent.

A próxima linha, const account = data.accountId;, usa o valor de accountId que foi criado na etapa 5 e o armazena em uma constante chamada account.

A terceira linha de código, const url = 'https://endpoint.example.com/?account=' + encodeUriComponent(account);, define uma constante url que concatena um endpoint de URL fixo que registra dados de análise e o ID codificado da conta, usado na configuração da tag.

A última linha, sendPixel(url, data.gtmOnSuccess, data.gtmOnFailure), executa a função sendPixel() com os parâmetros obrigatórios e faz uma solicitação ao URL especificado. Os valores data.gtmOnSuccess e data.gtmOnFailure informam ao Gerenciador de tags do Google quando a tarefa foi concluída ou falhou. Além disso, são usados por ele para recursos como sequenciamento de tags ou modo de visualização.

8. Clique em Salvar para registrar seu progresso. Com isso, as permissões detectadas serão carregadas no editor de modelos.

Algumas APIs de modelo têm permissões associadas que determinam o que elas podem fazer. Quando você usa uma API de modelo (como sendPixel) no seu código, o Gerenciador de tags mostra as autorizações relevantes na guia Permissões.

9. Clique em Permissões para refinar a que domínios sendPixel pode enviar dados. Para a entrada Enviar pixels, clique no ícone de expansão (ícone de expansão) e insira https://endpoint.example.com/ em Padrões de correspondência de URL permitidos.

Quando um modelo de tag está configurado para enviar dados, é necessário especificar um Padrão de correspondência de URL permitido na permissão associada para restringir o destino das informações. Se o URL especificado no código não corresponde a um padrão, a chamada do sendPixel falhará.

Um padrão de correspondência de URL precisa usar HTTPS e especificar os padrões de host e caminho. O host pode ser um domínio (por exemplo, "https://example.com/") ou subdomínio específico (como "https://sub.example.com/"). O caminho precisa ter pelo menos um "/". Use um asterisco (*) como caractere coringa para indicar um subdomínio ou padrão de caminho de qualquer tamanho (como "https://\*.example.com/test/"). O asterisco captura os diversos padrões possíveis. Por exemplo, "\*.example.com/" corresponde a www.example.com, shop.example.com, blog.example.com etc. Antes dele, precisa haver um caractere de barra invertida: "\*". Um URL sem caracteres extras ("https://example.com/") é considerado como se terminasse em um caractere curinga (ou seja, equivalente a "https://example.com/\*").

Especifique padrões de correspondência de URL adicionais em linhas separadas.

10. Clique em Executar código e confira se há problemas na janela Console.

Os erros detectados aparecerão na janela Console.

11. Clique em Salvar e feche o editor de modelos.

O modelo de tag estará pronto para ser usado.

Usar sua tag nova

O processo de criação de uma tag que usa seu modelo de tag personalizada recém-definido é igual ao de qualquer outra tag:

  1. No Gerenciador de tags do Google, clique em Tags > Nova.
  2. Ela aparecerá na seção Personalizada da janela Nova tag. Clique nela para abrir o modelo de tag.
  3. Preencha os campos necessários para a configuração desse modelo.
  4. Clique em Acionamento e selecione um acionador apropriado para o disparo da tag.
  5. Salve a tag e publique seu contêiner.

Criar seu primeiro modelo de variável personalizada

Modelos de variáveis personalizadas são semelhantes aos modelos de tags, com algumas diferenças importantes:

  • Os modelos de variáveis personalizadas precisam retornar um valor.

    Em vez de chamar data['gtmOnSuccess'] para indicar a conclusão, as variáveis retornam um valor diretamente.

  • Os modelos de variáveis personalizadas são usados em diferentes partes da interface do Gerenciador de tags.

  • Em vez de acessar Tags > Nova para criar uma variável com base na personalizada, clique em Variáveis > Nova.

Consulte Criar uma variável personalizada para ver um guia completo sobre como criar um modelo de variável personalizada.

Exportar e importar

Para compartilhar um modelo personalizado na sua organização, você pode exportar e importá-lo para outros contêineres do Gerenciador de tags. Para exportar um modelo, faça o seguinte:

  1. No Gerenciador de tags, clique em Modelos.
  2. Clique no nome do modelo que você quer exportar na lista. Ele será aberto no editor de modelos.
  3. Clique no menu Mais ações () e selecione Exportar.

Para importar um modelo, siga estas etapas:

  1. No Gerenciador de tags, clique em Modelos.
  2. Clique em Novo. Um modelo em branco será aberto no editor de modelos.
  3. Clique no menu Mais ações () e selecione Importar.
  4. Selecione o arquivo .tpl que você quer importar.