Propriedades de entrada persistentes
Quando um Canvas é disparado por um evento personalizado, uma compra ou uma chamada de API, você pode usar metadados da chamada de API, do evento personalizado ou do evento de compra para personalização em cada etapa do fluxo de trabalho do seu Canvas. Você pode usar essas propriedades para enviar mensagens mais direcionadas.
As propriedades de entrada persistentes são um artefato do editor original do Canvas, então existem referências depreciadas a termos como propriedades de entrada do Canvas que permanecem para referência histórica. Para o editor atual do Canvas, consulte Propriedades de contexto e evento.
Para usar propriedades de entrada persistentes no editor atual do Canvas, você deve criar um novo Canvas ou clonar um existente para o editor atual.
Uso de propriedades de entrada
As propriedades de entrada podem ser usadas em Canvas baseados em ação e disparados por API. Essas propriedades de entrada são definidas quando um Canvas é disparado por um evento personalizado, uma compra ou uma chamada de API. Consulte os artigos a seguir para saber mais:
As propriedades passadas a partir desses objetos podem ser referenciadas usando a Liquid tag canvas_entry_properties. Por exemplo, uma requisição com "canvas_entry_properties": {"product_name": "shoes", "product_price": 79.99} poderia adicionar a palavra “shoes” a uma mensagem usando o Liquid {{canvas_entry_properties.${product_name}}}.
Quando um Canvas inclui uma mensagem com a Liquid tag canvas_entry_properties, os valores associados a essas propriedades serão salvos durante toda a jornada do usuário no Canvas e excluídos quando o usuário sair do Canvas. As propriedades de entrada do Canvas estão disponíveis apenas para referência em Liquid. Para filtrar pelas propriedades dentro do Canvas, use a segmentação por propriedades de evento.
O objeto de propriedades de entrada do Canvas tem um limite máximo de tamanho de 50 KB.
Atualizando o Canvas para usar propriedades de entrada
Se um Canvas ativo que anteriormente não incluía nenhuma mensagem usando canvas_entry_properties for editado para incluir canvas_entry_properties, o valor correspondente a essa propriedade não estará disponível para usuários que entraram no Canvas antes de canvas_entry_properties ser adicionado ao Canvas. Os valores serão salvos apenas para usuários que entrarem no Canvas após a alteração ser feita.
Por exemplo, se você lançou inicialmente um Canvas que não usava nenhuma propriedade de entrada em 3 de novembro e depois adicionou uma nova propriedade product_name ao Canvas em 11 de novembro, os valores de product_name seriam salvos apenas para usuários que entraram no Canvas a partir de 11 de novembro.
No caso de uma propriedade de entrada do Canvas ser nula ou estar em branco, você pode cancelar mensagens usando condicionais. O trecho de código a seguir é um exemplo de como usar Liquid para cancelar uma mensagem.
1
2
3
{% if canvas_entry_properties.${product_name} == blank %}
{% abort_message() %}
{% endif %}
Para saber mais sobre como cancelar mensagens com Liquid, confira nossa documentação de Liquid.
Propriedades de entrada globais do Canvas
Com canvas_entry_properties, você pode definir propriedades globais que se aplicam a todos os usuários ou propriedades específicas do usuário que se aplicam apenas ao usuário especificado. A propriedade específica do usuário substituirá a propriedade global para esse usuário.
Exemplo de requisição
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
curl -X POST \
-H 'Content-Type: application/json' \
-d '{
"api_key": "a valid rest api key",
"canvas_id": "the ID of your Canvas",
"canvas_entry_properties": {
"food_allergies": "none"
},
"recipients": [
{
"external_user_id": "Customer_123",
"canvas_entry_properties": {
"food_allergies": ["dairy", "soy"],
"nutrition": {
"calories_per_serving": 200,
"serving_size_in_ounces": 4
}
}
}
]
}'
Nesta requisição, o valor global para “food allergies” é “none”. Para Customer_123, o valor é “dairy”. As mensagens neste Canvas que contêm o trecho Liquid {{canvas_entry_properties.${food_allergies}}} serão preenchidas com “dairy” para Customer_123 e “none” para todos os outros.
Caso de uso
Se você tem um Canvas que é disparado quando um usuário navega por um item no seu site de eCommerce, mas não o adiciona ao carrinho, a primeira etapa do Canvas pode ser uma notificação por push perguntando se ele tem interesse em comprar o item. Você pode referenciar o nome do produto usando {{canvas_entry_properties.${product_name}}}
A segunda etapa pode enviar outra notificação por push incentivando o usuário a finalizar a compra caso ele tenha adicionado o item ao carrinho, mas ainda não tenha concluído a compra. Você pode continuar referenciando a propriedade de entrada product_name usando {{canvas_entry_properties.${product_name}}}.
