Implement autoplay gesture override experiment.

Source/core/html/AutoplayExperimentHelper.h

+/*
+ * Copyright (C) 2015 Google Inc. All rights reserved.

[philipj_slow, 2015/08/13 10:15:40]

This is new code, so I think you can use the short header.

[liberato (no reviews please), 2015/09/01 06:54:20]

thanks, forgot about the short one.

+ *
+ * Redistribution and use in source and binary forms, with or without
+ * modification, are permitted provided that the following conditions are
+ * met:
+ *
+ *     * Redistributions of source code must retain the above copyright
+ * notice, this list of conditions and the following disclaimer.
+ *     * Redistributions in binary form must reproduce the above
+ * copyright notice, this list of conditions and the following disclaimer
+ * in the documentation and/or other materials provided with the
+ * distribution.
+ *     * Neither the name of Google Inc. nor the names of its
+ * contributors may be used to endorse or promote products derived from
+ * this software without specific prior written permission.
+ *
+ * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+ * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
+ * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
+ * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
+ * OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+ * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
+ * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
+ * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
+ * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+ * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+ * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+ */
+
+#ifndef AutoplayExperimentHelper_h
+#define AutoplayExperimentHelper_h
+
+#include "platform/Timer.h"
+
+namespace blink {

[philipj_slow, 2015/08/13 10:15:40]

Hmm, merge this into the below namespace blink block?

[liberato (no reviews please), 2015/09/01 06:54:20]

done.

+class Document;
+class HTMLMediaElement;
+class EventListener;
+} // namespace blink
+
+namespace blink {
+
+// These values are used for a histogram. Do not reorder.
+enum AutoplayMetrics {
+    // Media element with autoplay seen.
+    AutoplayMediaFound = 0,
+    // Autoplay enabled and user stopped media play at any point.
+    AutoplayStopped = 1,
+    // Autoplay enabled but user bailed out on media play early.
+    AutoplayBailout = 2,
+    // Autoplay disabled but user manually started media.
+    AutoplayManualStart = 3,
+    // Autoplay was (re)enabled through a user-gesture triggered load()
+    AutoplayEnabledThroughLoad = 4,
+    // Autoplay disabled by sandbox flags.
+    AutoplayDisabledBySandbox = 5,
+
+    // These metrics indicate "no gesture but gesture requirement was
+    // overridden by experiment".  They do not include cases where no
+    // user gesture is required (!m_userGestureRequiredForPlay).
+    // Gestureless playback when media scrolled into view.  We don't

[philipj_slow, 2015/08/13 10:15:40]

I can't parse "Gestureless playback when media scrolled into view." :)

A blank line somewhere around here would help make it clear that "We don't
record whether it was a javascript or attribute autoplay request" is talking
about the scroll bit, not more generally. (I was scratching my head about
GesturelessPlaybackStartedByLoad which does distinguish.)

[liberato (no reviews please), 2015/09/01 06:54:20]

Done.

+    // record whether it was a javascript or attribute autoplay request.
+    GesturelessPlaybackStartedByScroll = 6,
+    // Autoplay started by experiment override during initial load.

[philipj_slow, 2015/08/13 10:15:40]

If I'm reading this right, GesturelessPlaybackStartedByLoad will measure only
the cases where there was a user gesture requirement at the point where where
autoplaying flag is consulted, and playback was started at that very point. If
that's right, then GesturelessPlaybackStartedByAutoplayingFlag would make this
more clear to me. The documentation can say that it's only the synchronous case,
not anything that happens after scrolling.

[liberato (no reviews please), 2015/09/01 06:54:20]

i renamed these.  i also separated GesturelessPlaybackStartedByScroll into
'autoplay flag after scroll' and 'play() after scroll' cases.

+    GesturelessPlaybackStartedByLoad = 7,
+    // Autoplay started by experiment override in play() call.
+    GesturelessPlaybackStartedByPlayMethod = 8,
+
+    // play() failed to play due to gesture requirement.
+    PlayMethodFailed = 9,
+
+    // Some play, whether user initiated or not, started.
+    AnyPlaybackStarted = 10,
+    // Some play, whether user initiated or not, stopped.
+    AnyPlaybackStopped = 11,
+    // Some playback, whether user initiated or not, bailed out early.
+    AnyPlaybackBailout = 12,
+
+    // This enum value must be last.
+    NumberOfAutoplayMetrics,
+};
+
+class AutoplayExperimentHelper {
+public:
+    AutoplayExperimentHelper(HTMLMediaElement&);
+    ~AutoplayExperimentHelper();
+
+    void onReadyToPlay();

[philipj_slow, 2015/08/13 10:15:40]

The name had me thinking it was a callback based on a readyState change or
perhaps around prepareToPlay. Perhaps onAutoplayingWithoutUserGesture? Also,
would it make sense for either all or none of these to be called only if the
regular gesture requirement failed?

I can't find anything in the style guide, but it strikes me as unfamiliar to
have onFoo methods in Blink. More common seems to be method names in the past
tense (see e.g. WebMediaPlayerClient) and in some cases pre/post pairs, like in
pre/postDispatchEventHandler.

[liberato (no reviews please), 2015/09/01 06:54:20]

Done.

+    void onPlayMethodCalled();
+    void onPauseMethodCalled();
+    void onMuteChanged();
+
+private:
+    // Install an event listener to check for changes in visibility.  If a
+    // listener is already installed, then this does nothing.
+    void installEventListenerIfNeeded();
+
+    // Remove any event listener.  It's okay to call this if one isn't
+    // installed already.
+    void clearEventListenerIfNeeded();
+
+    // Return true if any only if this player meets (most) of the eligibility
+    // requirements for the experiment to override the need for a user
+    // gesture.  This includes everything except the visibility test.
+    bool isEligible() const;
+
+    // Return true if and only if the player is visible.
+    bool isInViewportIfNeeded();
+
+    // Set the mute flag on the media if we're in an experiment mode that

[philipj_slow, 2015/08/13 10:15:40]

s/mute/muted/

[liberato (no reviews please), 2015/09/01 06:54:20]

Done.

+    // requires it, else do nothing.
+    void muteIfNeeded();
+
+    // Maybe override the requirement for a user gesture, and start playing
+    // autoplay media.  Returns true if only if it starts playback.
+    bool maybeStartPlaying();
+
+    // Configure internal state to record that the autoplay experiment is
+    // going to start playback.  This doesn't actually start playback, since
+    // there are several different cases.
+    void prepareToPlay(AutoplayMetrics);
+
+    // Begin (or start over) a periodic check for visibility.  We will poll
+    // during this check to see if the video is in the viewport.
+    void notifyScrolled();
+
+    // Process a timer for checking visibility.
+    void viewportTimerFired(Timer<AutoplayExperimentHelper>*);
+
+    // Return our media player's document.

[philipj_slow, 2015/08/13 10:15:40]

s/player/element/

[liberato (no reviews please), 2015/09/01 06:54:20]

Done.

+    Document& document() const;
+
+private:
+    HTMLMediaElement& m_element;
+
+    enum AutoplayExperimentMode {
+        ExperimentOff        = 0,
+        ExperimentEnabled    = 1 << 0,
+        ExperimentIfViewport = 1 << 1,
+        ExperimentIfMuted    = 1 << 2,
+        ExperimentIfMobile   = 1 << 3,
+        ExperimentPlayMuted  = 1 << 4
+    };
+    int m_mode; // Bitwise-or of AutoplayExperimentMode
+
+    // Autoplay experiment state.
+    // True if we've received a play() without a pause().
+    bool m_playPending : 1;
+
+    // Scroll listener for the autoplay experiment, to help us determine when
+    // the user has scrolled the player into the viewport.

[philipj_slow, 2015/08/13 10:15:40]

To be pedantic, it could also be scripts driving the scrolling.

[liberato (no reviews please), 2015/09/01 06:54:20]

listener was removed, as part of Ojan's suggested changes.

+    class ScrollListener;
+    friend class AutoplayExperimentScrollListener;
+    RefPtrWillBeMember<EventListener> m_scrollListener;
+    Timer<AutoplayExperimentHelper> m_viewportTimer;
+};
+
+} // namespace blink
+
+#endif // AutoplayExperimentHelper_h