chromium/chrome/browser/web_applications/web_app_pref_guardrails.h

// 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 CHROME_BROWSER_WEB_APPLICATIONS_WEB_APP_PREF_GUARDRAILS_H_
#define CHROME_BROWSER_WEB_APPLICATIONS_WEB_APP_PREF_GUARDRAILS_H_

#include <optional>
#include <string>
#include <string_view>

#include "base/memory/raw_ptr.h"
#include "base/memory/raw_ref.h"
#include "base/time/time.h"
#include "chrome/browser/web_applications/web_app_constants.h"
#include "chrome/common/pref_names.h"
#include "components/prefs/scoped_user_pref_update.h"
#include "components/webapps/common/web_app_id.h"

class PrefService;

namespace user_prefs {
class PrefRegistrySyncable;
}

namespace web_app {

struct GuardrailData { … };

struct GuardrailPrefNames { … };

std::optional<int> GetIntWebAppPref(const PrefService* pref_service,
                                    const webapps::AppId& app_id,
                                    std::string_view path);

std::optional<base::Time> GetTimeWebAppPref(const PrefService* pref_service,
                                            const webapps::AppId& app_id,
                                            std::string_view path);

// WebAppPrefGuardrails provide a simple way of building guardrails based on the
// number of times a prompt on an app has been ignored or dismissed in the past.
// The guardrails help prevent the prompt from showing up after a specific
// number of times based on the user behavior. Data for computing these
// guardrails are stored in the prefs.
class WebAppPrefGuardrails { … };

// ----------------------PWA Install IPH guardrails----------------------------
// In Product Help (IPH) notifications are limited by guardrails to avoid
// becoming a nuisance to users. This is an overview of how they work:
// - Accepting the IPH bubble will not decrease further prompts, and resets
// existing guardrails. Otherwise:
// - IPH is limited globally to one every:
//   - 14 days if prompt is ignored.
// - A specific site will show the IPH for installation after:
//   - 90 days if prompt is ignored.
// - For a specific site, the IPH is shown 3 times at max, and then it gets
// blocked.
// - Globally, the IPH is shown 4 times at max.
inline constexpr GuardrailData kIphGuardrails{ … };

inline constexpr GuardrailPrefNames kIphPrefNames{ … };

// ----------------------ML guardrails----------------------------
// Machine Learning (ML) triggered install prompts are limited by guardrails to
// avoid becoming a nuisance to users. This is an overview of how they work:
// - Accepting and installing an app from a prompt will not decrease further
// prompts and resets all guardrails. Otherwise:
// - Prompt is limited globally to one every:
//   - 7 day if prompt is ignored.
//   - 14 days if prompt is dismissed.
// - A specific site will only be suggested again after:
//   - 14 days for an ignored prompt.
//   - 28 days for a dismissed prompt.
// - For a specific site, the prompt is shown 3 times at max, and then it gets
// blocked.
// - Globally, the prompt is shown 5 times at max.
// - The guardrails are reset every `kTotalDaysToStoreMLGuardrails` days (this
// value is Finch configurable).
// - Example scenarios for triggering guardrails:
//   - Multi site scenario: Visiting at least two ML promotable web-apps daily
//   and ignoring the prompts. The prompt is then seen on days 0, 7, 14, 21 and
//   28, after which they are blocked.
//   - Single site scenario: Visiting one ML promotable web-app daily and
//   ignoring the prompts. The prompt is then seen on for the same app on day 0,
//   14 and 28, after which they are blocked.
//   - In both cases, the user is blocked for `kTotalDaysToStoreMLGuardrails`
//   days, after which the guardrails are cleared.
inline constexpr GuardrailData kMlPromoGuardrails{ … };

inline constexpr GuardrailPrefNames kMlPromoPrefNames{ … };

// -----------------------IPH Navigation Capturing guardrails-------------------
// Navigation capturing In Product Help (IPH) is limited by guardrails to avoid
// becoming a nuisance to users. This is an overview of how they work:
// - Accepting the IPH bubble will not decrease further prompts, and resets
// existing guardrails. All values are measured globally and not per app.
// - The IPH bubble is limited to 1 per day.
// - The IPH bubble shows up 6 times at max, after which it does not show up
// again.
// - Example scenarios for triggering guardrails:
//   - User launches a site in an installed app with navigation capturing
//   enabled and dismisses the IPH prompt. The prompt is then seen on days 0, 1,
//   2, 3, 4 and 5, after which the user never sees the IPH prompt again.
inline constexpr GuardrailData kIPHNavigationCapturingGuardrails{ … };

// TODO(crbug.com/362123239): Rename pref keys from link capturing to navigation
// capturing, migrate data if needed.
inline constexpr GuardrailPrefNames kIPHNavigationCapturingPrefNames{ … };
}  // namespace web_app

#endif  // CHROME_BROWSER_WEB_APPLICATIONS_WEB_APP_PREF_GUARDRAILS_H_