Visualizações em extensões da Web

OBSERVAÇÃO

A Adobe Experience Platform Launch foi reformulada como um conjunto de tecnologias de coleta de dados no Adobe Experience Platform. Como resultado, várias alterações de terminologia foram implementadas na documentação do produto. Consulte o seguinte documento para obter uma referência consolidada das alterações de terminologia.

Cada tipo de evento, condição, ação ou elemento de dados pode fornecer uma visualização, o que permite ao usuário fornecer configurações. A extensão também pode ter uma visualização de configuração de extensão de nível superior, o que permite aos usuários fornecer configurações globais para a extensão inteira. O processo de construção de uma visualização é idêntico em todos os tipos de visualizações.

Incluir um tipo de documento

Certifique-se de incluir uma tag doctype no arquivo HTML. Normalmente, isso significa iniciar o arquivo HTML com o seguinte:

<!DOCTYPE html>

Inclusão do script de iframe das tags

Inclua o script do iframe das tags no HTML da sua exibição:

<script src="https://assets.adobedtm.com/activation/reactor/extensionbridge/extensionbridge.min.js"></script>

Esse script fornece uma API de comunicação para permitir que sua exibição se comunique com o aplicativo de tags.

Registro com a API de comunicação de bridge de extensão

Após o carregamento do script do iframe, será necessário fornecer alguns métodos para tags que serão usadas para comunicação. Chame window.extensionBridge.register e passe um objeto da seguinte maneira:

window.extensionBridge.register({
  init: function(info) {
    // Populate view with info.settings which will exist if the user is editing something
    // that was previously saved.
    if (info.settings) {
      document.getElementById('name').value = info.settings.name;
    }
  },
  validate: function() {
    // Return whether the view is valid.
    return document.getElementById('name').value.length > 0;
  },
  getSettings: function() {
    // Return user-provided settings.
    return {
      name: document.getElementById('name').value
    };
  }
});

O conteúdo de cada um dos métodos precisará ser modificado para acomodar seus requisitos de visualização específicos.

init

O método init será chamado pelas tags assim que a exibição for carregada no iframe. Será transmitido um único argumento (info) que deve ser um objeto com as seguintes propriedades:

Propriedade Descrição
settings Um objeto que contém as configurações que foram salvas anteriormente dessa visualização. Se settings for null, isso indicará que o usuário está criando as configurações iniciais em vez de carregar uma versão salva. Se settings for um objeto, você deverá usá-lo para preencher sua visualização, pois o usuário optou por editar as configurações persistidas anteriormente.
extensionSettings Configurações salvas da visualização de configuração de extensão. Isso pode ser útil para acessar configurações de extensão em visualizações que não sejam a de configuração de extensão. Se a visualização atual for a de configuração de extensão, use settings.
propertySettings Um objeto que contém configurações da propriedade. Consulte o guia de objetos de turbina para obter detalhes sobre o que está contido nesse objeto.
tokens Um objeto que contém tokens de API. Para acessar as APIs da Adobe na visualização, geralmente é necessário usar um token IMS em tokens.imsAccess. Esse token será disponibilizado somente para extensões desenvolvidas pelo Adobe. Se você for um funcionário do Adobe representando uma extensão criada pelo Adobe, envie um email para a equipe de engenharia de coleta de dados e forneça o nome da extensão para que possamos adicioná-la à lista de permissões.
company Um objeto que contém uma única propriedade, orgId, que representa ela mesma sua Adobe Experience Cloud ID (uma sequência alfanumérica de 24 caracteres).
schema Um objeto no formato de esquema JSON. Este objeto será proveniente do manifesto da extensão e pode ser útil para validar o formulário.

A visualização deve usar essas informações para renderizar e gerenciar o formulário. É provável que você só precise lidar com info.settings, mas as outras informações são fornecidas, caso sejam necessárias.

validate

O método validate será chamado depois que o usuário clicar no botão "Salvar". Ele deve retornar uma das seguintes opções:

  • Um booliano que indica se a entrada do usuário é válida.
  • Uma promessa a ser resolvida posteriormente com um booliano que indica se a entrada do usuário é válida.

Como desenvolvedor da extensão, você deve determinar o que constitui uma entrada válida, já que seu módulo da biblioteca atuará em relação a essa entrada.

Se a entrada do usuário for inválida, mostre alguma indicação disso na visualização para que os usuários saibam o que precisa ser corrigido.

getSettings

O método getSettings será chamado depois que o usuário clicar no botão "Salvar" e a exibição for validada. A função deve retornar uma das seguintes opções:

  • Um objeto que contém configurações com base na entrada do usuário.
  • Uma promessa a ser resolvida posteriormente com um objeto que contém configurações com base na entrada do usuário.

Posteriormente, esse objeto de configuração será emitido na biblioteca de tempo de execução de tags. O conteúdo desse objeto fica a seu critério. O objeto deve ser serializável e desserializável de e para JSON. Valores como funções ou instâncias RegExp não atendem a esses critérios e, portanto, não são permitidos.

Aproveitamento de visualizações compartilhadas

O objeto window.extensionBridge tem vários métodos que permitem aproveitar as visualizações existentes disponíveis por meio de tags, de modo que você não precisa reproduzi-las em sua visualização. As opções disponíveis são as seguintes:

openCodeEditor

window.extensionBridge.openCodeEditor().then(function(code) { 
  console.log(code);
});

Chamar esse método mostrará um modal que permite ao usuário editar um trecho de código. Quando o usuário terminar de editar o código, a promessa será resolvida com o código atualizado. Se o usuário fechar o editor de código sem optar por salvar as alterações, a promessa nunca será resolvida. O objeto options deve ser estruturado da seguinte maneira:

Propriedade Descrição
code Código que deve ser mostrado no editor. Normalmente, isso é fornecido quando o usuário está editando o código existente. Caso isso não seja fornecido, o editor de código ficará vazio quando aberto.
language A linguagem do código que será editado. As opções válidas são javascript, html, css, json e plaintext. Caso isso não seja fornecido, javascript será presumido.

openRegexTester

window.extensionBridge.openRegexTester().then(function(pattern) { 
  console.log(pattern);
});

Chamar esse método mostrará um modal que permite ao usuário testar e modificar um padrão de expressão regular. Quando o usuário terminar de editar a expressão normal, a promessa será resolvida com o padrão de expressão regular atualizado. Se o usuário fechar o testador regex sem optar por salvar as alterações, a promessa nunca será resolvida. O objeto options deve conter as seguintes propriedades:

Propriedade Descrição
pattern O padrão de expressão regular que deve ser usado como o valor inicial do campo de padrão no testador. Normalmente, isso é fornecido quando o usuário edita uma expressão regular existente. Se isso não for fornecido, o campo padrão estará inicialmente vazio.
flags Os sinalizadores de expressão regular que devem ser usados pelo testador. Por exemplo, gi indicaria o sinalizador de correspondência global e o sinalizador para ignorar maiúsculas e minúsculas. Esses sinalizadores não podem ser modificados pelo usuário no testador, mas são usados para demonstrar os sinalizadores específicos que a extensão usará ao executar a expressão regular. Se isso não for fornecido, nenhum sinalizador será usado no testador. Consulte a Documentação de RegExp do MDN para obter mais informações sobre sinalizadores de expressão regular.

Um cenário comum é uma extensão que permite aos usuários ativar e desativar a detecção de maiúsculas e minúsculas de uma expressão regular. Para oferecer suporte a isso, a extensão normalmente fornece uma caixa de seleção em sua visualização de extensão que, quando marcada, ativa a não diferenciação entre maiúsculas e minúsculas (representada pelo sinalizador i ). O objeto de configurações salvo pela visualização precisaria representar se a caixa de seleção estava marcada para que o módulo da biblioteca que executa a expressão regular pudesse saber se o sinalizador i deve ser usado. Além disso, quando a exibição de extensão deseja abrir o testador de expressão regular, ele precisaria passar o sinalizador i se a caixa de seleção de não diferenciação entre maiúsculas e minúsculas estiver marcada. Isso permite que o usuário teste adequadamente a expressão regular com a não diferenciação entre maiúsculas e minúsculas ativada.

openDataElementSelector

window.extensionBridge.openDataElementSelector().then(function(dataElement) { 
  console.log(dataElement);
});

Chamar esse método mostrará um modal que permite ao usuário selecionar um elemento de dados. Quando o usuário terminar de selecionar um elemento de dados, a promessa será resolvida com o nome do elemento de dados selecionado (por padrão, o nome estará entre sinais de porcentagem). Se o usuário fechar o seletor de elementos sem optar por salvar as alterações, a promessa nunca será resolvida.

O objeto options deve conter uma única propriedade booleana, tokenize. Essa propriedade indica se o nome do elemento de dados selecionado deve ser colocado entre sinais de porcentagem antes de resolver a promessa. Consulte a seção sobre elementos de dados de suporte para saber por que isso é útil. O padrão dessa opção é true.

Elementos de dados de suporte

Suas exibições provavelmente têm campos de formulário nos quais os usuários gostaria de aproveitar os elementos de dados. Por exemplo, se sua exibição tem um campo de texto onde o usuário deve inserir um nome de produto, pode não fazer sentido que o usuário digite um valor codificado no campo. Em vez disso, eles podem desejar que o valor do campo seja dinâmico (determinado no tempo de execução) e podem fazer isso usando um elemento de dados.

Como exemplo, suponha que estejamos construindo uma extensão que envia um sinal para rastrear uma conversão. Vamos supor também que um dos dados que nosso beacon envia é um nome de produto. Nossa exibição de extensão que permite que o usuário configure o beacon provavelmente teria um campo de texto para o nome do produto. Normalmente, não faria muito sentido para o usuário do Platform digitar um nome de produto estático, como "Calzone Oven XL", porque o nome do produto provavelmente depende da página da qual o beacon será enviado. Este é um caso ideal para um elemento de dados.

Se um usuário quiser usar o elemento de dados chamado productname como o valor do nome do produto, ele poderá digitar o nome do elemento de dados com sinais de porcentagem em ambos os lados (%productname%). Nós nos referimos ao nome do elemento de dados com sinal de porcentagem como um "token de elemento de dados". Os usuários da plataforma geralmente estão familiarizados com essa construção. Por sua vez, a extensão salvaria o token do elemento de dados dentro do objeto settings exportado. Seu objeto de configurações pode ter a seguinte aparência:

{
  productName: '%productname%'
}

No tempo de execução, antes de passar o objeto de configurações para o módulo da biblioteca, o objeto de configurações é digitalizado e todos os tokens de elemento de dados são substituídos pelos respectivos valores. Se no tempo de execução, o valor do elemento de dados productname fosse Ceiling Medallion Pro 2000, o objeto de configurações que seria passado para seu módulo de biblioteca seria o seguinte:

{
  productName: 'Ceiling Medallion Pro 2000'
}

Para indicar onde pode ser útil para os usuários usar elementos de dados e facilitar a inserção de um elemento de dados, é altamente recomendável adicionar um botão de ícone ao lado desses campos, como mostrado aqui:

campo de elemento de dados

Quando um usuário clicar no botão ao lado do campo de texto, chamar window.extensionBridge.openDataElementSelector como descrito acima. Isso exibirá uma lista dos elementos de dados do usuário que ele pode escolher, em vez de forçá-lo a lembrar o nome e digitar os sinais de porcentagem. Depois que o usuário selecionar um elemento de dados, você receberá o nome do elemento de dados selecionado encapsulado em sinais de porcentagem (a menos que a opção tokenize esteja definida como false). Recomendamos que você preencha o campo de texto com o resultado.

Substituição de tokens de elementos de dados

Conforme descrito anteriormente, se um objeto de configurações persistidas consistisse no seguinte:

{
  productName: '%productname%'
}

E, se no tempo de execução, o valor do elemento de dados productname fosse Ceiling Medallion Pro 2000, então o objeto de configurações passado para seu módulo de biblioteca seria o seguinte:

{
  productName: 'Ceiling Medallion Pro 2000'
}

Sempre que for encontrado um valor em um objeto de configurações que consista em um sinal de porcentagem, em seguida, uma sequência de caracteres, um sinal de porcentagem, e nada mais, ele será substituído pelo valor do elemento de dados sem alterar o tipo do valor do elemento de dados.

Por exemplo, se o valor de productname no tempo de execução fosse o número 538 (não uma sequência de caracteres), o objeto de configurações passado para o módulo da biblioteca seria o seguinte:

{
  productName: 538
}

Observe que o 538 resultante é um número aqui e não uma sequência de caracteres. Da mesma maneira, se o valor do elemento de dados em tempo de execução fosse uma função (um caso de uso raro, mas possível), o objeto de configurações resultante seria o seguinte:

{
  productName: function() { … }
}

Por outro lado, vamos supor que os objetos de configurações persistentes sejam os seguintes:

{
  productName: '%productname% - %modelnumber%'
}

Nesse caso, como o valor de productName é maior que um token de elemento de dados único, o resultado sempre será uma sequência de caracteres. Cada token de elemento de dados será substituído pelo respectivo valor depois de ser convertido em uma sequência de caracteres. Se no tempo de execução, o valor de productname fosse Ceiling Medallion Pro (uma string) e modelnumber fosse 2000 (um número), o objeto de configurações resultante passado para o módulo da biblioteca seria:

{
  productName: 'Ceiling Medallion Pro - 2000'
}

Evitar a navegação

A comunicação entre a exibição de extensão e a interface do usuário contendo Coleta de dados está subordinada à ausência de navegação na exibição de extensão. Assim, evite adicionar algo à sua visualização de extensão que permita ao usuário navegar para fora da página HTML da visualização de extensão. Por exemplo, se você fornecer um link na visualização de extensão, verifique se ele abre uma nova janela do navegador (normalmente adicionando target="_blank" à tag de âncora). Se você optar por usar um elemento form na visualização de extensão, garanta que o formulário nunca seja enviado. O envio do formulário poderá ocorrer acidentalmente se você tiver um elemento button no formulário e não adicionar type="button" a ele. O envio de um formulário na visualização de extensão faria com que o documento HTML fosse atualizado, resultando em uma experiência do usuário com problemas.

Nesta página