Nesta página: Saiba como transmitir coleções simples e de objetos para parâmetros de ação personalizados para que elas sejam populadas dinamicamente em tempo de execução.
Você pode passar uma coleção nos parâmetros de ação personalizados que é preenchida dinamicamente no tempo de execução.
Há suporte para dois tipos de coleções:
-
Coleções simples
Use coleções simples para listas de valores básicos, como sequências, números ou boolianos. Elas são úteis quando você só precisa passar uma lista de itens sem propriedades adicionais.
Por exemplo, uma lista de tipos de dispositivos:
code language-json { "deviceTypes": [ "android", "ios" ] } -
Coleções de objetos
Use coleções de objetos quando cada item incluir vários campos ou propriedades. Normalmente, eles são usados para transmitir dados estruturados, como detalhes do produto, registros de evento ou atributos de item.
Por exemplo:
code language-json { "products":[ { "id":"productA", "name":"A", "price":20.1 }, { "id":"productB", "name":"B", "price":10.0 }, { "id":"productC", "name":"C", "price":5.99 } ] }
Procedimento geral general-procedure
Nesta seção, usamos o exemplo de carga JSON a seguir. Esta é uma matriz de objetos com um campo que é uma coleção simples.
{
"ctxt": {
"products": [
{
"id": "productA",
"name": "A",
"price": 20.1,
"color":"blue",
"locations": [
"Paris",
"London"
]
},
{
"id": "productB",
"name": "B",
"price": 10.99
}
]
}
}
Você pode ver que products é uma matriz de dois objetos. Você precisa ter pelo menos um objeto.
-
Crie sua ação personalizada. Saiba mais nesta página.
-
Na seção Parâmetros de ação, cole o exemplo de JSON. A estrutura exibida é estática: ao colar a carga, todos os campos são definidos como constantes.
-
Se necessário, ajuste os tipos de campo. Os seguintes tipos de campo são compatíveis com coleções: listString, listInteger, listDecimal, listBoolean, listDateTime, listDateTimeOnly, listDateOnly, listObject
note NOTE O tipo de campo é inferido automaticamente de acordo com o exemplo de carga útil. -
Se você quiser passar objetos dinamicamente, precisará defini-los como variáveis. Neste exemplo, definimos
productscomo variável. Todos os campos de objeto incluídos no objeto são definidos como variáveis automaticamente.note NOTE O primeiro objeto do exemplo de carga útil é usado para definir os campos. -
Para cada campo, defina o rótulo que será exibido na tela de jornada.
-
Crie sua jornada e adicione a ação personalizada que você criou. Saiba mais nesta página.
-
Na seção Parâmetros de ação, defina o parâmetro de matriz (
productsem nosso exemplo) usando o editor de expressão avançado.
-
Para cada um dos campos de objeto a seguir, digite o nome do campo correspondente do esquema XDM de origem. Se os nomes forem idênticos, isso não será necessário. Em nosso exemplo, precisamos apenas definir
product ide “cor”.
Para o campo de matriz, também é possível usar o editor de expressão avançado para executar a manipulação de dados. No exemplo a seguir, usamos as funções filtro e interseção:
Limitações limitations
Embora as coleções em ações personalizadas forneçam flexibilidade para transmitir dados dinâmicos, há certas restrições estruturais a serem observadas:
-
Suporte para Matrizes Aninhadas em Ações Personalizadas
Adobe Journey Optimizer dá suporte a matrizes aninhadas de objetos em cargas de resposta de ação personalizada, mas esse suporte é limitado em cargas de solicitação.
Nas cargas de solicitação, matrizes aninhadas só são suportadas quando contêm um número fixo de itens, conforme definido na configuração de ação personalizada. Por exemplo, se uma matriz aninhada sempre incluir exatamente três itens, ela poderá ser configurada como uma constante. Quando o número de itens precisa ser dinâmico, somente as matrizes não aninhadas (matrizes no nível inferior) podem ser definidas como variáveis.
Exemplo:
-
O exemplo a seguir ilustra um caso de uso não suportado.
Neste exemplo, a matriz products inclui uma matriz aninhada (
locations) com um número dinâmico de itens, para o qual não há suporte em cargas de solicitação.code language-json { "products": [ { "id": "productA", "name": "A", "price": 20, "locations": [ { "name": "Paris" }, { "name": "London" } ] } ] } -
Exemplo compatível, com itens fixos definidos como constantes.
Nesse caso, os locais aninhados são substituídos por campos fixos (
location1,location2), permitindo que a carga permaneça válida dentro da configuração com suporte.code language-json { "products": [ { "id": "productA", "name": "A", "price": 20, "location1": { "name": "Paris" }, "location2": { "name": "London" } } ] }
-
-
Testando coleções: para testar coleções usando o modo de teste, você deve usar o modo de exibição de código. Observe que o modo de exibição de código não é compatível com eventos comerciais, portanto, nesse caso, você só pode enviar uma coleção contendo um único elemento.
Casos específicos examples
Para tipos heterogêneos e arrays de arrays, o array é definido com o tipo listAny. Você só pode mapear itens individuais, mas não pode alterar a matriz para a variável.
Exemplo de tipo heterogêneo:
{
"data_mixed-types": [
"test",
"test2",
null,
0
]
}
Exemplo de matriz de matrizes:
{
"data_multiple-arrays": [
[
"test",
"test1",
"test2"
]
]
}
Recursos adicionais
Navegue pelas seções abaixo para saber mais sobre como configurar, usar e solucionar problemas de ações personalizadas:
- Introdução a ações personalizadas - Saiba o que é uma ação personalizada e como ela ajuda você a se conectar a sistemas de terceiros
- Configurar ações personalizadas - Saiba como criar e configurar uma ação personalizada
- Usar ações personalizadas - Saiba como usar ações personalizadas em suas jornadas
- Solução de problemas de ação personalizada - Saiba como solucionar problemas de uma ação personalizada
- Iterar em dados contextuais - Saiba como trabalhar com matrizes em expressões de Jornada e iterar em respostas de ação personalizadas, dados de eventos e pesquisas de conjunto de dados na personalização de mensagens
This section contains structured knowledge intended to support interpretation, retrieval, and question answering related to this topic.
For complete understanding, this information should be combined with the documentation on this page. Neither source is intended to stand alone; the page describes the feature, while this section provides additional context that helps disambiguate terminology, intent, applicability, and constraints.
- TL;DR: This page explains how to pass simple and object collections dynamically into custom action parameters in Journey Optimizer, including supported field types, the configuration procedure, and known limitations around nested arrays.
Intents:
- Configure a custom action to accept a collection (simple or object) as a dynamic parameter
- Define array parameters as variables in the advanced expression editor when building a journey
- Apply filter and intersect functions to manipulate array data in the expression editor
- Understand and work within the nested array limitations for custom action request payloads
- Test collection parameters using code view mode in journey test mode
Glossary:
- Simple collection: A list of basic scalar values (strings, numbers, booleans) passed as a custom action parameter (product-specific)
- Object collection: A list of structured objects, each with multiple fields, passed as a custom action parameter (product-specific)
- listObject: The field type used in custom action configuration to represent an array of objects (product-specific)
- listAny: The field type used for heterogeneous arrays or arrays of arrays where items have mixed types (product-specific)
- Variable (vs. Constant): In action parameter configuration, a field set to “variable” is populated dynamically at runtime from the journey context, while a “constant” is a fixed value set at configuration time (product-specific)
Guardrails:
- Nested arrays in request payloads are only supported when they contain a fixed number of items (defined as constants); dynamic nested arrays are not supported
- Code view mode is required to test collections in test mode; code view is not supported for business events, so only single-element collections can be sent in that case
- At least one object must be present in the payload example used to define collection fields
- The first object of the payload example defines the fields for the entire collection
Terminology:
- Canonical name: Collection — Acronym: none — variants: array, list, dynamic collection
- Synonyms: “simple collection” = “list of scalar values” ; “object collection” = “array of objects”
- Do not confuse: “listAny” ≠ “listObject” (listAny handles heterogeneous or nested arrays; listObject handles uniform arrays of structured objects)
FAQ:
- Q: What is the difference between a simple collection and an object collection? — A simple collection contains basic scalar values (strings, numbers, booleans), while an object collection contains structured objects each with multiple named fields.
- Q: How do I make a collection parameter dynamic at runtime? — In the custom action’s Action parameters section, set the array field to “variable”; all object fields within it are then automatically set to variables.
- Q: Are nested arrays supported in custom action request payloads? — Only partially. Nested arrays with a fixed, known number of items can be defined as constants. Nested arrays with a dynamic number of items are not supported in request payloads.
- Q: How do I test a collection in journey test mode? — Use code view mode in the test interface. Note that business events do not support code view, so only single-element collections can be tested in that context.
- Q: What field types are supported for collections? — listString, listInteger, listDecimal, listBoolean, listDateTime, listDateTimeOnly, listDateOnly, and listObject are all supported.