Manifesto de extensão

No diretório base da sua extensão, você deve criar um arquivo chamado extension.json. Ele contém detalhes críticos da sua extensão que permitem que o Adobe Experience Platform o consuma corretamente. Alguns conteúdos são formados à maneira de npms package.json.

Um exemplo extension.json pode ser encontrado na extensão Hello World do repositório GitHub.

Um manifesto de extensão deve consistir no seguinte:

Apêndice

Regras de nomenclatura naming-rules

O valor de qualquer campo name em extension.json deve estar em conformidade com as seguintes regras:

Eles são compatíveis com as regras de nome de pacote npm.

Propriedades de objetos de configuração config-object

O objeto de configuração deve ser estruturado da seguinte maneira:

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "delay": {
      "type": "number",
      "minimum": 1
    }
  },
  "required": [
    "delay"
  ],
  "additionalProperties": false
}

Definições de tipo type-definitions

Uma definição de tipo é um objeto usado para descrever um evento, uma condição, uma ação ou um tipo de elemento de dados. O objeto consiste no seguinte:

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "delay": {
      "type": "number",
      "minimum": 1
    }
  },
  "required": [
    "delay"
  ],
  "additionalProperties": false
}

Transformações transforms

Para certos casos de uso específicos, as extensões precisam que os objetos de configuração salvos de uma visualização sejam transformados pela Experience Platform antes de serem emitidos para a biblioteca de tempo de execução da tag. Você pode solicitar que uma ou mais dessas transformações ocorram definindo a propriedade transforms ao definir uma definição de tipo dentro de extension.json. A propriedade transforms é uma matriz de objetos na qual cada objeto representa uma transformação que deve ocorrer.

Todas as transformações exigem um type e um propertyPath. O type deve ser um dos function, remove e file e descreve qual transformação do Experience Platform deve ser aplicada ao objeto de configurações. O propertyPath é uma string delimitada por ponto que indica às tags onde localizar a propriedade que precisa ser modificada no objeto de configurações. Este é um exemplo de objeto de configurações e alguns propertyPaths:

{
  foo: {
    bar: "A string",
    baz: [
      "A",
      "B",
      "C"
    ]
  }
}

Os caminhos de propriedade podem usar qualquer combinação de matriz e notação de objeto para aplicar transformações em qualquer nível do objeto de configurações.

As seções abaixo descrevem as transformações disponíveis e como usá-las.

Transformação de função

A transformação de função permite que o código escrito pelos usuários do Experience Platform seja executado por um módulo de biblioteca dentro da biblioteca de tempo de execução de tag emitida.

Suponhamos que gostaríamos de fornecer um tipo de ação de "script personalizado". A visualização de ação "script personalizado" pode fornecer uma área de texto na qual o usuário pode digitar algum código. Suponhamos que um usuário tenha inserido o seguinte código na área de texto:

console.log('Welcome, ' + username +'. This is ZomboCom.');

Quando o usuário salva a regra, o objeto de configurações salvo pela visualização pode ter a seguinte aparência:

{
  foo: {
    bar: "console.log('Welcome, ' + username +'. This is ZomboCom.');"
  }
}

Quando uma regra que usa nossa ação é acionada na biblioteca de tempo de execução da tag, queremos executar o código do usuário e passar um nome de usuário para ele.

No ponto em que o objeto de configurações é salvo da visualização do tipo de ação, o código do usuário é simplesmente uma string. Isso é bom porque pode ser serializado corretamente de e para JSON. No entanto, também é ruim porque, normalmente, seria emitido na biblioteca de tempo de execução de tags como uma string, em vez de uma função executável. Embora você possa tentar executar o código no módulo de biblioteca do tipo de ação usando eval ou um construtor de função, isso é altamente desencorajado devido a políticas de segurança de conteúdo que potencialmente bloqueiam a execução.

Como solução alternativa para essa situação, o uso da transformação de função instrui o Experience Platform a envolver o código do usuário em uma função executável quando ele for emitido na biblioteca de tempo de execução de tags. Para resolver nosso problema de exemplo, definimos a transformação na definição de tipo em extension.json da seguinte forma:

{
  "transforms": [
    {
      "type": "function",
      "propertyPath": "foo.bar",
      "parameters": ["username"]
    }
  ]
}

Quando o objeto de configurações for emitido na biblioteca de tempo de execução de tags, ele será transformado no seguinte:

{
  foo: {
    bar: function(username) {
      console.log('Welcome, ' + username +'. This is ZomboCom.');
    }
  }
}

Seu módulo de biblioteca pode então chamar a função que contém o código do usuário e passar o argumento username.

Transformação de arquivo

A transformação de arquivo permite que o código escrito pelos usuários do Experience Platform seja emitido em um arquivo separado da biblioteca de tempo de execução de tags. O arquivo será hospedado com a biblioteca de tempo de execução de tags e poderá ser carregado conforme necessário por sua extensão no tempo de execução.

Suponhamos que gostaríamos de fornecer um tipo de ação de "script personalizado". A visualização do tipo de ação pode fornecer uma área de texto na qual o usuário pode digitar algum código. Suponhamos que um usuário tenha inserido o seguinte código na área de texto:

console.log('This is ZomboCom.');

Quando o usuário salva a regra, o objeto de configurações salvo pela visualização pode ter a seguinte aparência:

{
  foo: {
    bar: "console.log('This is ZomboCom.');"
  }
}

Queremos que o código do usuário seja colocado em um arquivo separado em vez de ser incluído na biblioteca de tempo de execução de tags. Quando uma regra que usa nossa ação é acionada na biblioteca de tempo de execução de tags, queremos carregar o código do usuário anexando um elemento de script ao corpo do documento. Para resolver nosso problema de exemplo, definiríamos a transformação na definição do tipo de ação em extension.json da seguinte maneira:

{
  "transforms": [
    {
      "type": "file",
      "propertyPath": "foo.bar"
    }
  ]
}

Quando o objeto de configurações for emitido na biblioteca de tempo de execução de tags, ele será transformado no seguinte:

{
  foo: {
    bar: "//launch.cdn.com/path/abc.js"
  }
}

Nesse caso, o valor de foo.bar foi transformado em um URL. O URL exato será determinado no momento em que a biblioteca for criada. O arquivo sempre receberá uma extensão .js e será entregue usando um tipo MIME orientado por JavaScript. Podemos adicionar suporte para outros tipos MIME no futuro.

Remover transformação

Por padrão, todas as propriedades do objeto de configurações são emitidas na biblioteca de tempo de execução de tags. Se determinadas propriedades forem usadas apenas para a visualização de extensão, especialmente se contiverem informações confidenciais (por exemplo, token secreto), você deverá remover a transformação para impedir que as informações sejam emitidas para a biblioteca de tempo de execução de tags.

Vamos supor que gostaríamos de oferecer um novo tipo de ação. A visualização do tipo de ação pode fornecer uma entrada na qual o usuário pode inserir uma chave secreta que permitirá a conexão com uma API específica. Vamos supor que um usuário tenha inserido o seguinte texto na entrada:

ABCDEFG

Quando o usuário salva a regra, o objeto de configurações salvo pela visualização pode ter a seguinte aparência:

{
  foo: {
    bar: "ABCDEFG"
  }
}

Não queremos incluir a propriedade bar na biblioteca de tempo de execução de tags. Para resolver nosso problema de exemplo, definiríamos a transformação na definição do tipo de ação em extension.json da seguinte maneira:

{
  "transforms": [
    {
      "type": "remove",
      "propertyPath": "foo.bar"
    }
  ]
}

Quando o objeto de configurações for emitido na biblioteca de tempo de execução de tags, ele será transformado no seguinte:

{
  foo: {
  }
}

Nesse caso, o valor de foo.bar foi removido do objeto de configurações.