View source for Firefox/Input/Heartbeat

= Heartbeat =

<big>'''Note: If you are a user and are looking for an explanation of what Heartbeat is, you are probably looking for [[Advocacy/heartbeat]].'''</big>

== Summary ==

The telemetry experiments tool allows people to deploy add-ons to users based on user profile, version, OS, set sample rates, etc. We will be using this tool as a platform to deliver in-product polls that ask a for very simply happy/sad or star rating for a specified question. Gathering sentiment from our overall user base on a daily/weekly basis is what we are calling Firefox Heartbeat.

This page covers only the implementation work done on Input.

== Status ==

* '''Project owner''': [[User:Willkg|Will Kahn-Greene]]
* '''Status''': Done.

== History ==

* v1
** June 17th, 2014: Planning meeting conference call
** July 1st, 2014: Will talked with Gregg
*** Going to build a prototype which requires an addon and some infrastructure on Input to handle incoming data.
*** It'll be minimal so we can tweak it easily as we flesh things out.
** July 16th, 2014: Will started working on v1 implementation
** August 12th, 2014: v1 backend implementation was finished
** September 8th, 2014: Heartbeat was renamed to Pulse and it was decided that instead of sending data to Input, we'd send it to Bagheera. This project is hereby put on hold until that's finalized. If it is finalized, then this project will be canceled and code will be removed.
* v2
** October 31st, 2014: Pulse was renamed to Heartbeat. I decided v1 is done and successful. We're going to use Input for v2.
** November 21nd, 2014: Finished up development for Heartbeat v2. There are still some minor bugs, but they're not in the critical path for pushing Heartbeat out.

== Requirements ==

=== v1: signs of life ===

Requirements:

# API endpoint to capture specified data as JSON content: <tt>/api/v1/hb/</tt>
# captured data is put into a db table that's specific to heartbeat
# need to capture the following:
#* '''locale''': the locale the user is using the product in (e.g. <tt>en-US</tt>)
#* '''platform''': the operating system information (e.g. <tt>Windows 8</tt>)
#* '''product''': the product name (e.g. <tt>Firefox</tt>)
#* '''version''': the version (e.g. <tt>33.0a1</tt>)
#* '''channel''': the channel being used (e.g. <tt>beta</tt>)
#* '''poll''': the slug of the poll being used; the poll must have been created on the system in question before posting heartbeat answers to it
#* '''answer''': the answer the user gave (e.g. <tt>1</tt>); for the most part this is an integer, but we're going to make this a text field to allow for different answer domains in the future
#* arbitrary additional contextual content

Anti-requirements:

# don't need to provide a way to access the data on Input--people will pull it from the db
# don't need to allow for multiple answers--all polls will be a single answer for now
# this is a prototype to get all our ducks in a row--it doesn't need to be perfect and we expect to make it better for the next iteration

Will's thoughts:

# Gregg asked for GET querystring params, but that has spam/abuse issues, so we're going to do POST content instead
# we'll toss all the arbitrary additional contextual content into a JSON blob and stick it in an '''extra''' field in the db; this means we won't be able to easily query this via SQL, but we can extract it other ways and if this turns out to be a problem, we can redo the db structure

Bugs:

Tracker: https://bugzilla.mozilla.org/show_bug.cgi?id=1052459

<bugzilla>
    {
        "blocks": "1052459"
    }
</bugzilla>

API docs: http://fjord.readthedocs.org/en/latest/api.html#posting-heartbeat-feedback-api-v1-hb

Prototype addon: https://github.com/gregglind/firefox-pulse

=== v2: beat harder ===

Requirements:

# API endpoint to capture specified data as JSON content: <tt>/api/v2/hb/</tt>
# captured data is put into a db table that's specific to heartbeat
# API should return a rollup of all errors with a packet all at once
# timestamps are milliseconds since epoch (which requires BigIntegerField)
# need a way to see hb data and hb errors for debugging the heartbeat client--these CANNOT be publicly available

Anti-requirements:

# no access to reading/analyzing the data via the Input website
# doesn't have to be forever-future-proof--just six-months-future-proof

Bugs:

Tracker: https://bugzilla.mozilla.org/show_bug.cgi?id=1092280

<bugzilla>
    {
        "blocks": "1092280"
    }
</bugzilla>

API docs: TBD