Visualizações em extensões da Web

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>

Incluir o script de iframe do Platform Launch

Inclua o script de iframe do Platform Launch no HTML da visualizaçã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 visualização se comunique com o aplicativo do Platform Launch.

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

Depois que o script de iframe for carregado, será necessário fornecer alguns métodos para o Platform Launch que serão usados 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 pelo Platform Launch assim que a visualizaçã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 as configurações.
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 pela Adobe. Se você for um funcionário da Adobe que representa uma extensão criada pela Adobe, envie um email para a equipe de engenharia do Platform Launch 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" no Platform Launch. 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 pressionar o botão "Salvar" no Platform Launch e a visualizaçã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.

Esse objeto de configurações será emitido posteriormente na biblioteca de tempo de execução do Platform Launch. 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 no Platform Launch para que não seja necessário reproduzi-las na 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 opção de não detectar 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 visualização de extensão desejar abrir o testador de expressão regular, será necessário passar o sinalizador i se a caixa de seleção da opção de não detectar maiúsculas e minúsculas estiver marcada. Isso permite que o usuário teste corretamente a expressão regular com a opção de não detectar 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 booliana, 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

Provavelmente, suas visualizações têm campos de formulário nos quais os usuários gostariam de aproveitar os elementos de dados. Por exemplo, caso sua visualização tenha um campo de texto no qual o usuário deve digitar um nome de produto, poderá não fazer sentido que o usuário digite um valor embutido em código 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 visualização de extensão que permite ao usuário do Platform Launch configurar o beacon provavelmente terá um campo de texto para o nome do produto. Normalmente, não faria muito sentido para o usuário do Platform Launch 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%). O nome do elemento de dados entre sinais de porcentagem é chamado de "token de elemento de dados", e os usuários do Platform Launch 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 Platform Launch verifica detalhadamente o objeto de configurações e substitui quaisquer tokens de elementos de dados por seus 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 o 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 sequência de caracteres) e modelnumber fosse 2000 (um número), o objeto de configurações resultante passado para o módulo de biblioteca seria:

{
  productName: 'Ceiling Medallion Pro - 2000'
}

Evitar a navegação

A comunicação entre a visualização de extensão e a interface do usuário que contém o Platform Launch depende da ausência de navegação na visualizaçã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

Adobe Summit Banner

A virtual event April 27-28.

Expand your skills and get inspired.

Register for free
Adobe Summit Banner

A virtual event April 27-28.

Expand your skills and get inspired.

Register for free