Breaking change on events with_data() method introduced with v1.13.0 …

…release (#184)

* Make Event class instance method with_data() backwards compatible

* Update docs

* Fix typo

README.md

@@ -311,7 +311,7 @@ event = DfE::Analytics::Event.new
   .with_user(current_user)
   .with_request_details(request)
   .with_namespace('some_namespace')
-  .with_data(some: 'custom details about event')
+  .with_data(data: { some: 'custom details about event' })
 ```
 
 If you need to include hidden PII, you can use the `hidden_data` key which will allow all fields listed to be sent separately to BigQuery where they will be hidden.
@@ -323,17 +323,30 @@ event = DfE::Analytics::Event.new
   .with_request_details(request)
   .with_namespace('some_namespace')
   .with_data(
-    data: 
-    { 
+    data:
+    {
       some: 'custom details about event'
     },
-    hidden_data: { 
+    hidden_data: {
       some_hidden: 'some data to be hidden',
       more_hidden: 'more data to be hidden,
     }
   )
 ```
 
+**NOTE**:
+
+Backwards compatability for the `with_data` method was added after v1.15.2 that allows the following call:
+
+```ruby
+  event
+    .with_data(
+       some: 'custom details about event'
+    )
+```
+
+Backwards compatibility was missing in analytics versions v1.13.0 - v1.15.2 inclusive. This means that any custom events or other events using the `with_data` method for adding event data, sent from applications with analytics versions not backwards compatible, would have lost those events (unless event data is sent using the  `data` and/or `hidden_data` keys).
+
 Once all the events have been constructed, simply send them to your analytics:
 
 ```ruby

lib/dfe/analytics/event.rb

@@ -76,6 +76,9 @@ def with_data(hash)
         @event_hash.deep_merge!(data: hash_to_kv_pairs(hash[:data])) if hash.include?(:data)
         @event_hash.deep_merge!(hidden_data: hash_to_kv_pairs(hash[:hidden_data])) if hash.include?(:hidden_data)
 
+        # For backwards compatibility pre v1.13.0 add hash with :data key IF :data nor :hidden_data keys exist
+        @event_hash.deep_merge!(data: hash_to_kv_pairs(hash)) if hash.exclude?(:data) && hash.exclude?(:hidden_data)
+
         self
       end
 

spec/dfe/analytics/event_spec.rb

@@ -117,6 +117,21 @@ def find_data_pair(output, key)
       expect(updated_event_hash['data']).to eq([])
       expect(updated_event_hash['hidden_data']).to eq([])
     end
+
+    it 'remain backwards compatible when with_data is called without the :data and :hidden_data keys' do
+      event.with_data(some: 'custom details about event', ethnic_background: 'Red')
+      updated_event_hash = event.as_json
+
+      data_some_key = updated_event_hash['data'].find { |d| d['key'] == 'some' }
+      expect(data_some_key).not_to be_nil
+      expect(data_some_key['value']).to eq(['custom details about event'])
+
+      data_ethnic_background_key = updated_event_hash['data'].find { |d| d['key'] == 'ethnic_background' }
+      expect(data_ethnic_background_key).not_to be_nil
+      expect(data_ethnic_background_key['value']).to eq(['Red'])
+
+      expect(updated_event_hash['hidden_data']).to be_nil
+    end
   end
 
   describe 'handling invalid UTF-8' do