Skip to content

Commit 5075495

Browse files
LiangTheDevLiangTheDev
authored
Merge pull request #3201 from MicrosoftEdge/CustomStoragePartition
Custom data partition
2 parents 8ee0b56 + 573b49e commit 5075495

1 file changed

Lines changed: 212 additions & 0 deletions

File tree

‎specs/CustomDataPartition.md‎

Lines changed: 212 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,212 @@
1+
Custom Data Partition
2+
===
3+
4+
# Background
5+
For certain WebView host apps, there is a desire to have different contexts for
6+
different WebViews using the same profile so that when the same websites run in
7+
these WebViews, they will have different DOM storages and cookie jars. For example,
8+
a content editing application might use one WebView to visit a site as signed in user
9+
to modify content on the site, while using another WebView to visit the same site as
10+
anonymous user to view the changes as seen by normal users.
11+
Previously, the application can use different profiles for different contexts, but
12+
that has 2 short comings:
13+
- WebViews from different profiles are not allowed to have opener/opened window relationship.
14+
- Using profiles means totally different storage for all files like http caches and less performance.
15+
16+
To help managing different application contexts while using the same profile, we are
17+
introducing an API to set custom data partition and an API to clear all data in
18+
a custom data partition.
19+
20+
When an application sets custom data partition for a WebView, the sites and iframes
21+
running inside the WebView will act as if the site were running in a third party iframe
22+
inside a top level site uniquely associated with the custom data partition id and have
23+
separate [storage partition](https://developer.chrome.com/docs/privacy-sandbox/storage-partitioning/)
24+
and [cookie partition](https://developer.chrome.com/docs/privacy-sandbox/chips/).
25+
26+
# Conceptual pages (How To)
27+
This feature depends on [storage partition](https://developer.chrome.com/docs/privacy-sandbox/storage-partitioning/)
28+
and [cookie partition](https://developer.chrome.com/docs/privacy-sandbox/chips/) browser
29+
features which are currently experimental. Before those features are enabled by default,
30+
the application must enable them by ensuring `--enable-features=ThirdPartyStoragePartitioning,PartitionedCookies`
31+
is set in [CoreWebView2EnvironmentOptions.AdditionalBrowserArguments](https://learn.microsoft.com/microsoft-edge/webview2/reference/winrt/microsoft_web_webview2_core/corewebview2environmentoptions#additionalbrowserarguments)
32+
used to create CoreWebView2Environment. If the features are not enabled, no custom data partition will be
33+
created and all data will be treated as unpartitioned and stored in the global default
34+
location for the profile.
35+
The custom data partition APIs will remain experimental when related browser features
36+
are still experimental.
37+
38+
# Examples
39+
40+
The example below illustrates how to set partition id on WebView and how to clear all
41+
data stored in the custom data partition.
42+
43+
## Win32 C++
44+
```cpp
45+
wil::com_ptr<ICoreWebView2_18> m_webView;
46+
47+
void OnWebViewCreated()
48+
{
49+
// ...
50+
// other WebView setup like add event handlers, update settings.
51+
52+
// Sets custom data partition identified by the partitionId. Used by app
53+
// to uniquely identify an application context, like for visiting the site
54+
// as anonymous user instead of the signed in user in other WebViews.
55+
PCWSTR partitionId = L"Partition 1";
56+
CHECK_FAILURE(m_webview->put_CustomDataPartitionId(partitionId));
57+
58+
// Navigate to start page
59+
m_webview->Navigate(startPage);
60+
}
61+
62+
// Clears all data in custom data partition identified by the partitionId.
63+
// Called when the custom data partition is no longer needed.
64+
HRESULT ClearPartitionData(PCWSTR partitionId)
65+
{
66+
wil::com_ptr<ICoreWebView2Profile> webView2Profile;
67+
CHECK_FAILURE(m_webview->get_Profile(&webView2Profile));
68+
auto webView2Profile8 = webView2Profile.try_query<ICoreWebView2Profile8>();
69+
CHECK_FEATURE_RETURN(webView2Profile8);
70+
CHECK_FAILURE(webView2Profile8->ClearCustomDataPartition(
71+
partitionId,
72+
Callback<ICoreWebView2ClearCustomDataPartitionCompletedHandler>(
73+
[this](HRESULT result) -> HRESULT
74+
{
75+
if (SUCCEEDED(result))
76+
{
77+
AsyncMessageBox(L"Completed", L"Clear Custom Data Partition");
78+
}
79+
else
80+
{
81+
std::wstringstream message;
82+
message << L"Failed: " << std::to_wstring(result) << L"(0x" << std::hex
83+
<< result << L")" << std::endl;
84+
AsyncMessageBox(message.str(), L"Clear Custom Data Partition");
85+
}
86+
return S_OK;
87+
}).Get()));
88+
return S_OK;
89+
}
90+
91+
```
92+
93+
## .NET/WinRT
94+
```c#
95+
private CoreWebView2 m_webview;
96+
97+
void CoreWebView_Created()
98+
{
99+
// ...
100+
// other WebView setup like add event handlers, update settings.
101+
102+
// Sets custom data partition identified by the partitionId. Used by app
103+
// to uniquely identify an application context, like for visiting the site
104+
// as anonymous user instead of the signed in user in other WebViews.
105+
string partitionId = "Partition 1";
106+
m_webview.CustomDataPartitionId = partitionId;
107+
108+
// Navigate to start page
109+
m_webview.Navigate(startPage);
110+
}
111+
112+
// Clears all data in custom data partition identified by the partitionId.
113+
// Called when the custom data partition is no longer needed.
114+
async void ClearPartitionData(string partitionId)
115+
{
116+
await m_webview.Profile.ClearCustomDataPartitionAsync(partitionId);
117+
MessageBox.Show(this, "Completed", "Clear Custom Data Partition");
118+
}
119+
120+
```
121+
122+
# API Details
123+
## Win32 C++
124+
```
125+
interface ICoreWebView2_18 : ICoreWebView2_17 {
126+
/// Gets the `CustomDataPartitionId` property.
127+
[propget] HRESULT CustomDataPartitionId([out, retval] LPWSTR* customDataPartitionId);
128+
129+
/// Sets the `CustomDataPartitionId` property.
130+
/// This API requires enabling 2 experimental browser features to work properly.
131+
/// These features will be enabled by default in the future.
132+
/// Before these features are enabled by default, please enable them by ensuring
133+
/// `--enable-features=ThirdPartyStoragePartitioning,PartitionedCookies` is set in
134+
/// `AdditionalBrowserArguments` in `CoreWebView2EnvironmentOptions` used to create
135+
/// CoreWebView2Environment. If these features are not enabled, all data are treated
136+
/// as unpartitioned and stored in the global default location for the profile.
137+
/// When it is set, the page in the WebView will act as if the page were hosted in a
138+
/// top level site uniquely associated with the `partitionId` and have a separate
139+
/// storage partition as described in https://developer.chrome.com/docs/privacy-sandbox/storage-partitioning/
140+
/// and separete cookie partition as described in https://developer.chrome.com/docs/privacy-sandbox/chips/
141+
/// with all cookies partitioned.
142+
/// If `customDataPartitionId` is nullptr or empty string, the page inside the
143+
/// WebView will work normally with data treated as unpartitioned.
144+
/// The `customDataPartitionId` parameter is case sensitive. The default is
145+
/// an empty string. There is no restriction on the length or what characters
146+
/// can be used in partition id.
147+
/// The change of the custom data partition id will be applied to new
148+
/// page or iframe navigations and not impact existing pages and iframes.
149+
/// To avoid accidentally using the new partition id for new page or iframe navigations
150+
/// started by the old page, it is recommended to create a new WebView for new partition
151+
/// instead of changing partition. If you really have to change partition, it is
152+
/// recommended to navigate to a blank page before setting the new partition
153+
/// id and navigating to a page with the new partition.
154+
///
155+
/// As setting custom data partition id does not change DOM security
156+
/// model, developers should be very careful for WebViews with opener and
157+
/// opened window relationship, especially when the pages in the WebViews
158+
/// have same origin, like when the opened window is the same website or
159+
/// about:blank. The pages in these WebViews can access each other’s DOM and
160+
/// therefore can potentially access DOM storage and cookies in different
161+
/// partition for the same website. It is recommended to set the same custom
162+
/// data partition id for these WebViews, unless there is an absolute need
163+
/// to set different partition ids and only trusted code is hosted in them.
164+
///
165+
[propput] HRESULT CustomDataPartitionId([in] LPCWSTR customDataPartitionId);
166+
}
167+
168+
interface ICoreWebView2Profile8 : ICoreWebView2Profile7 {
169+
/// Clears all DOM storage and cookies in the custom data partition
170+
/// identified by the `customDataPartitionId`.
171+
/// If `customDataPartitionId` is nullptr or empty string, the API will fail with
172+
/// E_INVALIDARG. If no partition is found for the specified `customDataPartitionId`,
173+
/// the API succeeds without doing anything.
174+
/// As DOM storage and cookies in the custom data partition is also browsing
175+
/// data, they will also be cleared when `ClearBrowsingData`,
176+
/// `ClearBrowsingDataInTimeRange` or `ClearBrowsingDataAll` is called and
177+
/// the clearing condition is met.
178+
///
179+
HRESULT ClearCustomDataPartition(
180+
[in] LPCWSTR customDataPartitionId,
181+
[in] ICoreWebView2ClearCustomDataPartitionCompletedHandler* handler);
182+
}
183+
184+
interface ICoreWebView2ClearCustomDataPartitionCompletedHandler : IUnknown {
185+
186+
/// Provide the completion status of the corresponding asynchronous method.
187+
HRESULT Invoke([in] HRESULT errorCode);
188+
}
189+
190+
```
191+
192+
## .NET/WinRT
193+
```c#
194+
namespace Microsoft.Web.WebView2.Core
195+
{
196+
197+
class CoreWebView2
198+
{
199+
[interface_name("Microsoft.Web.WebView2.Core.ICoreWebView2_18")]
200+
{
201+
public string CustomDataPartitionId { get; set; };
202+
}
203+
}
204+
205+
class CoreWebView2Profile
206+
{
207+
[interface_name("Microsoft.Web.WebView2.Core.ICoreWebView2Profile8")]
208+
{
209+
public async Task ClearCustomDataPartitionAsync(string customDataPartitionId);
210+
}
211+
}
212+
```

0 commit comments

Comments
 (0)