[HBD] Gate the advertising of Flash on Site Engagement.

chrome/browser/engagement/site_engagement_service.h

 // Copyright 2015 The Chromium Authors. All rights reserved.
 // Use of this source code is governed by a BSD-style license that can be
 // found in the LICENSE file.
 
 #ifndef CHROME_BROWSER_ENGAGEMENT_SITE_ENGAGEMENT_SERVICE_H_
 #define CHROME_BROWSER_ENGAGEMENT_SITE_ENGAGEMENT_SERVICE_H_
 
 #include <map>
 #include <memory>
 #include <set>
@@ skipping 16 matching lines @@
 
 namespace content {
 class WebContents;
 }
 
 namespace history {
 class HistoryService;
 }
 
 class GURL;
+class HostContentSettingsMap;
 class Profile;
 class SiteEngagementScore;
 
 class SiteEngagementScoreProvider {
  public:
   // Returns a non-negative integer representing the engagement score of the
   // origin for this URL.
   virtual double GetScore(const GURL& url) const = 0;
 
   // Returns the sum of engagement points awarded to all sites.
   virtual double GetTotalEngagementPoints() const = 0;
 };
 
 // Stores and retrieves the engagement score of an origin.
 //
-// An engagement score is a positive integer that represents how much a user has
-// engaged with an origin - the higher it is, the more engagement the user has
-// had with this site recently.
+// An engagement score is a non-negative double that represents how much a user
+// has engaged with an origin - the higher it is, the more engagement the user
+// has had with this site recently.
 //
-// Positive user activity, such as visiting the origin often and adding it to
-// the homescreen, will increase the site engagement score. Negative activity,
-// such as rejecting permission prompts or not responding to notifications, will
-// decrease the site engagement score.
+// User activity such as visiting the origin often, interacting with the origin,
+// and adding it to the homescreen will increase the site engagement score. If
+// a site's score does not increase for some time, it will decay, eventually
+// reaching zero with further disuse.
+//
+// The SiteEngagementService object must be created and used on the UI thread
+// only. Engagement scores may be queried in a read-only fashion from other
+// threads using SiteEngagementService::GetScoreFromSettings, but use of this
+// method is discouraged unless it is not possible to use the UI thread.
 class SiteEngagementService : public KeyedService,
                               public history::HistoryServiceObserver,
                               public SiteEngagementScoreProvider {
  public:
   // WebContentsObserver that detects engagement triggering events and notifies
   // the service of them.
   class Helper;
 
   enum EngagementLevel {
     ENGAGEMENT_LEVEL_NONE,
     ENGAGEMENT_LEVEL_LOW,
     ENGAGEMENT_LEVEL_MEDIUM,
     ENGAGEMENT_LEVEL_HIGH,
     ENGAGEMENT_LEVEL_MAX,
   };
 
   // The name of the site engagement variation field trial.
   static const char kEngagementParams[];
 
-  // Returns the site engagement service attached to this profile. May return
-  // null if the service does not exist (e.g. the user is in incognito).
+  // Returns the site engagement service attached to this profile. The service
+  // exists in incognito mode; scores will be initialised using the score from
+  // the profile that the incognito session was created from, and will increase
+  // and decrease as usual. Engagement earned or decayed in incognito will not
+  // be persisted or reflected in the original profile.
+  //
+  // This method must be called on the UI thread.
   static SiteEngagementService* Get(Profile* profile);
 
   // Returns the maximum possible amount of engagement that a site can accrue.
   static double GetMaxPoints();
 
   // Returns whether or not the site engagement service is enabled.
   static bool IsEnabled();
 
+  // Returns the score for |origin| based on |settings|. Can be called on any
+  // thread and does not cause any cleanup, decay, etc.
+  //
+  // Should only be used if you cannot create a SiteEngagementService (i.e. you
+  // cannot run on the UI thread).
+  static double GetScoreFromSettings(HostContentSettingsMap* settings,
+                                     const GURL& origin);
+
   explicit SiteEngagementService(Profile* profile);
   ~SiteEngagementService() override;
 
-  // Returns the engagement level of |url|. This is the recommended API for
-  // clients
+  // Returns the engagement level of |url|.
   EngagementLevel GetEngagementLevel(const GURL& url) const;
 
   // Returns a map of all stored origins and their engagement scores.
   std::map<GURL, double> GetScoreMap() const;
 
   // Returns whether the engagement service has enough data to make meaningful
   // decisions. Clients should avoid using engagement in their heuristic until
   // this is true.
   bool IsBootstrapped() const;
 
@@ skipping 24 matching lines @@
   FRIEND_TEST_ALL_PREFIXES(SiteEngagementServiceTest, LastShortcutLaunch);
   FRIEND_TEST_ALL_PREFIXES(SiteEngagementServiceTest,
                            CleanupOriginsOnHistoryDeletion);
   FRIEND_TEST_ALL_PREFIXES(SiteEngagementServiceTest, IsBootstrapped);
   FRIEND_TEST_ALL_PREFIXES(SiteEngagementServiceTest, EngagementLevel);
   FRIEND_TEST_ALL_PREFIXES(SiteEngagementServiceTest, Observers);
   FRIEND_TEST_ALL_PREFIXES(SiteEngagementServiceTest, ScoreDecayHistograms);
   FRIEND_TEST_ALL_PREFIXES(SiteEngagementServiceTest, LastEngagementTime);
   FRIEND_TEST_ALL_PREFIXES(SiteEngagementServiceTest,
                            IncognitoEngagementService);
+  FRIEND_TEST_ALL_PREFIXES(SiteEngagementServiceTest, GetScoreFromSettings);
   FRIEND_TEST_ALL_PREFIXES(AppBannerSettingsHelperTest, SiteEngagementTrigger);
 
   // Only used in tests.
   SiteEngagementService(Profile* profile, std::unique_ptr<base::Clock> clock);
 
   // Adds the specified number of points to the given origin, respecting the
   // maximum limits for the day and overall.
   void AddPoints(const GURL& url, double points);
 
   // Retrieves the SiteEngagementScore object for |origin|.
@@ skipping 88 matching lines @@
   // A list of observers. When any origin registers an engagement-increasing
   // event, each observer's OnEngagementIncreased method will be called.
   base::ObserverList<SiteEngagementObserver> observer_list_;
 
   base::WeakPtrFactory<SiteEngagementService> weak_factory_;
 
   DISALLOW_COPY_AND_ASSIGN(SiteEngagementService);
 };
 
 #endif  // CHROME_BROWSER_ENGAGEMENT_SITE_ENGAGEMENT_SERVICE_H_