chromium/components/webapps/browser/installable/ml_installability_promoter.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 COMPONENTS_WEBAPPS_BROWSER_INSTALLABLE_ML_INSTALLABILITY_PROMOTER_H_
#define COMPONENTS_WEBAPPS_BROWSER_INSTALLABLE_ML_INSTALLABILITY_PROMOTER_H_

#include <memory>

#include "base/functional/callback.h"
#include "base/memory/scoped_refptr.h"
#include "base/memory/weak_ptr.h"
#include "base/run_loop.h"
#include "base/time/time.h"
#include "base/types/pass_key.h"
#include "components/segmentation_platform/public/trigger.h"
#include "components/webapps/browser/installable/installable_metrics.h"
#include "components/webapps/browser/installable/metrics/site_quality_metrics_task.h"
#include "components/webapps/browser/installable/ml_install_result_reporter.h"
#include "content/public/browser/service_worker_context_observer.h"
#include "content/public/browser/web_contents_observer.h"
#include "content/public/browser/web_contents_user_data.h"
#include "mojo/public/cpp/bindings/struct_ptr.h"
#include "third_party/blink/public/mojom/favicon/favicon_url.mojom-forward.h"
#include "third_party/blink/public/mojom/manifest/manifest.mojom.h"
#include "url/gurl.h"

namespace content {
class NavigationHandle;
class RenderFrameHost;
class ServiceWorkerContext;
class StoragePartition;
class WebContents;
enum class Visibility;
}  // namespace content

namespace segmentation_platform {
struct ClassificationResult;
}  // namespace segmentation_platform

namespace webapps {
class AppBannerManager;
class MlInstallOperationTracker;
class SiteManifestMetricsTask;

constexpr base::TimeDelta kTimeToWaitForWebContentsObservers = …;

struct SiteInstallMetrics { … };

// This class is used to measure metrics after page load and trigger a ML model
// to promote installability of a site.
// Note: This class only runs it's pipeline if the web contents also has an
// AppBannerManager constructed.
//
// To use this class, any type of user installation showing installation UX to
// the user MUST:
// - Create a `MlInstallOperationTracker` via
//   `RegisterCurrentInstallForWebContents(source)`.
// - Call the `ReportResult` method on that tracker when the user installs,
//   dismisses, or ignores the installation UX.
// - Destroy the tracker when the installation UX is complete (this allows
//   `HasCurrentInstall()` to return false again).
//
// If that is done properly, then this class will:
// - Gather metrics on the given page load (to be used by ML model).
// - Call the segmentation service via
//   `AppBannerManager::GetSegmentationPlatformService()` to request
//   classification for the `kWebAppInstallationPromoKey`.
// - Automatically report the result to Ml if an installation is already showing
//   (AKA triggered by the user or developer) and exit.
// - Automatically reject the classification if the
//   `AppBannerManager::IsMlPromotionBlockedByHistoryGuardrail` returns true,
//   and exit.
// - Wait for the web contents to be visible.
// - Finally call `AppBannerManager::OnMlInstallPrediction` if none of the above
//   cases exited early.
//
// The reporting of the ML results & updating of the guardrails is done through
// `MlInstallOperationTracker::ReportResult` method, but ONLY if the
// installation was triggered/received a classification from ML.
//
// The following methods are used from AppBannerManager:
// `IsAppFullyInstalledForSiteUrl`, `IsAppPartiallyInstalledForSiteUrl`,
// `SaveInstallation*`, `IsMlPromotionBlockedByHistoryGuardrail`,
// `OnMlInstallPrediction`, `GetSegmentationPlatformService`.
//
// Browsertests are located in
// chrome/browser/web_applications/ml_promotion_browsertest.cc
class MLInstallabilityPromoter
    : public content::WebContentsObserver,
      public content::ServiceWorkerContextObserver,
      public content::WebContentsUserData<MLInstallabilityPromoter> { … };

}  // namespace webapps

#endif  // COMPONENTS_WEBAPPS_BROWSER_INSTALLABLE_ML_INSTALLABILITY_PROMOTER_H_