Skip to content

Commit 5242651

Browse files
monica-chmonica-ch
authored
Add spec for Tracking Prevention. (#2886)
* Add Tracking Prevention API spec
1 parent 80a15bf commit 5242651

File tree

2 files changed

+224
-0
lines changed

2 files changed

+224
-0
lines changed

‎specs/TrackingPrevention.md

Lines changed: 224 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,224 @@
1+
Tracking Prevention
2+
===
3+
4+
# Background
5+
The WebView2 team has been asked for an API to control levels of tracking prevention and also to turn off tracking prevention feature in WebView2.
6+
7+
We are proposing two API's
8+
9+
CoreWebView2Profile.PreferredTrackingPreventionLevel: This API allows you to control levels of tracking prevention for WebView2 which
10+
are associated with a profile and persisted in the user data folder. However, the level is not respected if tracking prevention feature is
11+
disabled using `CoreWebView2EnvironmentOptions.EnableTrackingPrevention`. That means, if you set the property when the feature is disabled
12+
it is updated and persisted but it will takes effect only if `CoreWebView2EnvironmentOptions.EnableTrackingPrevention` is true.
13+
The levels are similar to Edge: `Off`, `Basic`, `Balanced` and `Strict`.
14+
15+
For reference, in the screenshot below, this API sets the levels of tracking prevention as a WebView2 API.
16+
17+
![Edge Tracking Prevention](images/TrackingPreventionLevels.png)
18+
19+
CoreWebView2EnvironmentOptions.EnableTrackingPrevention: This API allows you to enable/disable the tracking prevention feature.
20+
Default value is true. When this is true, the level of tracking prevention is controlled by the `CoreWebView2Profile.PreferredTrackingPreventionLevel` property.
21+
You can set this property to false to disable the tracking prevention feature for WebView2 when creating environment that also skips the related code and improves the performance.
22+
23+
# Examples
24+
## EnableTrackingPrevention
25+
26+
```c#
27+
Create WebView Environment with option that disable tracking prevention feature.
28+
29+
void CreateEnvironmentWithOption()
30+
{
31+
CoreWebView2EnvironmentOptions options = new CoreWebView2EnvironmentOptions();
32+
// If we're displaying app content or otherwise are not worried about tracking, we can
33+
// disable the tracking prevention feature to improve runtime performance.
34+
options.EnableTrackingPrevention = false;
35+
CoreWebView2Environment environment = await CoreWebView2Environment.CreateAsync(BrowserExecutableFolder, UserDataFolder, options);
36+
}
37+
```
38+
39+
```cpp
40+
void AppWindow::InitializeWebView()
41+
{
42+
auto options = Microsoft::WRL::Make<CoreWebView2EnvironmentOptions>();
43+
Microsoft::WRL::ComPtr<ICoreWebView2EnvironmentOptions3> options3;
44+
if (options.As(&options3) == S_OK)
45+
{
46+
// If we're displaying app content or otherwise are not worried about tracking, we can
47+
// disable the tracking prevention feature to improve runtime performance.
48+
CHECK_FAILURE(options3->put_EnableTrackingPrevention(FALSE));
49+
}
50+
// ... other option properties
51+
52+
HRESULT hr = CreateCoreWebView2EnvironmentWithOptions(
53+
subFolder, m_userDataFolder.c_str(), options.Get(),
54+
Callback<ICoreWebView2CreateCoreWebView2EnvironmentCompletedHandler>(
55+
this, &AppWindow::OnCreateEnvironmentCompleted)
56+
.Get());
57+
}
58+
```
59+
60+
## PreferredTrackingPreventionLevel
61+
Example of code in end user facing UI to change the TrackingPreventionLevel.
62+
63+
```c#
64+
65+
void SetTrackingPreventionLevel(CoreWebView2TrackingPreventionLevel value)
66+
{
67+
CoreWebView2Profile webViewProfile;
68+
if (webView.CoreWebView2 != null)
69+
{
70+
webViewProfile = webView.CoreWebView2.Profile;
71+
WebViewProfile.PreferredTrackingPreventionLevel = value;
72+
MessageBox.Show(this, "Tracking prevention level is set successfully", "Tracking Prevention Level");
73+
}
74+
}
75+
```
76+
77+
```cpp
78+
void SettingsComponent::SetTrackingPreventionLevel(
79+
COREWEBVIEW2_TRACKING_PREVENTION_LEVEL value)
80+
{
81+
wil::com_ptr<ICoreWebView2_13> webView2_13;
82+
webView2_13 = m_webView.try_query<ICoreWebView2_13>();
83+
84+
if (webView2_13)
85+
{
86+
wil::com_ptr<ICoreWebView2Profile> profile;
87+
CHECK_FAILURE(webView2_13->get_Profile(&profile));
88+
89+
auto profile5 = profile.try_query<ICoreWebView2Profile5>();
90+
if (profile5)
91+
{
92+
CHECK_FAILURE(profile5->put_PreferredTrackingPreventionLevel(value));
93+
MessageBox(
94+
nullptr,
95+
L"Tracking prevention level is set successfully",
96+
L"Tracking Prevention Level", MB_OK);
97+
}
98+
}
99+
}
100+
```
101+
102+
# API Details
103+
```
104+
/// Tracking prevention levels.
105+
[v1_enum] typedef enum COREWEBVIEW2_TRACKING_PREVENTION_LEVEL {
106+
/// Tracking prevention is turned off.
107+
COREWEBVIEW2_TRACKING_PREVENTION_LEVEL_NONE,
108+
/// The least restrictive level of tracking prevention. Set to this level to
109+
/// protect against malicious trackers but allows most other trackers and personalize content and ads.
110+
///
111+
/// See [Current tracking prevention behavior](/microsoft-edge/web-platform/tracking-prevention#current-tracking-prevention-behavior)
112+
/// for fine-grained information on what is being blocked with this level. This can change with different Edge versions.
113+
COREWEBVIEW2_TRACKING_PREVENTION_LEVEL_BASIC,
114+
/// The default level of tracking prevention. Set to this level to
115+
/// protect against social media tracking in addition to malicious trackers. Content and ads will likely be less personalized.
116+
///
117+
/// See [Current tracking prevention behavior](/microsoft-edge/web-platform/tracking-prevention#current-tracking-prevention-behavior)
118+
/// for fine-grained information on what is being blocked with this level. This can change with different Edge versions.
119+
COREWEBVIEW2_TRACKING_PREVENTION_LEVEL_BALANCED,
120+
/// The most restrictive level of tracking prevention. Set to this level to protect
121+
/// against malicious trackers and most trackers across sites. Content and ads will likely have minimal personalization.
122+
///
123+
/// This level blocks the most trackers but could cause some websites to not behave as expected.
124+
///
125+
/// See [Current tracking prevention behavior](/microsoft-edge/web-platform/tracking-prevention#current-tracking-prevention-behavior)
126+
/// for fine-grained information on what is being blocked with this level. This can change with different Edge versions.
127+
COREWEBVIEW2_TRACKING_PREVENTION_LEVEL_STRICT,
128+
} COREWEBVIEW2_TRACKING_PREVENTION_LEVEL;
129+
130+
/// Additional options used to create WebView2 Environment.
131+
[uuid(12e494a2-c876-11eb-b8bc-0242ac130003), object, pointer_default(unique)]
132+
interface ICoreWebView2EnvironmentOptions3 : IUnknown {
133+
/// The `EnableTrackingPrevention` property is used to enable/disable tracking prevention feature in WebView2.
134+
/// This property enable/disable tracking prevention for all the WebView2's created in the same environment.
135+
/// By default this feature is enabled to block potentially harmful trackers and trackers from sites that
136+
/// aren't visited before and set to `COREWEBVIEW2_TRACKING_PREVENTION_LEVEL_BALANCED` or whatever value was
137+
/// last changed/persisted on the profile.
138+
///
139+
/// You can set this property to false to disable the tracking prevention feature if the app only renders
140+
/// content in the WebView2 that is known to be safe. Disabling this feature when creating environment also
141+
/// improves runtime performance by skipping related code.
142+
///
143+
/// You shouldn't disable this property if WebView2 is being used as a "full browser" with arbitrary navigation
144+
/// and should protect end user privacy.
145+
///
146+
/// There is `CoreWebView2Profile.PreferredTrackingPreventionLevel` property to control levels of tracking prevention
147+
/// of the WebView2's associated with a same profile. However, you can also disable tracking prevention later using
148+
/// `CoreWebView2Profile.PreferredTrackingPreventionLevel` property and `COREWEBVIEW2_TRACKING_PREVENTION_LEVEL_NONE` value
149+
/// but that doesn't improves runtime performance.
150+
/// See `CoreWebView2Profile.PreferredTrackingPreventionLevel` for more details.
151+
///
152+
/// Tracking prevention protects users from online tracking by restricting
153+
/// the ability of trackers to access browser-based storage as well as the network.
154+
/// See [Tracking prevention](microsoft-edge/web-platform/tracking-prevention).
155+
[propget] HRESULT EnableTrackingPrevention([out, retval] BOOL* value);
156+
/// Sets the `EnableTrackingPrevention` property.
157+
[propput] HRESULT EnableTrackingPrevention([in] BOOL value);
158+
}
159+
160+
/// This is the ICoreWebView2 profile.
161+
[uuid(ddc4070a-c873-11eb-b8bc-0242ac130003), object, pointer_default(unique)]
162+
interface ICoreWebView2Profile5: IUnknown {
163+
/// The `PreferredTrackingPreventionLevel` property allows you to control levels of tracking prevention for WebView2 which
164+
/// are associated with a profile. This level would apply to the context of the profile. That is, all WebView2s sharing the same
165+
/// profile will be affected and also the value is persisted in the user data folder.
166+
///
167+
/// See `COREWEBVIEW2_TRACKING_PREVENTION_LEVEL` for descriptions of levels.
168+
///
169+
/// If tracking prevention feature is enabled when creating the WebView2 environment, you can also disable
170+
/// tracking prevention later using this property and `COREWEBVIEW2_TRACKING_PREVENTION_LEVEL_NONE` value
171+
/// but that doesn't improves runtime performance.
172+
///
173+
/// There is `CoreWebView2EnvironmentOptions.EnableTrackingPrevention` property to enable/disable tracking prevention feature
174+
/// for all the WebView2's created in the same environment. If enabled, `PreferredTrackingPreventionLevel` is set to
175+
/// `COREWEBVIEW2_TRACKING_PREVENTION_LEVEL_BALANCED` by default for all the WebView2's and profiles created in the same environment
176+
/// or is set to the level whatever value was last changed/persisted to the profile. If disabled `PreferredTrackingPreventionLevel`
177+
/// is not respected by WebView2. If `PreferredTrackingPreventionLevel` is set when the feature is disabled, the property value get changed and
178+
/// persisted but it will takes effect only if `CoreWebView2EnvironmentOptions.EnableTrackingPrevention` is true.
179+
///
180+
/// See `CoreWebView2EnvironmentOptions.EnableTrackingPrevention` for more details.
181+
[propget] HRESULT PreferredTrackingPreventionLevel(
182+
[out, retval] COREWEBVIEW2_TRACKING_PREVENTION_LEVEL* value);
183+
/// Set the `PreferredTrackingPreventionLevel` property.
184+
///
185+
/// If `CoreWebView2EnvironmentOptions.EnableTrackingPrevention` is false, this property will be changed and persisted to the profile but
186+
/// the WebView2 ignores the level silently.
187+
[propput] HRESULT PreferredTrackingPreventionLevel(
188+
[in] COREWEBVIEW2_TRACKING_PREVENTION_LEVEL value);
189+
}
190+
```
191+
192+
```c# (but really MIDL3)
193+
namespace Microsoft.Web.WebView2.Core
194+
{
195+
enum CoreWebView2TrackingPreventionLevel
196+
{
197+
None = 0,
198+
Basic = 1,
199+
Balanced = 2,
200+
Strict = 3,
201+
};
202+
203+
// ...
204+
runtimeclass CoreWebView2EnvironmentOptions
205+
{
206+
// ...
207+
[interface_name("Microsoft.Web.WebView2.Core.ICoreWebView2EnvironmentOptions3")]
208+
{
209+
// ICoreWebView2EnvironmentOptions3 members
210+
Boolean EnableTrackingPrevention { get; set; };
211+
}
212+
}
213+
214+
runtimeclass CoreWebView2Profile
215+
{
216+
// ...
217+
[interface_name("Microsoft.Web.WebView2.Core.ICoreWebView2Profile5")]
218+
{
219+
// ICoreWebView2Profile5 members
220+
CoreWebView2TrackingPreventionLevel PreferredTrackingPreventionLevel { get; set; };
221+
}
222+
}
223+
}
224+
```

‎specs/images/TrackingPreventionLevels.png

35.4 KB
Loading

0 commit comments

Comments
 (0)