Get Event Data (getEventRecords method)

Overview

The data stored within the Contact Activities 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"
    }
  ]

{$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)

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'])}

Render the data in a message

After the data is available with the getEventRecords method, you can render the data in the message.

Loop 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, you can learn about getting JSON feeds.