Merge pull request #9 from poswald/master

Allow sending events and properties to KISSmetrics

AUTHORS.rst

@@ -1,5 +1,9 @@
-The django-analytical package is was written by `Joost Cassee`_, with
-contributions by `Eric Davis`_.
+The django-analytical package was written by `Joost Cassee`_, with
+contributions from:
+
+`Eric Davis`_
+`Paul Oswald`_
+and others.
 
 Included Javascript code snippets for integration of the analytics
 services were written by the respective service providers.
@@ -13,3 +17,4 @@ The work on Crazy Egg was made possible by `Bateau Knowledge`_.
 .. _`Eric Davis`: https://github.com/edavis
 .. _Analytical: https://github.com/jkrall/analytical
 .. _`Bateau Knowledge`: http://www.bateauknowledge.nl/
+.. _`Paul Oswald`: https://github.com/poswald

analytical/templatetags/kiss_metrics.py

@@ -34,7 +34,10 @@ TRACKING_CODE = """
 """
 IDENTIFY_CODE = "_kmq.push(['identify', '%s']);"
 EVENT_CODE = "_kmq.push(['record', '%(name)s', %(properties)s]);"
+PROPERTY_CODE = "_kmq.push(['set', %(properties)s]);"
+
 EVENT_CONTEXT_KEY = 'kiss_metrics_event'
+PROPERTY_CONTEXT_KEY = 'kiss_metrics_properties'
 
 register = Library()
 
@@ -70,6 +73,12 @@ class KissMetricsNode(Node):
                     'properties': simplejson.dumps(properties)})
         except KeyError:
             pass
+        try:
+            properties = context[PROPERTY_CONTEXT_KEY]
+            commands.append(PROPERTY_CODE % {
+                    'properties': simplejson.dumps(properties)})
+        except KeyError:
+            pass
         html = TRACKING_CODE % {'api_key': self.api_key,
                 'commands': " ".join(commands)}
         if is_internal_ip(context, 'KISS_METRICS'):

analytical/tests/test_tag_kiss_metrics.py

@@ -53,6 +53,12 @@ class KissMetricsTagTestCase(TagTestCase):
         self.assertTrue("_kmq.push(['record', 'test_event', "
                 '{"prop1": "val1", "prop2": "val2"}]);' in r, r)
 
+    def test_property(self):
+        r = KissMetricsNode().render(Context({'kiss_metrics_properties':
+                {'prop1': 'val1', 'prop2': 'val2'}}))
+        self.assertTrue("_kmq.push(['set', "
+                '{"prop1": "val1", "prop2": "val2"}]);' in r, r)
+
     @override_settings(ANALYTICAL_INTERNAL_IPS=['1.1.1.1'])
     def test_render_internal_ip(self):
         req = HttpRequest()

docs/services/kiss_metrics.rst

@@ -9,7 +9,6 @@ many drop out at each stage.
 
 .. _KISSmetrics: http://www.kissmetrics.com/
 
-
 .. kiss-metrics-installation:
 
 Installation
@@ -108,3 +107,43 @@ a context processor that you add to the
 Just remember that if you set the same context variable in the
 :class:`~django.template.context.RequestContext` constructor and in a
 context processor, the latter clobbers the former.
+
+.. _kiss-metrics-event:
+
+Recording events
+----------------
+
+You may tell KISSmetrics about an event by setting a variable in the context.
+
+For example::
+
+    context = RequestContext({
+        'kiss_metrics_event': ['Signed Up', {'Plan' : 'Pro', 'Amount' : 9.99}],
+    })
+    return some_template.render(context)
+
+The output script tag will then include the corresponding Javascript event as
+documented in the `KISSmetrics record API`_ docs.
+
+
+.. _kiss-metrics-properties:
+
+Recording properties
+--------------------
+
+You may also set KISSmetrics properties without a corresponding event.
+
+For example::
+
+    context = RequestContext({
+        'kiss_metrics_properties': {'gender': 'Male'},
+    })
+    return some_template.render(context)
+
+The output script tag will then include the corresponding properties as
+documented in the `KISSmetrics set API`_ docs.
+
+
+.. _`KISSmetrics set API`: http://support.kissmetrics.com/apis/common-methods#record
+.. _`KISSmetrics record API`: http://support.kissmetrics.com/apis/common-methods#set
+