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