API

Live examples below!
Provide your project code and API secret and all the
curl
commands will be executable:

API Overview

The
Preact Events API
is used to log events for a given
person
or
account.

Event URL:
https://api.preact.io/api/v2/events

The
Preact Background Signals API
records counters, scores, and other quantities associated with a
person
or
account.

Background Signal URL:
https://api.preact.io/api/v2/metrics

Bulk Background Signal URL:
https://api.preact.io/api/v2/metrics/bulk

Authentication

Authentication is done over HTTPS using
Basic Auth
with your API credentials. Your
Project Code
will be your username and your
API 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.

Versioning

The current stable API version is v2.

As we work on new features, we try to maintain backwards compatibility. In the event we make breaking changes, we will bump the API version.

Logging Basics

In general, a Person, Account and Event are required for each event log entry. You can send your
POST request
via
Form
or
JSON
format to our
/api/v2/events
endpoint.

Parameter Name

Type

Description

Required Objects

person

object

The person object contains the personal information of the user. For example, the user's name, email and the unix timestamp of the account creation date. See the
Person Object
section.

event

object

The event object contains information about the event being logged. For example, the event name, note, associated revenue, timestamp, etc. See the
Event Object
section.

account

object

The account in which this peron's event took place. See the
Account Object
section.

If you're submitting via
JSON
make sure to include proper header information. For instance, with
curl:

Additional Parameters

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, on any event that represents revenue (a checkout, successful billing, etc) you must pass the
revenue
parameter so that Preact can build up the revenue-to-date value for each person.

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).

Note:
If you're using the Javascript API library, the extras field preceded by an '_' are automatically generated for you. However, if you're using any of the server side API libraries, you'll have to provide this data. Specifically, if you're looking to have geolocation information on your users, please populate the '_ip' field.

Events (Bulk)

Note:
There are two options for bulk loading data. Option 1 lends itself to less denormalization, and Option 2 is an easy bulk method if you've already done the denormalization, and it also mirrors the standard events API.
For both options, it should be noted that the account object containing the account 'id' and 'name' must still be embedded within each event object in the events array. The Unix timestamp property of each event object is required to be passed.

All of these samples assume you've configured the API library with your Project Code and API Secret. They also assume you are using the Preact gem. As such, the first parameter is the Person hash and the second parameter is the Event hash in the
log_event
function.

For more information about integrating with Preact using Ruby, see the
Ruby API Library
documentation.

All of these samples assume you've configured the API library with your Project Code and API Secret. Using the Javascript API Library, you only have to set the person data once, but we'll set it in each example below for completeness.

For more information about integrating with Preact using Javascript, see the
Javascript API Library
documentation.

API Libraries

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.