1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
|
// Copyright 2024 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_UI_USER_EDUCATION_BROWSER_USER_EDUCATION_INTERFACE_H_
#define CHROME_BROWSER_UI_USER_EDUCATION_BROWSER_USER_EDUCATION_INTERFACE_H_
#include <concepts>
#include "base/feature_list.h"
#include "base/types/pass_key.h"
#include "components/user_education/common/feature_promo/feature_promo_controller.h"
#include "components/user_education/common/feature_promo/feature_promo_handle.h"
#include "components/user_education/common/feature_promo/feature_promo_result.h"
#include "components/user_education/common/new_badge/new_badge_controller.h"
class AppMenuButton;
class BrowserHelpBubble;
class UserEducationInternalsPageHandlerImpl;
namespace content {
class WebContents;
}
namespace web_app {
class WebAppUiManagerImpl;
}
// Describes what to do when the feature associated with an IPH is used.
enum class FeaturePromoFeatureUsedAction {
// If the promo is showing, it is dismissed. If it is queued, it will be
// canceled. In most cases, the promo will not be shown again.
kClosePromoIfPresent,
// If the promo is showing or queued, it continues to be showing or queued.
// However, marking the feature as used may prevent the promo from showing
// in the future. If you intend to use e.g. CloseFeaturePromoAndContinue(),
// this option will avoid terminating the promo prematurely.
kIgnorePromoIfPresent,
};
// Provides the interface for common User Education actions.
class BrowserUserEducationInterface {
public:
BrowserUserEducationInterface() = default;
BrowserUserEducationInterface(const BrowserUserEducationInterface&) = delete;
void operator=(const BrowserUserEducationInterface&) = delete;
virtual ~BrowserUserEducationInterface() = default;
// Gets the windows's FeaturePromoController which manages display of
// in-product help. Will return null in incognito and guest profiles.
user_education::FeaturePromoController*
GetFeaturePromoControllerForTesting() {
return GetFeaturePromoControllerImpl();
}
// Only a limited number of non-test classes are allowed direct access to the
// feature promo controller.
template <typename T>
requires std::same_as<T, AppMenuButton> ||
std::same_as<T, BrowserHelpBubble> ||
std::same_as<T, UserEducationInternalsPageHandlerImpl> ||
std::same_as<T, web_app::WebAppUiManagerImpl>
user_education::FeaturePromoController* GetFeaturePromoController(
base::PassKey<T>) {
return GetFeaturePromoControllerImpl();
}
// Returns whether `iph_feature` is queued to be shown. Promos can be queued
// for a period of time before they become active, if they are being held due
// to an incompatible UI state or a blocking IPH.
virtual bool IsFeaturePromoQueued(const base::Feature& iph_feature) const = 0;
// Returns whether the promo associated with `iph_feature` is running.
//
// Includes promos with visible bubbles and those which have been continued
// with CloseFeaturePromoAndContinue() and are still running in the
// background.
virtual bool IsFeaturePromoActive(const base::Feature& iph_feature) const = 0;
// Returns whether `MaybeShowFeaturePromo()` would succeed if called now.
//
// USAGE NOTE: Only call this method if figuring out whether to try to show an
// IPH would involve significant expense. This method may itself have
// non-trivial cost.
virtual user_education::FeaturePromoResult CanShowFeaturePromo(
const base::Feature& iph_feature) const = 0;
// Maybe shows an in-product help promo.
//
// If this feature promo is likely to be shown at browser startup, prefer
// calling `MaybeShowStartupFeaturePromo()` instead.
//
// If determining whether to call this method would involve significant
// expense, you *may* first call `CanShowFeaturePromo()` before doing the
// required computation; otherwise just call this method.
virtual void MaybeShowFeaturePromo(
user_education::FeaturePromoParams params) = 0;
// Maybe shows an in-product help promo at startup, whenever the Feature
// Engagement system is fully initialized. If the promo cannot be queued for
// whatever reason, `params.show_promo_result_callback` will be called with
// the appropriate error. The promo may still not run if it is excluded for
// other reasons (e.g. another promo starts first; its Feature Engagement
// conditions are not satisfied).
//
// On success, when the FE system is initialized (which might be immediately),
// or when the promo is determined to have failed to show for any reason,
// `show_promo_result_callback` is called with the result of whether the promo
// was actually shown. Since `show_promo_result_callback` could be called any
// time, make sure that you will not experience any race conditions or UAFs if
// the calling object goes out of scope.
virtual void MaybeShowStartupFeaturePromo(
user_education::FeaturePromoParams params) = 0;
// Aborts the in-product help promo for `iph_feature` if it is showing or
// cancels a pending startup promo. Aborting a promo means it was not fully
// shown or interacted with, and may allow the promo to show again. Returns
// whether a showing or pending promo was canceled.
virtual bool AbortFeaturePromo(const base::Feature& iph_feature) = 0;
// Closes the bubble for a feature promo but continues the promo; returns a
// handle that can be used to end the promo when it is destructed. The handle
// will be valid (i.e. have a true boolean value) if the promo was showing,
// invalid otherwise.
virtual user_education::FeaturePromoHandle CloseFeaturePromoAndContinue(
const base::Feature& iph_feature) = 0;
// Records that the user has engaged the specific `feature` associated with an
// IPH promo; this information is used to determine whether to show the promo
// in the future. Also specifies which `action` should be taken regarding
// existing queued or showing promos associated with `feature`.
//
// Returns whether a promo was closed as a result.
virtual bool NotifyFeaturePromoFeatureUsed(
const base::Feature& feature,
FeaturePromoFeatureUsedAction action) = 0;
// Records that the user has performed an action that is specified in in a
// FeaturePromoSpecification by calling the `SetAdditionalConditions()`
// method; this information may be used to determine whether and when to show
// the promo in the future.
virtual void NotifyAdditionalConditionEvent(const char* event_name) = 0;
// Returns whether a "New" Badge should be shown on the entry point for
// `feature`; the badge must be registered for the feature in
// browser_user_education_service.cc. Call exactly once per time the surface
// containing the badge will be shown to the user.
virtual user_education::DisplayNewBadge MaybeShowNewBadgeFor(
const base::Feature& feature) = 0;
// Records that the user has engaged the specific `feature` associated with a
// "New" Badge; this information is used to determine whether to show the
// badge in the future.
//
// You can also call `UserEducationService::MaybeNotifyNewBadgeFeatureUsed()`
// if you only have access ot a `BrowserContext` or `Profile`.
virtual void NotifyNewBadgeFeatureUsed(const base::Feature& feature) = 0;
// Returns the interface associated with the browser containing `contents` in
// its tabstrip, or null if `contents` is not a tab in any known browser.
//
// For WebUI embedded in a specific browser window or secondary UI of a
// browser window, instead just use the appropriate BrowserWindow[Interface]
// for that window.
static BrowserUserEducationInterface* MaybeGetForWebContentsInTab(
content::WebContents* contents);
protected:
virtual user_education::FeaturePromoController*
GetFeaturePromoControllerImpl() = 0;
};
#endif // CHROME_BROWSER_UI_USER_EDUCATION_BROWSER_USER_EDUCATION_INTERFACE_H_
|
