Class: SnowplowTracker::SelfDescribingJson

Inherits:
Object
  • Object
show all
Defined in:
lib/snowplow-tracker/self_describing_json.rb

Overview

Creates the self-describing JSONs necessary for sending context or self-describing events. These are a specific kind of [JSON schema](json-schema.org/).

A unique schema can be designed for each type of event or entity (for event context) that you want to track. This allows you to track the specific things that are important to you, in a way that is defined by you.

A self-describing JSON has two keys, ‘schema` and `data`. The `schema` value should point to a valid self-describing JSON schema. They are called self-describing because the schema will specify the fields allowed in the `data` value. After events have been collected by the event collector, they are validated to ensure that the self-describing JSONs are correct. Mistakes (e.g. extra fields, or incorrect types) will result in events being processed as Bad Events.

A SelfDescribingJson is initialized with ‘schema` and `data` as separate arguments. These parameters are combined into a complete self-describing JSON during the event creation, which is stringified and sent as part of the event. By default, they will be sent base64-encoded. This can be changed on Tracker initialization.

The ‘data` argument must be a flat hash of key-value pairs. Either strings or symbols are accepted as keys. The `schema` argument must be a correctly formatted schema ID.

When used to send event context data, stringified self-describing JSONs will be sent in the raw event as ‘cx`, or `co` if not encoded. Whether encoded or not, these strings will be converted back to JSON within the `contexts` parameter of the processed event. All the event context is contained within this one parameter, even if multiple context entities were sent.

Self-describing JSONs in self-describing events are sent in a similar manner. They are sent as ‘ue_px` in the raw event, or `ue_pr` if not encoded. This is processed into the `unstruct_event` parameter of the finished event.

Examples:

# This example schema describes an ad_click event.
# It defines a single property for that event type, a "bannerId".

{
  "$schema": "http://json-schema.org/schema#",
  "self": {
      "vendor": "com.snowplowanalytics",
      "name": "ad_click",
      "format": "jsonschema",
      "version": "1-0-0"
  },
  "type": "object",
  "properties": {
      "bannerId": {
          "type": "string"
      }
  },
  "required": ["bannerId"],
  "additionalProperties": false
}

# Creating the SelfDescribingJson
schema_name = "iglu:com.snowplowanalytics/ad_click/jsonschema/1-0-0"
event_data = { bannerId: "4acd518feb82" }
SnowplowTracker::SelfDescribingJson.new(schema_name, event_data)

# The self-describing JSON that will be sent (stringified) with the event
{
  "schema": "iglu:com.snowplowanalytics/ad_click/jsonschema/1-0-0",
  "data": {
      "bannerId": "4acd518feb82"
  }
}

See Also:

Instance Method Summary collapse

Constructor Details

#initialize(schema, data) ⇒ SelfDescribingJson

Returns a new instance of SelfDescribingJson.

Parameters:

  • schema (String) —

    schema identifier

  • data (Hash) —

    a flat hash that matches the description in the schema



103
104
105
106
 
# File 'lib/snowplow-tracker/self_describing_json.rb', line 103

def initialize(schema, data)
  @schema = schema
  @data = data
end

Instance Method Details

#to_json ⇒ Object

make the self-describing JSON out of the instance variables



110
111
112
113
114
115
 
# File 'lib/snowplow-tracker/self_describing_json.rb', line 110

def to_json
  {
    schema: @schema,
    data: @data
  }
end