Timeline Attribute

[#1]

This article describes the timeline attribute and how to use it.

• How it Works
• Capture Attribute Data
• Expiration of Entries
• Timeline Enrichments
• Update Timeline
• Set Expiration for Timeline Events

How it Works

Before you begin, familiarize yourself with the following:

• Using Attributes
• Using Enrichments

The timeline attribute records a list of events over a specified time period. A captured event generates an entry in the timeline that contains captured attribute values and a timestamp. The timestamp can be the time of the event or a date/time provided by another attribute. Timestamps are recorded in Unix/Epoch format.

Capture Attribute Data

In addition to the timestamp of the event, you can also capture the value of one or more attributes when the event occurs. Captured attribute values provide more information about the event when it occurred. Numbers and tallies are the only useful attribute types to capture because only those attribute types can be aggregated using enrichments.

For example, to track the order total for each purchase you would capture the attribute order_total in a purchase timeline.

Expiration of Entries

Entries in a timeline can be set to expire after a set number of days. This expiration only applies to entries within the timeline and not the timeline attribute itself. The expiration period is evaluated at the start of each visit. If an entry is older than the expiration time, it is removed from the timeline.

Timelines work well with numbers because numeric entries are easily used to create a "Rolling Sum" or a "Rolling Average" value based on the timeline entries.

The timeline attribute is available in the following scopes: Visit and Visitor.

Timeline Enrichments

Update Timeline

Use this enrichment to record an entry in a timeline. To add this enrichment, click Create an Entry and select Update Timeline.

Choose one of the following options for recording the timestamp of the entry:

• Time of event received (default)
  The timestamp of the entry is set automatically when the event occurs.
• Based on date
  The timestamp of the entry is set to the value of another attribute. If you choose a string attribute, you must also use the date formatter to create a date/time pattern that matches the expected value.

To capture attribute values in the entry, select an attribute from the drop-down list and click Add Attribute. The added attribute is displayed as a captured attribute. Repeat this step for each attribute to capture in the entry.

Example

Attribute Name: Orders Last 60 days
Captured Attributes: order_subtotal and order_total
Example JSON Data:

"Orders Last 60 Days" : [
  {
    "timestamp" : 1576862494000,
    "snapshot" : {
      "order_total" : 44.00,
      "order_subtotal" : 38.00
    }
  },
  {
    "timestamp" : 1577640094000,
    "snapshot" : {
      "order_total" : 100.00,
      "order_subtotal" : 95.00
    }
  },
  {
    "timestamp" : 1578849694000,
    "snapshot": {
      "order_total" : 60.00,
      "order_subtotal" : 59.00
    }
  }
]

Set Expiration for Timeline Events

Use this enrichment to determine when an entry should be removed from the timeline based on the number of days since it was recorded. Each entry that is older than the expiration setting is removed from the timeline automatically. The expiration of timeline entries is evaluated at the beginning of a visit.

The expiration does not apply to the timeline itself, only to the entries within it.