Fazer upload e implementar testes completos

O teste de extensões envolve o uso da API do Adobe Experience Platform Launch e/ou de ferramentas de linha de comando para fazer upload de pacotes de extensão e, em seguida, o uso da interface do usuário do Platform Launch para instalar seu pacote de extensão em uma propriedade e aproveitar os recursos dele em uma biblioteca e build do Platform Launch.

As etapas básicas para alcançar isso são:

  1. Validar sua extensão
  2. Criar uma integração do Adobe I/O
  3. Fazer upload do pacote de extensão
  4. Criar uma propriedade de desenvolvimento
  5. Instalar a extensão
  6. Criar recursos para testar a extensão
  7. Publicar as alterações
  8. Instalar o Platform Launch em um site de teste
  9. Teste

Ao testar (Etapa 9 acima), ao descobrir problemas que precisam ser corrigidos, você vai:

  1. Atualizar o código da extensão
  2. Criar um novo pacote de extensão
  3. Fazer upload do novo pacote de extensão: sua extensão instalada fará referência a esse novo pacote automaticamente
  4. Atualizar recursos conforme necessário
  5. Publicar novamente
  6. Teste

Conforme percorrermos as etapas abaixo, presumiremos que você esteja usando o Mac OS com o nó e o npm instalado e disponível.

Validar sua extensão

Quando sua equipe estiver satisfeita com o desempenho da extensão e com os resultados vistos na ferramenta Sandbox, você deverá estar pronto para fazer upload do pacote de extensão para o Platform Launch.

Antes de fazer upload, valide se os campos ou configurações necessários estão presentes. Por exemplo, verificar o manifesto de extensão, a configuração de extensão, as visualizações e os módulos de biblioteca (no mínimo) seria uma boa prática.

Um exemplo específico é o arquivo de logotipo: Adicione uma linha "iconPath": "example.svg", ao arquivo extension.json e inclua esse arquivo de imagem de logotipo no projeto. Esse é o caminho relativo para o ícone que será exibido para a extensão no Platform Launch. Não deve começar com uma barra. Ele deve fazer referência a um arquivo SVG com uma extensão .svg. O SVG deve aparecer normalmente quando renderizado como quadrado e pode ser dimensionado pela interface do usuário. Consulte Como dimensionar SVG para obter mais detalhes.

OBSERVAÇÃO

Para extensões públicas, inclua um item em seu extension.json com um link para sua lista do Exchange. Seu manifesto de extensão deve incluir uma entrada como esta: "exchangeUrl":"https://www.adobeexchange.com/experiencecloud.details.12345.html" apontando para o URL da sua lista do Exchange.

Criar uma integração do Adobe I/O

Para usar a API ou as ferramentas de linha de comando, você precisa de uma conta técnica com o Adobe I/O. Criaremos a conta técnica no console do I/O e usaremos a ferramenta Uploader para fazer upload do pacote de extensão.

Para obter informações sobre como criar uma conta técnica para uso com o Platform Launch, consulte a guia Tokens de acesso.

IMPORTANTE

Para criar uma integração no Adobe I/O, você deve ser um Administrador de organização da Experience Cloud ou um Desenvolvedor de organização da Experience Cloud.

Se você não conseguir criar uma integração, provavelmente não terá as permissões corretas e precisará falar com um de seus Administradores de organização para concluir as etapas para você ou atribuí-lo como Desenvolvedor para que você mesmo possa fazê-lo.

Fazer upload do pacote de extensão

Com suas credenciais classificadas, você está pronto para testar seu pacote de extensão de ponta a ponta.

Quando você faz upload do pacote de extensão pela primeira vez, ele entra em um estado de development. Isso significa que ele só é visível com sua própria empresa do PlatformLaunch e somente com uma propriedade do PlatformLaunch que foi marcada para desenvolvimento de extensão (veremos isso mais adiante).

Por enquanto, volte para a linha de comando no diretório que contém seu pacote .zip.

npx @adobe/reactor-uploader

npx permite baixar e executar um pacote npm sem instalá-lo na sua máquina. Essa é a maneira mais simples de executar o Uploader.

O Uploader solicitará que você insira várias informações. A ID da conta técnica, a chave de API e outras informações podem ser recuperadas do console do Adobe I/O. Navegue até a página Integrações no console do I/O. Selecione a organização correta na lista suspensa, localize a integração correta e selecione View.

  • Qual é o caminho para sua chave privada? /path/to/private.key. Este é o local onde você salvou sua chave privada na etapa 2 acima.
  • Qual é a sua ID organizacional? Copie/cole isso da página de visão geral do Console do I/O que você deixou aberta anteriormente.
  • Qual é a sua ID de conta técnica? Copie/cole do Console do I/O.
  • Qual é a sua chave de API? Copie/cole do Console do I/O.
  • O que é segredo do cliente? Copie/cole do console do I/O.
  • Qual é o caminho para o extension_package do qual você deseja fazer upload? /path/to/extension_package.zip. Se você chamar o carregador do diretório que contém o pacote .zip, poderá selecioná-lo na lista em vez de digitar o caminho.

Seu pacote de extensão será carregado e o carregador fornecerá a ID do extension_package.

OBSERVAÇÃO

Observação: ao fazer upload ou aplicar patches, os pacotes de extensão são colocados em um estado pendente enquanto o sistema extrai o pacote de forma assíncrona e faz a implantação. Enquanto esse processo estiver ocorrendo, você poderá pesquisar a ID extension_package pelo seu status usando a API e, no PlatformLaunch, você verá um cartão de extensão no catálogo marcado como Pendente.

OBSERVAÇÃO

Observação: se você planeja executar o carregador com frequência, pode ser difícil incluir todas essas informações sempre. Você também pode passá-los como argumento da linha de comando. Consulte a seção Argumentos de linha de comando dos documentos do NPM para obter mais informações.

Criar uma propriedade de desenvolvimento

Ao fazer logon no PlatformLaunch, você verá a tela Propriedades primeiro. Uma propriedade é um container para as tags que você deseja implantar e pode ser usada em um ou vários sites.

Você verá minha propriedade 'test' aqui, mas não verá nenhuma propriedade em sua tela na primeira vez que fizer logon. Selecione Nova propriedade para criar uma. Insira um nome e um URL. Você provavelmente usará o URL do site ou da página de teste em que testará sua extensão. Esse campo de domínio pode ser usado por algumas extensões ou por uma condição que usa a extensão Principal (que examinaremos posteriormente). Observe que localhost não funcionará. Portanto, se você estiver em um URL localhost, use qualquer valor para esse teste, como exemplo.com.

Como você deseja usar essa propriedade para o teste de desenvolvimento de extensão, também é necessário expandir as Opções avançadas e marcar a caixa "Configurar para desenvolvimento de extensão".

Selecione Salvar na parte inferior para salvar a nova propriedade.

Isso leva você de volta à tela Propriedades. Selecione o nome da propriedade que você acabou de criar. Esta é a tela Visão geral em uma propriedade. Não acontece muito trabalho aqui, mas há links para cada área do sistema, com os links de navegação globais na parte superior.

Instalar a extensão

Para instalar a extensão nessa propriedade, selecione o link Extensões nos links de navegação principais na parte superior.

Você verá a extensão Principal nesta tela Instalada. A extensão Principal contém toda a funcionalidade de gerenciamento de tags no Platform Launch. Para adicionar a extensão, selecione o Catálogo:

O catálogo exibe ícones de cartão para cada extensão disponível. Se sua extensão não for exibida no catálogo, primeiro verifique se você concluiu as etapas acima nas seções Configuração do console de administração da Adobe e Criação do pacote de extensão. Seu pacote de extensão também poderá ser mostrado como Pendente se o Platform Launch não tiver concluído o processamento inicial.

Se você estiver convencido de que fez tudo corretamente e ainda não vir um pacote de extensão Pendente ou com Falha no catálogo, acesse a API diretamente para verificar o status do pacote de extensão. Para obter mais informações sobre isso, leia Obter um ExtensionPackage nos documentos da API.

Supondo que o processamento do pacote de extensão tenha terminado, o cartão terá um botão Instalar para que você o selecione:

Isso exibirá a tela de configuração que você criou para a extensão (se você tiver uma). Adicione todas as informações necessárias para configurar a extensão e selecione Salvar na parte inferior. Se a extensão não tiver configuração, ela será instalada assim que você selecionar Instalar.

Veja um exemplo com a extensão do Facebook:

Agora você deve ver a tela de extensões Instaladas com a extensão Principal e a sua extensão.

Criar recursos para testar sua extensão

As extensões fornecem novos recursos aos usuários no Platform Launch. Eles quase sempre são mostradas em Elementos de dados ou no Construtor de regras. A seguir discutiremos essas duas áreas.

Elementos de dados

Elementos de dados existe no Platform Launch para ajudar os usuários a fazer com que os valores persistam. Cada elemento de dados é um mapeamento ou ponteiro para dados de origem. Um único elemento de dados é uma variável cujo valor pode ser mapeado para sequências de consulta, URLs, valores de cookie, variáveis JavaScript e assim por diante.

As extensões podem definir tipos de elementos de dados, se necessário, para que sua extensão funcione, ou simplesmente como uma conveniência para os usuários. Quando uma extensão fornece tipos de elementos de dados, eles são mostrados em uma lista suspensa para usuários na tela Criar novo elemento de dados:

Quando um usuário seleciona sua extensão na lista suspensa Extensão, a lista suspensa Tipo de elemento de dados é preenchida com qualquer tipo de elemento de dados fornecido pela extensão. O usuário pode mapear cada elemento de dados para seu valor de origem. Os elementos de dados podem ser usados ao criar regras no Evento de alteração de elemento de dados ou no Evento de código personalizado para acionar a execução de uma regra. Um elemento de dados também pode ser usado na Condição do elemento de dados ou em outras Condições, Exceções ou Ações em uma regra.

Depois que o elemento de dados é criado (o mapeamento é configurado), os usuários podem fazer referência aos dados de origem simplesmente referenciando o elemento de dados. Se a origem do valor mudar (novos projetos de site etc.) os usuários só precisam atualizar o mapeamento uma vez no Platform Launch e todos os elementos de dados receberão automaticamente o novo valor de origem.

Regras

Selecione o link Regras na navegação superior e, em seguida, Adicionar regra:

Primeiro, nomeie a regra. Qualquer nome pode ser usado. A tela Criar nova regra é configurada como uma instrução if-then:

Se ocorrer um evento, as condições forem aprovadas e não houver exceções, a ação será acionada. Esse mesmo fluxo existe em extensões em que você pode criar ou aproveitar eventos, condições, exceções, elementos de dados ou ações.

Continuando com o exemplo do Facebook, vamos adicionar um evento a qualquer momento em que uma página for carregada em nosso site:

Com o Tipo de evento Window Loaded, sempre que uma página for carregada em nosso site, essa regra será acionada. Selecione Salvar. Para este exemplo, vamos ignorar as Condições e Exceções, pois queremos que essa regra seja acionada para qualquer página do nosso site: nossa regra "global" On Load, por assim dizer.

Em Ações, selecione Adicionar. Nesta tela Configuração de ação, podemos escolher a extensão com a qual queremos trabalhar e a ação que queremos que ocorra quando essa regra for acionada. Escolha Pixel do Facebook em Extensão e Enviar exibição de página em Tipo de ação:

Selecione Manter alterações na parte inferior e Salvar regra na tela seguinte. Ao testar sua extensão, você pode selecionar eventos, condições etc. fornecido pela sua extensão em qualquer número de regras.

Publicar suas alterações

Na navegação principal, selecione Publicação e, em seguida, selecione o link Adicionar nova biblioteca:

Uma biblioteca é um conjunto de instruções sobre como as extensões, os elementos de dados e as regras interagem entre si e com um site. As bibliotecas são compiladas em criações. Uma biblioteca pode conter quantas alterações o usuário quiser criar ou testar simultaneamente.

Na tela Criar nova biblioteca, adicione um Nome e escolha um Ambiente. O Platform Launch fornece um ambiente de desenvolvimento padrão chamado de Development, portanto, selecione-o na lista de Ambiente. Por enquanto, adicionaremos todos os recursos disponíveis. Portanto, selecione Adicionar todos os recursos alterados.

OBSERVAÇÃO

Quando você adiciona um recurso a uma biblioteca, um instantâneo desse recurso nesse momento exato é criado e adicionado à biblioteca. Ao fazer alterações em seus recursos posteriormente (por exemplo, como resultado de correções que devem ser feitas), você também precisará atualizar a biblioteca para incluir as alterações mais recentes em seus recursos. O botão Adicionar todos os recursos alterados também é útil para essa finalidade.

Em seguida, selecione Salvar na parte inferior. Agora que todas as alterações foram incluídas nesta biblioteca dev, vamos criá-la:

Depois que o processo de build for concluído, você deverá ver um indicador de sucesso verde ao lado do nome da biblioteca:

Agora a biblioteca do Platfom Launch foi publicada e está aguardando para ser usada. Agora precisamos instruir nossa página de teste a procurar essa biblioteca para que possamos testar o comportamento do usuário final em um navegador.

Instalar o Platform Launch em um site de teste

As instruções de instalação estão disponíveis na guia Ambientes, então, vamos acessá-la agora.

Nessa página, você verá todos os ambientes disponíveis e terá a capacidade de criar mais. Publicamos nossa biblioteca no ambiente de desenvolvimento. Vamos obter as instruções de instalação desse ambiente selecionando o ícone de caixa na coluna Instalar na linha Desenvolvimento.

Agora estamos vendo as instruções de instalação do ambiente de desenvolvimento. Aqui, basta copiar a tag <script> na caixa. Portanto, selecione o botão copiar.

Para concluir a instalação, coloque essa tag única <script> na seção <head> no documento ou modelo de site. Agora, viste o site de teste para verificar o comportamento da biblioteca publicada do Platform Launch.

Teste

Ao validar a extensão na página ou no site de teste, há alguns comandos de console que serão úteis:

  • _satellite.setDebug(true); colocará o Platform Launch no modo de depuração e exibirá instruções úteis de registro no console.
  • O objeto _satellite._container contém diversas informações úteis sobre a biblioteca implantada, incluindo detalhes sobre build, elementos de dados, regras e extensões incluídos.

Em última análise, seu objetivo é testar a funcionalidade da biblioteca implantada para garantir que o código que você escreveu no pacote de extensão se comporte como esperado quando o Platform Launch o compilar em uma biblioteca.

Quando você descobre alterações que precisam ser feitas no pacote de extensão, o processo de iteração é semelhante ao de desenvolvimento.

  1. Faça alterações no código do projeto
  2. Valide as alterações com a ferramenta Sandbox
  3. Use a ferramenta Packager para criar um novo pacote .zip
  4. Use a ferramenta Uploader para fazer upload do novo pacote .zip. Você pode seguir as mesmas instruções usadas acima para o upload inicial. Porém, você notará que, desta vez, como já existe um pacote de extensão com esse nome no modo de desenvolvimento, ele substituirá o outro em vez de criar um novo. Se quiser economizar tempo evitando inserir credenciais repetidamente, você poderá consultar a documentação do carregador da reactor e passar os argumentos na linha de comando.
  5. Podemos ignorar a etapa de instalação desta vez
  6. Modifique os recursos. Se você alterou a configuração de qualquer um dos componentes da extensão, convém atualizar esses recursos na interface do Platform Launch
  7. Adicione as alterações mais recentes à biblioteca e crie novamente
  8. Teste mais

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