components/rlz/rlz_tracker.h

   1 // Copyright (c) 2012 The Chromium Authors. All rights reserved.
   2 // Use of this source code is governed by a BSD-style license that can be
   3 // found in the LICENSE file.
   4
   5 #ifndef COMPONENTS_RLZ_RLZ_TRACKER_H_
   6 #define COMPONENTS_RLZ_RLZ_TRACKER_H_
   7
   8 #include <map>
   9 #include <memory>
  10 #include <string>
  11
  12 #include "base/macros.h"
  13 #include "base/memory/ref_counted.h"
  14 #include "base/memory/singleton.h"
  15 #include "base/sequence_checker.h"
  16 #include "base/strings/string16.h"
  17 #include "base/time/time.h"
  18 #include "build/build_config.h"
  19 #include "rlz/lib/rlz_lib.h"
  20
  21 namespace base {
  22 class SequencedTaskRunner;
  23 }
  24
  25 namespace rlz {
  26
  27 class RLZTrackerDelegate;
  28
  29 // RLZ is a library which is used to measure distribution scenarios.
  30 // Its job is to record certain lifetime events in the registry and to send
  31 // them encoded as a compact string at most twice. The sent data does
  32 // not contain information that can be used to identify a user or to infer
  33 // browsing habits. The API in this file is a wrapper around the open source
  34 // RLZ library which can be found at http://code.google.com/p/rlz.
  35 //
  36 // For partner or bundled installs, the RLZ might send more information
  37 // according to the terms disclosed in the EULA.
  38
  39 class RLZTracker {
  40  public:
  41   // Sets the RLZTrackerDelegate that should be used by the global RLZTracker
  42   // instance. Must be called before calling any other method of RLZTracker.
  43   static void SetRlzDelegate(std::unique_ptr<RLZTrackerDelegate> delegate);
  44
  45   // Initializes the RLZ library services for use in chrome. Schedules a delayed
  46   // task that performs the ping and registers some events when 'first-run' is
  47   // true.
  48   //
  49   // When |send_ping_immediately| is true, a financial ping should be sent
  50   // immediately after a first search is recorded, without waiting for |delay|.
  51   // However, we only want this behaviour on first run.
  52   //
  53   // If the chrome brand is organic (no partners) then the pings don't occur.
  54   static bool InitRlzDelayed(bool first_run,
  55                              bool send_ping_immediately,
  56                              base::TimeDelta delay,
  57                              bool is_google_default_search,
  58                              bool is_google_homepage,
  59                              bool is_google_in_startpages);
  60
  61   // Records an RLZ event. Some events can be access point independent.
  62   // Returns false it the event could not be recorded. Requires write access
  63   // to the HKCU registry hive on windows.
  64   static bool RecordProductEvent(rlz_lib::Product product,
  65                                  rlz_lib::AccessPoint point,
  66                                  rlz_lib::Event event_id);
  67
  68   // For the point parameter of RecordProductEvent.
  69   static rlz_lib::AccessPoint ChromeOmnibox();
  70 #if !defined(OS_IOS)
  71   static rlz_lib::AccessPoint ChromeHomePage();
  72   static rlz_lib::AccessPoint ChromeAppList();
  73 #endif
  74
  75   // Gets the HTTP header value that can be added to requests from the
  76   // specific access point.  The string returned is of the form:
  77   //
  78   //    "X-Rlz-String: <access-point-rlz>\r\n"
  79   //
  80   static std::string GetAccessPointHttpHeader(rlz_lib::AccessPoint point);
  81
  82   // Gets the RLZ value of the access point.
  83   // Returns false if the rlz string could not be obtained. In some cases
  84   // an empty string can be returned which is not an error.
  85   static bool GetAccessPointRlz(rlz_lib::AccessPoint point,
  86                                 base::string16* rlz);
  87
  88   // Invoked during shutdown to clean up any state created by RLZTracker.
  89   static void CleanupRlz();
  90
  91 #if defined(OS_CHROMEOS)
  92   // Clears all product state. Should be called when turning RLZ off. On other
  93   // platforms, this is done by product uninstaller.
  94   static void ClearRlzState();
  95 #endif
  96
  97   // This method is public for use by the Singleton class.
  98   static RLZTracker* GetInstance();
  99
 100   // Enables zero delay for InitRlzDelayed. For testing only.
 101   static void EnableZeroDelayForTesting();
 102
 103 #if !defined(OS_IOS)
 104   // Records that the app list search has been used.
 105   static void RecordAppListSearch();
 106 #endif
 107
 108   // The following methods are made protected so that they can be used for
 109   // testing purposes. Production code should never need to call these.
 110  protected:
 111   RLZTracker();
 112   virtual ~RLZTracker();
 113
 114   // Performs initialization of RLZ tracker that is purposefully delayed so
 115   // that it does not interfere with chrome startup time.
 116   virtual void DelayedInit();
 117
 118   // Used by test code to override the default RLZTracker instance returned
 119   // by GetInstance().
 120   void set_tracker(RLZTracker* tracker) { tracker_ = tracker; }
 121
 122   // Sends the financial ping to the RLZ servers and invalidates the RLZ string
 123   // cache since the response from the RLZ server may have changed then.
 124   // Protected so that its accessible from tests.
 125   void PingNowImpl();
 126
 127  private:
 128   friend struct base::DefaultSingletonTraits<RLZTracker>;
 129   friend class base::RefCountedThreadSafe<RLZTracker>;
 130
 131   // Implementation called from SetRlzDelegate() static method.
 132   void SetDelegate(std::unique_ptr<RLZTrackerDelegate> delegate);
 133
 134   // Implementation called from InitRlzDelayed() static method.
 135   bool Init(bool first_run,
 136             bool send_ping_immediately,
 137             base::TimeDelta delay,
 138             bool is_google_default_search,
 139             bool is_google_homepage,
 140             bool is_google_in_startpages);
 141
 142   // Implementation called from CleanupRlz static method.
 143   void Cleanup();
 144
 145   // Implementation called from RecordProductEvent() static method.
 146   bool RecordProductEventImpl(rlz_lib::Product product,
 147                               rlz_lib::AccessPoint point,
 148                               rlz_lib::Event event_id);
 149
 150   // Records FIRST_SEARCH event. Passed as bound callback to RLZTrackerDelegate.
 151   void RecordFirstSearch(rlz_lib::AccessPoint point);
 152
 153   // Implementation called from GetAccessPointRlz() static method.
 154   bool GetAccessPointRlzImpl(rlz_lib::AccessPoint point, base::string16* rlz);
 155
 156   // Schedules the delayed initialization. This method is virtual to allow
 157   // tests to override how the scheduling is done.
 158   virtual void ScheduleDelayedInit(base::TimeDelta delay);
 159
 160   // Schedules a call to rlz_lib::RecordProductEvent(). This method is virtual
 161   // to allow tests to override how the scheduling is done.
 162   virtual bool ScheduleRecordProductEvent(rlz_lib::Product product,
 163                                           rlz_lib::AccessPoint point,
 164                                           rlz_lib::Event event_id);
 165
 166   // Schedules a call to rlz_lib::RecordFirstSearch(). This method is virtual
 167   // to allow tests to override how the scheduling is done.
 168   virtual bool ScheduleRecordFirstSearch(rlz_lib::AccessPoint point);
 169
 170   // Schedules a call to rlz_lib::SendFinancialPing(). This method is virtual
 171   // to allow tests to override how the scheduling is done.
 172   virtual void ScheduleFinancialPing();
 173
 174   // Schedules a call to GetAccessPointRlz() on the I/O thread if the current
 175   // thread is not already the I/O thread, otherwise does nothing. Returns
 176   // true if the call was scheduled, and false otherwise. This method is
 177   // virtual to allow tests to override how the scheduling is done.
 178   virtual bool ScheduleGetAccessPointRlz(rlz_lib::AccessPoint point);
 179
 180   // Sends the financial ping to the RLZ servers. This method is virtual to
 181   // allow tests to override.
 182   virtual bool SendFinancialPing(const std::string& brand,
 183                                  const base::string16& lang,
 184                                  const base::string16& referral);
 185
 186 #if defined(OS_CHROMEOS)
 187   // Implementation called from ClearRlzState static method.
 188   void ClearRlzStateImpl();
 189
 190   // Schedules a call to ClearRlzStateImpl(). This method is virtual
 191   // to allow tests to override how the scheduling is done.
 192   virtual bool ScheduleClearRlzState();
 193 #endif
 194
 195   // Returns a pointer to the bool corresponding to whether |point| has been
 196   // used but not reported.
 197   bool* GetAccessPointRecord(rlz_lib::AccessPoint point);
 198
 199   // Tracker used for testing purposes only. If this value is non-NULL, it
 200   // will be returned from GetInstance() instead of the regular singleton.
 201   static RLZTracker* tracker_;
 202
 203   // Delegate abstracting embedder specific knowledge. Must not be null.
 204   std::unique_ptr<RLZTrackerDelegate> delegate_;
 205
 206   // Configuation data for RLZ tracker. Set by call to Init().
 207   bool first_run_;
 208   bool send_ping_immediately_;
 209   bool is_google_default_search_;
 210   bool is_google_homepage_;
 211   bool is_google_in_startpages_;
 212
 213   // Keeps track if the RLZ tracker has already performed its delayed
 214   // initialization.
 215   bool already_ran_;
 216
 217   // Keeps a cache of RLZ access point strings, since they rarely change.
 218   // The cache must be protected by a lock since it may be accessed from
 219   // the UI thread for reading and the IO thread for reading and/or writing.
 220   base::Lock cache_lock_;
 221   std::map<rlz_lib::AccessPoint, base::string16> rlz_cache_;
 222
 223   // Keeps track of whether the omnibox, home page or app list have been used.
 224   bool omnibox_used_;
 225   bool homepage_used_;
 226   bool app_list_used_;
 227
 228   // Main and (optionally) reactivation brand codes, assigned on UI thread.
 229   std::string brand_;
 230   std::string reactivation_brand_;
 231
 232   // Minimum delay before sending financial ping after initialization.
 233   base::TimeDelta min_init_delay_;
 234
 235   // Runner for RLZ background tasks.  The checked is used to verify operations
 236   // occur in the correct sequence, especially in tests.
 237   scoped_refptr<base::SequencedTaskRunner> background_task_runner_;
 238   SEQUENCE_CHECKER(sequence_checker_);
 239
 240   DISALLOW_COPY_AND_ASSIGN(RLZTracker);
 241 };
 242
 243 }  // namespace rlz
 244
 245 #endif  // COMPONENTS_RLZ_RLZ_TRACKER_H_