Liquid Documentation

Data Collection API Edit

Liquid offers a REST API for sending data to Liquid servers. This data is tipically sent from the official iOS, Android and Windows SDKs, but as an open API it can also be used directly from backend or other type of clients.

This REST API has two endpoints available and authentication is mandatory, in a per-app basis, by App key for the Data Collection API, e.g.: vE_S7CluDfNVPx_UgWCpn-5CPszRCOjC. This key is available in your app settings on Liquid dashboard.

The available endpoints are:

POST	Resource info
/data_points	Used to create a new data point. The structure of a data point is described here.
/aliases	Used to create a new user alias, tipically called when a user changes its unique ID, e.g. when switching from an anonymous to an identified state.

POST /data_points Edit

This endpoint is used to create a data point. The only request format accepted is JSON.

Session handling is automatically managed by Liquid backend, and not at the generation of a data point. Two data points are considered on the same session if they’re timestamps are close to each other in less than the maximum time between two events after which a new session is inferred (e.g. if a data point is not within 5 minutes or less from an already existent data point it will generate a new session, otherwise it will be added to the session of that already existent data point). You may to change this definition by setting this value in your App Settings.

It is very important to understand the structure of a data point before creating them.

Headers

Header	Example	Notes
Authorization	`Token vE_S7CluDfNVPx_UgWCpn-5CPszRCOjC`	The app API key
Accept	`application/json`	Use `application/vnd.lqd.v1+json` if you want to stick to a specific API version.
Content-Type	`application/json`

Resource URL

https://collect.lqd.io/data_points

Parameters

We highly recommend a full understanding of the structure of a data point before generating new data points. A full explanation of each of those parameters and its nested attributes is explained below.

timestamp

String (ISO8601)

The date and time of the moment the event happens.

Example:

"2015-01-07T17:28:05.270+00:00"

user

Hash/Dictionary

Check data point structure for full info.

Example:

{ "unique_id": "02318f2cdd156d78fd4431", "identified": true, "name": "John Doe", "age": 30 }

device

Hash/Dictionary

Check data point structure for full info.

Example:

{ "unique_id": "F348DE-31E0-4ACF-B2B0-5065FF8FCFB0", "model": "iPad2,5", vendor: "Apple" }

event

Hash/Dictionary

Check data point structure for full info.

Example:

{ "name": "Buy Product", "product_id": 3293 }

Example request

POST

https://collect.lqd.io/data_points

{
  "timestamp": "2015-01-07T17:28:58.270+00:00",
  "user": {
    "unique_id": "02318f2cdd156d78fd4431",
    "identified": true,
    "first_name": "John",
    "last_name": "Doe",
    "age": 30,
    "gender": "male"
  },
  "device": {
    "unique_id": "78F348DE-31E0-4ACF-B2B0-5065FF8FCFB0",
    "app_bundle": "io.lqd.LiquidDemo",
    "app_name": "Demo App",
    "app_version": "1.0",
    "release_version": "1.0.1",
    "carrier": "Vodafone",
    "internet_connectivity": "Cellular",
    "sdk_version": "1.0.0",
    "model": "iPad2,5",
    "name": "Username's iPad",
    "vendor": "Apple",
    "push_token": "5862036a860c6b6aada50117caea626d20ed3187d6981c8190cfa6199526ce30",
    "screen_size": "768x1024",
    "system_version": "7.0.1",
    "system_language": "en_GB",
    "locale": "en_GB"
  },
  "event": {
    "name": "Buy Product",
    "product_id": 3293,
    "price": 17.24
  }
}

Response

Code	Status	Content	Scenario
200	OK	n/a	Data point is valid and was enqueued for processing.
400	Bad Request	n/a	Content is not a valid JSON.
401	Unauthorized	n/a	Authorization failed (invalid API token).
422	Unprocessable Entity	Production app: n/a Development app: error message (see below)	Data point is invalid.

Error messages for Unprocessable Entity (422) have the following structure:

{
  "error": "Error Message",
  "details": "A string explaining the error in detail"
}

POST /aliases Edit

Creates a user alias, typically to alias an anonymous user to an identified user. Aliasing a user to another one merges all user’s history (profile and behaviour information) from the “old” user (typically the anonymous one) to the “new” user (typically the identified one). This means that you’ll see only one user on Liquid dashboard, independently of the unique ID you’re using on the data point’s user.unique_id.

Furthermore, after the creation of an alias, all data points received from the old (aliased) user will be associated to the new one.

Important note

This process is not reversible, i.e. after creating an alias it is not possible to destroy it.

Headers

Header	Example	Notes
Authorization	`Token vE_S7CluDfNVPx_UgWCpn-5CPszRCOjC`	The app API key, available at the App settings on Liquid dashboard.
Accept	`application/json`	Optionally, use `application/vnd.lqd.v1+json` if you want to stick to a specific API version.
Content-Type	`application/json`

Resource URL

https://collect.lqd.io/alias

Parameters

Both parameters of this endpoint are User unique IDs. The unique_id_alias (the old user) is the user ID of the user that will be an alias to the unique_id (the new user). The typical situation is the example below, where 02318f2cdd156d78fd4431 signs up and “receives” all the analytics data from the period before the sign-up (while anonymous, with the identifier F348DE-31E0-4ACF-B2B0-5065FF8FCFB0).

unique_id

String

The unique ID of the reference user (tipically an identified/non-anonymous user).

Example:

"02318f2cdd156d78fd4431"

unique_id_alias

String

The unique ID of the user that is being aliased (tipically an anonymous user).

Example:

"F348DE-31E0-4ACF-B2B0-5065FF8FCFB0"

Example Request

POST

https://collect.lqd.io/alias

{
  "unique_id": "02318f2cdd156d78fd4431",
  "unique_id_alias": "F348DE-31E0-4ACF-B2B0-5065FF8FCFB0"
}

Response

Code	Status	Content	Scenario
201	Created	n/a	Alias was successfuly created.
400	Bad Request	n/a	Content is not a valid JSON.
401	Unauthorized	n/a	Authorization failed (invalid API token).
422	Unprocessable Entity	Production app: n/a Development app: error message (see below)	Alias is invalid.

Error messages for Unprocessable Entity (422) have the following structure:

{
  "error": "Error Message",
  "details": "A string explaining the error in detail"
}

Structure of a data point Edit

A data point represents a snapshot of a device in a certain state, at the moment of an event generation (e.g.: when the user buys a product on their app).

Each datapoint includes 4 entities (User, Device, Event and Timestamp):

{
  "user": {},
  "device": {},
  "event": {},
  "timestamp": "2016-01-01T00:00:00.000+00:00"
}

Entities Edit

Timestamp

The date and time (a string with the ISO 8601 format) of the moment the event happens.

User

Contains information about the user that performed the event, a unique identifier (like a primary key) that uniquely identifies the user, a flag stating if the user is anonymous or identified and other optional custom fields.

Mandatory fields:

unique_id

String

A unique ID that uniquely identifies the user. For anonymous users we recommend using a strong UUID.

Example:

username@example.com

identified

Boolean

Should be true if the user is identified, false if user is anonymous.

Example:

true

Custom fields (optional):

You can always include custom fields, Liquid supports String, Integer, Float, Boolean or DateTime(ISO8601), for example:

{
  "user": {
    "age": 30,
    "identified": true,
    "name": "Username",
    "rating": 4.3,
    "sign_up_date": "2016-01-01T00:00:00.000+00:00",
    "unique_id": "02318f2cdd156d78fd4431"
  }
}

Device

Contains information about the device where the user generated the event. The only mandatory field is unique_id. All the other fields are optional but recommended to be present, as they’re very useful for segmentation on Liquid dashboard.

Mandatory fields:

unique_id

String

A unique ID that uniquely identifies the device.

Example:

"BE74F041-69B7-4E3B-AB91-A3C7FD150683"

Custom fields (optional):

{
  "device": {
    "app_bundle": "io.lqd.LiquidDemo",
    "app_name": "Demo App",
    "app_version": 1.0,
    "release_version": "1.0.1",
    "carrie": "Vodafone",
    "internet_connectivity": "Cellular",
    "sdk_version": "1.0.0",
    "mode": "iPad2,5",
    "name": "Username's iPad",
    "vendor": "Apple",
    "push_token": "5862036a860b6aa...c8190cfa61526ce30",
    "screen_size": "768x1024",
    "system_version": "7.0.1",
    "system_language": "en_GB",
    "locale": "en_GB",
    "latitude": 41.342543,
    "longitude": -8.846341,
    "unique_id": "BE74F041-69B7-4E3B-AB91-A3C7FD150683"
  }
}

Event

Contains information about the event. The only mandatory field is name, which should contain a string with a name that describes the event. All the other fields are custom attributes related with the event, e.g.: product_id: 5634 or price: 13.54.

Mandatory fields:

name

String

An identifier, event names should have a minimum length of 3 characters and a maximum of 50.

Example:

“buy_product”

Custom fields (optional):

{
  "event": {
    "name": "Buy Product",
    "product_id": "57634",
    "price": 13.54
  }
}

Examples Edit

Example of a minimum-filled data point:

An example of a data point with just the minimum required fields is shown below:

{
  "timestamp": "2016-01-01T00:00:00.000+00:00",
  "user": {
    "unique_id": "02318f2cdd156d78fd4431",
    "identified": true
  },
  "device": {
    "unique_id": "78F348DE-31E0-4ACF-B2B0-5065FF8FCFB0"
  },
  "event": {
    "name": "buy_product"
  }
}

Example of a fully-filled data point

An example of a data point with all the recommended fields present plus some custom attributes on User, Device and Event is shown below:

{
  "timestamp": "2016-01-07T17:28:58.270+00:00",
  "user": {
    "unique_id": "02318f2cdd156d78fd4431",
    "identified": true,
    "first_name": "User",
    "last_name": "Name",
    "age": 30,
    "gender": "male",
    "sign_up_date": "2016-01-07T17:28:05.270+00:00"
  },
  "device": {
    "unique_id": "78F348DE-31E0-4ACF-B2B0-5065FF8FCFB0",
    "app_bundle": "io.lqd.LiquidDemo",
    "app_name": "Demo App",
    "app_version": "1.0",
    "release_version": "1.0.1",
    "carrier": "Vodafone",
    "internet_connectivity": "Cellular",
    "sdk_version": "1.0.0",
    "model": "iPad2,5",
    "name": "Username's iPad",
    "vendor": "Apple",
    "push_token": "52036a860c6b6aada50117caea626d20ed3187d6981c8190cfa6199526ce30",
    "screen_size": "768x1024",
    "system_version": "7.0.1",
    "system_language": "en",
    "locale": "en",
    "latitude": 41.342543,
    "longitude": -8.846341
  },
  "event": {
    "name": "Buy Product",
    "product_id": 3293,
    "price": 17.24
  }
}

Good practices Edit

We strongly recommend you to choose a strong UUID generator algorithm (at least UUID Version 4) since the generation of real unique IDs - or at least near real - for devices and anonymous users are extremely important as they uniquely identify a resource.

If the algorithm is not strong-enough to avoid colisions of those unique IDs (e.g. generating two users with the same Unique ID) different users, or devices would be erroneously merged.