snowplow-tracker 0.7.0.pre.alpha.2 → 0.7.0

data/lib/snowplow-tracker/tracker.rb

@@ -1,4 +1,4 @@
-# Copyright (c) 2013-2014 Snowplow Analytics Ltd. All rights reserved.
+# Copyright (c) 2013-2021 Snowplow Analytics Ltd. All rights reserved.
 #
 # This program is licensed to you under the Apache License Version 2.0,
 # and you may not use this file except in compliance with the Apache License Version 2.0.
@@ -9,335 +9,635 @@
 # "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 # See the Apache License Version 2.0 for the specific language governing permissions and limitations there under.
 
-# Author:: Alex Dean, Fred Blundun (mailto:support@snowplowanalytics.com)
-# Copyright:: Copyright (c) 2013-2014 Snowplow Analytics Ltd
+# Author:: Snowplow Analytics Ltd
+# Copyright:: Copyright (c) 2013-2021 Snowplow Analytics Ltd
 # License:: Apache License Version 2.0
 
+
 require 'contracts'
 require 'securerandom'
 require 'set'
 
 module SnowplowTracker
-
+  # Allows the tracking of events. The tracker accepts event properties to its
+  # various `track_x_event` methods, and creates an appropriate event payload.
+  # This payload is passed to one or more Emitters for sending to the event
+  # collector.
+  #
+  # A Tracker is always associated with one {Subject}, and one or more
+  # {Emitter}. The Subject object stores information about the user, and will be
+  # generated automatically if one is not provided during initialization. It can
+  # be swapped out for another Subject using {#set_subject}.
+  #
+  # Tracker objects can access the methods of their associated {Subject}, e.g.
+  # {#set_user_id}.
+  #
+  # The Emitter, or an array of Emitters, must be given during initialization.
+  # They will send the prepared events to the event collector. It's possible to
+  # add further Emitters to an existing Tracker, using {#add_emitter}. However,
+  # Emitters cannot be removed from Trackers.
+  #
+  # At initialization, two Tracker parameters can be set which will be added to
+  # all events. The first is the Tracker namespace. This is especially useful to
+  # distinguish between events from different Trackers, if more than one is
+  # being used. The namespace value will be sent as the `tna` field in the raw
+  # event, mapping to `name_tracker` in the processed event.
+  #
+  # The second user-set Tracker property is the app ID (`aid`; `app_id`). This
+  # is the unique identifier for the site or application, and is particularly
+  # useful for distinguishing between events when Snowplow tracking has been
+  # implemented in multiple apps.
+  #
+  # The final initialization parameter is a setting for the base64-encoding of
+  # any JSONs in the event payload. These will be the {SelfDescribingJson}s used
+  # to provide context to events, or in the {#track_self_describing_event}
+  # method. The default is for JSONs to be encoded. Once the Tracker has been
+  # instantiated, it is not possible to change this setting.
+  #
+  # # Tracking events
+  #
+  # The Tracker `#track_x_event` methods all work similarly. An event payload is
+  # created containing the relevant properties, which is passed to an {Emitter}
+  # for sending. All payloads have a unique event ID (`event_id`) added to them
+  # (a type-4 UUID created using the SecureRandom module). This is sent as the
+  # `eid` field in the raw event.
+  #
+  # The Ruby tracker provides the ability to track multiple types of events
+  # out-of-the-box. The `#track_x_event` methods range from single purpose
+  # methods, such as {#track_page_view}, to the more complex but flexible
+  # {#track_self_describing_event}, which can be used to track any kind of
+  # event. We strongly recommend using {#track_self_describing_event} for your
+  # tracking, as it allows you to design custom event types to match your
+  # business requirements.
+  #
+  # This table gives the event type in the raw and processed events, defined in
+  # the Snowplow Tracker Protocol. This is the `e` or `event` parameter. Note
+  # that {#track_screen_view} calls {#track_self_describing_event} behind the
+  # scenes, resulting in a `ue` event type.
+  #
+  # <br>
+  #
+  # | Tracker method | `e` (raw) | `event` (processed) |
+  # | --- | --- | --- |
+  # | {#track_self_describing_event} | `ue` | `unstruct` |
+  # | {#track_struct_event} | `se` | `struct` |
+  # | {#track_page_view} | `pv` | `page_view` |
+  # | {#track_ecommerce_transaction} | `tr` and `ti` | `transaction` and `transaction_item` |
+  # | {#track_screen_view} | `ue` | `unstruct` |
+  #
+  # <br>
+  #
+  # The name `ue`, "unstructured event", is partially depreciated. This event
+  # type was originally created as a counterpart to "structured event", but the
+  # name is misleading. An `unstruct` event requires a schema ruleset and
+  # therefore can be considered more structured than a `struct` event. We prefer
+  # the name "self-describing event", after the {SelfDescribingJson} schema.
+  # Changing the event name in the Tracker Protocol would be a breaking change,
+  # so for now the self-describing events are still sent as "unstruct".
+  #
+  # All the `#track_x_event` methods share common features and parameters. Every
+  # type of event can have an optional context, {Subject}, and {Page} added. A
+  # {Timestamp} can also be provided for all event types to override the default
+  # event timestamp.
+  #
+  # [Event
+  # context](https://docs.snowplowanalytics.com/docs/understanding-tracking-design/understanding-events-entities/)
+  # can be provided as an array of {SelfDescribingJson}. Each element of the
+  # array is called an entity. Contextual entities can be used to describe the
+  # setting in which the event occurred. For example, a "user" entity could be
+  # created and attached to all events from each user. For a search event,
+  # entities could be attached for each of the search results. The Ruby tracker
+  # does not automatically add any event context. This is in contrast to the
+  # [Snowplow JavaScript Tracker](https://docs.snowplowanalytics.com/docs/collecting-data/collecting-from-own-applications/javascript-trackers/),
+  # which automatically attaches a "webpage" entity to every event that it tracks,
+  # containing a unique ID for that loaded page.
+  #
+  # @see Subject
+  # @see Emitter
+  # @see
+  #   https://docs.snowplowanalytics.com/docs/collecting-data/collecting-from-own-applications/snowplow-tracker-protocol
+  #   the Snowplow Tracker Protocol
+  # @see
+  #   https://docs.snowplowanalytics.com/docs/understanding-tracking-design/introduction-to-tracking-design/
+  #   introduction to Snowplow tracking design
+  # @api public
   class Tracker
-
     include Contracts
 
-    @@EmitterInput = Or[lambda {|x| x.is_a? Emitter}, ArrayOf[lambda {|x| x.is_a? Emitter}]]
+    # Contract types
 
-    @@required_transaction_keys =   Set.new(%w(order_id total_value))
-    @@recognised_transaction_keys = Set.new(%w(order_id total_value affiliation tax_value shipping city state country currency))
+    # @private
+    EMITTER_INPUT = Or[->(x) { x.is_a? Emitter }, ArrayOf[->(x) { x.is_a? Emitter }]]
 
-    @@Transaction = lambda { |x|
+    # @private
+    REQUIRED_TRANSACTION_KEYS =   Set.new(%w[order_id total_value])
+    # @private
+    RECOGNISED_TRANSACTION_KEYS = Set.new(%w[
+                                            order_id total_value affiliation tax_value
+                                            shipping city state country currency
+                                          ])
+
+    # @private
+    TRANSACTION = ->(x) {
       return false unless x.class == Hash
-      transaction_keys = Set.new(x.keys)
-      @@required_transaction_keys.subset? transaction_keys and
-        transaction_keys.subset? @@recognised_transaction_keys
+      transaction_keys = Set.new(x.keys.map(&:to_s))
+      REQUIRED_TRANSACTION_KEYS.subset?(transaction_keys) &&
+        transaction_keys.subset?(RECOGNISED_TRANSACTION_KEYS)
     }
+    # @private
+    REQUIRED_ITEM_KEYS =   Set.new(%w[sku price quantity])
+    # @private
+    RECOGNISED_ITEM_KEYS = Set.new(%w[sku price quantity name category context])
 
-    @@required_item_keys =   Set.new(%w(sku price quantity))
-    @@recognised_item_keys = Set.new(%w(sku price quantity name category context))
-
-    @@Item = lambda { |x|
+    # @private
+    ITEM = ->(x) {
       return false unless x.class == Hash
-      item_keys = Set.new(x.keys)
-      @@required_item_keys.subset? item_keys and
-        item_keys.subset? @@recognised_item_keys
+      item_keys = Set.new(x.keys.map(&:to_s))
+      REQUIRED_ITEM_KEYS.subset?(item_keys) &&
+        item_keys.subset?(RECOGNISED_ITEM_KEYS)
     }
+    # @private
+    REQUIRED_AUGMENTED_ITEM_KEYS =   Set.new(%w[sku price quantity tstamp order_id])
+    # @private
+    RECOGNISED_AUGMENTED_ITEM_KEYS = Set.new(%w[sku price quantity name category context tstamp order_id currency])
 
-    @@required_augmented_item_keys =   Set.new(%w(sku price quantity tstamp order_id))
-    @@recognised_augmented_item_keys = Set.new(%w(sku price quantity name category context tstamp order_id currency))
-
-    @@AugmentedItem = lambda { |x|
+    # @private
+    AUGMENTED_ITEM = ->(x) {
       return false unless x.class == Hash
       augmented_item_keys = Set.new(x.keys)
-      @@required_augmented_item_keys.subset? augmented_item_keys and
-        augmented_item_keys.subset? @@recognised_augmented_item_keys
+      REQUIRED_AUGMENTED_ITEM_KEYS.subset?(augmented_item_keys) &&
+        augmented_item_keys.subset?(RECOGNISED_AUGMENTED_ITEM_KEYS)
     }
 
-    @@ContextsInput = ArrayOf[SelfDescribingJson]
+    # @private
+    CONTEXTS_INPUT = ArrayOf[SelfDescribingJson]
 
-    @@version = TRACKER_VERSION
-    @@default_encode_base64 = true
+    # Other constants
 
-    @@base_schema_path = "iglu:com.snowplowanalytics.snowplow"
-    @@schema_tag = "jsonschema"
-    @@context_schema = "#{@@base_schema_path}/contexts/#{@@schema_tag}/1-0-1"
-    @@unstruct_event_schema = "#{@@base_schema_path}/unstruct_event/#{@@schema_tag}/1-0-0"
+    # @!group Public constants
 
-    Contract @@EmitterInput, Maybe[Subject], Maybe[String], Maybe[String], Bool => Tracker
-    def initialize(emitters, subject=nil, namespace=nil, app_id=nil, encode_base64=@@default_encode_base64)
+    # SelfDescribingJson objects are sent encoded by default
+    DEFAULT_ENCODE_BASE64 = true
+
+    # @private
+    BASE_SCHEMA_PATH = 'iglu:com.snowplowanalytics.snowplow'
+    # @private
+    SCHEMA_TAG = 'jsonschema'
+    # @private
+    CONTEXT_SCHEMA = "#{BASE_SCHEMA_PATH}/contexts/#{SCHEMA_TAG}/1-0-1"
+    # @private
+    UNSTRUCT_EVENT_SCHEMA = "#{BASE_SCHEMA_PATH}/unstruct_event/#{SCHEMA_TAG}/1-0-0"
+    # @private
+    SCREEN_VIEW_SCHEMA = "#{BASE_SCHEMA_PATH}/screen_view/#{SCHEMA_TAG}/1-0-0"
+
+    # @!endgroup
+
+    Contract KeywordArgs[emitters: EMITTER_INPUT, subject: Maybe[Subject], namespace: Maybe[String],
+                         app_id: Maybe[String], encode_base64: Optional[Bool]] => Any
+    # Create a new Tracker. `emitters` is the only strictly required parameter.
+    #
+    # @param emitters [Emitter, Array<Emitter>] one or more Emitter objects
+    # @param subject [Subject] a Subject object
+    # @param namespace [String] a name for the Tracker
+    # @param app_id [String] the app ID
+    # @param encode_base64 [Bool] whether JSONs will be base64-encoded or not
+    # @example Initializing a Tracker with all possible options
+    #   Tracker.new(
+    #               emitters: Emitter.new('collector.example.com'),
+    #               subject: Subject.new,
+    #               namespace: 'tracker_no_encode',
+    #               app_id: 'rails_main',
+    #               encode_base64: false
+    #              )
+    # @api public
+    def initialize(emitters:, subject: nil, namespace: nil, app_id: nil, encode_base64: DEFAULT_ENCODE_BASE64)
       @emitters = Array(emitters)
-      if subject.nil?
-        @subject = Subject.new
-      else
-        @subject = subject
-      end
-      @standard_nv_pairs = {
+      @subject = if subject.nil?
+                   Subject.new
+                 else
+                   subject
+                 end
+      @settings = {
         'tna' => namespace,
-        'tv'  => @@version,
+        'tv'  => TRACKER_VERSION,
         'aid' => app_id
       }
-      @config = {
-        'encode_base64' => encode_base64
-      }
-
-      self
+      @encode_base64 = encode_base64
     end
 
-    # Call subject methods from tracker instance
-    #
+    # @!method set_color_depth(depth)
+    #   call {Subject#set_color_depth}
+    # @!method set_domain_session_id(sid)
+    #   call {Subject#set_domain_session_id}
+    # @!method set_domain_session_idx(vid)
+    #   call {Subject#set_domain_session_idx}
+    # @!method set_domain_user_id(duid)
+    #   call {Subject#set_domain_user_id}
+    # @!method set_fingerprint(fingerprint)
+    #   call {Subject#set_fingerprint}
+    # @!method set_ip_address(ip)
+    #   call {Subject#set_ip_address}
+    # @!method set_lang(lang)
+    #   call {Subject#set_lang}
+    # @!method set_network_user_id(nuid)
+    #   call {Subject#set_network_user_id}
+    # @!method set_platform(platform)
+    #   call {Subject#set_platform}
+    # @!method set_screen_resolution(width:, height:)
+    #   call {Subject#set_screen_resolution}
+    # @!method set_timezone(timezone)
+    #   call {Subject#set_timezone}
+    # @!method set_user_id(user_id)
+    #   call {Subject#set_user_id}
+    # @!method set_useragent(useragent)
+    #   call {Subject#set_useragent}
+    # @!method set_viewport(width:, height:)
+    #   call {Subject#set_viewport}
     Subject.instance_methods(false).each do |name|
-      define_method name, ->(*splat) do
-        @subject.method(name.to_sym).call(*splat)
+      if RUBY_VERSION >= '3.0.0'
+        define_method name, ->(*args, **kwargs) do
+          @subject.method(name.to_sym).call(*args, **kwargs)
+
+          self
+        end
+      else
+        define_method name, ->(*args) do
+          @subject.method(name.to_sym).call(*args)
 
-        self
+          self
+        end
       end
     end
 
-    # Generates a type-4 UUID to identify this event
     Contract nil => String
-    def get_event_id()
+    # Generates a type-4 UUID to identify this event
+    # @private
+    def event_id
       SecureRandom.uuid
     end
 
-    # Generates the timestamp (in milliseconds) to be attached to each event
-    #
-    Contract nil => Num
-    def get_timestamp
-      (Time.now.to_f * 1000).to_i
-    end
-
-    # Builds a self-describing JSON from an array of custom contexts
-    #
-    Contract @@ContextsInput => Hash
+    Contract CONTEXTS_INPUT => Hash
+    # Builds a single self-describing JSON from an array of custom contexts
+    # @private
     def build_context(context)
       SelfDescribingJson.new(
-        @@context_schema,
-        context.map {|c| c.to_json}
-        ).to_json
+        CONTEXT_SCHEMA,
+        context.map(&:to_json)
+      ).to_json
     end
 
-    # Tracking methods
-
-    # Attaches all the fields in @standard_nv_pairs to the request
-    #  Only attaches the context vendor if the event has a custom context
-    #
     Contract Payload => nil
-    def track(pb)
-      pb.add_dict(@subject.standard_nv_pairs)
-      pb.add_dict(@standard_nv_pairs)
-      pb.add('eid', get_event_id())
-      @emitters.each{ |emitter| emitter.input(pb.context)}
+    # Sends the payload hash as a request to the Emitter(s)
+    # @private
+    def track(payload)
+      @emitters.each { |emitter| emitter.input(payload.data) }
 
       nil
     end
 
-    # Log a visit to this page with an inserted device timestamp
-    #
-    Contract String, Maybe[String], Maybe[String], Maybe[@@ContextsInput], Maybe[Num] => Tracker
-    def track_page_view(page_url, page_title=nil, referrer=nil, context=nil, tstamp=nil)
-      if tstamp.nil?
-        tstamp = get_timestamp
-      end
-
-      track_page_view(page_url, page_title, referrer, context, DeviceTimestamp.new(tstamp))  
+    Contract Or[Timestamp, Num, nil] => Timestamp
+    # Ensures that either a DeviceTimestamp or TrueTimestamp is associated with
+    # every event.
+    # @private
+    def process_tstamp(tstamp)
+      tstamp = Timestamp.create if tstamp.nil?
+      tstamp = DeviceTimestamp.new(tstamp) if tstamp.is_a? Numeric
+      tstamp
     end
 
-    # Log a visit to this page
+    Contract Payload, Maybe[CONTEXTS_INPUT], Timestamp, Maybe[Subject], Maybe[Page] => nil
+    # Attaches the more generic fields to the event payload. This includes
+    # context, Subject, and Page if they are present. The timestamp is added, as
+    # well as all fields from `@settings`.
     #
-    Contract String, Maybe[String], Maybe[String], Maybe[@@ContextsInput], SnowplowTracker::Timestamp => Tracker
-    def track_page_view(page_url, page_title=nil, referrer=nil, context=nil, tstamp=nil)
-      pb = Payload.new
-      pb.add('e', 'pv')
-      pb.add('url', page_url)
-      pb.add('page', page_title)
-      pb.add('refr', referrer)
-
-      unless context.nil?
-        pb.add_json(build_context(context), @config['encode_base64'], 'cx', 'co')
+    # Finally, the Tracker generates and attaches an event ID.
+    # @private
+    def finalise_payload(payload, context, tstamp, event_subject, page)
+      payload.add_json(build_context(context), @encode_base64, 'cx', 'co') unless context.nil? || context.empty?
+      payload.add_hash(page.details) unless page.nil?
+
+      if event_subject.nil?
+        payload.add_hash(@subject.details)
+      else
+        payload.add_hash(@subject.details.merge(event_subject.details))
       end
 
-      pb.add(tstamp.type, tstamp.value)
-
-      track(pb)
+      payload.add(tstamp.type, tstamp.value)
+      payload.add_hash(@settings)
+      payload.add('eid', event_id)
 
-      self
+      nil
     end
 
-    # Track a single item within an ecommerce transaction
-    #   Not part of the public API
-    #
-    Contract @@AugmentedItem => self
-    def track_ecommerce_transaction_item(argmap)
-      pb = Payload.new
-      pb.add('e', 'ti')
-      pb.add('ti_id', argmap['order_id'])
-      pb.add('ti_sk', argmap['sku'])
-      pb.add('ti_pr', argmap['price'])
-      pb.add('ti_qu', argmap['quantity'])
-      pb.add('ti_nm', argmap['name'])
-      pb.add('ti_ca', argmap['category'])
-      pb.add('ti_cu', argmap['currency'])
-      unless argmap['context'].nil?
-        pb.add_json(build_context(argmap['context']), @config['encode_base64'], 'cx', 'co')
-      end
-      pb.add(argmap['tstamp'].type, argmap['tstamp'].value)
-      track(pb)
+    Contract KeywordArgs[page_url: String, page_title: Maybe[String], referrer: Maybe[String],
+                         context: Maybe[CONTEXTS_INPUT], tstamp: Or[Timestamp, Num, nil],
+                         subject: Maybe[Subject], page: Maybe[Page]] => Tracker
+    # Track a visit to a page.
+    #
+    # @param page_url [String] the URL of the page
+    # @param page_title [String] the page title
+    # @param referrer [String] the URL of the referrer page
+    # @param context [Array<SelfDescribingJson>] an array of SelfDescribingJson objects
+    # @param tstamp [DeviceTimestamp, TrueTimestamp, Num] override the default DeviceTimestamp of the event
+    # @param subject [Subject] event-specific Subject object
+    # @param page [Page] override the page_url, page_title, or referrer
+    #
+    # @api public
+    def track_page_view(page_url:, page_title: nil, referrer: nil,
+                        context: nil, tstamp: nil, subject: nil, page: nil)
+      tstamp = process_tstamp(tstamp)
 
-      self
-    end
+      payload = Payload.new
+      payload.add('e', 'pv')
+      payload.add('url', page_url)
+      payload.add('page', page_title)
+      payload.add('refr', referrer)
 
-    # Track an ecommerce transaction and all the items in it
-    # Set the timestamp as the device timestamp
-    Contract @@Transaction, ArrayOf[@@Item], Maybe[@@ContextsInput], Maybe[Num] => Tracker
-    def track_ecommerce_transaction(transaction, 
-                                    items,
-                                    context=nil,
-                                    tstamp=nil)      
-      if tstamp.nil?
-        tstamp = get_timestamp
-      end
+      finalise_payload(payload, context, tstamp, subject, page)
+      track(payload)
 
-      track_ecommerce_transaction(transaction, items, context, DeviceTimestamp.new(tstamp))
+      self
     end
 
-    # Track an ecommerce transaction and all the items in it
-    #
-    Contract @@Transaction, ArrayOf[@@Item], Maybe[@@ContextsInput], Timestamp => Tracker
-    def track_ecommerce_transaction(transaction, items,
-                                    context=nil, tstamp=nil)
-      pb = Payload.new
-      pb.add('e', 'tr')
-      pb.add('tr_id', transaction['order_id'])
-      pb.add('tr_tt', transaction['total_value'])
-      pb.add('tr_af', transaction['affiliation'])
-      pb.add('tr_tx', transaction['tax_value'])
-      pb.add('tr_sh', transaction['shipping'])
-      pb.add('tr_ci', transaction['city'])
-      pb.add('tr_st', transaction['state'])
-      pb.add('tr_co', transaction['country'])
-      pb.add('tr_cu', transaction['currency'])
-      unless context.nil?
-        pb.add_json(build_context(context), @config['encode_base64'], 'cx', 'co')
-      end
-
-      pb.add(tstamp.type, tstamp.value)
-
-      track(pb)
-
-      for item in items
+    Contract KeywordArgs[transaction: TRANSACTION, items: ArrayOf[ITEM],
+                         context: Maybe[CONTEXTS_INPUT], tstamp: Or[Timestamp, Num, nil],
+                         subject: Maybe[Subject], page: Maybe[Page]] => Tracker
+    # Track an eCommerce transaction, and all the items in it.
+    #
+    # This method is unique in sending multiple events: one `transaction` event,
+    # and one `transaction_item` event for each item. If Subject or Page objects
+    # are provided, their parameters will be merged into both `transaction` and
+    # `transaction_item` events. The timestamp and event ID of the
+    # `transaction_item` events will always be the same as the `transaction`.
+    # Transaction items are also automatically populated with the `order_id` and
+    # `currency` fields from the transaction.
+    #
+    # Event context is handled differently for `transaction` and
+    # `transaction_item` events. A context array argument provided to this
+    # method will be attached to the `transaction` event only. To attach a
+    # context array to a transaction item, use the key "context" in the item
+    # hash.
+    #
+    # The transaction and item hash arguments must contain the correct keys, as
+    # shown in the tables below.
+    #
+    # | Transaction fields | Description | Required? | Type |
+    # | --- | --- | --- | --- |
+    # | order_id |  ID of the eCommerce transaction  | Yes  | String |
+    # | total_value |  Total transaction value  | Yes  | Num |
+    # | affiliation |  Transaction affiliation  | No  | String |
+    # | tax_value |  Transaction tax value  | No  | Num |
+    # | shipping |  Delivery cost charged  | No  | Num |
+    # | city |  Delivery address city  | No  | String |
+    # | state |  Delivery address state  | No  | String |
+    # | country |  Delivery address country  | No  | String |
+    # | currency |  Transaction currency  | No  | String |
+    #
+    # <br>
+    #
+    # | Item fields | Description | Required? | Type |
+    # | --- | --- | --- | --- |
+    # | sku | Item SKU  | Yes | String |
+    # | price | Item price  | Yes | Num |
+    # | quantity |  Item quantity | Yes | Integer |
+    # | name |  Item name | No |  String |
+    # | category |  Item category | No |  String |
+    # | context | Item event context  | No |  Array[{SelfDescribingJson}] |
+    #
+    # @example Tracking a transaction containing two items
+    #   SnowplowTracker::Tracker.new.track_ecommerce_transaction(
+    #     transaction: {
+    #       'order_id' => '12345',
+    #       'total_value' => 49.99,
+    #       'affiliation' => 'my_company',
+    #       'tax_value' => 0,
+    #       'shipping' => 0,
+    #       'city' => 'Phoenix',
+    #       'state' => 'Arizona',
+    #       'country' => 'USA',
+    #       'currency' => 'USD'
+    #     },
+    #     items: [
+    #       {
+    #         'sku' => 'pbz0026',
+    #         'price' => 19.99,
+    #         'quantity' => 1
+    #       },
+    #       {
+    #         'sku' => 'pbz0038',
+    #         'price' => 15,
+    #         'quantity' => 2,
+    #         'name' => 'crystals',
+    #         'category' => 'magic'
+    #       }
+    #     ]
+    #   )
+    #
+    # @param transaction [Hash] the correctly structured transaction hash
+    # @param items [Array<Hash>] an array of correctly structured item hashes
+    # @param context [Array<SelfDescribingJson>] an array of SelfDescribingJson objects
+    # @param tstamp [DeviceTimestamp, TrueTimestamp, Num] override the default DeviceTimestamp of the event
+    # @param subject [Subject] event-specific Subject object
+    # @param page [Page] event-specific Page object
+    #
+    # @api public
+    def track_ecommerce_transaction(transaction:, items:,
+                                    context: nil, tstamp: nil,
+                                    subject: nil, page: nil)
+      tstamp = process_tstamp(tstamp)
+
+      transform_keys(transaction)
+
+      payload = Payload.new
+      payload.add('e', 'tr')
+      payload.add('tr_id', transaction['order_id'])
+      payload.add('tr_tt', transaction['total_value'])
+      payload.add('tr_af', transaction['affiliation'])
+      payload.add('tr_tx', transaction['tax_value'])
+      payload.add('tr_sh', transaction['shipping'])
+      payload.add('tr_ci', transaction['city'])
+      payload.add('tr_st', transaction['state'])
+      payload.add('tr_co', transaction['country'])
+      payload.add('tr_cu', transaction['currency'])
+
+      finalise_payload(payload, context, tstamp, subject, page)
+
+      track(payload)
+
+      items.each do |item|
+        transform_keys(item)
         item['tstamp'] = tstamp
         item['order_id'] = transaction['order_id']
         item['currency'] = transaction['currency']
-        track_ecommerce_transaction_item(item)
+        track_ecommerce_transaction_item(item, subject, page)
       end
 
       self
     end
 
-    # Track a structured event
-    # set the timestamp to the device timestamp
-    Contract String, String, Maybe[String], Maybe[String], Maybe[Num], Maybe[@@ContextsInput], Maybe[Num] => Tracker
-    def track_struct_event(category, action, label=nil, property=nil, value=nil, context=nil, tstamp=nil)
-      if tstamp.nil?
-        tstamp = get_timestamp
-      end
-
-      track_struct_event(category, action, label, property, value, context, DeviceTimestamp.new(tstamp))
+    # Makes sure all hash keys are strings rather than symbols.
+    # The Ruby core language added a method for this in Ruby 2.5.
+    # @private
+    def transform_keys(hash)
+      hash.keys.each { |key| hash[key.to_s] = hash.delete key }
     end
-    # Track a structured event
-    #
-    Contract String, String, Maybe[String], Maybe[String], Maybe[Num], Maybe[@@ContextsInput], Timestamp => Tracker
-    def track_struct_event(category, action, label=nil, property=nil, value=nil, context=nil, tstamp=nil)
-      pb = Payload.new
-      pb.add('e', 'se')
-      pb.add('se_ca', category)
-      pb.add('se_ac', action)
-      pb.add('se_la', label)
-      pb.add('se_pr', property)
-      pb.add('se_va', value)
-      unless context.nil?
-        pb.add_json(build_context(context), @config['encode_base64'], 'cx', 'co')
-      end
 
-      pb.add(tstamp.type, tstamp.value)
-      track(pb)
+    Contract AUGMENTED_ITEM, Maybe[Subject], Maybe[Page] => self
+    # Track a single item within an ecommerce transaction.
+    # @private
+    def track_ecommerce_transaction_item(details, subject, page)
+      payload = Payload.new
+      payload.add('e', 'ti')
+      payload.add('ti_id', details['order_id'])
+      payload.add('ti_sk', details['sku'])
+      payload.add('ti_pr', details['price'])
+      payload.add('ti_qu', details['quantity'])
+      payload.add('ti_nm', details['name'])
+      payload.add('ti_ca', details['category'])
+      payload.add('ti_cu', details['currency'])
+
+      finalise_payload(payload, details['context'], details['tstamp'], subject, page)
+      track(payload)
 
       self
     end
 
-    # Track a screen view event
+    Contract KeywordArgs[category: String, action: String, label: Maybe[String],
+                         property: Maybe[String], value: Maybe[Num],
+                         context: Maybe[CONTEXTS_INPUT], tstamp: Or[Timestamp, Num, nil],
+                         subject: Maybe[Subject], page: Maybe[Page]] => Tracker
+    # Track a structured event. `category` and `action` are required.
     #
-    Contract Maybe[String], Maybe[String],  Maybe[@@ContextsInput], Or[Timestamp, Num, nil] => Tracker
-    def track_screen_view(name=nil, id=nil, context=nil, tstamp=nil)
-      screen_view_properties = {}
-      unless name.nil? 
-        screen_view_properties['name'] = name
-      end
-      unless id.nil? 
-        screen_view_properties['id'] = id
-      end
-      screen_view_schema = "#{@@base_schema_path}/screen_view/#{@@schema_tag}/1-0-0"
-
-      event_json = SelfDescribingJson.new(screen_view_schema, screen_view_properties)
-
-      self.track_unstruct_event(event_json, context, tstamp)
+    # This event type can be used to track many types of user activity, as it is
+    # somewhat customizable. This event type is provided particularly for
+    # concordance with Google Analytics tracking, where events are structured by
+    # "category", "action", "label", and "value".
+    #
+    # For fully customizable event tracking, we recommend you use
+    # self-describing events.
+    #
+    # @see #track_self_describing_event
+    #
+    # @param category [String] the event category
+    # @param action [String] the action performed
+    # @param label [String] an event label
+    # @param property [String] an event property
+    # @param value [Num] a value for the event
+    # @param context [Array<SelfDescribingJson>] an array of SelfDescribingJson objects
+    # @param tstamp [DeviceTimestamp, TrueTimestamp, Num] override the default DeviceTimestamp of the event
+    # @param subject [Subject] event-specific Subject object
+    # @param page [Page] event-specific Page object
+    #
+    # @api public
+    def track_struct_event(category:, action:, label: nil, property: nil,
+                           value: nil, context: nil, tstamp: nil, subject: nil, page: nil)
+      tstamp = process_tstamp(tstamp)
+
+      payload = Payload.new
+      payload.add('e', 'se')
+      payload.add('se_ca', category)
+      payload.add('se_ac', action)
+      payload.add('se_la', label)
+      payload.add('se_pr', property)
+      payload.add('se_va', value)
+
+      finalise_payload(payload, context, tstamp, subject, page)
+      track(payload)
 
       self
     end
 
-    # Better name for track unstruct event
+    Contract KeywordArgs[name: Maybe[String], id: Maybe[String],
+                         context: Maybe[CONTEXTS_INPUT], tstamp: Or[Timestamp, Num, nil],
+                         subject: Maybe[Subject], page: Maybe[Page]] => Tracker
+    # Track a screen view event. Note that while the `name` and `id` parameters
+    # are both optional, you must provided at least one of them to create a
+    # valid event.
     #
-    Contract SelfDescribingJson, Maybe[@@ContextsInput], Timestamp => Tracker
-    def track_self_describing_event(event_json, context=nil, tstamp=nil)
-      track_unstruct_event(event_json, context, tstamp)
-    end
-
-    # Better name for track unstruct event
-    # set the timestamp to the device timestamp
-    Contract SelfDescribingJson, Maybe[@@ContextsInput], Maybe[Num] => Tracker
-    def track_self_describing_event(event_json, context=nil, tstamp=nil)
-      track_unstruct_event(event_json, context, tstamp)
-    end
+    # This method creates an `unstruct` event, by creating a
+    # {SelfDescribingJson} and calling {#track_self_describing_event}. The
+    # schema ID for this is
+    # "iglu:com.snowplowanalytics.snowplow/screen_view/jsonschema/1-0-0", and
+    # the data field will contain the name and/or ID.
+    #
+    # @see #track_page_view
+    # @see #track_self_describing_event
+    #
+    # @param name [String] the screen name (human readable)
+    # @param id [String] the unique screen ID
+    # @param context [Array<SelfDescribingJson>] an array of SelfDescribingJson objects
+    # @param tstamp [DeviceTimestamp, TrueTimestamp, Num] override the default DeviceTimestamp of the event
+    # @param subject [Subject] event-specific Subject object
+    # @param page [Page] event-specific Page object
+    #
+    # @api public
+    def track_screen_view(name: nil, id: nil, context: nil, tstamp: nil, subject: nil, page: nil)
+      screen_view_properties = {}
+      screen_view_properties['name'] = name unless name.nil?
+      screen_view_properties['id'] = id unless id.nil?
 
-    # Track an unstructured event
-    # set the timestamp to the device timstamp
-    Contract SelfDescribingJson, Maybe[@@ContextsInput], Maybe[Num] => Tracker
-    def track_unstruct_event(event_json, context=nil, tstamp=nil)
-      if tstamp.nil?
-        tstamp = get_timestamp
-      end
+      event_json = SelfDescribingJson.new(SCREEN_VIEW_SCHEMA, screen_view_properties)
+      track_unstruct_event(event_json: event_json, context: context,
+                           tstamp: tstamp, subject: subject, page: page)
 
-      track_unstruct_event(event_json, context, DeviceTimestamp.new(tstamp))
+      self
     end
 
-    # Track an unstructured event
+    Contract KeywordArgs[event_json: SelfDescribingJson, context: Maybe[CONTEXTS_INPUT],
+                         tstamp: Or[Timestamp, Num, nil], subject: Maybe[Subject],
+                         page: Maybe[Page]] => Tracker
+    # Track a self-describing event. These are custom events based on
+    # {SelfDescribingJson}, i.e. a JSON schema and a defined set of properties.
+    #
+    # This is useful for tracking specific or proprietary event types, or events
+    # with unpredicable or frequently changing properties.
+    #
+    # This method creates an `unstruct` event type. It is actually an alias for
+    # {#track_unstruct_event}, which is depreciated due to its unhelpful name.
     #
-    Contract SelfDescribingJson, Maybe[@@ContextsInput], Timestamp => Tracker
-    def track_unstruct_event(event_json, context=nil, tstamp=nil)
-      pb = Payload.new
-      pb.add('e', 'ue')
-      
-      envelope = SelfDescribingJson.new(@@unstruct_event_schema, event_json.to_json)
+    # @param event_json [SelfDescribingJson] a SelfDescribingJson object
+    # @param context [Array<SelfDescribingJson>] an array of SelfDescribingJson objects
+    # @param tstamp [DeviceTimestamp, TrueTimestamp, Num] override the default DeviceTimestamp of the event
+    # @param subject [Subject] event-specific Subject object
+    # @param page [Page] event-specific Page object
+    #
+    # @api public
+    def track_self_describing_event(event_json:, context: nil, tstamp: nil, subject: nil, page: nil)
+      track_unstruct_event(event_json: event_json, context: context,
+                           tstamp: tstamp, subject: subject, page: page)
+    end
 
-      pb.add_json(envelope.to_json, @config['encode_base64'], 'ue_px', 'ue_pr')
+    Contract KeywordArgs[event_json: SelfDescribingJson, context: Maybe[CONTEXTS_INPUT],
+                         tstamp: Or[Timestamp, Num, nil], subject: Maybe[Subject],
+                         page: Maybe[Page]] => Tracker
+    # @deprecated Use {#track_self_describing_event} instead.
+    #
+    # @api public
+    def track_unstruct_event(event_json:, context: nil, tstamp: nil, subject: nil, page: nil)
+      tstamp = process_tstamp(tstamp)
 
-      unless context.nil?
-        pb.add_json(build_context(context), @config['encode_base64'], 'cx', 'co')
-      end
+      payload = Payload.new
+      payload.add('e', 'ue')
 
-      pb.add(tstamp.type, tstamp.value)
+      envelope = SelfDescribingJson.new(UNSTRUCT_EVENT_SCHEMA, event_json.to_json)
+      payload.add_json(envelope.to_json, @encode_base64, 'ue_px', 'ue_pr')
 
-      track(pb)
+      finalise_payload(payload, context, tstamp, subject, page)
+      track(payload)
 
       self
     end
 
-    # Flush all events stored in all emitters
+    Contract KeywordArgs[async: Optional[Bool]] => Tracker
+    # Manually flush all events stored in all Tracker-associated Emitters. By
+    # default, this happens synchronously. {Emitter}s can only send events
+    # synchronously, while {AsyncEmitter}s can send either synchronously or
+    # asynchronously.
+    #
+    # @param async [Bool] whether to flush asynchronously or not
     #
-    Contract Bool => Tracker
-    def flush(async=false)
+    # @api public
+    def flush(async: false)
       @emitters.each do |emitter|
         emitter.flush(async)
       end
@@ -345,27 +645,32 @@ module SnowplowTracker
       self
     end
 
-    # Set the subject of the events fired by the tracker
-    #
     Contract Subject => Tracker
+    # Replace the existing Tracker-associated Subject with the provided one. All
+    # subsequent events will have the properties of the new Subject, unless they
+    # are overriden by event-specific Subject parameters.
+    #
+    # @param subject [Subject] a Subject object
+    #
+    # @api public
     def set_subject(subject)
       @subject = subject
       self
     end
 
-    # Add a new emitter
-    #
     Contract Emitter => Tracker
+    # Add a new Emitter to the internal array of Tracker-associated Emitters.
+    #
+    # @param emitter [Emitter] an Emitter object
+    #
+    # @api public
     def add_emitter(emitter)
       @emitters.push(emitter)
       self
     end
 
-    private :get_timestamp,
-            :build_context,
+    private :build_context,
             :track,
             :track_ecommerce_transaction_item
-
   end
-
 end