fix(docs): document the new flow events

r=vbudhram

docs/overview.md

@@ -34,14 +34,13 @@ We log several events for analytical and metrics purposes:
 
 We emit activity events for metrics purposes.
 These events contain the `uid` of the account to be able to better understand new user activity.
-In addition these events have a `metricsContext` that contains the user agent, `utm_*` parameters and the specific metrics `flowId`.
-The activity events respect the `dnt` "Do not track" header and do not send `utm_*` parameters if the header is set.
 
 #### Available events
 
 * account.created - [Account is created](api.md#post-v1accountcreate)
 * account.verified - [Account is verified](api.md#post-v1recovery_emailverify_code)
 * account.login - [Account login event](api.md#post-v1accountlogin)
+* account.confirmed - [Account login is confirmed](api.md#post-v1recovery_emailverify_code)
 * account.keyfetch - [Sync encryption keys have been fetched](api.md#get-v1accountkeys)
 * account.signed - [Certificate signed](api.md#post-v1certificatesign)
 * account.reset - [Account reset event](api.md#post-v1accountreset)
@@ -53,35 +52,81 @@ The activity events respect the `dnt` "Do not track" header and do not send `utm
 
 #### Activity event structure
 
-Activity events are JSON data.
+Activity events are JSON data
+containg the following fields:
+
+* `event`
+* `time`
+* `uid`
+* `userAgent`
+* `account_created_at` (optional)
+* `device_id` (optional)
+* `service` (optional)
+
+##### Example event
+
+```
+{
+  "event": "account.created",
+  "userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10.10; rv:50.0) Gecko/20100101 Firefox/50.0",
+  "time": 1471258615891,
+  "uid": "6bf1375cf2b4439bb36d02479c35ef0d"
+}
+```
+
+### Flow events
+
+Flow events are used to analyse
+end-to-end user journeys
+through the sign-up/sign-in flow.
+For each activity event,
+a flow event is also emited.
+There are also further flow events
+that do not correspond to an activity event.
+In addition to the data that is present on activity events,
+these events also have a metrics context
+that includes the `utm_*` parameters and a `flowId`.
+The flow events respect the `dnt` "Do not track"
+header and do not send `utm_*` parameters
+if that header is set to `1`.
+
+#### Flow event structure
+
+Flow events are JSON data.
 Some fields are common to all events,
 others are event-specific.
 Some fields are optional depending on context,
 others are mandatory.
 
 |Event|Mandatory fields|Optional fields|
 |-----|----------------|---------------|
-|`account.created`|`event`, `userAgent`, `time`, `flow_id`, `flow_time`, `uid`|`context`, `entrypoint`, `migration`, `service`, `utm_campaign`, `utm_content`, `utm_medium`, `utm_source`, `utm_term`|
-|`account.verified`|`event`, `userAgent`, `time`, `flow_id`, `flow_time`, `uid`|`context`, `entrypoint`, `migration`, `service`, `utm_campaign`, `utm_content`, `utm_medium`, `utm_source`, `utm_term`|
-|`account.login`|`event`, `userAgent`, `time`, `flow_id`, `flow_time`, `uid`|`context`, `entrypoint`, `migration`, `service`, `utm_campaign`, `utm_content`, `utm_medium`, `utm_source`, `utm_term`|
-|`account.keyfetch`|`event`, `userAgent`, `time`, `uid`|`flow_id`, `flow_time`, `context`, `entrypoint`, `migration`, `service`, `utm_campaign`, `utm_content`, `utm_medium`, `utm_source`, `utm_term`|
-|`account.signed`|`event`, `userAgent`, `time`, `uid`, `account_created_at`, `device_id`|`flow_id`, `flow_time`, `context`, `entrypoint`, `migration`, `service`, `utm_campaign`, `utm_content`, `utm_medium`, `utm_source`, `utm_term`|
-|`account.reset`|`event`, `userAgent`, `time`, `uid`|`context`, `entrypoint`, `migration`, `service`, `utm_campaign`, `utm_content`, `utm_medium`, `utm_source`, `utm_term`|
-|`account.reminder`|`event`, `userAgent`, `time`, `uid`|`context`, `entrypoint`, `migration`, `service`, `utm_campaign`, `utm_content`, `utm_medium`, `utm_source`, `utm_term`|
-|`account.deleted`|`event`, `userAgent`, `time`, `uid`|`context`, `entrypoint` `migration`, `service`, `utm_campaign`, `utm_content`, `utm_medium`, `utm_source`, `utm_term`|
-|`device.created`|`event`, `userAgent`, `time`, `uid`, `device_id`|`flow_id`, `flow_time`, `context`, `entrypoint`, `migration`, `service`, `utm_campaign`, `utm_content`, `utm_medium`, `utm_source`, `utm_term`|
-|`device.updated`|`event`, `userAgent`, `time`, `uid`, `device_id`|`flow_id`, `flow_time`, `context`, `entrypoint`, `migration`, `service`, `utm_campaign`, `utm_content`, `utm_medium`, `utm_source`, `utm_term`|
-|`device.deleted`|`event`, `userAgent`, `time`, `uid`, `device_id`|`context`, `entrypoint`, `migration`, `service`, `utm_campaign`, `utm_content`, `utm_medium`, `utm_source`, `utm_term`|
+|`account.created`|`event`, `flow_id`, `flow_time`, `time`, `userAgent`|`context`, `entrypoint`, `migration`, `service`, `utm_campaign`, `utm_content`, `utm_medium`, `utm_source`, `utm_term`|
+|`account.verified`|`event`, `flow_id`, `flow_time`, `time`, `userAgent`|`context`, `entrypoint`, `migration`, `service`, `utm_campaign`, `utm_content`, `utm_medium`, `utm_source`, `utm_term`|
+|`account.login`|`event`, `flow_id`, `flow_time`, `time`, `userAgent`|`context`, `entrypoint`, `migration`, `service`, `utm_campaign`, `utm_content`, `utm_medium`, `utm_source`, `utm_term`|
+|`account.confirmed`|`event`, `flow_id`, `flow_time`, `time`, `userAgent`|`context`, `entrypoint`, `migration`, `service`, `utm_campaign`, `utm_content`, `utm_medium`, `utm_source`, `utm_term`|
+|`account.keyfetch`|`event`, `time`, `userAgent`|`context`, `entrypoint`, `flow_id`, `flow_time`, `migration`, `service`, `utm_campaign`, `utm_content`, `utm_medium`, `utm_source`, `utm_term`|
+|`account.signed`|`event`, `time`, `userAgent`|`context`, `entrypoint`, `flow_id`, `flow_time`, `migration`, `service`, `utm_campaign`, `utm_content`, `utm_medium`, `utm_source`, `utm_term`|
+|`account.reset`|`event`, `time`, `userAgent`|`context`, `entrypoint`, `migration`, `service`, `utm_campaign`, `utm_content`, `utm_medium`, `utm_source`, `utm_term`|
+|`account.reminder`|`event`, `time`, `userAgent`|`context`, `entrypoint`, `migration`, `service`, `utm_campaign`, `utm_content`, `utm_medium`, `utm_source`, `utm_term`|
+|`account.deleted`|`event`, `time`, `userAgent`|`context`, `entrypoint` `migration`, `service`, `utm_campaign`, `utm_content`, `utm_medium`, `utm_source`, `utm_term`|
+|`device.created`|`event`, `time`, `userAgent`|`context`, `entrypoint`, `flow_id`, `flow_time`, `migration`, `service`, `utm_campaign`, `utm_content`, `utm_medium`, `utm_source`, `utm_term`|
+|`device.updated`|`event`, `time`, `userAgent`|`context`, `entrypoint`, `flow_id`, `flow_time`, `migration`, `service`, `utm_campaign`, `utm_content`, `utm_medium`, `utm_source`, `utm_term`|
+|`device.deleted`|`event`, `time`, `userAgent`|`context`, `entrypoint`, `migration`, `service`, `utm_campaign`, `utm_content`, `utm_medium`, `utm_source`, `utm_term`|
+|`customs.blocked`|`event`, `time`, `userAgent`|`context`, `entrypoint`, `flow_id`, `flow_time`, `migration`, `service`, `utm_campaign`, `utm_content`, `utm_medium`, `utm_source`, `utm_term`|
 
 ##### Example event
 
 ```
 {
   "event": "account.created",
-  "userAgent": "Mozilla\/5.0 (Macintosh; Intel Mac OS X 10_11_3) AppleWebKit\/537.36 (KHTML, like Gecko) Chrome\/50.0.2661.102 Safari\/537.36",
-  "time": 1466614312474,
-  "flow_id": "1ba211797e3a87d1f6604bec8a33a5827a4751239b4ef118072380b101967dc7",
-  "flow_time": 4353,
-  "uid": "d03249d2af7d4447be3debc674110978"
+  "userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10.10; rv:50.0) Gecko/20100101 Firefox/50.0",
+  "time": 1471258615891,
+  "flow_id": "1386176a76f4359d30aea806400ebbf8af1fb0040891ff32cd0d5cc5038f6d58",
+  "flow_time": 11948,
+  "uid": "d03249d2af7d4447be3debc674110978",
+  "context": "fx_desktop_v3",
+  "entrypoint": "menupanel",
+  "service": "sync"
 }
 ```
+