diff --git a/_docs/_user_guide/data_and_analytics/custom_data/custom_events.md b/_docs/_user_guide/data_and_analytics/custom_data/custom_events.md index 4fc76e2e03b..d593a76a16b 100644 --- a/_docs/_user_guide/data_and_analytics/custom_data/custom_events.md +++ b/_docs/_user_guide/data_and_analytics/custom_data/custom_events.md @@ -111,15 +111,34 @@ When making API calls and using the "is blank" filter, a specific custom event p In regards to subscription usage, custom event properties enabled for segmentation with the filters `X Custom Event Property in Y Days` or `X Purchase Property in Y Days` are all counted as separate data points in addition to the data point counted by the custom event itself. -### Canvas guidelines +### Canvas entry properties and event properties -#### Original workflow +You can leverage `canvas_entry_properties` and `event_properties` in your Canvas user journeys. Check out [Canvas entry properties and event properties]({{site.baseurl}}/user_guide/engagement_tools/canvas/create_a_canvas/canvas_entry_properties_event_properties/) for more information and examples. -Event properties can only be used in an action-based Canvas step using the original workflow. +{% tabs local %} +{% tab Canvas Entry Properties %} + +[Canvas entry properties]({{site.baseurl}}/api/objects_filters/canvas_entry_properties_object/) are the properties you map for Canvases that are action-based or API-triggered. Note that the `canvas_entry_properties` object has a maximum size limit of 50 KB. -#### Canvas Flow +For Canvas Flow messaging, `canvas_entry_properties` can be used in Liquid in any Message step. Use this Liquid when referencing these properties: ``{% raw %} canvas_entry_properties${property_name} {% endraw %}``. Note that the events must be custom events or purchase events to be used this way. -Custom event and purchase event properties can be used in Liquid in any [Message]({{site.baseurl}}/user_guide/engagement_tools/canvas/canvas_components/message_step/) step that follows an [Action Paths]({{site.baseurl}}/user_guide/engagement_tools/canvas/canvas_components/action_paths/) step. Make sure to use `` {% raw %} {{event_properties.${property_name}}} {% endraw %}`` if referencing these event properties in Canvas Flow. For more details, check out [Event properties in Message steps]({{site.baseurl}}/user_guide/engagement_tools/canvas/canvas_components/message_step/#event-properties). +{% raw %} +For example, consider the following request: `\"canvas_entry_properties\" : {\"product_name\" : \"shoes\", \"product_price\" : 79.99}`. You could add the word "shoes" to a message with the Liquid `{{canvas_entry_properties.${product_name}}}`. +{% endraw %} + +For the Canvases built with the original editor, `canvas_entry_properties` can be referenced only in the first full step of a Canvas. + +{% endtab %} + +{% tab Event Properties %} +Event properties refer to the properties that you set for custom events and purchases. These `event_properties` can be used in campaigns with action-based delivery as well as Canvases. + +In Canvas Flow, custom event and purchase event properties can be used in Liquid in any Message step that follows an Action Paths step. For Canvas Flow, make sure to use {% raw %} ``{{event_properties.${property_name}}}``{% endraw %} if referencing these `event_properties`. These events must be custom events or purchase events to be used this way in the Message component. + +In the first Message step following an Action Path, you can use `event_properties` related to the event referenced in that Action Path. These `event_properties` can only be used if the user actually took the action (didn’t go to the Everyone Else group). You can have other steps (that are not another Action Paths or Message step) in between this Action Paths and the Message step. + +{% endtab %} +{% endtabs %} ### Nested objects {#nested-objects} diff --git a/_docs/_user_guide/data_and_analytics/custom_data/purchase_events.md b/_docs/_user_guide/data_and_analytics/custom_data/purchase_events.md index fe4242f0e12..113a0da4742 100644 --- a/_docs/_user_guide/data_and_analytics/custom_data/purchase_events.md +++ b/_docs/_user_guide/data_and_analytics/custom_data/purchase_events.md @@ -91,26 +91,37 @@ These segmentation filters include: Unlike with [segment extensions]({{site.baseurl}}/user_guide/engagement_tools/segments/segment_extension/), segments used are updated in real-time, support an unlimited amount of segments, offer a look back history of at most 30 days, and incur data points. Because of the additional data point charge, you must reach out to your CSM to get event properties turned on for your custom events. Once approved, additional properties can be added in the dashboard under **Manage Settings > Custom Events > Mangage Properties** and used in the target step of the campaign or Canvas builder. -### Referencing purchase event properties with Liquid +### Canvas entry properties and event properties -When you send through purchase data that includes purchase properties, you can use the `event_properties` tag to reference the purchase properties in your channel messaging. +You can leverage `canvas_entry_properties` and `event_properties` in your Canvas user journeys. Check out [Canvas entry properties and event properties]({{site.baseurl}}/user_guide/engagement_tools/canvas/create_a_canvas/canvas_entry_properties_event_properties/) for more information and examples. -{% raw %} +{% tabs local %} +{% tab Canvas Entry Properties %} + +[Canvas entry properties]({{site.baseurl}}/api/objects_filters/canvas_entry_properties_object/) are the properties you map for Canvases that are action-based or API-triggered. Note that the `canvas_entry_properties` object has a maximum size limit of 50 KB. -```liquid -{{event_properties.${your_custom_event_property}}} -``` +For Canvas Flow messaging, `canvas_entry_properties` can be used in Liquid in any Message step. Use this Liquid when referencing these properties: ``{% raw %} canvas_entry_properties${property_name} {% endraw %}``. Note that the events must be custom events or purchase events to be used this way. +{% raw %} +For example, consider the following request: `\"canvas_entry_properties\" : {\"product_name\" : \"shoes\", \"product_price\" : 79.99}`. You could add the word "shoes" to a message with the Liquid `{{canvas_entry_properties.${product_name}}}`. {% endraw %} -For example, to reference the name of a product, replace `your_custom_event_property` with the `product_id`. +For the Canvases built with the original editor, `canvas_entry_properties` can be referenced only in the first full step of a Canvas. -### Log purchases at the order level -If you would like to log purchases at the order level instead of the product level, you can use order name or order category as the `product_id`. Refer to our [purchase object specification]({{site.baseurl}}/api/objects_filters/purchase_object/#product-id-naming-conventions) to learn more. +{% endtab %} -#### Canvas Flow +{% tab Event Properties %} +Event properties refer to the properties that you set for custom events and purchases. These `event_properties` can be used in campaigns with action-based delivery as well as Canvases. -Custom event and purchase event properties can be used in Liquid in any [Message]({{site.baseurl}}/user_guide/engagement_tools/canvas/canvas_components/message_step/) step that follows an [Action Paths]({{site.baseurl}}/user_guide/engagement_tools/canvas/canvas_components/action_paths/) step. Make sure to use `` {% raw %} {{event_properties.${property_name}}} {% endraw %}`` if referencing these event properties in Canvas Flow. For more details, check out [Event properties in Message steps]({{site.baseurl}}/user_guide/engagement_tools/canvas/canvas_components/message_step/#event-properties). +In Canvas Flow, custom event and purchase event properties can be used in Liquid in any Message step that follows an Action Paths step. For Canvas Flow, make sure to use {% raw %} ``{{event_properties.${property_name}}}``{% endraw %} if referencing these `event_properties`. These events must be custom events or purchase events to be used this way in the Message component. + +In the first Message step following an Action Path, you can use `event_properties` related to the event referenced in that Action Path. These `event_properties` can only be used if the user actually took the action (didn’t go to the Everyone Else group). You can have other steps (that are not another Action Paths or Message step) in between this Action Paths and the Message step. + +{% endtab %} +{% endtabs %} + +### Log purchases at the order level +If you would like to log purchases at the order level instead of the product level, you can use order name or order category as the `product_id`. Refer to our [purchase object specification]({{site.baseurl}}/api/objects_filters/purchase_object/#product-id-naming-conventions) to learn more. [1]: {% image_buster /assets/img/purchase1.png %} [2]: {% image_buster /assets/img/purchase2.png %} diff --git a/_docs/_user_guide/engagement_tools/canvas/canvas_components/message_step.md b/_docs/_user_guide/engagement_tools/canvas/canvas_components/message_step.md index 3a6cf899709..0793117c277 100644 --- a/_docs/_user_guide/engagement_tools/canvas/canvas_components/message_step.md +++ b/_docs/_user_guide/engagement_tools/canvas/canvas_components/message_step.md @@ -41,25 +41,41 @@ Delivery validations provide an additional check to confirm your audience meets ### Canvas entry properties -Canvas entry properties are properties from the event that triggered the Canvas. These entry properties can only be used in the first full step of a Canvas using the original workflow. +Canvas entry properties are configured in the Entry Schedule step of creating a Canvas and will indicate the trigger that enters a user into a Canvas. These properties can also access the properties of entry payloads in API-triggered Canvases. Note that the `canvas_entry_properties` object has a maximum size limit of 50 KB. -Conversely, in Canvas Flow, you can leverage [persistent entry properties]({{site.baseurl}}/user_guide/engagement_tools/canvas/create_a_canvas/canvas_persistent_entry_properties/) in any Message step to guide your users through personalized steps throughout your Canvas workflow. +#### Original workflow + +For the Canvases built with the original editor, `canvas_entry_properties` can be referenced only in the first Full Step of a Canvas. + +#### Canvas Flow + +For Canvas Flow messaging, `canvas_entry_properties` can be used in Liquid in any Message step. Use this Liquid if referencing these properties: ``{% raw %} canvas_entry_properties${property_name} {% endraw %}``. Note that the events must be custom events or purchase events to be used this way. + +{% raw %} +For example, consider the following request: `\"canvas_entry_properties\" : {\"product_name\" : \"shoes\", \"product_price\" : 79.99}`. You could add the word "shoes" to a message with the Liquid `{{canvas_entry_properties.${product_name}}}`. +{% endraw %} + +You can also leverage [persistent entry properties]({{site.baseurl}}/user_guide/engagement_tools/canvas/create_a_canvas/canvas_persistent_entry_properties/) in any Message step to guide your users through personalized steps throughout your Canvas workflow. ### Event properties +Event properties refer to the properties that you set for custom events and purchases. These `event_properties` can be used in campaigns with action-based delivery as well as Canvases. + #### Original workflow -Event properties can only be used in any action-based Canvas step using the original workflow. +`event_properties` can only be used in any action-based Canvas step using the original workflow. #### Canvas Flow {% alert important %} -Event properties cannot be used independently of Action Paths for Canvas Flow. +`event_properties` cannot be used independently of Action Paths for Canvas Flow. {% endalert %} -In Canvas Flow, custom event and purchase event properties can be used in Liquid in any Message step that follows an [Action Paths]({{site.baseurl}}/user_guide/engagement_tools/canvas/canvas_components/action_paths/) step. For Canvas Flow, make sure to use `` {% raw %} {{event_properties.${property_name}}} {% endraw %}`` if referencing these event properties. These events must be custom events or purchase events to be used this way in the Message component. +In Canvas Flow, custom event and purchase event properties can be used in Liquid in any Message step that follows an [Action Paths]({{site.baseurl}}/user_guide/engagement_tools/canvas/canvas_components/action_paths/) step. For Canvas Flow, use this Liquid `` {% raw %} {{event_properties.${property_name}}} {% endraw %}`` when referencing these `event_properties`. These events must be custom events or purchase events to be used this way in the Message component. + +In the first Message step following an Action Path, you can use `event_properties` related to the event referenced in that Action Path. You can have other steps (that are not another Action Paths or Message step) in between this Action Paths step and the Message step. Note that you’ll only have access to `event_properties` if your Message step can be traced back to a non-Everyone Else path in an Action Path step. -In the first Message step following an Action Path, you can use event properties related to the event referenced in that Action Path. These event properties can only be used if the user actually took the action (didn't go to the Everyone Else group). You can have other steps (that are not another Action Paths or Message step) in between this Action Paths and the Message step. +For more information and examples, check out [Canvas entry properties and event properties]({{site.baseurl}}/user_guide/engagement_tools/canvas/create_a_canvas/canvas_entry_properties_event_properties/). ## Analytics diff --git a/_docs/_user_guide/engagement_tools/canvas/create_a_canvas.md b/_docs/_user_guide/engagement_tools/canvas/create_a_canvas.md index e46528b9629..d83243ef19e 100644 --- a/_docs/_user_guide/engagement_tools/canvas/create_a_canvas.md +++ b/_docs/_user_guide/engagement_tools/canvas/create_a_canvas.md @@ -27,6 +27,9 @@ guide_featured_list: - name: Exception Events link: /docs/user_guide/engagement_tools/canvas/create_a_canvas/exception_events/ fa_icon: fas fa-exchange-alt + - name: Canvas Entry Properties and Event Properties + link: /docs/user_guide/engagement_tools/canvas/create_a_canvas/canvas_entry_properties_event_properties/ + fa_icon: fas fa-user-check - name: Persistent Entry Properties link: /docs/user_guide/engagement_tools/canvas/create_a_canvas/canvas_persistent_entry_properties/ fa_icon: fas fa-project-diagram diff --git a/_docs/_user_guide/engagement_tools/canvas/create_a_canvas/canvas_entry_properties_event_properties.md b/_docs/_user_guide/engagement_tools/canvas/create_a_canvas/canvas_entry_properties_event_properties.md new file mode 100644 index 00000000000..c625f2f5ca0 --- /dev/null +++ b/_docs/_user_guide/engagement_tools/canvas/create_a_canvas/canvas_entry_properties_event_properties.md @@ -0,0 +1,50 @@ +--- +nav_title: Canvas Entry Properties and Event Properties +article_title: Canvas Entry Properties and Event Properties +page_type: reference +description: "This reference article describes the differences between Canvas entry properties and event properties, and when to use each property." +tool: Canvas +page_order: 8 +--- + +# Canvas entry properties and event properties + +> This reference article covers information about `canvas_entry_properties` and `event_properties`, including when to use each property and the differences in behavior. + +Though similar in name, Canvas entry properties and event properties function differently within your Canvas workflows. Properties of events or API calls that trigger a user's entry into a Canvas are known as `canvas_entry_properties`. Properties of events that occur as a user moves through a Canvas journey are known as `event_properties`. The key difference here is `canvas_entry_properties` focuses on more than just events by also accessing the properties of entry payloads in API-triggered Canvases. + +Behavior can vary between workflows built with the original Canvas editor versus Canvas Flow. For example, in the original Canvas editor, you can use `event_properties` in the first Full Step if it's an action-based step. In Canvas Flow, Full Steps aren't supported, so this does not apply. + +Check out this table for a summary of differences between `canvas_entry_properties` and `event_properties`. + +| | Canvas Entry Properties | Event Properties +|----|----|----| +| **Liquid** | `canvas_entry_properties` | `event_properties` | +| **Persistence** | Can be referenced by all [Message][1] steps for the duration of a Canvas for Canvas Flow only. | - Can only be referenced once.
- Cannot be referenced by any subsequent Message steps. | +| **Original Canvas behavior** | Can only reference `canvas_entry_properties` in the first Full Step of a Canvas. The Canvas must be action-based or API triggered. | You can reference `event_properties` in any Full Step that uses action-based delivery in a Canvas. However, if a user is using a [Canvas component][2] in the original Canvas editor, the behavior follows the Canvas Flow rules for `event_properties`. | +| **Canvas Flow behavior** | Can reference `canvas_entry_properties` in any step of a Canvas. | - Can reference `event_properties` in the first Message step **after** an [Action Paths][3] step where the action taken is a custom event or purchase event.
- Cannot be after the Everyone Else path of the Action Paths step.
- Can have other non-Message Canvas components in between the Action Path and Message Step. If one of these non-Message Canvas components is an Action Paths step, the user can go through that Action Paths' Everyone Else path. | +{: .reset-td-br-1 .reset-td-br-2 .reset-td-br-3} + +## Example + +![][7]{: style="float:right;max-width:30%;margin-left:15px;"} + +Here's an example that explains behavior for `canvas_entry_properties` and `event_properties` in Canvas Flow. Let's say we have an action-based Canvas. In this scenario, users will enter this Canvas if they perform the custom event "add item to wishlist". + +The `canvas_entry_properties` are configured in the [Entry Schedule][4] step of creating a Canvas and will correspond to when a user enters a Canvas. These `canvas_entry_properties` can also be referenced in any Message Step in Canvas Flow since Canvas Flow supports [persistent entry properties][5]. + +In this Canvas, we have a user journey that begins at an Action Paths step to determine if a user has added an item to their wishlist. From here, if the user has added an item, then they will experience a delay before receiving a message "New item in your wishlist!" from the Message step. The first Message step in a user journey will have access to the custom `event_properties` from your Action Paths step, so in this case, we're able to include `` {% raw %} {{event_properties.${property_name}}} {% endraw %}`` here in this Message step as part of our message content. + +If a user doesn't add an item to their wishlist, they go through the Everyone Else path, so the `event_properties` can't be referenced and will reflect an invalid settings error. + +Note that you’ll only have access to `event_properties` if your Message Step can be traced back to a non-Everyone Else path in an Action Path step. If the Message Step is connected to an Everyone Else path but can be traced back to an Action Paths step in the user journey, then you will also still have access to `event_properties`. For more information on these behaviors, check out [Message][8]. + +Note that you’ll only have access to event_properties if your Message Step can be traced back to a non-Everyone Else path in an Action Path step. + +[1]: {{site.baseurl}}/user_guide/engagement_tools/canvas/canvas_components/message_step/ +[2]: {{site.baseurl}}/user_guide/engagement_tools/canvas/canvas_components/ +[3]: {{site.baseurl}}/user_guide/engagement_tools/canvas/canvas_components/action_paths/ +[4]: ({{site.baseurl}}/user_guide/engagement_tools/canvas/create_a_canvas/create_a_canvas/#step-2b-set-your-canvas-entry-schedule) +[5]: ({{site.baseurl}}/user_guide/engagement_tools/canvas/create_a_canvas/canvas_persistent_entry_properties/ +[7]: {% image_buster /assets/img_archive/canvas_entry_properties1.png %} +[8]: {{site.baseurl}}/user_guide/engagement_tools/canvas/canvas_components/message_step/ \ No newline at end of file diff --git a/_docs/_user_guide/engagement_tools/canvas/create_a_canvas/create_a_canvas.md b/_docs/_user_guide/engagement_tools/canvas/create_a_canvas/create_a_canvas.md index f2bbf822c48..00958dcf136 100644 --- a/_docs/_user_guide/engagement_tools/canvas/create_a_canvas/create_a_canvas.md +++ b/_docs/_user_guide/engagement_tools/canvas/create_a_canvas/create_a_canvas.md @@ -292,28 +292,30 @@ Click **Done** once you've finished configuring your Canvas component. {% tabs local %} {% tab Canvas Entry Properties %} -[Canvas entry properties]({{site.baseurl}}/api/objects_filters/canvas_entry_properties_object/) are the properties mapped by you when triggering or scheduling a Canvas via the API. Note that the Canvas entry properties object has a maximum size limit of 50 KB. +The `canvas_entry_properties` are configured in the Entry Schedule step of creating a Canvas and will indicate the trigger that enters a user into a Canvas. These properties can also access the properties of entry payloads in API-triggered Canvases. Note that the `canvas_entry_properties` object has a maximum size limit of 50 KB. -{% raw %} -For example, a request with `\"canvas_entry_properties\" : {\"product_name\" : \"shoes\", \"product_price\" : 79.99}` could add the word \"shoes\" to a message by adding the Liquid `{{canvas_entry_properties.${product_name}}}`. -{% endraw %} +For the Canvases built with the original editor, `canvas_entry_properties` can be referenced only in the first Full Step of a Canvas. -For the Canvases built with the original editor, entry properties can be referenced only in the first full step of a Canvas. +For Canvas Flow messaging, entry properties can be used in Liquid in any Message step. Use the following Liquid when referencing these entry properties: {% raw %} ``canvas_entry_properties${property_name}`` {% endraw %}. Note that the events must be custom events or purchase events to be used this way. -For Canvas Flow messaging, entry properties can be used in Liquid in any Message step. So, be sure to use ``{% raw %} canvas_entry_properties${property_name} {% endraw %}`` if referencing these Canvas entry properties. Note that the events must be custom events or purchase events to be used this way. +{% raw %} +For example, consider the following request: `\"canvas_entry_properties\" : {\"product_name\" : \"shoes\", \"product_price\" : 79.99}`. You could add the word "shoes" to a message with this Liquid ``{{canvas_entry_properties.${product_name}}}``. +{% endraw %} {% endtab %} -{% tab Custom Event Properties %} -[Custom event properties]({{site.baseurl}}/user_guide/data_and_analytics/custom_data/custom_events/#custom-event-properties) are the properties set by you on custom events and purchases, used mainly in action-based delivery campaigns. +{% tab Event Properties %} +Event properties are the properties set by you on custom events and purchases. These `event_properties` can be used in campaigns with action-based delivery as well as Canvases. -For the original Canvas editor, event properties don’t persist, so if you are scheduling a Canvas step rather than using action-based delivery, you wouldn’t be able to use an event property (as we don’t store that data). You can’t reference the event property for an event that’s already happened. This means that custom event properties can only be referenced in the first step of a Canvas. Make sure to use ``{% raw %} {{canvas_entry_properties.${property_name}}} {% endraw %}`` if referencing event properties in the first step. +In Canvas Flow, custom event and purchase event properties can be used in Liquid in any Message step that follows an Action Paths step. For Canvas Flow, use this Liquid {% raw %} ``{{event_properties.${property_name}}}`` {% endraw %} when referencing these `event_properties`. These events must be custom events or purchase events to be used this way in the Message component. -For Canvas Flow messaging, action-based delivery event properties that trigger Canvas entry are not ephemeral, and can be used in Liquid in any [Message]({{site.baseurl}}/user_guide/engagement_tools/canvas/canvas_components/message_step/) step. Be sure to use ``{% raw %} {{event_properties.${property_name}}} {% endraw %}`` if referencing these Canvas entry properties. Check out how to use [custom event properties in Message steps]({{site.baseurl}}/user_guide/engagement_tools/canvas/canvas_components/message_step/#event-properties). +In the first Message step following an Action Path, you can use `event_properties` related to the event referenced in that Action Path. You can have other steps (that are not another Action Paths or Message step) in between this Action Paths step and the Message step. Note that you’ll only have access to `event_properties` if your Message step can be traced back to a non-Everyone Else path in an Action Path step {% endtab %} {% endtabs %} +For more information and examples, check out [Canvas entry properties and event properties]({{site.baseurl}}/user_guide/engagement_tools/canvas/create_a_canvas/canvas_entry_properties_event_properties/). + {% alert tip %} Did you know you can include Canvas component names in your messages and link templates?
Use the `campaign.${name}` Liquid tag in Canvas to display the current Canvas component name. diff --git a/_docs/_user_guide/personalization_and_dynamic_content/liquid/supported_personalization_tags.md b/_docs/_user_guide/personalization_and_dynamic_content/liquid/supported_personalization_tags.md index 8d1c51410f8..6f2fc6a0c91 100644 --- a/_docs/_user_guide/personalization_and_dynamic_content/liquid/supported_personalization_tags.md +++ b/_docs/_user_guide/personalization_and_dynamic_content/liquid/supported_personalization_tags.md @@ -24,6 +24,7 @@ As a convenience, a summary of supported personalization tags are provided. For | Card Attributes | `{{card.${api_id}}}`
`{{card.${name}}}` | | Geofencing Events | `{{event_properties.${geofence_name}}}`
`{{event_properties.${geofence_set_name}}}` | | Event Properties
(These are custom to your app group.)| `{{event_properties.${your_custom_event_property}}}` | +| Canvas Entry Properties| `{{canvas_entry_properties}}` | | Custom Attributes
(These are custom to your app group.) | `{{custom_attribute.${your_custom_attribute}}}` | {: .reset-td-br-1 .reset-td-br-2} diff --git a/assets/img_archive/canvas_entry_properties1.png b/assets/img_archive/canvas_entry_properties1.png new file mode 100644 index 00000000000..4d8b6eb539b Binary files /dev/null and b/assets/img_archive/canvas_entry_properties1.png differ