Logging Events to Preact

Authentication is done over HTTPS using Basic Auth with your API keys.

Your Project Code will be your username and your Project Secret will be the password. Your API keys are located on the API Settings page of your Preact dashboard. All API calls must be made over HTTPS otherwise they will fail.

The current stable API version is v2.

As we work on new features, we try very hard to make things backwards compatible so that we minimize change for you. In the event we make breaking changes, we will bump the version number when it's released.

Events should be named with simple verb/object pairs and must not include any whitespace.

We find that there are a fairly small number of distinct events that practically every app will need to use. You should set these up first, and then you can get fancy and add more custom events. Some of these will also have special meaning in our analysis:

Tenses
Event names should generally be past tense: uploaded, deleted, created, registered, logged-in, viewed. Event item names (if provided) should be singular: image, profile, media, person. We'll convert singular items to plural when necessary for readability.

For each event logged, you must pass an event and a person parameter with nested values.

These are both required in order to accept the event and they should be sent as form parameters in an HTTP POST request to the /api/v2/events endpoint (not JSON objects in the request body).

The minimum required params to track an event are as follows:

  
# for the person
person[email] = "cgooley@preact.io"   # email of the user
person[name] = "Christopher Gooley"   # name of the user
person[created_at] = 1367259292.74    # unix timestamp (in secs or ms) of user registration

# for the event
event[name] = "viewed:item"           # name of the event
event[target_id] = "sku_1234"         # id of the target of the event

So a curl request to record the above event would look like this:

  
curl -s -k https://api.preact.io/api/v2/events \
  --user 'project_code:project_secret' \
  -F person[email]='cgooley@preact.io'\
  -F person[name]='Christopher Gooley' \
  -F person[created_at]=1367259292.74 \
  -F event[name]='viewed:item'\
  -F event[target_id]='sku_1234'

The same event, logged from Ruby would look similar. Note that Ruby hashes are converted to form params by the HTTP library, not passed as JSON. Using the Preact gem, the first parameter is the Person hash and the second parameter is the Event hash.

  
Preact.log_event(
  { :email       => "gooley@preact.io",
    :name        => "Christopher Gooley",
    :created_at  => 1367259292.74
  }, {
    :name        => "viewed:item",
    :target_id   => "sku_1234"
  })

Preact has a number of additional parameters that should be passed when appropriate for the event.

Some of them are treated as special properties and Preact will do interesting things with them. For instance, for any event that represents revenue (a checkout, succesful billing, etc) you must pass the revenue parameter so that Preact can build up the revenue-to-date value for each person.

Person

  
# REQUIRED root-level person parameters
person[email] = "cgooley@preact.io"       # email address (will be the unique id)
person[created_at] = 1367259292.74        # unix timestamp (in secs or ms)
person[name] = "Christopher Gooley"       # full display name

# optional
person[uid] = "cgooley"                   # your internal user id for this person
person[twitter_id] = "gooley"             # twitter handle (without the @)
person[facebook_id] = "12805383"          # facebook id
person[stripe_id] = "cus_1123f3f5"        # stripe customer id

# nested special "properties" of the person
person[properties][subscription_level_name] = "Platinum"
person[properties][subscription_level] = 5
person[properties][is_paying] = true

Custom Person Properties can include arbitrary additional "properties" for any person. These are additive and will build out the profile of the person over time.

  
# nested custom "properties" of the person
person[properties][favorite_color] = "red"
person[properties][birthday] = "1984-02-03"

Event

  
# REQUIRED root-level event parameters
event[name] = "purchased:item"

# optional
event[timestamp] = 1367259292.74        # unix timestamp (in secs or ms)
event[revenue] = 995                    # revenue in cents (995 = $9.95 USD)
event[note] = "Turnstone Desk"          # human-readable description
event[target_id] = "sku_2345"           # your id for the target of this action
event[link_url] = "http://blah/2345"    # link to the target of this action
event[thumb_url] = "http://blah/23345.jpg" # link to a thumb of the target

# REQUIRED for Preact B2B account tracking
event[account][id] = "12345"            # your internal account id
event[account][name] = "Bitium"         # name of the account

# certain event extras have meaning and are populated by the offical JS library
# you may pass these if you are using server-side logging and have them handy
event[extras][_ua] = "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_8_3) AppleWebKit/537.31 (KHTML, like Gecko) Chrome/26.0.1410.65 Safari/537.31"
event[extras][_page_title] = "Turnstone :: Tables"
event[extras][_ip] = "216.24.174.102"
event[extras][_referer] = "http://google.com?q=awesome+desks"
event[extras][_url] = "http://myturnstone.com/products/tables"

Custom Event Extras can include arbitrary additional "extras" for any event. These will be available within the sidebar view for review. Good ideas for extras would be additional information useful to support or account managers (such as error messages, or other extra information).

  
# nested custom "extras" for the event
event[extras][category] = "desks"
event[extras][color] = "titanium"

If you are a Preact B2B customer, you must also log the account id and name for each event.

This will activate Account Health monitoring and provide additional analysis at the account level. Because many systems will allow a single user account to interact with multiple "accounts", you will pass account info at the Event level, rather than the Person level. This allows us to track account health while separating distinct behaviors between these multi-account users.

You can add account info by simply adding event[account][id] and event[account][name] parameters to the existing event object. For instance, if you are using a direct HTTP POST via curl or your language's built-in library, you would do something like this:

  
curl -s -k https://api.preact.io/api/v2/events \
  --user 'project_code:project_secret' \
  -F person[email]='cgooley@preact.io'\
  -F person[name]='Christopher Gooley' \
  -F person[created_at]=1367259292.74 \
  -F event[name]='viewed:item'\
  -F event[target_id]='sku_1234'\
  -F event[account][id]='828492'\
  -F event[account][name]='Bitium'\

By adding those two final field parameters, Preact will associate this event with that account (creating a new account if necessary) and will properly aggregate analysis.

Note: If your users sometimes perform actions outside the context of an account (such as the initial login or a password reset) you can simply omit the account parameters and we will only attach those actions to the person directly.

Ok, so let's look at how you should be logging... We'll run through an example user lifecycle in Ruby to explain what and how to log the first few events:

API Setup

Before you log anything, make sure you have your API configured. See the detailed docs from one of our API libraries for more suggestions on how to do this.

User Registration

A user registers for the first time on your site. uid should be set to the username or user_id that you're using in your system. In Ruby, this will be done in the User.to_preact method you created during Ruby API setup. So all you need to do is log the "registered" event for the current user.

  
Preact.log_event(@current_user, 'registered')

User Upgraded

A user upgrades from one account level to another.

If you're including the user's subscription level in the User.to_preact method, it will automatically update Preact with the new info when you log the event.

  
Preact.log_event(@current_user, 'upgraded')

User Purchased Item

A user purchases a product from your site. You should include the amount of the purchase as revenue on the event, and this amount should be an integer number of cents. Note that the second parameter of Preact.log_event can be a String (as above) or a Hash which has additional parameters for the event.

  
Preact.log_event(@current_user, {
  :name => "purchased:item",
  :note => "Timbuk2 Classic Messenger Bag",
  :revenue => 7999, # $79.99 in cents
  :extras => {
    :category => "bags",
    :color => "black"
  }
})

Official Client Logging Libraries:
Ruby
Javascript
PHP
Objective-C
C#
Python

We have several helper libraries that the user community has helped us build. We try to keep these as up to date as possible with the stable API version. If you find that a library does not provide everything you need, please feel free to fork the repo and add changes as needed. We are happy to accept pull requests on the changes if it helps push the library forward towards being API feature complete.

You can also hit our API end-point with basic http calls. If we don't have an official library for your language, please let us know. If you build one we'll link to your Github repo.

  
curl -s -k https://api.preact.io/api/v2/events \
  --user 'project_code:project_secret' \
  -F person[name]='Christopher Gooley' \
  -F person[email]='gooley@preact.io'\
  -F person[uid]='cgooley'\
  -F person[created_at]=1367259292\
  -F event[name]='registered'

  
curl -s -k https://api/react.io/api/v2/events \
  --user 'project_code:project_secret' \
  -F person[name]='Christopher Gooley' \
  -F person[email]='gooley@preact.io'\
  -F person[uid]='cgooley'\
  -F person[created_at]=1367259292\
  -F person[properties][is_paying]='1'\
  -F person[properties][subscription_level]='2'\
  -F person[properties][subscription_level_name]='Pro'\
  -F event[name]='upgraded'

  
curl -s -k https://api.preact.io/api/v2/events \
  --user 'project_code:project_secret' \
  -F person[name]='Christopher Gooley' \
  -F person[email]='gooley@preact.io'\
  -F person[uid]='cgooley'\
  -F person[created_at]=1367259292\
  -F event[name]='purchased:item' \
  -F event[note]='Georgia Tech Hoodie' \
  -F event[revenue]=3995 \
  -F event[extras][color]='blue' \
  -F event[extras][size]='L'