search_engine_choice_utils.h | Explore in Territory

// Copyright 2023 The Chromium Authors
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.

#ifndef COMPONENTS_SEARCH_ENGINES_SEARCH_ENGINE_CHOICE_SEARCH_ENGINE_CHOICE_UTILS_H_
#define COMPONENTS_SEARCH_ENGINES_SEARCH_ENGINE_CHOICE_SEARCH_ENGINE_CHOICE_UTILS_H_

#include <optional>
#include <string>
#include <vector>

#include "base/memory/raw_ptr.h"
#include "build/build_config.h"
#include "components/search_engines/choice_made_location.h"
#include "components/search_engines/search_engine_type.h"
#include "components/search_engines/template_url.h"
#include "third_party/abseil-cpp/absl/types/variant.h"

class PrefService;
class SearchTermsData;
struct TemplateURLData;

namespace search_engines {

extern const char kSearchEngineChoiceScreenProfileInitConditionsHistogram[];
extern const char kSearchEngineChoiceScreenNavigationConditionsHistogram[];
extern const char kSearchEngineChoiceScreenEventsHistogram[];
extern const char kSearchEngineChoiceScreenDefaultSearchEngineTypeHistogram[];
extern const char kSearchEngineChoiceScreenSelectedEngineIndexHistogram[];
extern const char kSearchEngineChoiceScreenShowedEngineAtHistogramPattern[];
extern const char
    kSearchEngineChoiceScreenShowedEngineAtCountryMismatchHistogram[];
extern const char kSearchEngineChoiceWipeReasonHistogram[];
extern const char kSearchEngineChoiceRepromptHistogram[];
extern const char kSearchEngineChoiceRepromptWildcardHistogram[];
extern const char kSearchEngineChoiceRepromptSpecificCountryHistogram[];
extern const char kSearchEngineChoiceUnexpectedIdHistogram[];

// These values are persisted to logs. Entries should not be renumbered and
// numeric values should never be reused.
// LINT.IfChange(SearchEngineChoiceScreenConditions)
enum class SearchEngineChoiceScreenConditions { … };
// LINT.ThenChange(/tools/metrics/histograms/enums.xml:SearchEngineChoiceScreenConditions)

// These values are persisted to logs. Entries should not be renumbered and
// numeric values should never be reused.
// LINT.IfChange(SearchEngineChoiceScreenEvents)
enum class SearchEngineChoiceScreenEvents { … };
// LINT.ThenChange(/tools/metrics/histograms/enums.xml:SearchEngineChoiceScreenEvents)

enum class ChoicePromo { … };

// The cause for wiping the search engine choice preferences. Only used for
// metrics.
// These values are persisted to logs. Entries should not be renumbered and
// numeric values should never be reused.
enum class WipeSearchEngineChoiceReason { … };

// Exposed for testing.
// These values are persisted to logs. Entries should not be renumbered and
// numeric values should never be reused.
enum class RepromptResult { … };

struct ChoiceScreenDisplayState { … };

// Contains basic information about the search engine choice screen, notably
// the list of actual search engines to show, and other metadata associated
// with how it was determined.
class ChoiceScreenData { … };

// The state of the search engine choice country command line override.
enum class SearchEngineCountryListOverride { … };

SearchEngineCountryOverride;

// Gets the search engine country command line override.
// Returns an int if the country id is passed to the command line or a
// `SearchEngineCountryListOverride` if the special values of
// `kDefaultListCountryOverride` or `kEeaListCountryOverride` are passed.
std::optional<SearchEngineCountryOverride> GetSearchEngineCountryOverride();

// Returns whether the search engine list is overridden in the command line to
// return the default list or the list of all eea engines.
bool HasSearchEngineCountryListOverride();

// Whether the choice screen flag is generally enabled for the specific flow.
// TODO(b/318824817): To be removed post-launch.
bool IsChoiceScreenFlagEnabled(ChoicePromo promo);

// Returns whether the provided `country_id` is eligible for the EEA default
// search engine choice prompt.
// See `//components/country_codes` for the Country ID format.
bool IsEeaChoiceCountry(int country_id);

// Records the specified choice screen condition at profile initialization.
void RecordChoiceScreenProfileInitCondition(
    SearchEngineChoiceScreenConditions event);

// Records the specified choice screen condition for relevant navigations.
void RecordChoiceScreenNavigationCondition(
    SearchEngineChoiceScreenConditions condition);

// Records the specified choice screen event.
void RecordChoiceScreenEvent(SearchEngineChoiceScreenEvents event);

// Records the type of the default search engine that was chosen by the user
// in the search engine choice screen or in the settings page.
void RecordChoiceScreenDefaultSearchProviderType(SearchEngineType engine_type);

// Records the index of the search engine that was chosen by the user as it was
// displayed on the choice screen.
void RecordChoiceScreenSelectedIndex(int selected_engine_index);

// Records the positions of search engines in a choice screen. Intended to be
// recorded when a choice happens, so that we emit it at most once per choice
// "scope". For more info, please see
// http://go/chrome-choice-screen-positions-histogram-design (Google-internal).
// Don't call this directly. Instead, go through
// `SearchEngineChoiceService::MaybeRecordChoiceScreenDisplayState()`.
void RecordChoiceScreenPositions(
    const std::vector<SearchEngineType>& displayed_search_engines);

// Records whether `RecordChoiceScreenPositions()` had to be skipped due to
// a mismatch between the Variations/UMA country and the profile/choice
// country. If `has_mismatch` is `true`, we record that it was "skipped", or
// that it was "not skipped" otherwise.
void RecordChoiceScreenPositionsCountryMismatch(bool has_mismatch);

// For debugging purposes, record the ID of the current default search engine
// that does not exist in the prepopulated search providers data.
void RecordUnexpectedSearchProvider(const TemplateURLData& data);

// Clears the search engine choice prefs, such as the timestamp and the Chrome
// version, to ensure the choice screen is shown again.
void WipeSearchEngineChoicePrefs(PrefService& profile_prefs,
                                 WipeSearchEngineChoiceReason reason);

#if !BUILDFLAG(IS_ANDROID)
// Returns the engine marketing snippet string resource id or -1 if the snippet
// was not found.
// The function definition is generated in `generated_marketing_snippets.cc`.
// `engine_keyword` is the search engine keyword.
int GetMarketingSnippetResourceId(const std::u16string& engine_keyword);

// Returns the marketing snippet string or the fallback string if the search
// engine didn't provide its own.
std::u16string GetMarketingSnippetString(
    const TemplateURLData& template_url_data);

// Returns the resource ID for the icon associated with `engine_keyword`, or -1
// if not found. All search engines prepopulated in EEA countries are guaranteed
// to have an icon.
// The function definition is generated by `generate_search_engine_icons.py`in
// `generated_search_engine_resource_ids.cc`.
int GetIconResourceId(const std::u16string& engine_keyword);

#endif

}  // namespace search_engines

#endif  // COMPONENTS_SEARCH_ENGINES_SEARCH_ENGINE_CHOICE_SEARCH_ENGINE_CHOICE_UTILS_H_
chromium/components/search_engines/search_engine_choice/search_engine_choice_utils.h
