From dd6794a43b1198f98e834240afdde2df4784de18 Mon Sep 17 00:00:00 2001
From: Vaidehi Joshi <vaidehi.sj@gmail.com>
Date: Thu, 25 Jun 2020 11:47:51 -0700
Subject: [PATCH] Add documentation for tracking (#8914) [deploy]

* Add documentation for tracking

* Reword a sentence in backend tracking documentation
---
 docs/backend/metrics.md   |  2 +-
 docs/backend/tracking.md  | 73 +++++++++++++++++++++++++++++++++++++++
 docs/frontend/tracking.md | 29 ++++++++++++++++
 3 files changed, 103 insertions(+), 1 deletion(-)
 create mode 100644 docs/backend/tracking.md
 create mode 100644 docs/frontend/tracking.md

diff --git a/docs/backend/metrics.md b/docs/backend/metrics.md
index b94083a37..1af7c6292 100644
--- a/docs/backend/metrics.md
+++ b/docs/backend/metrics.md
@@ -1,5 +1,5 @@
 ---
-title: Tracking Metrics
+title: Metrics
 ---
 
 ## Time series data
diff --git a/docs/backend/tracking.md b/docs/backend/tracking.md
new file mode 100644
index 000000000..18c8c9655
--- /dev/null
+++ b/docs/backend/tracking.md
@@ -0,0 +1,73 @@
+---
+title: Backend Tracking
+---
+
+## Visits & Events
+
+For first-party analytics, we use the
+[`ahoy_matey` gem](https://github.com/ankane/ahoy), which tracks visits and
+events.
+
+We intentionally choose to limit what user data we track and persist, and have
+opted to follow the GDPR compliance standards
+[set by Ahoy](https://github.com/ankane/ahoy#gdpr-compliance-1). By default, we
+have configured the Ahoy library to mask IP addresses, disable geocode tracking,
+and not track user cookies.
+
+### Visits
+
+Ahoy creates an `Ahoy::Visit` record for each visit that it tracks.
+
+By default, we have turned off visit tracking in the `ApplicationController`:
+
+```ruby
+skip_before_action :track_ahoy_visit
+```
+
+We currently only create visits on the server-side when they are required to be
+created by events. Visits can be re-enabled for specific controller actions if
+necessary, but this should be done so _with explict care_.
+
+We do not collect any personal user data when tracking visits. Our collected
+data is limited to the user's `id`. Each user has a unique `visitor_token`,
+while each visit to the site is marked with a unique `visit_token`.
+
+### Events
+
+Ahoy creates an `Ahoy::Event` record for each event that it tracks. If no visit
+is recorded for a user when an event is tracked, Ahoy will simultaneously create
+an `Ahoy::Visit` for the event being tracked.
+
+Events can be tracked in a controller action on the backend, or with JavaScript
+on the frontend. Learn more about tracking events with JavaScript in our
+[frontend tracking guide](../frontend/tracking.md).
+
+When an event is tracked, it should include a `name` and a `properties` hash.
+When adding new events, be sure that the name is unique per-event. The
+properties will help you differentiate between events.
+
+In order to track a specific event in a controller, use the `ahoy.track` call:
+
+```ruby
+class YourController < ApplicationController
+  after_action :track_my_action
+
+  protected
+
+  def track_my_action
+    ahoy.track "A specific description of your event", request.path_parameters
+  end
+end
+```
+
+Event tracking can be enabled for specific controller actions, but should be
+done so _with explict care_.
+
+## Messages
+
+For email analytics, we use the
+[`ahoy_messages` gem](https://github.com/ankane/ahoy_email), which tracks a
+history of email messages sent to users.
+
+Ahoy creates an `Ahoy::Message` record for each email sent by default, but can
+be disabled on a per-mailer basis.
diff --git a/docs/frontend/tracking.md b/docs/frontend/tracking.md
new file mode 100644
index 000000000..c414f0879
--- /dev/null
+++ b/docs/frontend/tracking.md
@@ -0,0 +1,29 @@
+---
+title: Frontend Tracking
+---
+
+## Ahoy.js
+
+For first-party analytics, we use the
+[`ahoy.js` library](https://github.com/ankane/ahoy.js), which tracks visits and
+events. This library works in conjunction with the `ahoy_matey` gem, which is
+documented in our [backend tracking guide](../backend/tracking.md).
+
+### Configuration
+
+The configuration for `ahoy.js` lives in `app/assets/javascripts/base.js.erb`.
+Since we do not track user cookies on the backend, we have configured
+`ahoy.js`'s defaults to match that on the frontend.
+
+### Events
+
+In order to track an event, use the `ahoy.track` function:
+
+```javascript
+ahoy.track(name, properties);
+```
+
+This function will send a `POST` request to the `/ahoy/events` endpoint on our
+backend with the `name` and `properties` of the event. The backend endpoint will
+also create a corresponding `Ahoy::Visit` for the event if one does not exist
+already.