Introduce event tags (#35)

Author: onufryk

optimizely/event_builder.py

@@ -1,4 +1,4 @@
-# Copyright 2016, Optimizely
+# Copyright 2016-2017, Optimizely
 # Licensed under the Apache License, Version 2.0 (the "License");
 # you may not use this file except in compliance with the License.
 # You may obtain a copy of the License at
@@ -19,6 +19,7 @@
 from . import project_config
 from . import version
 from .helpers import enums
+from .helpers import event_tag_utils
 
 
 class Event(object):
@@ -225,19 +226,22 @@ def create_impression_event(self, experiment, variation_id, user_id, attributes)
     return Event(self.OFFLINE_API_PATH.format(project_id=self.params[self.EventParams.PROJECT_ID]),
                  self.params)
 
-  def create_conversion_event(self, event_key, user_id, attributes, event_value, valid_experiments):
+  def create_conversion_event(self, event_key, user_id, attributes, event_tags, valid_experiments):
     """ Create conversion Event to be sent to the logging endpoint.
 
     Args:
       event_key: Event key representing the event which needs to be recorded.
       user_id: ID for user.
-      event_value: Value associated with the event. Can be used to represent revenue in cents.
+      attributes: Dict representing user attributes and values.
+      event_tags: Dict representing metadata associated with the event.
       valid_experiments: List of tuples representing valid experiments for the event.
 
     Returns:
       Event object encapsulating the conversion event.
     """
 
+    event_value = event_tag_utils.get_revenue_value(event_tags)
+
     self.params = {}
     self._add_common_params(user_id, attributes)
     self._add_conversion_goal(event_key, event_value)
@@ -254,7 +258,6 @@ class EventBuilderV2(BaseEventBuilder):
   CONVERSION_ENDPOINT = 'https://logx.optimizely.com/log/event'
   HTTP_VERB = 'POST'
   HTTP_HEADERS = {'Content-Type': 'application/json'}
-  EVENT_VALUE_METRIC = 'revenue'
 
   class EventParams(object):
     ACCOUNT_ID = 'accountId'
@@ -329,25 +332,40 @@ def _add_required_params_for_impression(self, experiment, variation_id):
       self.EventParams.IS_LAYER_HOLDBACK: False
     }
 
-  def _add_required_params_for_conversion(self, event_key, user_id, event_value, valid_experiments):
+  def _add_required_params_for_conversion(self, event_key, user_id, event_tags, valid_experiments):
     """ Add parameters that are required for the conversion event to register.
 
     Args:
       event_key: Key representing the event which needs to be recorded.
       user_id: ID for user.
-      event_value: Value associated with the event. Can be used to represent revenue in cents.
+      event_tags: Dict representing metadata associated with the event.
       valid_experiments: List of tuples representing valid experiments for the event.
     """
 
     self.params[self.EventParams.IS_GLOBAL_HOLDBACK] = False
     self.params[self.EventParams.EVENT_FEATURES] = []
     self.params[self.EventParams.EVENT_METRICS] = []
 
-    if event_value:
-      self.params[self.EventParams.EVENT_METRICS] = [{
-        'name': self.EVENT_VALUE_METRIC,
-        'value': event_value
-      }]
+    if event_tags:
+      event_value = event_tag_utils.get_revenue_value(event_tags)
+      if event_value is not None:
+        self.params[self.EventParams.EVENT_METRICS] = [{
+          'name': event_tag_utils.EVENT_VALUE_METRIC,
+          'value': event_value
+        }]
+
+      for event_tag_id in event_tags.keys():
+        event_tag_value = event_tags.get(event_tag_id)
+        if event_tag_value is None:
+          continue
+
+        event_feature = {
+          'id': event_tag_id,
+          'type': 'custom',
+          'value': event_tag_value,
+          'shouldIndex': False,
+        }
+        self.params[self.EventParams.EVENT_FEATURES].append(event_feature)
 
     self.params[self.EventParams.LAYER_STATES] = []
     for experiment in valid_experiments:
@@ -387,23 +405,23 @@ def create_impression_event(self, experiment, variation_id, user_id, attributes)
                  http_verb=self.HTTP_VERB,
                  headers=self.HTTP_HEADERS)
 
-  def create_conversion_event(self, event_key, user_id, attributes, event_value, valid_experiments):
+  def create_conversion_event(self, event_key, user_id, attributes, event_tags, valid_experiments):
     """ Create conversion Event to be sent to the logging endpoint.
 
     Args:
       event_key: Key representing the event which needs to be recorded.
       user_id: ID for user.
-      event_value: Value associated with the event. Can be used to represent revenue in cents.
-      valid_experiments: List of tuples representing valid experiments for the event.
       attributes: Dict representing user attributes and values.
+      event_tags: Dict representing metadata associated with the event.
+      valid_experiments: List of tuples representing valid experiments for the event.
 
     Returns:
       Event object encapsulating the conversion event.
     """
 
     self.params = {}
     self._add_common_params(user_id, attributes)
-    self._add_required_params_for_conversion(event_key, user_id, event_value, valid_experiments)
+    self._add_required_params_for_conversion(event_key, user_id, event_tags, valid_experiments)
     return Event(self.CONVERSION_ENDPOINT,
                  self.params,
                  http_verb=self.HTTP_VERB,

optimizely/exceptions.py

@@ -1,4 +1,4 @@
-# Copyright 2016, Optimizely
+# Copyright 2016-2017, Optimizely
 # Licensed under the Apache License, Version 2.0 (the "License");
 # you may not use this file except in compliance with the License.
 # You may obtain a copy of the License at
@@ -21,6 +21,11 @@ class InvalidAudienceException(Exception):
   pass
 
 
+class InvalidEventTagException(Exception):
+  """ Raised when provided event tag is invalid. """
+  pass
+
+
 class InvalidExperimentException(Exception):
   """ Raised when provided experiment key is invalid. """
   pass

optimizely/helpers/enums.py

@@ -1,4 +1,4 @@
-# Copyright 2016, Optimizely
+# Copyright 2016-2017, Optimizely
 # Licensed under the Apache License, Version 2.0 (the "License");
 # you may not use this file except in compliance with the License.
 # You may obtain a copy of the License at
@@ -32,6 +32,7 @@ class Errors(object):
   INVALID_INPUT_ERROR = 'Provided "{}" is in an invalid format.'
   INVALID_ATTRIBUTE_ERROR = 'Provided attribute is not in datafile.'
   INVALID_ATTRIBUTE_FORMAT = 'Attributes provided are in an invalid format.'
+  INVALID_EVENT_TAG_FORMAT = 'Event tags provided are in an invalid format.'
   INVALID_AUDIENCE_ERROR = 'Provided audience is not in datafile.'
   INVALID_EXPERIMENT_KEY_ERROR = 'Provided experiment is not in datafile.'
   INVALID_EVENT_KEY_ERROR = 'Provided event is not in datafile.'

optimizely/helpers/event_tag_utils.py

@@ -0,0 +1,34 @@
+# Copyright 2017, Optimizely
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+import numbers
+
+EVENT_VALUE_METRIC = 'revenue'
+
+
+def get_revenue_value(event_tags):
+  if event_tags is None:
+    return None
+
+  if not isinstance(event_tags, dict):
+    return None
+
+  if EVENT_VALUE_METRIC not in event_tags:
+    return None
+
+  raw_value = event_tags[EVENT_VALUE_METRIC]
+
+  if not isinstance(raw_value, numbers.Integral):
+    return None
+
+  return raw_value

optimizely/helpers/validator.py

@@ -1,4 +1,4 @@
-# Copyright 2016, Optimizely
+# Copyright 2016-2017, Optimizely
 # Licensed under the Apache License, Version 2.0 (the "License");
 # you may not use this file except in compliance with the License.
 # You may obtain a copy of the License at
@@ -116,3 +116,16 @@ def are_attributes_valid(attributes):
   """
 
   return type(attributes) is dict
+
+
+def are_event_tags_valid(event_tags):
+  """ Determine if event tags provided are dict or not.
+
+  Args:
+    event_tags: Event tags which need to be validated.
+
+  Returns:
+    Boolean depending upon whether event_tags are in valid format or not.
+  """
+
+  return type(event_tags) is dict

optimizely/optimizely.py

@@ -1,4 +1,4 @@
-# Copyright 2016, Optimizely
+# Copyright 2016-2017, Optimizely
 # Licensed under the Apache License, Version 2.0 (the "License");
 # you may not use this file except in compliance with the License.
 # You may obtain a copy of the License at
@@ -11,6 +11,7 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
+import numbers
 import sys
 
 from . import bucketer
@@ -176,14 +177,14 @@ def activate(self, experiment_key, user_id, attributes=None):
 
     return variation.key
 
-  def track(self, event_key, user_id,  attributes=None, event_value=None):
+  def track(self, event_key, user_id,  attributes=None, event_tags=None):
     """ Send conversion event to Optimizely.
 
     Args:
       event_key: Event key representing the event which needs to be recorded.
       user_id: ID for user.
       attributes: Dict representing visitor attributes and values which need to be recorded.
-      event_value: Value associated with the event. Can be used to represent revenue in cents.
+      event_tags: Dict representing metadata associated with the event.
     """
 
     if not self.is_valid:
@@ -195,6 +196,19 @@ def track(self, event_key, user_id,  attributes=None, event_value=None):
       self.error_handler.handle_error(exceptions.InvalidAttributeException(enums.Errors.INVALID_ATTRIBUTE_FORMAT))
       return
 
+    if event_tags:
+      if isinstance(event_tags, numbers.Number):
+        event_tags = {
+          'revenue': event_tags
+        }
+        self.logger.log(enums.LogLevels.WARNING,
+                        'Event value is deprecated in track call. Use event tags to pass in revenue value instead.')
+
+      if not validator.are_event_tags_valid(event_tags):
+        self.logger.log(enums.LogLevels.ERROR, 'Provided event tags are in an invalid format.')
+        self.error_handler.handle_error(exceptions.InvalidEventTagException(enums.Errors.INVALID_EVENT_TAG_FORMAT))
+        return
+
     event = self.config.get_event(event_key)
     if not event:
       self.logger.log(enums.LogLevels.INFO, 'Not tracking user "%s" for event "%s".' % (user_id, event_key))
@@ -211,7 +225,7 @@ def track(self, event_key, user_id,  attributes=None, event_value=None):
 
     # Create and dispatch conversion event if there are valid experiments
     if valid_experiments:
-      conversion_event = self.event_builder.create_conversion_event(event_key, user_id, attributes, event_value,
+      conversion_event = self.event_builder.create_conversion_event(event_key, user_id, attributes, event_tags,
                                                                     valid_experiments)
       self.logger.log(enums.LogLevels.INFO, 'Tracking event "%s" for user "%s".' % (event_key, user_id))
       self.logger.log(enums.LogLevels.DEBUG,

tests/helpers_tests/test_event_tag_utils.py

@@ -0,0 +1,50 @@
+# Copyright 2017, Optimizely
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+import unittest
+
+from optimizely.helpers import event_tag_utils
+
+class EventTagUtilsTest(unittest.TestCase):
+
+  def test_get_revenue_value__invalid_args(self):
+    """ Test that revenue value is not returned for invalid arguments. """
+    self.assertIsNone(event_tag_utils.get_revenue_value(None))
+    self.assertIsNone(event_tag_utils.get_revenue_value(0.5))
+    self.assertIsNone(event_tag_utils.get_revenue_value(65536))
+    self.assertIsNone(event_tag_utils.get_revenue_value(9223372036854775807))
+    self.assertIsNone(event_tag_utils.get_revenue_value('9223372036854775807'))
+    self.assertIsNone(event_tag_utils.get_revenue_value(True))
+    self.assertIsNone(event_tag_utils.get_revenue_value(False))
+
+  def test_get_revenue_value__no_revenue_tag(self):
+    """ Test that revenue value is not returned when there's no revenue event tag. """
+    self.assertIsNone(event_tag_utils.get_revenue_value([]))
+    self.assertIsNone(event_tag_utils.get_revenue_value({}))
+    self.assertIsNone(event_tag_utils.get_revenue_value({'non-revenue': 42}))
+
+  def test_get_revenue_value__invalid_revenue_tag(self):
+    """ Test that revenue value is not returned when revenue event tag has invalid data type. """
+    self.assertIsNone(event_tag_utils.get_revenue_value({'non-revenue': None}))
+    self.assertIsNone(event_tag_utils.get_revenue_value({'non-revenue': 0.5}))
+    self.assertIsNone(event_tag_utils.get_revenue_value({'non-revenue': '65536'}))
+    self.assertIsNone(event_tag_utils.get_revenue_value({'non-revenue': True}))
+    self.assertIsNone(event_tag_utils.get_revenue_value({'non-revenue': False}))
+    self.assertIsNone(event_tag_utils.get_revenue_value({'non-revenue': [1, 2, 3]}))
+    self.assertIsNone(event_tag_utils.get_revenue_value({'non-revenue': {'a', 'b', 'c'}}))
+
+  def test_get_revenue_value__revenue_tag(self):
+    """ Test that correct revenue value is returned. """
+    self.assertEqual(0, event_tag_utils.get_revenue_value({'revenue': 0}))
+    self.assertEqual(65536, event_tag_utils.get_revenue_value({'revenue': 65536}))
+    self.assertEqual(9223372036854775807, event_tag_utils.get_revenue_value({'revenue': 9223372036854775807}))

tests/helpers_tests/test_validator.py

@@ -1,4 +1,4 @@
-# Copyright 2016, Optimizely
+# Copyright 2016-2017, Optimizely
 # Licensed under the Apache License, Version 2.0 (the "License");
 # you may not use this file except in compliance with the License.
 # You may obtain a copy of the License at
@@ -89,6 +89,18 @@ def test_are_attributes_valid__returns_false(self):
     self.assertFalse(validator.are_attributes_valid(['key', 'value']))
     self.assertFalse(validator.are_attributes_valid(42))
 
+  def test_are_event_tags_valid__returns_true(self):
+    """ Test that valid event tags returns True. """
+
+    self.assertTrue(validator.are_event_tags_valid({'key': 'value', 'revenue': 0}))
+
+  def test_are_event_tags_valid__returns_false(self):
+    """ Test that invalid event tags returns False. """
+
+    self.assertFalse(validator.are_event_tags_valid('key:value'))
+    self.assertFalse(validator.are_event_tags_valid(['key', 'value']))
+    self.assertFalse(validator.are_event_tags_valid(42))
+
 
 class DatafileV2ValidationTests(base.BaseTestV2):