Implement media playing engagement detection for the site engagement service.

chrome/browser/engagement/site_engagement_helper.h

Index: chrome/browser/engagement/site_engagement_helper.h
diff --git a/chrome/browser/engagement/site_engagement_helper.h b/chrome/browser/engagement/site_engagement_helper.h
index 9ba18079767d2f56a099f6eaf6c4a384dd671377..3ceca39ff8598f1f853d31a08b791015b783f11e 100644
--- a/chrome/browser/engagement/site_engagement_helper.h
+++ b/chrome/browser/engagement/site_engagement_helper.h
@@ -37,22 +37,19 @@ class SiteEngagementHelper
   void WasHidden() override;
 
  private:
-  // Class to encapsulate the user input listening.
+  // Class to encapsulate the periodic detection of site engagement.
   //
-  // Time on site is recorded by detecting any user input (mouse click,
-  // keypress, or touch gesture tap) per some discrete time unit. If there is
-  // user input, then record a positive site engagement.
+  // All engagement detection begins at some constant time delta following
+  // navigation or tab activation. Once engagement is recorded, detection is
+  // suspended for another constant time delta. For sites to continually record
+  // engagement, this overall design requires:
   //
-  // When input is detected, SiteEngagementHelper::RecordUserInput is called,
-  // and the input detection callbacks are paused for
-  // g_seconds_between_user_input_check. This ensures that there is minimal
-  // overhead in input listening, and that input over an extended length of time
-  // is required to continually increase the engagement score.
-  class InputTracker : public content::WebContentsObserver {
+  // 1. engagement at a non-trivial time after a site loads
+  // 2. continual engagement over a non-trivial length of time
+  class PeriodicTracker {
    public:
-    explicit InputTracker(content::WebContents* web_contents,
-                          SiteEngagementHelper* helper);
-    ~InputTracker() override;
+    explicit PeriodicTracker(SiteEngagementHelper* helper);
+    virtual ~PeriodicTracker();
 
     // Begin tracking input after |initial_delay|.
     void Start(base::TimeDelta initial_delay);
@@ -63,28 +60,88 @@ class SiteEngagementHelper
     // Stop listening for user input.
     void Stop();
 
-    // Returns whether the tracker will respond to user input via
-    // DidGetUserInteraction.
-    bool is_tracking() const { return is_tracking_; }
-
     // Set the timer object for testing purposes.
     void SetPauseTimerForTesting(scoped_ptr<base::Timer> timer);
 
-   private:
+    SiteEngagementHelper* helper() { return helper_; }
+
+   protected:
     friend class SiteEngagementHelperTest;
 
-    // Starts the timer for detecting user interaction.
+    // Called when tracking is to be paused by |delay|. Used when tracking first
+    // starts or is paused.
     void StartTimer(base::TimeDelta delay);
 
-    // Callback for StartTimer that activates the user input tracking.
-    void StartTracking();
+    // Called when the timer expires and engagement tracking is active.

[calamity, 2015/11/04 02:08:10]

nit: s/active/activated/?

[dominickn, 2015/11/04 04:20:32]

Done.

+    virtual void TrackingStarted() {}
 
-    // content::WebContentsObserver overrides.
-    void DidGetUserInteraction(const blink::WebInputEvent::Type type) override;
+    // Called when engagement tracking is paused or stopped.
+    virtual void TrackingStopped() {}
 
+   private:
     SiteEngagementHelper* helper_;
     scoped_ptr<base::Timer> pause_timer_;
+  };
+
+  // Class to encapsulate time-on-site engagement detection. Time-on-site is
+  // recorded by detecting user input on a focused WebContents (mouse click,
+  // mouse wheel, keypress, or touch gesture tap) over time.
+  //
+  // After an initial delay, the input tracker begins listening to
+  // DidGetUserInteraction. When user input is signaled, site engagement is
+  // recorded, and the tracker sleeps for
+  // |g_seconds_to_pause_engagement_detection|.
+  class InputTracker : public PeriodicTracker,
+                       public content::WebContentsObserver {
+   public:
+    InputTracker(SiteEngagementHelper* helper,
+                 content::WebContents* web_contents);
+
+    bool is_tracking() const { return is_tracking_; }
+
+   private:
+    friend class SiteEngagementHelperTest;
+
+    void TrackingStarted() override;
+    void TrackingStopped() override;
+
+    // Returns whether the tracker will respond to user input via
+    // DidGetUserInteraction.
     bool is_tracking_;
+
+    // content::WebContentsObserver overrides.
+    void DidGetUserInteraction(const blink::WebInputEvent::Type type) override;
+  };
+
+  // Class to encapsulate media detection. Any media playing in a WebContents
+  // (focused or not) will accumulate engagement points. Media in a hidden
+  // WebContents will accumulate engagement more slowly than in an active
+  // WebContents. Media which has been muted will also accumulate engagement
+  // more slowly.
+  //
+  // The tracker continually notes the visible/hidden state of the WebContents
+  // that it observes, as well as whether media is playing. After an initial
+  // delay, the tracker wakes up every |g_seconds_to_pause_engagement_detection|
+  // and records engagement if media is currently playing.
+  class MediaTracker : public PeriodicTracker,
+                       public content::WebContentsObserver {
+   public:
+    MediaTracker(SiteEngagementHelper* helper,
+                 content::WebContents* web_contents);
+
+   private:
+    friend class SiteEngagementHelperTest;
+
+    void TrackingStarted() override;
+
+    // content::WebContentsObserver overrides.
+    void MediaStartedPlaying() override;
+    void MediaPaused() override;
+    void WasShown() override;
+    void WasHidden() override;
+
+    bool is_hidden_;
+    bool is_playing_;
   };
 
   explicit SiteEngagementHelper(content::WebContents* web_contents);
@@ -92,10 +149,15 @@ class SiteEngagementHelper
   friend class SiteEngagementHelperTest;
 
   // Ask the SiteEngagementService to record engagement via user input at the
-  // current contents location.
+  // current WebContents URL.
   void RecordUserInput(SiteEngagementMetrics::EngagementType type);
 
+  // Ask the SiteEngagementService to record engagement via media playing at the
+  // current WebContents URL.
+  void RecordMediaPlaying(bool is_hidden);
+
   InputTracker input_tracker_;
+  MediaTracker media_tracker_;
   bool record_engagement_;
 
   DISALLOW_COPY_AND_ASSIGN(SiteEngagementHelper);