Events

Events represent an action performed at a specific point in time on behalf of an individual Profile, and are the primary method of sending data to Firstparty. Events describe who, how, and when an activity happened in your business.

The most common event, collected automatically when Firstparty.js is installed on your website, is a "Page Viewed" Event. This fundamental metric informs you of traffic. Adding custom Events will give you much more feedback on the usage of your website or product. Common event examples on a website are "Page Viewed", "Form Submitted", and "Button Clicked".

Events naturally happen on every website, web application, mobile application, and software product. If you are not collecting Events, they still happen, but you will not be informed with data on the usage patterns around that Event. Tracking Events can dramatically enhance your fact-based decision making. Will you deprioritize work on a feature that is rarely used? Should you focus on a changing a page that has a high bounce rate, but is your most popular page? Do your users' navigation patterns change if you change the text of a label? These questions can be answered with the help of collecting and later reporting on Events.

As the property owner, the level of detail you collect is up to you to decide. Only you know what's important to your business, and what actions your users will take. As a general starting point, you'll want to Track Events that show user intent and affect state change. Abandoning a populated shopping cart can be more important than initiating a customer service ticket, but both are important. Without Event collecting, understanding your user behavior is much more difficult if not impossible.

To submit a custom event, you'll simply POST a bit of JSON to your Firstparty account. The minimum required data needed is the name of your Event, and a Write Key. The Write key is your public key that ties your Source in Firstparty to the Event you are sending in. The minimum JSON looks like this.

{
    "event": "Newsletter Signup",
    "write_key": "_______"
}

Write Keys are created for you when you create a new Source. You may have many sources in each Workspace to collect. Example sources might be your www Marketing Page, a Help Desk application, a Web Application, an IoS Application and an Android Application. This example Workspace can collect events from five different sources.

While the Event name and write key are the two required key value pairs, there are also optional data you can include with your Event. These are Properties and Context.

Properties on an Event are immutable after all Rules have run immediately after collecting the Event. Properties is a simple Key/Value store with any arbitrary data that is worth collecting for this user. This could be an account number, first+middle+last names, email addresses, or any other supporting information available that may make understanding and acting on these events in the future. Here is a sample JSON payload for "Agent Assigned" that contains supporting Properties.

{
    "event": "Agent Assigned",
    "write_key": "_______",
    "properties": 
    {
        "email": "sally@example.com",
        "display_name": "Sally",
        "initiated_from": "Chat Widget",
        "subject":"Help with my billing"
    }
}

This payload enhances the Event with additional Properties known at the time the Event occurred.

Remember an Event has to be posted with a Write Key. This identifies which Source the Event is happening in, and will be written to. An Event can only have one Source, and later you'll be able to query Events by suppling a SourceId. This will return your filtered Events that happened inside that Source.

When creating Events, you'll also need to supply an Event Name. This can be any UTF-8 String name you desire but having a standard will help you later when creating filters. Firstparty recommends the following naming Guidelines for Event Names.

• Event names should be combination of "Noun" plus "Past tense Verb"
• Title Case each word
• A-Z only, no other special characters
• Use a single space between each word

"Page Viewed" is the correct format, where the following would be considered bad practice.

• "form submitted": Not correctly title cased
• "Button clicked": Not correctyl title cased
• "Product 126": Using numbers in Event names is a bad idea
• "Cart-Abandoned": Using special characters in Event names is a bad idea

You may trigger as many Events as you'd like - there are no rate limits or constraints.