Add support for attaching true timestamp for events (closes #196)

snowplow-tracker/src/androidTest/java/com/snowplowanalytics/snowplow/tracker/EmitterTest.java

@@ -192,7 +192,7 @@ private JSONObject assertPOSTRequest(RecordedRequest req) throws JSONException {
         JSONObject payload = new JSONObject(req.getBody().readUtf8());
         assertEquals(2, payload.length());
         assertEquals(
-                "iglu:com.snowplowanalytics.snowplow/payload_data/jsonschema/1-0-3",
+                "iglu:com.snowplowanalytics.snowplow/payload_data/jsonschema/1-0-4",
                 payload.getString("schema")
         );
 

snowplow-tracker/src/androidTest/java/com/snowplowanalytics/snowplow/tracker/events/StructuredTest.java

@@ -43,6 +43,9 @@ public void testExpectedForm() {
                 .label("some label")
                 .property("some property")
                 .value(123.56700)
+                .timestamp(123456789)
+                .deviceCreatedTimestamp(987654321)
+                .trueTimestamp(123456789)
                 .build();
 
         data = structured.getPayload().getMap();
@@ -54,6 +57,8 @@ public void testExpectedForm() {
         assertEquals("some label", data.get(Parameters.SE_LABEL));
         assertEquals("some property", data.get(Parameters.SE_PROPERTY));
         assertEquals("123.567", data.get(Parameters.SE_VALUE));
+        assertEquals("987654321", data.get(Parameters.DEVICE_TIMESTAMP));
+        assertEquals("123456789", data.get(Parameters.TRUE_TIMESTAMP));
     }
 
     public void testBuilderFailures() {

snowplow-tracker/src/androidTest/java/com/snowplowanalytics/snowplow/tracker/integration/EventSendingTest.java

@@ -233,7 +233,7 @@ public void checkPostRequest(LinkedList<RecordedRequest> requests) throws Except
             assertEquals("POST", request.getMethod());
 
             JSONObject body = new JSONObject(request.getBody().readUtf8());
-            assertEquals("iglu:com.snowplowanalytics.snowplow/payload_data/jsonschema/1-0-3", body.getString("schema"));
+            assertEquals("iglu:com.snowplowanalytics.snowplow/payload_data/jsonschema/1-0-4", body.getString("schema"));
 
             JSONArray data = body.getJSONArray("data");
             for (int i = 0; i < data.length(); i++) {
@@ -345,29 +345,29 @@ public void checkUnstructuredEvent(JSONObject json) throws Exception {
     public void trackPageView(Tracker tracker) throws Exception {
         tracker.track(PageView.builder().pageUrl("pageUrl").pageTitle("pageTitle").referrer("pageReferrer").build());
         tracker.track(PageView.builder().pageUrl("pageUrl").pageTitle("pageTitle").referrer("pageReferrer").customContext(getCustomContext()).build());
-        tracker.track(PageView.builder().pageUrl("pageUrl").pageTitle("pageTitle").referrer("pageReferrer").timestamp((long) 1433791172).build());
-        tracker.track(PageView.builder().pageUrl("pageUrl").pageTitle("pageTitle").referrer("pageReferrer").timestamp((long) 1433791172).customContext(getCustomContext()).build());
+        tracker.track(PageView.builder().pageUrl("pageUrl").pageTitle("pageTitle").referrer("pageReferrer").deviceCreatedTimestamp((long) 1433791172).build());
+        tracker.track(PageView.builder().pageUrl("pageUrl").pageTitle("pageTitle").referrer("pageReferrer").deviceCreatedTimestamp((long) 1433791172).customContext(getCustomContext()).build());
     }
 
     public void trackStructuredEvent(Tracker tracker) throws Exception {
         tracker.track(Structured.builder().category("category").action("action").label("label").property("property").value(0.00).build());
         tracker.track(Structured.builder().category("category").action("action").label("label").property("property").value(0.00).customContext(getCustomContext()).build());
-        tracker.track(Structured.builder().category("category").action("action").label("label").property("property").value(0.00).timestamp((long) 1433791172).build());
-        tracker.track(Structured.builder().category("category").action("action").label("label").property("property").value(0.00).timestamp((long) 1433791172).customContext(getCustomContext()).build());
+        tracker.track(Structured.builder().category("category").action("action").label("label").property("property").value(0.00).deviceCreatedTimestamp((long) 1433791172).build());
+        tracker.track(Structured.builder().category("category").action("action").label("label").property("property").value(0.00).deviceCreatedTimestamp((long) 1433791172).customContext(getCustomContext()).build());
     }
 
     public void trackScreenView(Tracker tracker) throws Exception {
         tracker.track(ScreenView.builder().name("screenName").id("screenId").build());
         tracker.track(ScreenView.builder().name("screenName").id("screenId").customContext(getCustomContext()).build());
-        tracker.track(ScreenView.builder().name("screenName").id("screenId").timestamp((long) 1433791172).build());
-        tracker.track(ScreenView.builder().name("screenName").id("screenId").timestamp((long) 1433791172).customContext(getCustomContext()).build());
+        tracker.track(ScreenView.builder().name("screenName").id("screenId").deviceCreatedTimestamp((long) 1433791172).build());
+        tracker.track(ScreenView.builder().name("screenName").id("screenId").deviceCreatedTimestamp((long) 1433791172).customContext(getCustomContext()).build());
     }
 
     public void trackTimings(Tracker tracker) throws Exception {
         tracker.track(Timing.builder().category("category").variable("variable").timing(1).label("label").build());
         tracker.track(Timing.builder().category("category").variable("variable").timing(1).label("label").customContext(getCustomContext()).build());
-        tracker.track(Timing.builder().category("category").variable("variable").timing(1).label("label").timestamp((long) 1433791172).build());
-        tracker.track(Timing.builder().category("category").variable("variable").timing(1).label("label").timestamp((long) 1433791172).customContext(getCustomContext()).build());
+        tracker.track(Timing.builder().category("category").variable("variable").timing(1).label("label").deviceCreatedTimestamp((long) 1433791172).build());
+        tracker.track(Timing.builder().category("category").variable("variable").timing(1).label("label").deviceCreatedTimestamp((long) 1433791172).customContext(getCustomContext()).build());
     }
 
     public void trackUnstructuredEvent(Tracker tracker) throws Exception {
@@ -376,8 +376,8 @@ public void trackUnstructuredEvent(Tracker tracker) throws Exception {
         SelfDescribingJson test = new SelfDescribingJson("iglu:com.snowplowanalytics.snowplow/test_sdj/jsonschema/1-0-1", attributes);
         tracker.track(SelfDescribing.builder().eventData(test).build());
         tracker.track(SelfDescribing.builder().eventData(test).customContext(getCustomContext()).build());
-        tracker.track(SelfDescribing.builder().eventData(test).timestamp((long) 1433791172).build());
-        tracker.track(SelfDescribing.builder().eventData(test).timestamp((long) 1433791172).customContext(getCustomContext()).build());
+        tracker.track(SelfDescribing.builder().eventData(test).deviceCreatedTimestamp((long) 1433791172).build());
+        tracker.track(SelfDescribing.builder().eventData(test).deviceCreatedTimestamp((long) 1433791172).customContext(getCustomContext()).build());
     }
 
     public void trackEcommerceEvent(Tracker tracker) throws Exception {
@@ -386,8 +386,8 @@ public void trackEcommerceEvent(Tracker tracker) throws Exception {
         items.add(item);
         tracker.track(EcommerceTransaction.builder().orderId("order-1").totalValue(42.50).affiliation("affiliation").taxValue(2.50).shipping(5.00).city("Sydney").state("NSW").country("Australia").currency("AUD").items(items).build());
         tracker.track(EcommerceTransaction.builder().orderId("order-1").totalValue(42.50).affiliation("affiliation").taxValue(2.50).shipping(5.00).city("Sydney").state("NSW").country("Australia").currency("AUD").items(items).customContext(getCustomContext()).build());
-        tracker.track(EcommerceTransaction.builder().orderId("order-1").totalValue(42.50).affiliation("affiliation").taxValue(2.50).shipping(5.00).city("Sydney").state("NSW").country("Australia").currency("AUD").items(items).timestamp((long) 1433791172).build());
-        tracker.track(EcommerceTransaction.builder().orderId("order-1").totalValue(42.50).affiliation("affiliation").taxValue(2.50).shipping(5.00).city("Sydney").state("NSW").country("Australia").currency("AUD").items(items).timestamp((long) 1433791172).customContext(getCustomContext()).build());
+        tracker.track(EcommerceTransaction.builder().orderId("order-1").totalValue(42.50).affiliation("affiliation").taxValue(2.50).shipping(5.00).city("Sydney").state("NSW").country("Australia").currency("AUD").items(items).deviceCreatedTimestamp((long) 1433791172).build());
+        tracker.track(EcommerceTransaction.builder().orderId("order-1").totalValue(42.50).affiliation("affiliation").taxValue(2.50).shipping(5.00).city("Sydney").state("NSW").country("Australia").currency("AUD").items(items).deviceCreatedTimestamp((long) 1433791172).customContext(getCustomContext()).build());
     }
 
     public List<SelfDescribingJson> getCustomContext() {

snowplow-tracker/src/main/java/com/snowplowanalytics/snowplow/tracker/Tracker.java

@@ -319,7 +319,7 @@ public void run() {
                     // Track each item individually
                     EcommerceTransaction ecommerceTransaction = (EcommerceTransaction) event;
                     for(EcommerceTransactionItem item : ecommerceTransaction.getItems()) {
-                        item.setTimestamp(ecommerceTransaction.getTimestamp());
+                        item.setDeviceCreatedTimestamp(ecommerceTransaction.getDeviceCreatedTimestamp());
                         addEventPayload(item.getPayload(), item.getContext(), item.getEventId());
                     }
                 } else if (eClass.equals(SelfDescribing.class)) {
@@ -332,7 +332,7 @@ public void run() {
                     SelfDescribing selfDescribing = SelfDescribing.builder()
                             .eventData((SelfDescribingJson) event.getPayload())
                             .customContext(context)
-                            .timestamp(event.getTimestamp())
+                            .deviceCreatedTimestamp(event.getDeviceCreatedTimestamp())
                             .eventId(event.getEventId())
                             .build();
 

snowplow-tracker/src/main/java/com/snowplowanalytics/snowplow/tracker/constants/Parameters.java

@@ -24,7 +24,10 @@ public class Parameters {
     public static final String DATA = "data";
     public static final String EVENT = "e";
     public static final String EID = "eid";
+    @Deprecated
     public static final String TIMESTAMP = "dtm";
+    public static final String DEVICE_TIMESTAMP = "dtm";
+    public static final String TRUE_TIMESTAMP = "ttm";
     public static final String SENT_TIMESTAMP = "stm";
     public static final String TRACKER_VERSION = "tv";
     public static final String APPID = "aid";

snowplow-tracker/src/main/java/com/snowplowanalytics/snowplow/tracker/constants/TrackerConstants.java

@@ -21,7 +21,7 @@ public class TrackerConstants {
     public static final String PROTOCOL_VENDOR = "com.snowplowanalytics.snowplow";
     public static final String PROTOCOL_VERSION = "tp2";
 
-    public static final String SCHEMA_PAYLOAD_DATA = "iglu:com.snowplowanalytics.snowplow/payload_data/jsonschema/1-0-3";
+    public static final String SCHEMA_PAYLOAD_DATA = "iglu:com.snowplowanalytics.snowplow/payload_data/jsonschema/1-0-4";
     public static final String SCHEMA_CONTEXTS = "iglu:com.snowplowanalytics.snowplow/contexts/jsonschema/1-0-1";
     public static final String SCHEMA_UNSTRUCT_EVENT = "iglu:com.snowplowanalytics.snowplow/unstruct_event/jsonschema/1-0-0";
     public static final String SCHEMA_SCREEN_VIEW = "iglu:com.snowplowanalytics.snowplow/screen_view/jsonschema/1-0-0";

snowplow-tracker/src/main/java/com/snowplowanalytics/snowplow/tracker/events/AbstractEvent.java

@@ -34,14 +34,16 @@
 public abstract class AbstractEvent implements Event {
 
     protected final List<SelfDescribingJson> context;
-    protected long timestamp;
     protected final String eventId;
+    protected long deviceCreatedTimestamp;
+    private Long trueTimestamp;
 
     public static abstract class Builder<T extends Builder<T>> {
 
         private List<SelfDescribingJson> context = new LinkedList<>();
-        private long timestamp = System.currentTimeMillis();
         private String eventId = Util.getEventId();
+        private long deviceCreatedTimestamp = System.currentTimeMillis();
+        private Long trueTimestamp = null;
 
         protected abstract T self();
 
@@ -56,26 +58,51 @@ public T customContext(List<SelfDescribingJson> context) {
             return self();
         }
 
+        /**
+         * A custom eventId for the event.
+         *
+         * @param eventId the eventId
+         * @return itself
+         */
+        public T eventId(String eventId) {
+            this.eventId = eventId;
+            return self();
+        }
+
         /**
          * A custom event timestamp.
          *
          * @param timestamp the event timestamp as
          *                  unix epoch
          * @return itself
          */
+        @Deprecated
         public T timestamp(long timestamp) {
-            this.timestamp = timestamp;
+            this.deviceCreatedTimestamp = timestamp;
             return self();
         }
 
         /**
-         * A custom eventId for the event.
+         * A custom event timestamp.
          *
-         * @param eventId the eventId
+         * @param deviceCreatedTimestamp the event timestamp as
+         *                               unix epoch
          * @return itself
          */
-        public T eventId(String eventId) {
-            this.eventId = eventId;
+        public T deviceCreatedTimestamp(long deviceCreatedTimestamp) {
+            this.deviceCreatedTimestamp = deviceCreatedTimestamp;
+            return self();
+        }
+
+        /**
+         * A custom event timestamp.
+         *
+         * @param trueTimestamp the true event timestamp as
+         *                      unix epoch
+         * @return itself
+         */
+        public T trueTimestamp(long trueTimestamp) {
+            this.trueTimestamp = trueTimestamp;
             return self();
         }
     }
@@ -88,7 +115,8 @@ protected AbstractEvent(Builder<?> builder) {
         Preconditions.checkArgument(!builder.eventId.isEmpty(), "eventId cannot be empty");
 
         this.context = builder.context;
-        this.timestamp = builder.timestamp;
+        this.deviceCreatedTimestamp = builder.deviceCreatedTimestamp;
+        this.trueTimestamp = builder.trueTimestamp;
         this.eventId = builder.eventId;
     }
 
@@ -104,8 +132,16 @@ public List<SelfDescribingJson> getContext() {
      * @return the events timestamp
      */
     @Override
-    public long getTimestamp() {
-        return this.timestamp;
+    public long getDeviceCreatedTimestamp() {
+        return this.deviceCreatedTimestamp;
+    }
+
+    /**
+     * @return the optional true events timestamp
+     */
+    @Override
+    public long getTrueTimestamp() {
+        return this.trueTimestamp;
     }
 
     /**
@@ -130,7 +166,10 @@ public String getEventId() {
      */
     protected TrackerPayload putDefaultParams(TrackerPayload payload) {
         payload.add(Parameters.EID, getEventId());
-        payload.add(Parameters.TIMESTAMP, Long.toString(getTimestamp()));
+        payload.add(Parameters.DEVICE_TIMESTAMP, Long.toString(getDeviceCreatedTimestamp()));
+        if (this.trueTimestamp != null) {
+            payload.add(Parameters.TRUE_TIMESTAMP, Long.toString(getTrueTimestamp()));
+        }
         return payload;
     }
 }

snowplow-tracker/src/main/java/com/snowplowanalytics/snowplow/tracker/events/EcommerceTransactionItem.java

@@ -139,10 +139,10 @@ protected EcommerceTransactionItem(Builder<?> builder) {
     }
 
     /**
-     * @param timestamp the new timestamp
+     * @param deviceCreatedTimestamp the new timestamp
      */
-    public void setTimestamp(long timestamp) {
-        this.timestamp = timestamp;
+    public void setDeviceCreatedTimestamp(long deviceCreatedTimestamp) {
+        this.deviceCreatedTimestamp = deviceCreatedTimestamp;
     }
 
     /**
@@ -154,7 +154,7 @@ public void setTimestamp(long timestamp) {
     public TrackerPayload getPayload() {
         TrackerPayload payload = new TrackerPayload();
         payload.add(Parameters.EVENT, TrackerConstants.EVENT_ECOMM_ITEM);
-        payload.add(Parameters.TIMESTAMP, Long.toString(this.timestamp));
+        payload.add(Parameters.DEVICE_TIMESTAMP, Long.toString(this.deviceCreatedTimestamp));
         payload.add(Parameters.TI_ITEM_ID, this.itemId);
         payload.add(Parameters.TI_ITEM_SKU, this.sku);
         payload.add(Parameters.TI_ITEM_NAME, this.name);

snowplow-tracker/src/main/java/com/snowplowanalytics/snowplow/tracker/events/Event.java

@@ -32,7 +32,12 @@ public interface Event {
     /**
      * @return the events timestamp
      */
-    long getTimestamp();
+    long getDeviceCreatedTimestamp();
+
+    /**
+     * @return the optional true events timestamp
+     */
+    long getTrueTimestamp();
 
     /**
      * @return the event id