Track an event

The track method can record any action performed by the users, along with any properties that describe the action. Each action is translated into an event.

Each event usually has a name (e.g. “Sign Up Completed”) and a bunch of properties.

How to make a track call

Calling track with one of our libraries is really easy.

Here’s the payload of a typical track call with most common fields removed:

{
  "type": "track",
  "event": "Sign Up Completed",
  "properties": {
    "plan": "Pro Annual",
    "billingCycle" : "monthly"
  }
}

And here’s the corresponding Javascript event that would generate the above payload:

plainflow.track("Sign Up Completed", {
    plan: "Pro Annual",
    billingCycle : "monthly"
});

Track fields

Beyond the common fields, thetrackcall has the following fields:

FieldTypeDescription
event requiredStringName of the action that a user has performed. See the Event field docs for more detail.
properties optionalObjectFree-form dictionary of properties of the event, like revenue. See the Properties docs for a list of reserved property names.

Identities

The User ID is a unique identifier for the user performing the actions. Check out the User ID docs for more detail.

The Anonymous ID can be any pseudo-unique identifier, for cases where you don’t know who the user is, but you still want to tie them to an event. Check out the Anonymous ID docs for more detail.

Note: In our browser and mobile libraries a User ID is automatically addedfrom the state stored by a previous identify call, so you do not need to add it yourself. They will also automatically handle Anonymous ID’s under the covers.

Event

Every track call records a single user action. We call these “events”. We recommend that you make your event names human-readable, so that everyone on your team (even you, after all that caffeine) can know what they mean instantly.

Do not use nondescript names like Event 12 or PflcartA. Instead, use unique but recognizable names like Video Recorded and Order Completed.

We recommend event names built from a noun and past-tense verb. For more information about best practices in event naming, check out the best practices for naming conventions for clean data.

We have standardized a series of reserved event names that have special semantic meaning. We map these events to tools that support them whenever possible. See the Semantic Events docs for more detail.

Properties

Properties are extra pieces of information you can tie to events you track. They can be anything that will be useful while analyzing the events later. We recommend sending properties whenever possible because they give you a more complete picture of what your users are doing.

We’ve reserved some properties that have semantic meanings, and we handle them in special ways. For example, we always expect revenue to be a dollar amount that we send to tools that handle revenue tracking.

You must only use reserved properties for their intended meaning.

The following is all the reserved properties we have standardized that apply to all events. Check out the Semantic Events docs for properties specific to individual reserved events.

PropertyTypeDescription
revenueNumberAmount of revenue an event resulted in. This should be a decimal value, so a shirt worth $19.99 would result in a revenue of 19.99.
currencyStringCurrency of the revenue an event resulted in. This should be sent in the ISO 4127 format. If this is not set, we assume the revenue to be in US dollars.
valueNumberAn abstract “value” to associate with an event. This is typically used in situations where the event doesn’t generate real-dollar revenue, but has an intrinsic value to a marketing team, like newsletter signups.

Example

Here’s a complete example of a track call:

{
  "anonymousId": "3c3296da-093a-432e-997f-5201e8a2a6c4",
  "context": {
    "library": {
      "name": "plainflow.js",
      "version": "2.11.0-p99"
    },
    "page": {
      "path": "/blog/",
      "referrer": "",
      "search": "",
      "title": "PlainFlow Blog | About SaaS marketing, product analytics, and automation.",
      "url": "https://www.plainflow.com/blog/"
    },
    "userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_11_0) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/46.0.2490.86 Safari/537.36",
    "ip": "108.0.78.21"
  },
  "event": "Newsletter Subscribed",
  "messageId": "pfl-f7e73490d51d46359800da8dcf2b5043",
  "properties": {
    "newsletterId": "pf-dw143"
  },
  "receivedAt": "2017-1-1T9:33:12.943Z",
  "sentAt": "2017-1-1T9:33:11.543Z",
  "timestamp": "2017-1-1T9:33:12.543Z",
  "type": "track",
  "userId": "2rgtr24fwt",
  "originalTimestamp": "2017-1-1T9:33:12.543Z"
}

Not using Plainflow yet? Get your free account here. 👈