Guia de início rápido sobre modelos personalizados

Visão geral

Com modelos personalizados, você pode criar suas próprias definições de tag e variáveis para que outras pessoas na organização possam usá-las com a tag e os modelos de variáveis integrados. 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 tags HTML e variáveis JavaScript personalizadas.

Os modelos de variável e tag personalizados são definidos na seção "Modelos" do Gerenciador de tags do Google. Se você tiver acesso ao recurso Modelos personalizados, o botão "Modelos" aparecerá à esquerda na navegação. A tela principal em Modelos listará todos os modelos de tag ou variável que já foram definidos no seu contêiner. Também é possível criar novos modelos a partir desta tela.

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:

  • Info: define propriedades básicas do modelo, como nome da tag ou variável e ícone.
  • Campos: editor visual utilizado para adicionar campos no seu modelo de tag.
  • Código: acessa o JavaScript em modo sandbox para mostrar como sua tag ou variável se comportará.
  • Permissões: para visualização e definição de limites sobre o que sua tag ou variável pode fazer de acordo com o respectivo código.

Criar seu primeiro modelo de tag personalizado

1. Para criar seu primeiro modelo, navegue até a tela "Modelos" e clique no botão Novo na 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 será exibido aos usuários quando eles implementarem essa tag pela interface do usuário do Gerenciador de tags.

A descrição é uma breve explicação (de 200 caracteres ou menos) da função da tag.

O ícone permite escolher a imagem que aparecerá quando a tag for exibida 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 pelo menos 64 x 64 pixels.

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 aparecerá. Clique nele para ver os resultados das suas alterações na aparência da tag.

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

Na guia Campos do editor de modelos, você pode adicionar e editar os campos no modelo de tag. 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.

Parabéns, você inseriu um campo de formulário na sua tag! Atente-se a alguns pontos sobre isso. Primeiro, cada campo tem o conhecido ícone de seletor de variável (ícone de seletor de variável) ao lado dele. Os usuários desse modelo podem usar o ícone para escolher as variáveis que estão ativas no contêiner. Ainda não há etiqueta de campo. Vamos adicioná-la em seguida:

6. No lado direito do campo de texto, há o ícone de expansão (ícone de expansão). Clique nele para ver mais opções desse campo e informe o ID da conta no campo Nome de exibição. Em Visualização do modelo, clique em Atualizar.

O texto "ID da conta" aparecerá acima do campo.

6. Clique na guia Código e insira este código 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'), inclui a API sendPixel.

A segunda linha, const encodeUriComponent = require('encodeUriComponent'), inclui a API encodeUriComponent.

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

const url = 'https://endpoint.example.com/?account=' + encodeUriComponent(account); define uma constante de url que concatena um endpoint de URL fixo que registra dados de análise e o ID da conta codificado com o qual a tag foi configurada.

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 de data['gtmOnSuccess'] e data['gtmOnFailure'] informam ao Gerenciador de tags do Google quando a tag concluiu ou falhou na tarefa e são usados por ele para recursos como o modo de visualização ou o sequenciamento de tags.

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

Algumas Template APIs 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 permissões relevantes na guia Permissões.

8. Clique em Permissões para refinar quais domínios podem receber dados de sendPixel. Para a entrada Enviar pixels, clique no ícone de expansão (ícone de expansão) e insira https://endpoint.example.com/ em Domínios 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 ambos os padrões, de host e caminho. O host pode ser um domínio (por exemplo, "https://example.com/") ou um subdomínio específico (como "https://sub.example.com/"). O caminho precisa contar com pelo menos um "/". Use um asterisco como curinga para indicar um subdomínio ou um padrão de caminho de qualquer tamanho (por exemplo, "https://\*.example.com/test/\*"). Um caminho sem caracteres à direita (por exemplo, "https://example.com/") será considerado como se tivesse um caractere curinga no final (o equivalente a "https://example.com/\*").

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

9. Clique em Teste e veja se há problemas na janela Console.

Os erros detectados aparecerão na janela Console.

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

O modelo de tag estará pronto para ser usado.

Usar sua nova tag

O processo de criação de uma nova tag que usa seu modelo personalizado recém-definido é igual a 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.