Add support for attaching true timestamp to events (closes #94)

lib/snowplow-tracker.rb

@@ -19,4 +19,6 @@
 require 'snowplow-tracker/payload.rb'
 require 'snowplow-tracker/subject.rb'
 require 'snowplow-tracker/emitters.rb'
+require 'snowplow-tracker/timestamp.rb'
 require 'snowplow-tracker/tracker.rb'
+

lib/snowplow-tracker/timestamp.rb

@@ -0,0 +1,46 @@
+# Copyright (c) 2016 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.
+# You may obtain a copy of the Apache License Version 2.0 at http://www.apache.org/licenses/LICENSE-2.0.
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the Apache License Version 2.0 is distributed on an
+# "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, Ed Lewis (mailto:support@snowplowanalytics.com)
+# Copyright:: Copyright (c) 2016 Snowplow Analytics Ltd
+# License:: Apache License Version 2.0
+
+module SnowplowTracker
+
+    class Timestamp
+
+        attr_reader :type
+        attr_reader :value
+
+        def initialize(type, value)
+            @type = type
+            @value = value
+        end
+
+    end
+
+    class TrueTimestamp < Timestamp
+
+        def initialize(value) 
+            super 'ttm', value
+        end
+
+    end
+
+    class DeviceTimestamp < Timestamp
+
+        def initialize(value) 
+            super 'dtm', value
+        end
+
+    end
+
+end

lib/snowplow-tracker/tracker.rb

@@ -133,23 +133,33 @@ def track(pb)
       nil
     end
 
-    # Log a visit to this page
+    # 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))  
+    end
+
+    # Log a visit to this page
+    #
+    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')
       end
 
-      if tstamp.nil?
-        tstamp = get_timestamp
-      end
-      pb.add('dtm', tstamp)
+      pb.add(tstamp.type, tstamp.value)
+
       track(pb)
 
       self
@@ -172,15 +182,29 @@ def track_ecommerce_transaction_item(argmap)
       unless argmap['context'].nil?
         pb.add_json(build_context(argmap['context']), @config['encode_base64'], 'cx', 'co')
       end
-      pb.add('dtm', argmap['tstamp'])
+      pb.add(argmap['tstamp'].type, argmap['tstamp'].value)
       track(pb)
 
       self
     end
 
     # 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
+
+      track_ecommerce_transaction(transaction, items, context, DeviceTimestamp.new(tstamp))
+    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
@@ -198,10 +222,7 @@ def track_ecommerce_transaction(transaction, items,
         pb.add_json(build_context(context), @config['encode_base64'], 'cx', 'co')
       end
 
-      if tstamp.nil?
-        tstamp = get_timestamp
-      end
-      pb.add('dtm', tstamp)
+      pb.add(tstamp.type, tstamp.value)
 
       track(pb)
 
@@ -216,8 +237,18 @@ def track_ecommerce_transaction(transaction, items,
     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))
+    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')
@@ -229,18 +260,16 @@ def track_struct_event(category, action, label=nil, property=nil, value=nil, con
       unless context.nil?
         pb.add_json(build_context(context), @config['encode_base64'], 'cx', 'co')
       end
-      if tstamp.nil?
-        tstamp = get_timestamp
-      end
-      pb.add('dtm', tstamp)
+
+      pb.add(tstamp.type, tstamp.value)
       track(pb)
 
       self
     end
 
     # Track a screen view event
     #
-    Contract Maybe[String], Maybe[String],  Maybe[@@ContextsInput], Maybe[Num] => Tracker
+    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? 
@@ -260,14 +289,32 @@ def track_screen_view(name=nil, id=nil, context=nil, tstamp=nil)
 
     # Better name for track unstruct 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
 
     # 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
+
+      track_unstruct_event(event_json, context, DeviceTimestamp.new(tstamp))
+    end
+
+    # Track an unstructured event
+    #
+    Contract SelfDescribingJson, Maybe[@@ContextsInput], Timestamp => Tracker
     def track_unstruct_event(event_json, context=nil, tstamp=nil)
       pb = Payload.new
       pb.add('e', 'ue')
@@ -280,10 +327,7 @@ def track_unstruct_event(event_json, context=nil, tstamp=nil)
         pb.add_json(build_context(context), @config['encode_base64'], 'cx', 'co')
       end
 
-      if tstamp.nil?
-        tstamp = get_timestamp
-      end
-      pb.add('dtm', tstamp)
+      pb.add(tstamp.type, tstamp.value)
 
       track(pb)