Self-describing events

You may wish to track events which are not directly supported by Snowplow and which structured event tracking does not adequately capture. Your event may have more than the five fields offered by Structured events, or its fields may not fit into the category-action-label-property-value model. The solution is Snowplow’s self-describing events. Self-describing events are a data structure based on JSON Schemas and can have arbitrarily many fields.

To define your own custom event, you will need to create a corresponding schema. Snowplow uses the schema to validate that the JSON containing the event properties is well-formed.

info

Historically, custom self-describing events were called “unstructured” and the legacy custom events were called “structured”. This terminology can be confusing, so we don’t use it anymore. However, you might find its remnants in some of the APIs.

An example of a self-describing event for a product view event:

{
  "schema": "iglu:com.my_company/viewed_product/jsonschema/1-0-0",
  "data": {
    "product_id": "ASO01043",
    "price": 49.95
  }
}

info

"iglu:com.my_company/viewed_product/jsonschema/1-0-0" respresents a self-describing JSON. It is used to validate the event data against a predefined JSON Schema as part of a Snowplow pipeline.

How are self-describing events serialized in event payload?

The tracker will wrap this self-describing JSON in an outer self-describing JSON, which is what gets sent in the payload:

{

  // Tells Snowplow this is an self-describing event
  "schema": "iglu:com.snowplowanalytics.snowplow/unstruct_event/jsonschema/1-0-0",
  "data": {

    // Tells Snowplow this is a viewed_product event
    "schema": "iglu:com.my_company/viewed_product/jsonschema/1-0-0",
    "data": {

      // The event data itself
      "product_id": "ASO01043",
      "price": 49.95
    }
  }
}

As well as setting e=ue, there are two custom event specific parameters that can be populated with the outer self-describing JSON:

Parameter	Table Column	Type	Description
ue_px	unstruct_event	JSON (URL-safe Base64 encoded)	The properties of the event
ue_pr	unstruct_event	JSON	The properties of the event

The tracker can decide to pass the ue_px or the ue_pr parameter. Encoding properties into URL-safe Base64 allows is the recommended approach although does sacrifice readability.