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.

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