From a569f950a9fd1d472ab668535f1972006aa47439 Mon Sep 17 00:00:00 2001
From: Tim Spurway <tspurway@gmail.com>
Date: Wed, 30 Mar 2016 16:23:13 -0400
Subject: [PATCH] Update data_dictionary.md

This is the spec for the changes proposed by #387

r? @k88hudson @ncloudioj
---
 data_dictionary.md | 39 ++++++++++++++++++++++++++++++++-------
 1 file changed, 32 insertions(+), 7 deletions(-)

diff --git a/data_dictionary.md b/data_dictionary.md
index 240b0b6dd..1154f9643 100644
--- a/data_dictionary.md
+++ b/data_dictionary.md
@@ -1,10 +1,16 @@
-# Example Activity Stream Log
+# Activity Stream Pings
+
+The Activity Stream addon sends two distinct types of pings to the backend (HTTPS POST) [Onyx server](https://github.com/mozilla/onyx) :
+- a `session` ping that describes the ending of an Ativity Stream session (lose focus event on Activity Stream), and
+- an `event` ping that records specific data about individual user interactions while interacting with Activity Stream
+
+
+# Example Activity Stream `session` Log
 
 ```json
 {
-  "action": "activity_stream",
+  "action": "activity_stream_session",
   "addon_version": "1.0.0",
-  "click_position": "100x100",
   "client_id": "374dc4d8-0cb2-4ac5-a3cf-c5a9bc3c602e",
   "date": "2016-03-07",
   "ip": "10.192.171.13",
@@ -12,7 +18,6 @@
   "locale": "en-US",
   "max_scroll_depth": 145,
   "session_duration": 1635,
-  "source": "top_sites",
   "tab_id": 3,
   "timestamp": 1457396660000,
   "total_bookmarks": 19,
@@ -23,14 +28,34 @@
 }
 ```
 
-The Activity Stream page will ping (HTTPS POST) [Onyx](https://github.com/mozilla/onyx) every time the page loses focus.
+# Example Activity Stream `event` Log
+
+```json
+{
+  "action": "activity_stream_event",
+  "addon_version": "1.0.0",
+  "click_position": 4,
+  "client_id": "374dc4d8-0cb2-4ac5-a3cf-c5a9bc3c602e",
+  "date": "2016-03-07",
+  "ip": "10.192.171.13",
+  "locale": "en-US",
+  "source": "top_sites",
+  "event": "delete",
+  "tab_id": 3,
+  "timestamp": 1457396660000,
+  "ua": "python-requests/2.9.1",
+  "ver": "3"
+}
+```
+
 
 | KEY | DESCRIPTION | &nbsp; |
 |-----|-------------|:-----:|
 | `action` | Always `activity_stream`. | :one:
 | `addon_version` | The version of the Activity Stream addon. | :one:
-| `click_position` | The index of the element that was clicked. | :one:
+| `click_position` | The index of the element in the `source` that was clicked. | :one:
 | `client_id` | An identifier for this client. | :one:
+| `event` | The type of event. Either ("click", "share", "delete", "more_items") | :one:
 | `load_reason` | Either ("newtab", "refocus", "restore") and is the reason the tab was focused. | :one:
 | `max_scroll_depth` | The maximum number of pixels the scroll bar was dragged in this session. | :one:
 | `session_duration` | Defined to be the time in milliseconds between the newtab gaining and losing focus. | :one:
@@ -41,7 +66,7 @@ The Activity Stream page will ping (HTTPS POST) [Onyx](https://github.com/mozill
 | `ver` | The version of the Onyx API the ping was sent to. | :one:
 | `ip` | The IP address of the client. | :two:
 | `locale` | The browser chrome's language (eg. en-US). | :two:
-| `source` | Either ("recent_links", "recent_bookmarks", "frecent_links", "top_sites", "spotlight") and indicates what was clicked. | :two:
+| `source` | Either ("recent_links", "recent_bookmarks", "frecent_links", "top_sites", "spotlight", "sidebar") and indicates what `action`. | :two:
 | `ua` | The user agent string. | :two:
 | `date` | The date in YYYY-MM-DD format. | :three:
 | `timestamp` | The time in ms since epoch. | :three: