Merge pull request #48 from mgaitan/uservoice_identify_users

Identifying authenticated users in Uservoice

analytical/templatetags/uservoice.py

@@ -9,8 +9,7 @@ import re
 
 from django.conf import settings
 from django.template import Library, Node, TemplateSyntaxError
-
-from analytical.utils import get_required_setting
+from analytical.utils import get_required_setting, get_identity
 
 
 WIDGET_KEY_RE = re.compile(r'^[a-zA-Z0-9]*$')
@@ -25,8 +24,10 @@ TRACKING_CODE = """
 
     UserVoice.push(['set', %(options)s]);
     %(trigger)s
+    %(identity)s
     </script>
 """
+IDENTITY = """UserVoice.push(['identify', %(options)s]);"""
 TRIGGER = "UserVoice.push(['addTrigger', {}]);"
 register = Library()
 
@@ -62,14 +63,24 @@ class UserVoiceNode(Node):
         options.update(getattr(settings, 'USERVOICE_WIDGET_OPTIONS', {}))
         options.update(context.get('uservoice_widget_options', {}))
 
+        identity = get_identity(context, 'uservoice', self._identify)
+        if identity:
+            identity = IDENTITY % {'options': json.dumps(identity, sort_keys=True)}
+
         trigger = context.get('uservoice_add_trigger',
                               getattr(settings, 'USERVOICE_ADD_TRIGGER', True))
 
         html = TRACKING_CODE % {'widget_key': widget_key,
                                 'options':  json.dumps(options, sort_keys=True),
-                                'trigger': TRIGGER if trigger else ''}
+                                'trigger': TRIGGER if trigger else '',
+                                'identity': identity if identity else ''}
         return html
 
+    def _identify(self, user):
+        name = user.get_full_name()
+        if not name:
+            name = user.username
+        return {'name': name, 'email': user.email}
 
 def contribute_to_analytical(add_node):
     UserVoiceNode()  # ensure properly configured

docs/services/uservoice.rst

@@ -171,6 +171,44 @@ For example, to show a specific widget to logged in users::
 The widget key passed in the context variable overrides both the default
 and the per-view widget key.
 
+Identifying users
+-----------------
+
+If your websites identifies visitors, you can pass this information on
+to Uservoice.  By default, the
+name and email of an authenticated user is passed to Uservoice automatically.  See
+:ref:`identifying-visitors`.
+
+You can also send the visitor identity yourself by adding either the
+``uservoice_identity`` or the ``analytical_identity`` variable to
+the template context [1]_. This should be a dictionary with the desired user traits as its keys. Check the `documentation <https://developer.uservoice.com/docs/widgets/identify/>`_ to see valid traits. For example::
+
+    context = RequestContext({'uservoice_identity': {'email': user_email,
+                                                     'name': username }})
+    return some_template.render(context)
+
+.. [1]: Remember that if both variables are set, the former takes precedence.
+
+If you can derive the identity from the HTTP request, you can also use
+a context processor that you add to the :data:`TEMPLATE_CONTEXT_PROCESSORS` list in :file:`settings.py`::
+
+    def identify(request):
+        try:
+            return {'uservoice_identity': {
+              email: request.user.username,
+              name: request.user.get_full_name(),
+              id: request.user.id,
+              type: 'vip',
+              account: {
+                name: 'Acme, Co.',
+                monthly_rate: 9.99,
+                ltv: 1495.00,
+                plan: 'Enhanced'
+              }
+             }
+            }
+        except AttributeError:
+            return {}
 
 ----