diff --git a/_docs/_api/endpoints/messaging/schedule_messages/post_schedule_triggered_canvases.md b/_docs/_api/endpoints/messaging/schedule_messages/post_schedule_triggered_canvases.md index 5b814c5fe36..697e1b4ed32 100644 --- a/_docs/_api/endpoints/messaging/schedule_messages/post_schedule_triggered_canvases.md +++ b/_docs/_api/endpoints/messaging/schedule_messages/post_schedule_triggered_canvases.md @@ -16,7 +16,9 @@ description: "This article outlines details about the Schedule API-triggered Can > Use this endpoint to schedule Canvas messages via API-triggered delivery, allowing you to decide what action should trigger the message to be sent. -You can pass in `canvas_entry_properties` that will be templated into the messages sent by the first steps of the Canvas. +You can pass in `context` that will be templated into the messages sent by the first steps of the Canvas. + +{% multi_lang_include alerts/important_alerts.md alert='context variable' %} Note that to send messages with this endpoint, you must have a [Canvas ID]({{site.baseurl}}/api/identifier_types/#canvas-api-identifier), created when you build a Canvas. @@ -49,7 +51,7 @@ Authorization: Bearer YOUR-REST-API-KEY // If 'recipients' and 'audience' are not provided and broadcast is not set to 'false', // the message will send to entire segment targeted by the Canvas "broadcast": (optional, boolean) see broadcast -- defaults to false on 8/31/17, must be set to true if "recipients" object is omitted, - "canvas_entry_properties": (optional, object) personalization key-value pairs for the first step for all users in this send; see trigger properties, + "context": (optional, object) personalization key-value pairs for the first step for all users in this send; see trigger properties, "schedule": { "time": (required, datetime as ISO 8601 string) time to send the message, "in_local_time": (optional, bool), @@ -66,7 +68,7 @@ Authorization: Bearer YOUR-REST-API-KEY | `recipients` | Optional | Array of recipients objects | See [recipients object]({{site.baseurl}}/api/objects_filters/recipient_object/). | | `audience` | Optional | Connected audience object | See [connected audience]({{site.baseurl}}/api/objects_filters/connected_audience/). | |`broadcast`| Optional | Boolean | You must set `broadcast` to true when sending a message to an entire segment that a campaign or Canvas targets. This parameter defaults to false (as of August 31, 2017).

If `broadcast` is set to true, a `recipients` list cannot be included. However, use caution when setting `broadcast: true`, as unintentionally setting this flag may cause you to send your message to a larger than expected audience. | -| `canvas_entry_properties` | Optional | Object | Personalization key-value pairs for all users in this send. See [Canvas entry properties object]({{site.baseurl}}/api/objects_filters/canvas_entry_properties_object). | +| `context` | Optional | Object | Personalization key-value pairs for all users in this send. See [Canvas context object]({{site.baseurl}}/api/objects_filters/context_object). | | `schedule` | Required | Schedule object | See [schedule object]({{site.baseurl}}/api/objects_filters/schedule_object/). | {: .reset-td-br-1 .reset-td-br-2 .reset-td-br-3 .reset-td-br-4 role="presentation" } @@ -81,7 +83,7 @@ curl --location --request POST 'https://rest.iad-01.braze.com/canvas/trigger/sch { "user_alias": "example_alias", "external_user_id": "external_user_identifier", - "canvas_entry_properties": {} + "context": {} } ], "audience": { @@ -132,7 +134,7 @@ curl --location --request POST 'https://rest.iad-01.braze.com/canvas/trigger/sch ] }, "broadcast": false, - "canvas_entry_properties": {}, + "context": {}, "schedule": { "time": "", "in_local_time": false, diff --git a/_docs/_api/endpoints/messaging/send_messages/post_send_triggered_canvases.md b/_docs/_api/endpoints/messaging/send_messages/post_send_triggered_canvases.md index 342384358a3..e95835451a0 100644 --- a/_docs/_api/endpoints/messaging/send_messages/post_send_triggered_canvases.md +++ b/_docs/_api/endpoints/messaging/send_messages/post_send_triggered_canvases.md @@ -40,18 +40,18 @@ Authorization: Bearer YOUR-REST-API-KEY ```json { "canvas_id": (required, string) see Canvas identifier, - "canvas_entry_properties": (optional, object) personalization key-value pairs that apply to all users in this request, + "context": (optional, object) personalization key-value pairs that apply to all users in this request, "broadcast": (optional, boolean) see Broadcast -- defaults to false on 8/31/17, must be set to true if `recipients` is omitted, "audience": (optional, connected audience object) see connected audience, // Including 'audience' will only send to users in the audience - "recipients": (optional, array; if not provided and broadcast is not set to 'false', message will send to the entire segment targeted by the Canvas) + "recipients": (optional, array; if not provided and broadcast is not set to 'false', message sends to the entire segment targeted by the Canvas) [{ // Either "external_user_id" or "user_alias" or "email" is required. Requests must specify only one. "user_alias": (optional, user alias object) user alias of user to receive message, "external_user_id": (optional, string) external identifier of user to receive message, "email": (optional, string) email address of user to receive message, "prioritization": (optional, array) prioritization array; required when using email, - "canvas_entry_properties": (optional, object) personalization key-value pairs that apply to this user (these key-value pairs override any keys that conflict with the parent `canvas_entry_properties`) + "context": (optional, object) personalization key-value pairs that apply to this user (these key-value pairs override any keys that conflict with the parent `context`) "send_to_existing_only": (optional, boolean) defaults to true, can't be used with user aliases "attributes": (optional, object) fields in the attributes object create or update an attribute of that name with the given value on the specified user profile before the message is sent and existing values are overwritten }], @@ -64,10 +64,10 @@ Authorization: Bearer YOUR-REST-API-KEY | Parameter | Required | Data Type | Description | | --------- | ---------| --------- | ----------- | |`canvas_id`| Required | String | See [Canvas identifier]({{site.baseurl}}/api/identifier_types/). | -|`canvas_entry_properties`| Optional | Object | This includes [Canvas entry properties]({{site.baseurl}}/api/objects_filters/canvas_entry_properties_object/). Personalization key-value pairs apply to all users in this request. The Canvas entry properties object has a maximum size limit of 50 KB.

**Note:** If you're participating in the [Canvas Context early access]({{site.baseurl}}/user_guide/engagement_tools/canvas/canvas_components/context/), this parameter is `context` and includes Canvas entry properties. | +|`context`| Optional | Object | This includes [Canvas entry properties]({{site.baseurl}}/api/objects_filters/context_object/). Personalization key-value pairs apply to all users in this request. The context object has a maximum size limit of 50 KB. | |`broadcast`| Optional | Boolean | You must set `broadcast` to true when sending a message to an entire segment that a campaign or Canvas targets. This parameter defaults to false (as of August 31, 2017).

If `broadcast` is set to true, a `recipients` list cannot be included. However, use caution when setting `broadcast: true`, as unintentionally setting this flag may cause you to send your message to a larger-than-expected audience. | |`audience`| Optional| Connected audience object | See [Connected audience]({{site.baseurl}}/api/objects_filters/connected_audience/). | -|`recipients`| Optional | Array | See [Recipients object]({{site.baseurl}}/api/objects_filters/recipient_object/).

If not provided and `broadcast` is set to `true`, the message is sent to the entire segment that the Canvas targets.

The `recipients` array may contain up to 50 objects, with each object containing a single `external_user_id` string and a `canvas_entry_properties` object. This call requires an `external_user_id`, `user_alias`, or `email`. Requests must specify only one.

If `email` is the identifier, you must include [`prioritization`]({{site.baseurl}}/api/endpoints/user_data/post_user_identify#identifying-users-by-email) in the recipients object. | +|`recipients`| Optional | Array | See [Recipients object]({{site.baseurl}}/api/objects_filters/recipient_object/).

If not provided and `broadcast` is set to `true`, the message is sent to the entire segment that the Canvas targets.

The `recipients` array may contain up to 50 objects, with each object containing a single `external_user_id` string and a `context` object. This call requires an `external_user_id`, `user_alias`, or `email`. Requests must specify only one.

If `email` is the identifier, you must include [`prioritization`]({{site.baseurl}}/api/endpoints/user_data/post_user_identify#identifying-users-by-email) in the recipients object. | {: .reset-td-br-1 .reset-td-br-2 .reset-td-br-3 .reset-td-br-4 role="presentation" } {% alert important %} @@ -87,7 +87,7 @@ curl --location --request POST 'https://rest.iad-01.braze.com/canvas/trigger/sen --header 'Authorization: Bearer YOUR-REST-API-KEY' \ --data-raw '{ "canvas_id": "canvas_identifier", - "canvas_entry_properties": {"product_name" : "shoes", "product_price" : 79.99}, + "context": {"product_name" : "shoes", "product_price" : 79.99}, "broadcast": false, "audience": { "AND": [ diff --git a/_docs/_api/objects_filters.md b/_docs/_api/objects_filters.md index fbb40be4eda..859acca0fb9 100644 --- a/_docs/_api/objects_filters.md +++ b/_docs/_api/objects_filters.md @@ -12,7 +12,7 @@ description: "This landing page lists the Braze API objects and filters used in ## Objects and filters -- [Canvas entry properties object]({{site.baseurl}}/api/objects_filters/canvas_entry_properties_object) +- [Canvas context object]({{site.baseurl}}/api/objects_filters/context_object) - [Connected audience filter & object]({{site.baseurl}}/api/objects_filters/connected_audience/) - [Event object]({{site.baseurl}}/api/objects_filters/event_object/) - [Purchase object]({{site.baseurl}}/api/objects_filters/purchase_object/) diff --git a/_docs/_api/objects_filters/canvas_entry_properties_object.md b/_docs/_api/objects_filters/canvas_entry_properties_object.md deleted file mode 100644 index 62e89c412c7..00000000000 --- a/_docs/_api/objects_filters/canvas_entry_properties_object.md +++ /dev/null @@ -1,30 +0,0 @@ ---- -nav_title: "Canvas entry properties object" -article_title: API Canvas Entry Properties Object -page_order: 2 -page_type: reference -tool: - - Canvas -description: "This article explains the Braze Canvas entry properties object." - ---- - -# Canvas entry properties object - -> When using one of the endpoints for triggering or scheduling a Canvas through the API, you may provide a map of keys and values to customize messages sent by the first steps of your Canvas, in the `canvas_entry_properties` namespace. - -{% alert note %} -The Canvas entry properties object has a maximum size limit of 50 KB. -{% endalert %} - -## Object body - -This object body contains an example request. - -```json -"canvas_entry_properties": {"product_name" : "shoes", "product_price" : 79.99} -``` - -{% 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 ```{{canvas_entry_properties.${product_name}}}``` to the request. -{% endraw %} diff --git a/_docs/_api/objects_filters/context_object.md b/_docs/_api/objects_filters/context_object.md new file mode 100644 index 00000000000..89ec7d94efc --- /dev/null +++ b/_docs/_api/objects_filters/context_object.md @@ -0,0 +1,31 @@ +--- +nav_title: "Canvas context object" +article_title: API Canvas Context Object +page_order: 2 +page_type: reference +alias: /api/objects_filters/canvas_entry_properties_object/ +tool: + - Canvas +description: "This article explains the Braze Canvas context object." + +--- + +# Canvas context object + +> When using one of the endpoints for triggering or scheduling a Canvas through the API, you may provide a map of keys and values to customize messages sent by the first steps of your Canvas, in the `context` namespace. + +{% alert note %} +The context object has a maximum size limit of 50 KB. +{% endalert %} + +## Object body + +This object body contains an example request. + +```json +"context": {"product_name" : "shoes", "product_price" : 79.99} +``` + +{% raw %} +For example, a request with `"context": {"product_name" : "shoes", "product_price" : 79.99}` could add the word "shoes" to a message by adding ```{{context.${product_name}}}``` to the request. +{% endraw %} diff --git a/_docs/_api/objects_filters/recipient_object.md b/_docs/_api/objects_filters/recipient_object.md index 40d91457c59..1aaa408c46a 100644 --- a/_docs/_api/objects_filters/recipient_object.md +++ b/_docs/_api/objects_filters/recipient_object.md @@ -25,7 +25,7 @@ The recipients object allows you to combine the [user alias object]({{site.baseu "email": (optional, string) email address of user to receive message, "prioritization": (optional, array) see Prioritization; required when using email, "trigger_properties": (optional, object) personalization key-value pairs for this user when sending a campaign or message; see Trigger Properties, - "canvas_entry_properties": (optional, object) personalization key-value pairs for this user when triggering a Canvas; see Canvas Entry Properties, + "context": (optional, object) personalization key-value pairs for this user when triggering a Canvas; see Canvas context object "send_to_existing_only": (optional, boolean) defaults to true; cannot be used with user aliases, "attributes": (optional, object) fields in the attributes object create or update an attribute of that name with the given value on the specified user profile before the message is sent and existing values are overwritten }] diff --git a/_docs/_hidden/archived_layouts/api_glossary.md b/_docs/_hidden/archived_layouts/api_glossary.md index 93d7ed02dcb..33ebcea56e0 100644 --- a/_docs/_hidden/archived_layouts/api_glossary.md +++ b/_docs/_hidden/archived_layouts/api_glossary.md @@ -186,7 +186,7 @@ Content-Type: application/json Authorization: Bearer YOUR-REST-API-KEY { "canvas_id": (required, string) see Canvas Identifier, - "canvas_entry_properties": (optional, object) personalization key-value pairs that will apply to all users in this request, + "context": (optional, object) personalization key-value pairs that will apply to all users in this request, "broadcast": (optional, boolean) see Broadcast -- defaults to false on 8/31/17, must be set to true if "recipients" is omitted, "audience": (optional, Connected Audience Object) see Connected Audience, // Including 'audience' will only send to users in the audience @@ -195,7 +195,7 @@ Authorization: Bearer YOUR-REST-API-KEY // Either "external_user_id" or "user_alias" is required. Requests must specify only one. "user_alias": (optional, User Alias Object) User Alias of user to receive message, "external_user_id": (optional, string) External ID of user to receive message, - "canvas_entry_properties": (optional, object) personalization key-value pairs that will apply to this user (these key-value pairs will override any keys that conflict with the parent canvas_entry_properties) + "context": (optional, object) personalization key-value pairs that will apply to this user (these key-value pairs will override any keys that conflict with the parent context) }, ... ] diff --git a/_docs/_partners/data_and_analytics/workflow_automation/zapier.md b/_docs/_partners/data_and_analytics/workflow_automation/zapier.md index e61188fb0b9..f3c35ad109d 100644 --- a/_docs/_partners/data_and_analytics/workflow_automation/zapier.md +++ b/_docs/_partners/data_and_analytics/workflow_automation/zapier.md @@ -62,7 +62,7 @@ When setting up your webhook, use the following settings and provide your Braze "recipients": [ { "external_user_id": "external_user_identifier", - "canvas_entry_properties":{ + "context":{ "string_property": "Your example string", "example_integer_property": 1 } diff --git a/_docs/_user_guide/data/activation/catalogs/catalog_triggers/back_in_stock_notifications.md b/_docs/_user_guide/data/activation/catalogs/catalog_triggers/back_in_stock_notifications.md index c023bb69831..57ed1ae5cf1 100644 --- a/_docs/_user_guide/data/activation/catalogs/catalog_triggers/back_in_stock_notifications.md +++ b/_docs/_user_guide/data/activation/catalogs/catalog_triggers/back_in_stock_notifications.md @@ -80,11 +80,13 @@ Now, your customers can be notified when an item is back in stock. ### Using Liquid -To template in details about the catalog item that's back in stock, you can use the `canvas_entry_properties` Liquid tag to access the `item_id`. +To template in details about the catalog item that's back in stock, you can use the `context` Liquid tag to access the `item_id`. -Using {%raw%}``{{canvas_entry_properties.${catalog_update}.item_id}}``{%endraw%} will return the ID of the item that came back in stock. {%raw%}``{{canvas_entry_properties.${catalog_update}.previous_value}}``{%endraw%} will return the inventory value of the item prior to the update, and {%raw%}``{{canvas_entry_properties.${catalog_update}.new_value}}``{%endraw%} will return the new inventory value after the update. +Using {%raw%}``{{context.${catalog_update}.item_id}}``{%endraw%} will return the ID of the item that came back in stock. {%raw%}``{{context.${catalog_update}.previous_value}}``{%endraw%} will return the inventory value of the item prior to the update, and {%raw%}``{{context.${catalog_update}.new_value}}``{%endraw%} will return the new inventory value after the update. -Use this Liquid tag {%raw%}``{% catalog_items {{canvas_entry_properties.${catalog_update}.item_id}} %}``{%endraw%} at the top of your message, then use {%raw%}``{{ items[0]. }}``{%endraw%} to access data about that item throughout the message. +Use this Liquid tag {%raw%}``{% catalog_items {{context.${catalog_update}.item_id}} %}``{%endraw%} at the top of your message, then use {%raw%}``{{ items[0]. }}``{%endraw%} to access data about that item throughout the message. + +{% multi_lang_include alerts/important_alerts.md alert='context variable' %} ## Considerations diff --git a/_docs/_user_guide/data/activation/catalogs/catalog_triggers/price_drop_notifications.md b/_docs/_user_guide/data/activation/catalogs/catalog_triggers/price_drop_notifications.md index 9b39249c05e..4595c832ab0 100644 --- a/_docs/_user_guide/data/activation/catalogs/catalog_triggers/price_drop_notifications.md +++ b/_docs/_user_guide/data/activation/catalogs/catalog_triggers/price_drop_notifications.md @@ -96,11 +96,13 @@ Now, your customers will be notified when an item's price drops. ### Using Liquid -To template in details about the catalog item that has dropped in price, you can use the `canvas_entry_properties` Liquid tag to access the `item_id`. +To template in details about the catalog item that has dropped in price, you can use the `context` Liquid tag to access the `item_id`. -Using {%raw%}``{{canvas_entry_properties.${catalog_update}.item_id}}``{%endraw%} will return the ID of the item that dropped in price. {%raw%}``{{canvas_entry_properties.${catalog_update}.previous_value}}``{%endraw%} will return the price value of the item before the update, and {%raw%}``{{canvas_entry_properties.${catalog_update}.new_value}}``{%endraw%} will return the new price value after the update. +Using {%raw%}``{{context.${catalog_update}.item_id}}``{%endraw%} will return the ID of the item that dropped in price. {%raw%}``{{context.${catalog_update}.previous_value}}``{%endraw%} will return the price value of the item before the update, and {%raw%}``{{context.${catalog_update}.new_value}}``{%endraw%} will return the new price value after the update. -Use this Liquid tag {%raw%}``{% catalog_items {{canvas_entry_properties.${catalog_update}.item_id}} %}}``{%endraw%} at the top of your message, then use {%raw%}`{{items[0].}}`{%endraw%} to access data about that item throughout the message. +Use this Liquid tag {%raw%}``{% catalog_items {{context.${catalog_update}.item_id}} %}}``{%endraw%} at the top of your message, then use {%raw%}`{{items[0].}}`{%endraw%} to access data about that item throughout the message. + +{% multi_lang_include alerts/important_alerts.md alert='context variable' %} ## Considerations 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 6e7e875da5e..3e6da29594b 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 @@ -63,20 +63,22 @@ All users who enter the Message step will advance to the next step when any one If an action-based Canvas is triggered by an inbound SMS message, you can reference SMS properties in the first step (Message step) or a Message step that is nested under an Action Path step. For example, in the Message step, you could use `{{sms.${inbound_message_body}}}` or `{{sms.${inbound_media_urls}}}`. {% endraw %} -## Referencing Canvas entry properties +## Referencing context properties -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. +{% multi_lang_include alerts/important_alerts.md alert='context variable' %} -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 %}. Events must be custom events or purchase events to be used this way. +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 `context` object has a maximum size limit of 50 KB. + +Entry properties can be used in Liquid in any Message step. Use the following Liquid when referencing these entry properties: {% raw %}``context.${property_name}``{% endraw %}. Events must be custom events or purchase events to be used this way. {% alert note %} -For in-app message channels specifically, `canvas_entry_properties` can only be referenced in Canvas. +For in-app message channels specifically, `context` can only be referenced in Canvas. {% endalert %} -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. +Use the following Liquid when referencing these entry properties: {% raw %}``context.${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}}}`. +For example, consider the following request: `\"context\" : {\"product_name\" : \"shoes\", \"product_price\" : 79.99}`. You could add the word "shoes" to a message with the Liquid `{{context.${product_name}}}`. {% endraw %} You can also leverage [persistent entry properties]({{site.baseurl}}/user_guide/engagement_tools/canvas/create_a_canvas/canvas_entry_properties_event_properties/canvas_persistent_entry_properties/) in any Message step to guide your users through personalized steps throughout your Canvas workflow. @@ -94,7 +96,7 @@ In Canvas, custom event and purchase event properties can be used in Liquid in a 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. {% alert important %} -You can't use `event_properties` in the lead Message step. Instead, you must use `canvas_entry_properties` or add an Action Paths step with the corresponding event before the Message step that includes `event_properties`. +You can't use `event_properties` in the lead Message step. Instead, you must use `context` or add an Action Paths step with the corresponding event before the Message step that includes `event_properties`. {% endalert %} {% details Expand for original Canvas editor %} @@ -102,8 +104,8 @@ You can't use `event_properties` in the lead Message step. Instead, you must use You can no longer create or duplicate Canvases using the original editor. This section is available for reference only. - `event_properties` can't be used in scheduled full steps. However, you can use `event_properties` in the first full step of an action-based Canvas, even if the full step is scheduled. -- `canvas_entry_properties` can be referenced only in the first full step of a Canvas. -- For in-app message channels specifically, `canvas_entry_properties` can be referenced in the original Canvas editor if you have persistent entry properties enabled as part of the previous early access. +- `context` can be referenced only in the first full step of a Canvas. +- For in-app message channels specifically, `context` can be referenced in the original Canvas editor if you have persistent entry properties enabled as part of the previous early access. {% enddetails %} diff --git a/_docs/_user_guide/engagement_tools/canvas/create_a_canvas/canvas_entry_properties_event_properties/canvas_persistent_entry_properties.md b/_docs/_user_guide/engagement_tools/canvas/create_a_canvas/canvas_entry_properties_event_properties/canvas_persistent_entry_properties.md index b2c496d2783..fb27b189c21 100644 --- a/_docs/_user_guide/engagement_tools/canvas/create_a_canvas/canvas_entry_properties_event_properties/canvas_persistent_entry_properties.md +++ b/_docs/_user_guide/engagement_tools/canvas/create_a_canvas/canvas_entry_properties_event_properties/canvas_persistent_entry_properties.md @@ -13,7 +13,7 @@ page_order: 5 > When a Canvas is triggered by a custom event, purchase, or an API call, you can use metadata from the API call, custom event, or purchase event for personalization in each step in your Canvas workflow. You can use these properties to send more curated messages. {% alert important %} -Persistent entry properties are an artifact of the original Canvas editor, so there are deprecated references to terms that remain for historical reference. For the current updated Canvas editor, refer to [Canvas entry properties and event properties]({{site.baseurl}}/user_guide/engagement_tools/canvas/create_a_canvas/canvas_entry_properties_event_properties). +Persistent entry properties are an artifact of the original Canvas editor, so there are deprecated references to terms like Canvas entry properties that remain for historical reference. For the current updated Canvas editor, refer to [Context and event properties]({{site.baseurl}}/user_guide/engagement_tools/canvas/create_a_canvas/context_and_event_properties). {% endalert %} ## Using entry properties 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/context_and_event_properties.md similarity index 54% rename from _docs/_user_guide/engagement_tools/canvas/create_a_canvas/canvas_entry_properties_event_properties.md rename to _docs/_user_guide/engagement_tools/canvas/create_a_canvas/context_and_event_properties.md index ab5a3092da6..28ad0ebcf29 100644 --- 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/context_and_event_properties.md @@ -1,32 +1,32 @@ --- -nav_title: Canvas entry properties and event properties -article_title: Canvas Entry Properties and Event Properties +nav_title: Context and event properties +article_title: Context and Event Properties page_order: 4.2 page_type: reference -description: "This reference article describes the differences between Canvas entry properties and event properties, and when to use each property." +description: "This reference article describes the differences between context and event properties, and when to use each property." tool: Canvas --- -# Canvas entry properties and event properties +# Context 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.

For information about custom event properties in general, check out [Custom events properties]({{site.baseurl}}/user_guide/data_and_analytics/custom_data/custom_events/#custom-event-properties). +> This reference article covers information about `context` and `event_properties`, including when to use each property and the differences in behavior.

For information about custom event properties in general, check out [Custom events properties]({{site.baseurl}}/user_guide/data_and_analytics/custom_data/custom_events/#custom-event-properties). {% multi_lang_include alerts/important_alerts.md alert='context variable' %} -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 is `canvas_entry_properties` focuses on more than just events by also accessing the properties of entry payloads in API-triggered Canvases. +Context 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 `context`. Properties of events that occur as a user moves within a Canvas journey are known as `event_properties`. The key difference is `context` focuses on more than just events by also accessing the properties of entry payloads in API-triggered Canvases. -Refer to the following table for a summary of differences between Canvas entry properties and event properties. +Refer to the following table for a summary of differences between context and event properties. -| | Canvas Entry Properties | Event Properties +| | Context properties | Event properties | |----|----|----| -| **Liquid** | `canvas_entry_properties` | `event_properties` | +| **Liquid** | `context` | `event_properties` | | **Persistence** | Can be referenced by all [Message]({{site.baseurl}}/user_guide/engagement_tools/canvas/canvas_components/message_step/) steps for the duration of a Canvas built using Canvas. | - Can only be referenced once.
- Cannot be referenced by any subsequent Message steps. | -| **Canvas behavior** | Can reference `canvas_entry_properties` in any step of a Canvas. For post-launch behavior, refer to [Editing Canvases after launch]({{site.baseurl}}/user_guide/engagement_tools/canvas/managing_canvases/change_your_canvas_after_launch/#canvas-entry-properties). | - Can reference `event_properties` in the first Message step **after** an [Action Paths]({{site.baseurl}}/user_guide/engagement_tools/canvas/canvas_components/action_paths/) 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 components in between the Action Paths and Message steps. If one of these non-Message components is an Action Paths step, the user can go through that action path's Everyone Else path. | +| **Canvas behavior** | Can reference `context` in any step of a Canvas. For post-launch behavior, refer to [Editing Canvases after launch]({{site.baseurl}}/user_guide/engagement_tools/canvas/managing_canvases/change_your_canvas_after_launch/#canvas-entry-properties). | - Can reference `event_properties` in the first Message step **after** an [Action Paths]({{site.baseurl}}/user_guide/engagement_tools/canvas/canvas_components/action_paths/) 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 components in between the Action Paths and Message steps. If one of these non-Message components is an Action Paths step, the user can go through that action path's Everyone Else path. | {: .reset-td-br-1 .reset-td-br-2 .reset-td-br-3 role="presentation" } {% details Original Canvas editor details %} -You can no longer create or duplicate Canvases using the original editor. This article is available for reference when using Canvas entry properties and event properties for the previous Canvas workflow. +You can no longer create or duplicate Canvases using the original editor. Note that Canvas Context is not supported in the original Canvas editor, so this section is available for reference when using Canvas entry properties and event properties for the previous Canvas workflow. **Canvas entry properties:** - Must have persistent entry properties turned on. @@ -43,22 +43,22 @@ You can no longer create or duplicate Canvases using the original editor. This a ### Things to know -- Canvas entry properties are only available for reference in Liquid. To filter on the properties within the Canvas, use [event property segmentation]({{site.baseurl}}/user_guide/data/custom_data/custom_events/nested_objects/) instead. -- For in-app message channels, `canvas_entry_properties` can only be referenced in a Canvas. `event_properties` can't be used for in-app message channels. -- You can't use `event_properties` in the lead Message step. Instead, you must use `canvas_entry_properties` or add an Action Paths step with the corresponding event **before** the Message step that includes `event_properties`. +- Context is only available for reference in Liquid. To filter on the properties within the Canvas, use [event property segmentation]({{site.baseurl}}/user_guide/data/custom_data/custom_events/nested_objects/) instead. +- For in-app message channels, `context` can only be referenced in a Canvas. `event_properties` can't be used for in-app message channels. +- You can't use `event_properties` in the lead Message step. Instead, you must use `context` or add an Action Paths step with the corresponding event **before** the Message step that includes `event_properties`. - When an Action Path step contains a "Sent an SMS Inbound Message" or "Sent a WhatsApp Inbound Message" trigger, the subsequent Canvas steps can include an SMS or WhatsApp Liquid property. This mirrors how event properties work in Canvases. This way you can leverage your messages to save and reference first-party data on user profiles and conversational messaging. {% multi_lang_include alerts/tip_alerts.md alert='Reference properties from triggering event' %} -### Timestamps for event properties +### Timestamps for triggers -If you're using timestamps with a [datetime type]({{site.baseurl}}/user_guide/data/custom_data/custom_events/#custom-event-properties) from [trigger event properties]({{site.baseurl}}/user_guide/engagement_tools/canvas/create_a_canvas/canvas_entry_properties_event_properties) in action-based Canvases, timestamps are normalized to UTC. Some exceptions are detailed below. +If you're using timestamps with a [datetime type]({{site.baseurl}}/user_guide/data/custom_data/custom_events/#custom-event-properties) from events that trigger action-based Canvases, which are referenced using [context]({{site.baseurl}}/user_guide/engagement_tools/canvas/create_a_canvas/canvas_entry_properties_event_properties), timestamps are normalized to UTC. Given this behavior, Braze strongly recommends you use a Liquid timezone filter like the following example to guarantee that your messages are sent with your [preferred timezone]({{site.baseurl}}/user_guide/personalization_and_dynamic_content/liquid/filters/#time-zone-filter). {% raw %} ```liquid -{{canvas_entry_properties.${timestamp_property} | time_zone: "America/Los_Angeles" | date: "%H:%M" } +{{context.${timestamp_property} | time_zone: "America/Los_Angeles" | date: "%H:%M" } ``` {% endraw %} @@ -71,9 +71,9 @@ Given this behavior, Braze strongly recommends you use a Liquid timezone filter ![An Action Path step followed by a Delay step and Message step for users who have added an item to their wishlist, and a path for everyone else.]({% image_buster /assets/img_archive/canvas_entry_properties1.png %}){: style="float:right;max-width:30%;margin-left:15px;"} -To further understand the differences for `canvas_entry_properties` and `event_properties`, let's consider this scenario where users will enter an action-based Canvas if they perform the custom event "add item to wishlist". +To further understand the differences for `context` and `event_properties`, let's consider this scenario where users will enter an action-based Canvas if they perform the custom event "add item to wishlist". -The `canvas_entry_properties` are configured in the [Entry Schedule]({{site.baseurl}}/user_guide/engagement_tools/canvas/create_a_canvas/create_a_canvas#step-2b-set-your-canvas-entry-schedule) 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. +Context is configured in the [Entry Schedule]({{site.baseurl}}/user_guide/engagement_tools/canvas/create_a_canvas/create_a_canvas#step-2b-set-your-canvas-entry-schedule) step of creating a Canvas and will correspond to when a user enters a Canvas. Context can also be referenced in any Message step. In this Canvas, we have a user journey that begins with 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, they will experience a delay before receiving a message "New item in your wishlist!" from the Message step. 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 42792269ba0..d60be292fef 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 @@ -110,7 +110,7 @@ You can choose one of three ways in which users can enter your Canvas. {% endtab %} {% tab API-Triggered Delivery %} - With API-triggered delivery, users will enter your Canvas and begin receiving messages after they have been added using the [`/canvas/trigger/send` endpoint]({{site.baseurl}}/api/endpoints/messaging/send_messages/post_send_triggered_canvases/) via the API. In the dashboard, you can find an example cURL request that does this as well as assign optional [`canvas_entry_properties`]({{site.baseurl}}/api/endpoints/messaging/send_messages/post_send_triggered_canvases/) using the [Canvas entry properties object]({{site.baseurl}}/api/objects_filters/canvas_entry_properties_object/). + With API-triggered delivery, users will enter your Canvas and begin receiving messages after they have been added using the [`/canvas/trigger/send` endpoint]({{site.baseurl}}/api/endpoints/messaging/send_messages/post_send_triggered_canvases/) via the API. In the dashboard, you can find an example cURL request that does this as well as assign optional [`context`]({{site.baseurl}}/api/endpoints/messaging/send_messages/post_send_triggered_canvases/) using the [Canvas entry properties object]({{site.baseurl}}/api/objects_filters/context_object/). ![An example of API-triggered delivery with a Canvas ID and an example of a cURL request.]({% image_buster /assets/img_archive/Canvas_API_Triggered_Delivery.png %}) @@ -281,12 +281,12 @@ Select **Done** after you've finished configuring your Canvas component. {% tabs local %} {% tab Canvas Entry Properties %} -The `canvas_entry_properties` are configured in the Entry Schedule step of creating a Canvas and 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 can be up to 50 KB. +The [`context` object]({{site.baseurl}}/api/objects_filters/context_object) is configured in the **Entry Schedule** step of creating a Canvas and indicates 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 `context` object can be up to 50 KB. -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. +Use the following Liquid when referencing these properties created upon entering the Canvas: {% raw %} ``context.${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 this Liquid ``{{canvas_entry_properties.${product_name}}}``. +For example, consider the following request: `\"context\" : {\"product_name\" : \"shoes\", \"product_price\" : 79.99}`. You could add the word "shoes" to a message with this Liquid ``{{context.${product_name}}}``. {% endraw %} {% endtab %} 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 089a8eb3e1e..2a3acb84ee6 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 @@ -31,8 +31,8 @@ As a convenience, a summary of supported personalization tags are provided. For | Event Properties
(These are custom to your workspace.)| `{{event_properties.${your_custom_event_property}}}` | | Canvas Context Variables | `{{context}}` | | Custom Attributes
(These are custom to your workspace.) | `{{custom_attribute.${your_custom_attribute}}}` | -| API trigger Properties |`{{api_trigger_properties}}` | -| Canvas Entry Properties | `{{canvas_entry_properties.${property_name}}}` | +| API Trigger Properties |`{{api_trigger_properties}}` | +| Canvas Entry Properties | `{{context.${property_name}}}` | {: .reset-td-br-1 .reset-td-br-2 role="presentation" } {% endraw %} diff --git a/_includes/alerts/important_alerts.md b/_includes/alerts/important_alerts.md index daf303d24f1..a0a4c8543eb 100644 --- a/_includes/alerts/important_alerts.md +++ b/_includes/alerts/important_alerts.md @@ -69,7 +69,7 @@ The Shopify integration supports Shopify customer create and customer update web {% if include.alert == 'context variable' %} {% alert important %} -If you're participating in the Canvas Context early access, Canvas entry properties are part of Canvas context variables. This means `canvas_entry_properties` is now referenced as `context`. Each context variable includes a name, data type, and a value that can include Liquid. Currently, `canvas_entry_properties` are still backwards compatible. For more details, see [Context]({{site.baseurl}}/user_guide/engagement_tools/canvas/canvas_components/context/#how-it-works) and [Canvas entry properties object]({{site.baseurl}}/api/objects_filters/canvas_entry_properties_object/). +Canvas entry properties are part of Canvas context variables. This means `canvas_entry_properties` is referenced as `context`. Each `context` variable includes a name, data type, and a value that can include Liquid. Currently, `canvas_entry_properties` are backwards compatible. For more details, see [Context]({{site.baseurl}}/user_guide/engagement_tools/canvas/canvas_components/context/#how-it-works) and [Canvas context object]({{site.baseurl}}/api/objects_filters/context_object). {% endalert %} {% endif %} \ No newline at end of file diff --git a/_includes/canvas_entry_event_properties.md b/_includes/canvas_entry_event_properties.md index 618e1566177..167ec1bedd1 100644 --- a/_includes/canvas_entry_event_properties.md +++ b/_includes/canvas_entry_event_properties.md @@ -3,27 +3,27 @@ You can use Canvas entry properties and event properties in your Canvas user jou {% 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 entry properties]({{site.baseurl}}/api/objects_filters/context_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. {% alert note %} -For in-app message channels specifically, `canvas_entry_properties` can only be referenced in Canvas. +For in-app message channels specifically, `context` can only be referenced in Canvas. {% endalert %} -You can reference `canvas_entry_properties` in any Message step with this Liquid format: ``{% raw %} canvas_entry_properties.${property_name} {% endraw %}``. Note that the events must be custom events or purchase events to be used this way. +You can reference `context` in any Message step with this Liquid format: ``{% raw %} context.${property_name} {% endraw %}``. Note that the events must be custom events or purchase events to be used this way. #### Use case {% raw %} -Let's say a retail store, RetailApp, has the following request: `\"canvas_entry_properties\" : {\"product_name\" : \"shoes\", \"product_price\" : 79.99}`. +Let's say a retail store, RetailApp, has the following request: `\"context\" : {\"product_name\" : \"shoes\", \"product_price\" : 79.99}`. -RetailApp can pull the product name (shoes) into a message with this Liquid: `{{canvas_entry_properties.${product_name}}}`. +RetailApp can pull the product name (shoes) into a message with this Liquid: `{{context.${product_name}}}`. {% endraw %} RetailApp can also trigger specific messages to send for different `product_name` properties in a Canvas that targets users after they've triggered a purchase event. For example, they can send different messages to users who purchased shoes and users who purchased something else by adding the following Liquid into a Message step. {% raw %} ```markdown -{% if {{canvas_entry_properties.${product_name}}} == "shoes" %} +{% if {{context.${product_name}}} == "shoes" %} Your order is set to ship soon. While you're waiting, why not step up your shoe care routine with a little upgrade? Check out our selection of shoelaces and premium shoe polish. {% else %} Your order will be on its way shortly. If you missed something, you have until the end of the week to add more items to your cart for the same discounts. @@ -44,7 +44,7 @@ You can no longer create or duplicate Canvases using the original editor. This s Event properties refer to the properties you set for custom events and purchases. These `event_properties` can be used in campaigns with action-based delivery and Canvases. {% alert important %} -You can't use `event_properties` in the first Message step of your Canvas. Instead, you must use `canvas_entry_properties` or add an Action Paths step with the corresponding event **before** the Message step that includes `event_properties`. +You can't use `event_properties` in the first Message step of your Canvas. Instead, you must use `context` or add an Action Paths step with the corresponding event **before** the Message step that includes `event_properties`. {% endalert %} In Canvas, custom event and purchase event properties can be used in Liquid in any Message step that follows an Action Paths step. Make sure to use {% raw %} ``{{event_properties.${property_name}}}``{% endraw %} if you're referencing these event properties. These events must be custom events or purchase events to be used this way in the Message component. diff --git a/assets/js/broken_redirect_list.js b/assets/js/broken_redirect_list.js index 0cc53a9f7df..84cfaa06966 100644 --- a/assets/js/broken_redirect_list.js +++ b/assets/js/broken_redirect_list.js @@ -3217,4 +3217,6 @@ validurls['/docs/hidden/archive_docs/windows_universal/analytics/setting_custom_ validurls['/docs/user_guide/message_building_by_channel/banners/creating_campaigns'] = '/docs/user_guide/message_building_by_channel/banners/create'; +validurls['/docs/api/objects_filters/canvas_entry_properties_object/'] = '/docs//api/objects_filters/context_object/'; + // validurls['OLD'] = 'NEW';