snowplow-tracker 0.7.0 → 0.8.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 23047d83eb7b5f22343e668d97e0885fbf1cacf684706b8bb83465e98fc78e40
-  data.tar.gz: edf65b28b3264412a3c11f2f0e9ee3a440647fbece99228ab450e9a01148b0f5
+  metadata.gz: 828096deb0a370f527d14f17e2e48eb1481428b5cdc1b2897235b539be64f327
+  data.tar.gz: e0b5b026cfad092a2c4269876bc0b7e5d240ba5ec8b18b67b8a1e97d7c127a93
 SHA512:
-  metadata.gz: d996e91a98e1ce69d459dd91655ff052d578e0dfed0c41c69731d1f37b93dfa95ca50e11b82d43df78b599197f8e94b5f5ad6a7fad5f4f8498d886c1dfdeae95
-  data.tar.gz: 88053e746e569713d537bfbbd75cb61ec4e38bbf19a0e8f36de13d057450fec5ab4f3e5a13715b13df1dc8188791e6e9dc38d9aed27b47bcc99c415d2edc6df5
+  metadata.gz: b75d45c5b03f55398ab27a9945d9ddbe91340348d803e8be8d4c74b108f39931cd7a7e17a661a818ffd9e3d81aac71bdf3a8d5486c397881a741bfc5e1b881b0
+  data.tar.gz: 650468a842f96ab6951aa54bc374115ee0dc3a466b6f15807c8a0e8fb1e86127b630ee226f8c0ba49b3316ae20d342c24c6211810e2c2eac65791d7f4fa9f478

data/README.md

@@ -9,30 +9,28 @@
 
 ## Overview
 
-Add analytics to your Ruby and Rails apps and gems with the **[Snowplow][snowplow]** event tracker for **[Ruby][ruby]**.
+Add analytics to your **[Ruby][ruby]** and **[Ruby on Rails][rails]** apps and **[gems][rubygems]** with the **[Snowplow][snowplow]** event tracker for **[Ruby][ruby]**.
 
 Snowplow is a scalable open-source platform for rich, high quality, low-latency data collection. It is designed to collect high quality, complete behavioral data for enterprise business.
 
 **To find out more, please check out the [Snowplow website][snowplow] and our [documentation][docs].**
 
-With this tracker you can collect event data from your **[Ruby][ruby]** applications, **[Ruby on Rails][rails]** web applications and **[Ruby gems][rubygems]**.
-
 ## Quickstart
 
 Add this gem to your Gemfile. It is compatible with Ruby versions 2.1 to 3.0+.
 
 ```ruby
-gem "snowplow-tracker", "~> 0.7.0"
+gem "snowplow-tracker", "~> 0.8.0"
 ```
 
 See our [demo app][demoapp] for an example of implementing the Ruby tracker in a Rails app.
 
 ## Find out more
 
-| Technical Docs                 | API Docs                | Contributing                        |
+| Snowplow Docs                 | API Docs                | Contributing                        |
 | ------------------------------ | ----------------------- | ----------------------------------- |
 | ![i1][techdocs-image]          | ![i1][techdocs-image]   | ![i4][contributing-image]           |
-| **[Technical Docs][techdocs]** | **[API Docs][apidocs]** | **[Contributing](Contributing.md)** |
+| **[Snowplow Docs][techdocs]** | **[API Docs][apidocs]** | **[Contributing](Contributing.md)** |
 
 ## Maintainer Quickstart
 
@@ -47,11 +45,16 @@ The `-v` flag for `docker run` creates a bind mount for the project directory. T
 
 Alternatively, test directly by installing Ruby 2.1+ and [Bundler][bundler]. Then run:
 
-```
+```bash
 bundle install
 rspec
 ```
 
+To generate documentation using YARD, make sure the YARD and redcarpet gems are installed locally. Then run:
+```bash
+yard doc
+```
+
 ## Contributing
 
 Feedback and contributions are welcome - if you have identified a bug, please log an issue on this repo. For all other feedback, discussion or questions please open a thread on our [Discourse forum][discourse].
@@ -72,7 +75,7 @@ limitations under the License.
 [license-image]: https://img.shields.io/badge/license-Apache--2-blue.svg?style=flat
 [license]: https://www.apache.org/licenses/LICENSE-2.0
 [gh-actions]: https://github.com/snowplow/snowplow-ruby-tracker/actions
-[gh-actions-image]: https://github.com/snowplow/snowplow-ruby-tracker/workflows/test.yml/badge.svg
+[gh-actions-image]: https://github.com/snowplow/snowplow-ruby-tracker/workflows/Test/badge.svg
 [tracker-classification]: https://docs.snowplowanalytics.com/docs/collecting-data/collecting-from-own-applications/tracker-maintenance-classification/
 [early-release]: https://img.shields.io/static/v1?style=flat&label=Snowplow&message=Early%20Release&color=014477&labelColor=9ba0aa&logo=data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAABAAAAAQCAMAAAAoLQ9TAAAAeFBMVEVMaXGXANeYANeXANZbAJmXANeUANSQAM+XANeMAMpaAJhZAJeZANiXANaXANaOAM2WANVnAKWXANZ9ALtmAKVaAJmXANZaAJlXAJZdAJxaAJlZAJdbAJlbAJmQAM+UANKZANhhAJ+EAL+BAL9oAKZnAKVjAKF1ALNBd8J1AAAAKHRSTlMAa1hWXyteBTQJIEwRgUh2JjJon21wcBgNfmc+JlOBQjwezWF2l5dXzkW3/wAAAHpJREFUeNokhQOCA1EAxTL85hi7dXv/E5YPCYBq5DeN4pcqV1XbtW/xTVMIMAZE0cBHEaZhBmIQwCFofeprPUHqjmD/+7peztd62dWQRkvrQayXkn01f/gWp2CrxfjY7rcZ5V7DEMDQgmEozFpZqLUYDsNwOqbnMLwPAJEwCopZxKttAAAAAElFTkSuQmCC
 

data/lib/snowplow-tracker/emitters.rb

@@ -17,7 +17,6 @@
 require 'net/https'
 require 'set'
 require 'logger'
-require 'contracts'
 
 module SnowplowTracker
   # @see Emitter
@@ -38,7 +37,10 @@ module SnowplowTracker
   # | Buffer size | 1 |
   # | Path | `/i` |
   #
-  # The buffer size is 1 because GET requests can only contain one event.
+  # The buffer size is the number of events which will be buffered before they
+  # are all sent simultaneously. The process of sending all buffered events is
+  # called "flushing". The default buffer size is 1 because GET requests can
+  # only contain one event.
   #
   # If you choose to use POST requests, the buffer_size defaults to 10, and the
   # buffered events are all sent together in a single request. The default path
@@ -61,42 +63,15 @@ module SnowplowTracker
   #   require 'logger'
   #   SnowplowTracker::LOGGER.level = Logger::DEBUG
   class Emitter
-    include Contracts
-
-    # Contract types
-
-    # @private
-    CONFIG_HASH = {
-      path: Maybe[String],
-      protocol: Maybe[Or['http', 'https']],
-      port: Maybe[Num],
-      method: Maybe[Or['get', 'post']],
-      buffer_size: Maybe[Num],
-      on_success: Maybe[Func[Num => Any]],
-      on_failure: Maybe[Func[Num, Hash => Any]],
-      thread_count: Maybe[Num],
-      logger: Maybe[Logger]
-    }
-
-    # @private
-    STRICT_CONFIG_HASH = And[CONFIG_HASH, ->(x) {
-                                            (x.class == Hash) && Set.new(x.keys).subset?(Set.new(CONFIG_HASH.keys))
-                                          }]
-
-    # @!group Public constants
-
     # Default Emitter settings
     DEFAULT_CONFIG = {
       protocol: 'http',
       method: 'get'
     }
 
-    # @!endgroup
-
     # @private
     attr_reader :logger
 
-    Contract KeywordArgs[endpoint: String, options: Optional[STRICT_CONFIG_HASH]] => Any
     # Create a new Emitter instance. The endpoint is required.
     #
     # @example Initializing an Emitter with all the possible extra configuration.
@@ -105,7 +80,7 @@ module SnowplowTracker
     #     puts "#{success_count} events sent successfully, #{failures.size} sent unsuccessfully"
     #   end
     #
-    #   Emitter.new(endpoint: 'collector.example.com',
+    #   SnowplowTracker::Emitter.new(endpoint: 'collector.example.com',
     #               options: { path: '/my-pipeline/1',
     #                          protocol: 'https',
     #                          port: 443,
@@ -124,8 +99,8 @@ module SnowplowTracker
     # | port | The port for the connection | Integer |
     # | method | 'get' or 'post' | String |
     # | buffer_size | Number of events to send at once | Integer |
-    # | on_success | A function to call if events were sent successfully | Function |
-    # | on_failure | A function to call if events did not send | Function |
+    # | on_success | A method to call if events were sent successfully | Method |
+    # | on_failure | A method to call if events did not send | Method |
     # | thread_count | Number of threads to use | Integer |
     # | logger | Log somewhere other than STDERR | Logger |
     #
@@ -134,6 +109,13 @@ module SnowplowTracker
     #
     # If you choose to use HTTPS, we recommend using port 443.
     #
+    # Only 2xx and 3xx status codes are considered successes.
+    #
+    # The `on_success` callback should accept one argument: the number of
+    # requests sent this way. The `on_failure` callback should accept two
+    # arguments: the number of successfully sent events, and an array containing
+    # the unsuccessful events.
+    #
     # @param endpoint [String] the endpoint to send the events to
     # @param options [Hash] allowed configuration options
     #
@@ -153,7 +135,6 @@ module SnowplowTracker
       logger.info("#{self.class} initialized with endpoint #{@collector_uri}")
     end
 
-    Contract Hash => Num
     # Creates the `@buffer_size` variable during initialization. Unless
     # otherwise defined, it's 1 for Emitters using GET and 10 for Emitters using
     # POST requests.
@@ -164,7 +145,6 @@ module SnowplowTracker
       config[:method] == 'get' ? 1 : 10
     end
 
-    Contract Hash => String
     # Creates the `@path` variable during initialization. Allows a non-standard
     # path to be provided.
     # @private
@@ -174,9 +154,6 @@ module SnowplowTracker
       config[:method] == 'get' ? '/i' : '/com.snowplowanalytics.snowplow/tp2'
     end
 
-    # Build the collector URI from the configuration hash
-    #
-    Contract String, String, Maybe[Num], String => String
     # Creates the `@collector_uri` variable during initialization.
     # The default is "http://{endpoint}/i".
     # @private
@@ -186,7 +163,6 @@ module SnowplowTracker
       "#{protocol}://#{endpoint}#{port_string}#{path}"
     end
 
-    Contract Hash => nil
     # Add an event to the buffer and flush it if maximum size has been reached.
     # This method is not required for standard Ruby tracker usage. A {Tracker}
     # privately calls this method once the event payload is ready to send.
@@ -197,6 +173,9 @@ module SnowplowTracker
     # to send. You could use {#input} as part of your callback to immediately
     # retry the failed event.
     #
+    # The `on_failure` callback should accept two arguments: the number of
+    # successfully sent events, and an array containing the unsuccessful events.
+    #
     # @example A possible `on_failure` method using `#input`
     #   def retry_on_failure(failed_event_count, failed_events)
     #     # possible backoff-and-retry timeout here
@@ -216,7 +195,6 @@ module SnowplowTracker
       nil
     end
 
-    Contract Bool => nil
     # Flush the Emitter, forcing it to send all the events in its
     # buffer, even if the buffer is not full. {Emitter} objects, unlike
     # {AsyncEmitter}s, can only `flush` synchronously. A {Tracker} can manually flush all
@@ -237,7 +215,6 @@ module SnowplowTracker
       nil
     end
 
-    Contract ArrayOf[Hash] => nil
     # Send all events in the buffer to the collector
     # @private
     def send_requests(events)
@@ -262,7 +239,6 @@ module SnowplowTracker
       nil
     end
 
-    Contract ArrayOf[Hash] => nil
     # Part of {#send_requests}.
     # @private
     def send_requests_with_post(events)
@@ -286,7 +262,6 @@ module SnowplowTracker
       nil
     end
 
-    Contract ArrayOf[Hash] => nil
     # Part of {#send_requests}.
     # @private
     def send_requests_with_get(events)
@@ -307,7 +282,6 @@ module SnowplowTracker
       nil
     end
 
-    Contract Hash => Bool
     # Part of {#send_requests_with_get}.
     # @private
     def process_get_event(event)
@@ -321,7 +295,6 @@ module SnowplowTracker
       get_succeeded
     end
 
-    Contract Hash => ->(x) { x.is_a? Net::HTTPResponse }
     # Part of {#process_get_event}. This sends a GET request.
     # @private
     def http_get(payload)
@@ -339,7 +312,6 @@ module SnowplowTracker
       response
     end
 
-    Contract Hash => ->(x) { x.is_a? Net::HTTPResponse }
     # Part of {#send_requests_with_post}. This sends a POST request.
     # @private
     def http_post(payload)
@@ -359,7 +331,6 @@ module SnowplowTracker
       response
     end
 
-    Contract String => Bool
     # Check if the response is good.
     # Only 2xx and 3xx status codes are considered successes.
     # @private
@@ -381,7 +352,6 @@ module SnowplowTracker
   # @see Emitter
   # @api public
   class AsyncEmitter < Emitter
-    Contract KeywordArgs[endpoint: String, options: Optional[STRICT_CONFIG_HASH]] => Any
     # Create a new AsyncEmitter object. The endpoint is required.
     #
     # @example Initializing an AsyncEmitter with all the possible extra configuration.
@@ -390,7 +360,7 @@ module SnowplowTracker
     #     puts "#{success_count} events sent successfully, #{failures.size} sent unsuccessfully"
     #   end
     #
-    #   Emitter.new(endpoint: 'collector.example.com',
+    #   SnowplowTracker::Emitter.new(endpoint: 'collector.example.com',
     #               options: { path: '/my-pipeline/1',
     #                          protocol: 'https',
     #                          port: 443,
@@ -420,6 +390,13 @@ module SnowplowTracker
     #
     # If you choose to use HTTPS, we recommend using port 443.
     #
+    # Only 2xx and 3xx status codes are considered successes.
+    #
+    # The `on_success` callback should accept one argument: the number of
+    # requests sent this way. The `on_failure` callback should accept two
+    # arguments: the number of successfully sent events, and an array containing
+    # the unsuccessful events.
+    #
     # @note if you test the AsyncEmitter by using a short script to send an
     #   event, you may find that the event fails to send. This is because the
     #   process exits before the flushing thread is finished. You can get round

data/lib/snowplow-tracker/page.rb

@@ -14,8 +14,6 @@
 # License:: Apache License Version 2.0
 
 
-require 'contracts'
-
 module SnowplowTracker
   # If the Ruby tracker is incorporated into a website server, the events
   # tracked will describe user activity on specific webpages. Knowing on which
@@ -33,18 +31,15 @@ module SnowplowTracker
   # @note For {Tracker#track_page_view}, properties set in the Page object will
   #   override those properties given as arguments.
   class Page
-    include Contracts
-
     # @return [Hash] the stored page properties
     attr_reader :details
 
-    Contract KeywordArgs[page_url: Maybe[String], page_title: Maybe[String], referrer: Maybe[String]] => Any
     # Create a Page object for attaching page properties to events.
     #
     # Page properties will directly populate the event's `page_url`, `page_title` and `referrer` parameters.
     #
     # @example Creating a Page
-    #   Page.new(page_url: 'http://www.example.com/second-page',
+    #   SnowplowTracker::Page.new(page_url: 'http://www.example.com/second-page',
     #            page_title: 'Example title',
     #            referrer: 'http://www.example.com/first-page')
     #

data/lib/snowplow-tracker/payload.rb

@@ -17,7 +17,6 @@
 require 'base64'
 require 'json'
 require 'net/http'
-require 'contracts'
 
 module SnowplowTracker
   # @private
@@ -26,28 +25,22 @@ module SnowplowTracker
   # hash. These properties form the raw event, after the completed hash is
   # given to the Emitter.
   class Payload
-    include Contracts
-
     attr_reader :data
 
-    Contract nil => Any
     def initialize
       @data = {}
     end
 
-    Contract String, Or[String, Bool, Num, nil] => Or[String, Bool, Num, nil]
     # Add a single name-value pair to @data.
     def add(name, value)
       @data[name] = value if (value != '') && !value.nil?
     end
 
-    Contract Hash => Hash
     # Add each name-value pair in a hash to @data.
     def add_hash(hash)
       hash.each { |key, value| add(key, value) }
     end
 
-    Contract Maybe[Hash], Bool, String, String => Maybe[String]
     # Stringify a JSON and add it to @data.
     #
     # In practice, the JSON provided will be a SelfDescribingJson. This method

data/lib/snowplow-tracker/self_describing_json.rb

@@ -77,7 +77,7 @@ module SnowplowTracker
   #   # Creating the SelfDescribingJson
   #   schema_name = "iglu:com.snowplowanalytics/ad_click/jsonschema/1-0-0"
   #   event_data = { bannerId: "4acd518feb82" }
-  #   SelfDescribingJson.new(schema_name, event_data)
+  #   SnowplowTracker::SelfDescribingJson.new(schema_name, event_data)
   #
   #   # The self-describing JSON that will be sent (stringified) with the event
   #   {

data/lib/snowplow-tracker/subject.rb

@@ -14,8 +14,6 @@
 # License:: Apache License Version 2.0
 
 
-require 'contracts'
-
 module SnowplowTracker
   # Subject objects store information about the user associated with the event,
   # such as their `user_id`, what type of device they used, or what size screen
@@ -68,7 +66,7 @@ module SnowplowTracker
   #
   # Since many of the Subject parameters describe the user, different Subject
   # properties may often be desired for each event, if there are multiple users.
-  # This can be achieved in one of two ways:
+  # This can be achieved in one of three ways:
   #
   # 1. the properties of the Tracker-associated Subject can be overriden by the
   #    properties of an event-specific Subject. A Subject can be added to any
@@ -76,19 +74,22 @@ module SnowplowTracker
   #    set the platform for the event Subject if you're not using `srv`.
   # 2. the Tracker-associated Subject can be swapped for another Subject, using
   #    the Tracker method {Tracker#set_subject}.
+  # 3. the properties of the Tracker-associated Subject can be changed before
+  #    every `#track_x_event`, by calling the Subject methods via the Tracker.
   #
   # @see Tracker#set_subject
   # @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/collecting-data/collecting-from-own-applications/ruby-tracker/enriching-your-events/
+  #   the Snowplow docs page about adding context and other extra data to events
   # @api public
   #
   # @note All the Subject instance methods return the Subject object, allowing
   #   method chaining, e.g.
-  #   `Subject.new.set_timezone('Europe/London').set_user_id('12345')`
+  #   `SnowplowTracker::Subject.new.set_timezone('Europe/London').set_user_id('12345')`
   class Subject
-    include Contracts
-
     # @private
     DEFAULT_PLATFORM = 'srv'
 
@@ -108,22 +109,22 @@ module SnowplowTracker
 
     # Access the Subject parameters
     # @example
-    #   Subject.new.set_user_id('12345').details
+    #   SnowplowTracker::Subject.new.set_user_id('12345').details
     #   => {"p"=>"srv", "uid"=>"12345"}
     # @api public
     attr_reader :details
 
-    Contract None => Any
     # @api public
     def initialize
       @details = { 'p' => DEFAULT_PLATFORM }
     end
 
-    Contract String => Subject
     # Set the platform to one of the supported platform values.
     # @note Value is sent in the event as `p` (raw event) or `platform` (processed event).
     # @see Subject::SUPPORTED_PLATFORMS
     # @param [String] platform a valid platform choice
+    # @example
+    #   subject.set_platform('app')
     # @return self
     # @api public
     def set_platform(platform)
@@ -133,7 +134,6 @@ module SnowplowTracker
       self
     end
 
-    Contract String => Subject
     # Set the unique business-defined user ID for a user.
     # @note Value is sent in the event as `uid` (raw event) or `user_id` (processed event).
     # For example, an email address.
@@ -152,45 +152,49 @@ module SnowplowTracker
       self
     end
 
-    Contract Num => Subject
     # Set a business-defined fingerprint for a user.
     # @note Value is sent in the event as `fp` (raw event) or `user_fingerprint` (processed event).
     # @param [Num] fingerprint a user fingerprint
     # @return self
+    # @example
+    #   subject.set_fingerprint(4048966212)
     # @api public
     def set_fingerprint(fingerprint)
       @details['fp'] = fingerprint
       self
     end
 
-    Contract KeywordArgs[width: Num, height: Num] => Subject
     # Set the device screen resolution.
     # @note Value is sent in the event as `res` (raw event) or `dvce_screenheight` and `dvce_screenwidth` (processed event).
-    # @param [Num] width the screen width, in pixels (must be a positive integer)
-    # @param [Num] height the screen height, in pixels (must be a positive integer)
+    # @param [Integer] width the screen width, in pixels (must be a positive integer)
+    # @param [Integer] height the screen height, in pixels (must be a positive integer)
     # @return self
+    # @example
+    #   subject.set_screen_resolution(width: 2880, height: 1800)
     # @api public
     def set_screen_resolution(width:, height:)
       @details['res'] = "#{width}x#{height}"
       self
     end
 
-    Contract KeywordArgs[width: Num, height: Num] => Subject
     # Set the dimensions of the current viewport.
     # @note Value is sent in the event as `vp` (raw event) or `br_viewwidth` and `br_viewheight` (processed event).
-    # @param [Num] width the viewport width, in pixels (must be a positive integer)
-    # @param [Num] height the viewport height, in pixels (must be a positive integer)
+    # @param [Integer] width the viewport width, in pixels (must be a positive integer)
+    # @param [Integer] height the viewport height, in pixels (must be a positive integer)
     # @return self
+    # @example
+    #   subject.set_viewport(width: 1440, height: 762)
     # @api public
     def set_viewport(width:, height:)
       @details['vp'] = "#{width}x#{height}"
       self
     end
 
-    Contract Num => Subject
-    # Set the color depth of the device, in bits per pixel.
+    # Set the color depth of the browser, in bits per pixel.
     # @note Value is sent in the event as `cd` (raw event) or `br_colordepth` (processed event).
     # @param [Num] depth the colour depth
+    # @example
+    #   subject.set_color_depth(24)
     # @return self
     # @api public
     def set_color_depth(depth)
@@ -198,7 +202,6 @@ module SnowplowTracker
       self
     end
 
-    Contract String => Subject
     # Set the timezone to that of the user's OS.
     # @note Value is sent in the event as `tz` (raw event) or `os_timezone` (processed event).
     # @example
@@ -211,7 +214,6 @@ module SnowplowTracker
       self
     end
 
-    Contract String => Subject
     # Set the language.
     # @note Value is sent in the event as `lang` (raw event) or `br_lang` (processed event).
     # @example Setting the language to Spanish
@@ -224,7 +226,6 @@ module SnowplowTracker
       self
     end
 
-    Contract String => Subject
     # Set the domain user ID.
     # @note Value is sent in the event as `duid` (raw event) or `domain_userid` (processed event).
     # @see Subject#set_network_user_id
@@ -260,7 +261,6 @@ module SnowplowTracker
       self
     end
 
-    Contract String => Subject
     # Set the domain session ID.
     # @note Value is sent in the event as `sid` (raw event) or `domain_sessionid` (processed event).
     # @see Subject#set_network_user_id
@@ -283,7 +283,6 @@ module SnowplowTracker
       self
     end
 
-    Contract Num => Subject
     # Set the domain session index.
     # @note Value is sent in the event as `vid` (raw event) or `domain_sessionidx` (processed event).
     # @see Subject#set_network_user_id
@@ -307,18 +306,18 @@ module SnowplowTracker
       self
     end
 
-    Contract String => Subject
     # Set the user's IP address.
     # @note Value is sent in the event as `ip` (raw event) or `user_ipaddress` (processed event).
     # @param [String] ip the IP address
     # @return self
+    # @example
+    #   subject.set_ip_address('37.157.33.178')
     # @api public
     def set_ip_address(ip)
       @details['ip'] = ip
       self
     end
 
-    Contract String => Subject
     # Set the browser user agent.
     # @note Value is sent in the event as `ua` (raw event) or `useragent` (processed event).
     # @example
@@ -331,7 +330,6 @@ module SnowplowTracker
       self
     end
 
-    Contract String => Subject
     # Set the network user ID.
     # @note Value is sent in the event as `tnuid` (raw event) and `network_userid` (processed event).
     # @see Subject#set_domain_user_id

data/lib/snowplow-tracker/timestamp.rb

@@ -38,41 +38,39 @@ module SnowplowTracker
   #    DeviceTimestamp by the Tracker, and will still be recorded as `dtm` in
   #    the event.
   # 2. Manually create a DeviceTimestamp (e.g.
-  #    `DeviceTimestamp.new(1633596554978)`), and provide this to the
+  #    `SnowplowTracker::DeviceTimestamp.new(1633596554978)`), and provide this to the
   #    `#track_x_event` method. This will still be recorded as `dtm` in the
   #    event.
   # 3. Provide a TrueTimestamp object to the `track_x_event` method (e.g.
-  #    `TrueTimestamp.new(1633596554978)`). This will result in a `ttm` field in
+  #    `SnowplowTracker::TrueTimestamp.new(1633596554978)`). This will result in a `ttm` field in
   #    the event.
   #
   # The timestamps that are added to the event once it has been emitted are not
   # the responsibility of this class. The collector receives the event and adds a
   # `collector_tstamp`. A later part of the pipeline adds the `etl_tstamp` when
-  # the event enrichment has finished. A `derived_tstamp` is also calculated and
-  # added to the event, which represents how long it took the event to be
-  # processed. This is calculated by `collector_tstamp - (dvce_sent_tstamp -
-  # dvce_created_tstamp)`.
+  # the event enrichment has finished.
+  #
+  # When DeviceTimestamp is used, a `derived_tstamp` is also calculated and
+  # added to the event. This timestamp attempts to take latency and possible
+  # inaccuracy of the device clock into account. It is calculated by
+  # `collector_tstamp - (dvce_sent_tstamp - dvce_created_tstamp)`. When
+  # TrueTimestamp is used, the `derived_stamp` will be the same as
+  # `true_tstamp`.
   #
   # @see
   #   https://docs.snowplowanalytics.com/docs/collecting-data/collecting-from-own-applications/snowplow-tracker-protocol
   #   the Snowplow Tracker Protocol
+  # @see
+  #   https://discourse.snowplowanalytics.com/t/which-timestamp-is-the-best-to-see-when-an-event-occurred/538
+  #   A Discourse forums post explaining timestamps
   # @api public
   class Timestamp
-    include Contracts
-
     # @private
     attr_reader :type
 
     # @private
     attr_reader :value
 
-    # @private
-    # Contract type
-    TIMESTAMP = ->(x) {
-      return false unless x.is_a? Integer
-      x.to_s.length == 13
-    }
-
     # @private
     def initialize(type, value)
       @type = type
@@ -92,10 +90,9 @@ module SnowplowTracker
   # it is, namely `ttm`. This raw event `ttm` field will be processed into
   # `true_tstamp` in the completed event.
   class TrueTimestamp < Timestamp
-    Contract TIMESTAMP => Any
     # @param [Num] value timestamp in milliseconds since the Unix epoch
     # @example
-    #   TrueTimestamp.new(1633596346786)
+    #   SnowplowTracker::TrueTimestamp.new(1633596346786)
     def initialize(value)
       super 'ttm', value
     end
@@ -107,10 +104,9 @@ module SnowplowTracker
   # it is, namely `dtm`. This raw event `dtm` field will be processed into
   # `dvce_created_tstamp` in the completed event.
   class DeviceTimestamp < Timestamp
-    Contract TIMESTAMP => Any
     # @param [Num] value timestamp in milliseconds since the Unix epoch
     # @example
-    #   DeviceTimestamp.new(1633596346786)
+    #   SnowplowTracker::DeviceTimestamp.new(1633596346786)
     def initialize(value)
       super 'dtm', value
     end

data/lib/snowplow-tracker/tracker.rb

@@ -14,7 +14,6 @@
 # License:: Apache License Version 2.0
 
 
-require 'contracts'
 require 'securerandom'
 require 'set'
 
@@ -118,62 +117,16 @@ module SnowplowTracker
   #   https://docs.snowplowanalytics.com/docs/collecting-data/collecting-from-own-applications/snowplow-tracker-protocol
   #   the Snowplow Tracker Protocol
   # @see
+  #   https://docs.snowplowanalytics.com/docs/collecting-data/collecting-from-own-applications/ruby-tracker/tracking-events/
+  #   the Snowplow docs page about tracking events
+  # @see
+  #   https://docs.snowplowanalytics.com/docs/collecting-data/collecting-from-own-applications/ruby-tracker/enriching-your-events/
+  #   the Snowplow docs page about adding context and other extra data to events
+  # @see
   #   https://docs.snowplowanalytics.com/docs/understanding-tracking-design/introduction-to-tracking-design/
   #   introduction to Snowplow tracking design
   # @api public
   class Tracker
-    include Contracts
-
-    # Contract types
-
-    # @private
-    EMITTER_INPUT = Or[->(x) { x.is_a? Emitter }, ArrayOf[->(x) { x.is_a? Emitter }]]
-
-    # @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.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])
-
-    # @private
-    ITEM = ->(x) {
-      return false unless x.class == Hash
-      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])
-
-    # @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) &&
-        augmented_item_keys.subset?(RECOGNISED_AUGMENTED_ITEM_KEYS)
-    }
-
-    # @private
-    CONTEXTS_INPUT = ArrayOf[SelfDescribingJson]
-
-    # Other constants
-
     # @!group Public constants
 
     # SelfDescribingJson objects are sent encoded by default
@@ -192,8 +145,6 @@ module SnowplowTracker
 
     # @!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
@@ -202,14 +153,18 @@ module SnowplowTracker
     # @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,
+    #   SnowplowTracker::Tracker.new(
+    #               emitters: SnowplowTracker::Emitter.new(endpoint: 'collector.example.com'),
+    #               subject: SnowplowTracker::Subject.new,
     #               namespace: 'tracker_no_encode',
     #               app_id: 'rails_main',
     #               encode_base64: false
     #              )
     # @api public
+    #
+    # @note All the Tracker instance methods return the Tracker object, allowing
+    #   method chaining, e.g.
+    #   `SnowplowTracker::Tracker.new.set_user_id('12345').track_page_view(page_url: 'www.example.com`
     def initialize(emitters:, subject: nil, namespace: nil, app_id: nil, encode_base64: DEFAULT_ENCODE_BASE64)
       @emitters = Array(emitters)
       @subject = if subject.nil?
@@ -269,14 +224,12 @@ module SnowplowTracker
       end
     end
 
-    Contract nil => String
     # Generates a type-4 UUID to identify this event
     # @private
     def event_id
       SecureRandom.uuid
     end
 
-    Contract CONTEXTS_INPUT => Hash
     # Builds a single self-describing JSON from an array of custom contexts
     # @private
     def build_context(context)
@@ -286,7 +239,6 @@ module SnowplowTracker
       ).to_json
     end
 
-    Contract Payload => nil
     # Sends the payload hash as a request to the Emitter(s)
     # @private
     def track(payload)
@@ -295,7 +247,6 @@ module SnowplowTracker
       nil
     end
 
-    Contract Or[Timestamp, Num, nil] => Timestamp
     # Ensures that either a DeviceTimestamp or TrueTimestamp is associated with
     # every event.
     # @private
@@ -305,7 +256,6 @@ module SnowplowTracker
       tstamp
     end
 
-    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`.
@@ -329,10 +279,11 @@ module SnowplowTracker
       nil
     end
 
-    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.
+    # @example
+    #   SnowplowTracker::Tracker.new.track_page_view(page_url: 'www.example.com',
+    #                                                page_title: 'example',
+    #                                                referrer: 'www.referrer.com')
     #
     # @param page_url [String] the URL of the page
     # @param page_title [String] the page title
@@ -359,9 +310,6 @@ module SnowplowTracker
       self
     end
 
-    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,
@@ -482,7 +430,6 @@ module SnowplowTracker
       hash.keys.each { |key| hash[key.to_s] = hash.delete key }
     end
 
-    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)
@@ -502,10 +449,6 @@ module SnowplowTracker
       self
     end
 
-    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.
     #
     # This event type can be used to track many types of user activity, as it is
@@ -516,6 +459,15 @@ module SnowplowTracker
     # For fully customizable event tracking, we recommend you use
     # self-describing events.
     #
+    # @example
+    #   SnowplowTracker::Tracker.new.track_struct_event(
+    #     category: 'shop',
+    #     action: 'add-to-basket',
+    #     property: 'pcs',
+    #     value: 2
+    #   )
+    #
+    #
     # @see #track_self_describing_event
     #
     # @param category [String] the event category
@@ -547,9 +499,6 @@ module SnowplowTracker
       self
     end
 
-    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.
@@ -560,6 +509,11 @@ module SnowplowTracker
     # "iglu:com.snowplowanalytics.snowplow/screen_view/jsonschema/1-0-0", and
     # the data field will contain the name and/or ID.
     #
+    # @example
+    #   SnowplowTracker::Tracker.new.track_screen_view(name: 'HUD > Save Game',
+    #                                                  id: 'screen23')
+    #
+    #
     # @see #track_page_view
     # @see #track_self_describing_event
     #
@@ -583,9 +537,6 @@ module SnowplowTracker
       self
     end
 
-    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.
     #
@@ -595,6 +546,20 @@ module SnowplowTracker
     # This method creates an `unstruct` event type. It is actually an alias for
     # {#track_unstruct_event}, which is depreciated due to its unhelpful name.
     #
+    # @example
+    #   self_desc_json = SnowplowTracker::SelfDescribingJson.new(
+    #     "iglu:com.example_company/save_game/jsonschema/1-0-2",
+    #     {
+    #       "saveId" => "4321",
+    #       "level" => 23,
+    #       "difficultyLevel" => "HARD",
+    #       "dlContent" => true
+    #     }
+    #   )
+    #
+    #   SnowplowTracker::Tracker.new.track_self_describing_event(event_json: self_desc_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
@@ -607,9 +572,6 @@ module SnowplowTracker
                            tstamp: tstamp, subject: subject, page: page)
     end
 
-    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
@@ -628,7 +590,6 @@ module SnowplowTracker
       self
     end
 
-    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
@@ -645,7 +606,6 @@ module SnowplowTracker
       self
     end
 
-    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.
@@ -658,7 +618,6 @@ module SnowplowTracker
       self
     end
 
-    Contract Emitter => Tracker
     # Add a new Emitter to the internal array of Tracker-associated Emitters.
     #
     # @param emitter [Emitter] an Emitter object

data/lib/snowplow-tracker/version.rb

@@ -24,13 +24,6 @@
 # see an example of how to incorporate the Snowplow Ruby tracker in Ruby on
 # Rails app.
 #
-# # Type checking
-#
-# This gem uses the [Contracts](https://github.com/egonSchiele/contracts.ruby)
-# gem for typechecking. This cannot be disabled. The {Tracker} `track_x_event`
-# methods expect arguments of a certain type. If a check fails, a runtime error
-# is thrown.
-#
 # @see https://github.com/snowplow/snowplow-ruby-tracker
 #   Ruby tracker on Github
 # @see https://github.com/snowplow-incubator/snowplow-ruby-tracker-examples
@@ -41,7 +34,7 @@
 # @api public
 module SnowplowTracker
   # The version of Ruby Snowplow tracker you are using
-  VERSION = '0.7.0'
+  VERSION = '0.8.0'
 
   # All events from this tracker will have this string
   TRACKER_VERSION = "rb-#{VERSION}"

metadata

@@ -1,35 +1,15 @@
 --- !ruby/object:Gem::Specification
 name: snowplow-tracker
 version: !ruby/object:Gem::Version
-  version: 0.7.0
+  version: 0.8.0
 platform: ruby
 authors:
 - Snowplow Analytics Ltd
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2021-10-14 00:00:00.000000000 Z
+date: 2021-10-29 00:00:00.000000000 Z
 dependencies:
-- !ruby/object:Gem::Dependency
-  name: contracts
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '0.7'
-    - - "<"
-      - !ruby/object:Gem::Version
-        version: '0.17'
-  type: :runtime
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '0.7'
-    - - "<"
-      - !ruby/object:Gem::Version
-        version: '0.17'
 - !ruby/object:Gem::Dependency
   name: rspec
   requirement: !ruby/object:Gem::Requirement