[TTS] Add aggregation of CTR metrics to the CS component.

components/contextual_search/browser/ctr_aggregator.h

+// Copyright 2016 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.
+
+// Provides aggregation of feature usage by tracking impressions and clicks

[marq (ping after 24h), 2016/08/30 08:30:36]

Define "impression" and "click" in this context ("click" is confusing when the
devices this is used on have touch interfaces)

[Donn Denman, 2016/08/31 04:35:20]

Done.

+// over 1-week and 28-day intervals.
+// Used by Contextual Search to record impressions of the Bar and CTR of

[marq (ping after 24h), 2016/08/30 08:30:36]

Define "CTR".

[Donn Denman, 2016/08/31 04:35:21]

Done.

+// panel opens to use as signals for Tap triggering.
+
+#ifndef COMPONENTS_CONTEXTUAL_SEARCH_BROWSER_CTR_AGGREGATOR_H_
+#define COMPONENTS_CONTEXTUAL_SEARCH_BROWSER_CTR_AGGREGATOR_H_
+
+#include <string>
+
+#include "base/gtest_prod_util.h"
+#include "base/macros.h"
+#include "components/contextual_search/browser/device_int_storage.h"
+
+namespace contextual_search {
+
+// Usage: Create a CTRAggregator and start recording impressions or reading
+// aggregated data.  Get data from the previous week or previous 4-week period

[marq (ping after 24h), 2016/08/30 08:30:36]

How is this data used? Does it leave the device? How can the user delete it?

[Donn Denman, 2016/08/31 04:35:20]

Done.

+// that ended with the previous week.
+// A new week starts at an arbitrary time based on seconds since the Epoch.
+// The data from the previous week and previous 28-day period are guaranteed to
+// be complete only if the HasPrevious method returns true.  If one of the data
+// accessors is called when the data is not complete the Impressions will return
+// data for only the partial period, and the CTR method will return NAN.
+class CTRAggregator {
+ public:
+  CTRAggregator(DeviceIntStorage& storage);
+  ~CTRAggregator();
+
+  // Record an impression.  Records a click if |did_click| is true.

[marq (ping after 24h), 2016/08/30 08:30:36]

s/Record/Records/

[Donn Denman, 2016/08/31 04:35:21]

Done.

+  void RecordImpression(bool did_click);
+
+  // Returns whether we have the previous week's data for this user.
+  bool HasPreviousWeekData();
+
+  // Gets the number of impressions from the previous week.
+  int GetPreviousWeekImpressions();
+
+  // Gets the CTR from the previous week.
+  // Returns NAN if there is no previous week's data for this user.
+  float GetPreviousWeekCTR();
+
+  // Returns whether we have data from a 28 day period ending in the previous
+  // week.
+  bool HasPrevious28DayData();
+
+  // Gets the number of impressions from a 28 day period ending in the previous
+  // week.
+  int GetPrevious28DayImpressions();
+
+  // Gets the CTR from a 28 day period ending in the previous week.
+  // Returns NAN if there is no data for that period for this user.
+  float GetPrevious28DayCTR();
+
+ private:
+  // This implementation uses a fixed number of bins to store integer impression
+  // and click data for the most recent N weeks, where N = 5 (in order to keep 4
+  // complete weeks).  Another bin keeps track of the current week being
+  // written.  Yet another bin records when data was first stored or accessed so
+  // we can know when a time period has complete data.
+  friend class CTRAggregatorTest;
+  FRIEND_TEST_ALL_PREFIXES(CTRAggregatorTest, SimpleOperationTest);
+  FRIEND_TEST_ALL_PREFIXES(CTRAggregatorTest, MultiWeekTest);
+  FRIEND_TEST_ALL_PREFIXES(CTRAggregatorTest, SkipOneWeekTest);
+  FRIEND_TEST_ALL_PREFIXES(CTRAggregatorTest, SkipThreeWeeksTest);
+  FRIEND_TEST_ALL_PREFIXES(CTRAggregatorTest, SkipFourWeeksTest);
+
+  // Constructor for testing; sets the week.
+  CTRAggregator(DeviceIntStorage& storage, int week_number);
+  // For testing, increment the current week number by |weeks|.
+  void IncrementWeek(int weeks);
+
+  // Ensure that the week number of the first week ever used is recorded.

[marq (ping after 24h), 2016/08/30 08:30:36]

Ensures.

[Donn Denman, 2016/08/31 04:35:21]

Done.

+  // This should be called at least once through every public API code path.
+  void EnsureFirstWeekRecorded();
+  // Updates storage of skipped weeks when advancing to a new current week.
+  void UpdateStorageToCurrentWeek();
+
+  // Returns the string key of the storage bin for the given week |which_week|.
+  std::string GetWeekKey(int which_week);
+  // Returns the string key for the "clicks" storage bin for the given week
+  // |which_week|.
+  std::string GetWeekClicksKey(int which_week);
+  // Returns the string key for the "impressions" storage bin for the given week
+  // |which_week|.
+  std::string GetWeekImpressionsKey(int which_week);
+
+  // Gets the number of clicks from the previous week.
+  int GetPreviousWeekClicks();
+  // Gets the number of clicks from a 28 day period ending in the previous
+  // week.
+  int GetPrevious28DayClicks();
+
+  // Increments the value in the storage bin with the given |key|.
+  void Increment(std::string key);
+
+  // Cached storage accessors:
+  // Reads and returns an int keyed by |storage_key|.
+  int ReadInt(std::string storage_key);
+  // Writes the given int |value| keyed by |storage_key|.
+  void WriteInt(std::string storage_key, int value);
+
+  // Persistently stores the CTR data.
+  DeviceIntStorage& storage_;
+  int week_number_;
+
+  DISALLOW_COPY_AND_ASSIGN(CTRAggregator);
+};
+
+}  // namespace contextual_search
+
+#endif  // COMPONENTS_CONTEXTUAL_SEARCH_BROWSER_CTR_AGGREGATOR_H_