The data stored within the contactactivities collection can be referenced and used within any message body.
Our Example
For our example we'll be using hypothetical event data. In order to test in your system you will need to add your own event data via the API. Learn more about event data.
Using the tabs below you can view the HTML and Smarty used in the message, the event data being referenced (in JSON format) and the rendered output that will display when a message is sent or previewed.
{$browseditems=$utils->getEventRecords("browse")} <strong>Items You Browsed</strong><br><br>
{foreach $browseditems as $item}
{$item.properties.title|capitalize}<br>
${$item.properties.price} <br>
{$item.properties.description|capitalize} <br>
{$item.properties.url} <br><br>
{/foreach}
[ { "cID": "58d2fc99ac0c8117814d4e78", "_id": "59014a9608ab4e356ec0706a", "properties": { "title": "khaki shirt" "url": "http://example.com/shirt", "price": 9.99, "description": "a really cool khaki shirt", }, "action": "browse", "time": "2017-04-27T01:34:13+0000", "email": "fredgarvin@gmail.com" }, { "cID": "58d2fc99ac0c8117814d4e78", "_id": "59014a9608ab4e356ec0706a", "properties": { "title": "khaki pants" "url": "http://example.com/pants", "price": 19.99, "description": "awesome khaki pants", }, "action": "browse", "time": "2017-04-27T01:37:13+0000", "email": "fredgarvin@gmail.com" }, { "cID": "58d2fc99ac0c8117814d4e78", "_id": "59014a9608ab4e356ec0706a", "properties": { "title": "suede shoes" "url": "http://example.com/shoes", "price": 29.99, "description": "sweet suede shoes", }, "action": "browse", "time": "2017-04-27T01:40:13+0000", "email": "fredgarvin@gmail.com" } ]
Khaki Shirt
$9.99
A Really Cool Khaki Shirt
http://example.com/shirts
Khaki Pants
$19.99
Awesome Khaki Pants
http://example.com/pants
Suede Shoes
$29.99
Sweet Suede Shoes
http://example.com/shoes
{$browseditems=$utils->getEventRecords("browse")} {$utils->jsonPrettyPrint($browseditems)}
The getEventRecords Method
In order to access event data within a message, use the getEventRecords method, which is a custom extension of Smarty provided by Cordial.
The getEventRecords method has 5 parameters: event name, newer than, properties, limit and sort. They must be written in this order and separated by commas. Event name is required, all others are optional.
getEventRecords($eventName, $newerThan, $properties, $limit, $sort)
Param | Description | Required | Expected | Default |
---|---|---|---|---|
eventName | The name of the event stored in the contactactivities collection. | Required | Valid event/contactactivity name | N/A |
newerThan | Filters the event records returned based on the timestamp of the events. | Optional | Date, null | null |
properties | Filters the event records returned based on a matching property value(s). | Optional | Array of property key value pairs | [] |
limit | Maximum number of records returned. | Optional | Integer, null | 25 |
sort | Sort order of the event records returned. | Optional | Array of sort instructions | [] |
How to set the eventName
All event data is stored in the contactactivities collection and includes standard message events (sends, opens, clicks, etc.), custom events associated with website behavior (browse) and external events captured by IoT devices (opened door, triggered alarm, etc).
In order to make event data available to render in a message, you must specify the event, referenced by the "eventName". You can access event names:
- Via the UI by navigating to Analytics › Event Data Reports
- Via the API by using the GET <path>/contactactivities call. View the interactive API documentation.
Here is an example:
{$browseditems=$utils->getEventRecords("browse")}
In the example above, a variable "browseditems" is assigned to the resulting data set returned from the contactactivities collection with the event name of "browse". The getEvents method will get the data from "browse" for each message that is rendered per contact.
How to set newerThan
Using the "newerThan" parameter, you can filter the results based on a date. Results will return all events after the date specified.
Return records filtered by a set date.
Example:
{$browseditems=$utils->getEventRecords("browse","2018-08-19T21:36:13+0000")}
Return records newer than 1 day in the past.
Example:
{$browseditems=$utils->getEventRecords("browse","-1 day"|date_format:"Y-m-d\TH:i:sO")}
Return records newer than the last send of an Automation.
Using the the Smarty utility, lastSendTimestamp
, you are able to set a variable for the last send date of an Automation and populate the newerThan
parameter.
last send: {$last_sent_date = $utils->lastSendTimestamp('automation_key')} {$last_sent_date|date_format:"Y-m-d\TH:i:sO"} {$browseditems=$utils->getEventRecords("browse",$last_sent_date|date_format:"Y-m-d\TH:i:sO")}
How to set properties
In some cases, you may want to get specific records from the event data collection. You can achieve this by adding property filters.
Return records filtered by a specified value.
["key"=>"value"]
Example:
{$browseditems=$utils->getEventRecords("browse",null,["category"=>"shirts"])}
Return records filtered by multiple specified values.
["key"=>"value", "key2"=>"value2"]
Example:
{$browseditems=$utils->getEventRecords("browse",null,["category"=>"shoes,"brand"=>"nike"])}
How to set the limit
Use the limit filter to limit the amount of records returned.
{$browseditems=$utils->getEventRecords("browse",null,[],5)}
How to sort the data
Sort results by timestamp in ascending order.
{$browseditems=$utils->getEventRecords("browse",null,[],null,['column'=>'ats','direction'=>'ASC'])}
Sort results by timestamp in descending order.
{$browseditems=$utils->getEventRecords("browse",null,[],null,['column'=>'ats','direction'=>'DESC'])}
Rendering the data in a message
After the data is available with the getEventRecords method, you can render the data in the message.
Looping through data with {foreach}
A {foreach} statement is the most common way to loop through the data array and render the results in a message.
Example:
{$browseditems=$utils->getEventRecords("browse")}
{foreach $browseditems as $item}
{$item.properties.title|capitalize}<br>
${$item.properties.price} <br>
{$item.properties.description|capitalize} <br>
{$item.properties.url} <br><br>
{/foreach}
Learn more about using the {foreach} statement.
Display unique browse events (deduping)
A site visitor may view the same item on a website multiple times which will generate duplicate browse events. We can use Smarty to display only the unique events using the following code:
{$browseditems=$utils->getEventRecords("browse")} {foreach $browseditems as $item} {$unique_products[$item.properties.productID] = [ 'productID' => $item.properties.productID, 'title' => $item.properties.title, 'price' => $item.properties.price, 'description' => $item.properties.description, 'url' => $item.properties.url ]} {/foreach} {foreach $unique_products as $unique_product} Title: {$unique_product.title}<br> Price: {$unique_product.price}<br> Description: {$unique_product.description}<br> URL: {$unique_product.url}<br><br> {/foreach}
Referencing an index of the array
You also have to option to target the "nth" item within an array using it's index. For example, if you only wanted to render the first item of the browse array you would write:
{$browseditems=$utils->getEventRecords("browse")}
{$browseditems[0].properties.title}<br>
${$browseditems[0].properties.price} <br>
{$browseditems[0].properties.category} <br>
{$browseditems[0].url} <br><br>
This example will look in the 1st item of the browse array and render the desired values.
In the next article learn about getting JSON feeds.
Comments
0 comments
Please sign in to leave a comment.