Skip to content

Commit f66ec4c

Browse files
LiangTheDevLiangTheDev
authored
Create CustomStoragePartition.md
1 parent 3892f91 commit f66ec4c

1 file changed

Lines changed: 186 additions & 0 deletions

File tree

‎specs/CustomStoragePartition.md‎

Lines changed: 186 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,186 @@
1+
Custom Storage 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. An example
8+
is different accounts within an application.
9+
Previosly, the application can use different profiles for different contexts, but
10+
that has 2 short comings:
11+
- WebViews from different profiles are not allowed to have opener/opened window relationship.
12+
- Using profiles means totally different storage for all files like http caches and less performance.
13+
14+
To help managing different application contexts while using the same profile, we are
15+
introducing an API to set custom storage parition and an API to clear all data in
16+
a custom storage partition.
17+
18+
When an application sets custom storage parition for a WebView, the sites and iframes
19+
running inside the WebView will act as if the site were running in a third party iframe
20+
inside a top level site uniquelly associated with the custom storage partition id and have
21+
separate [storage partition](https://developer.chrome.com/docs/privacy-sandbox/storage-partitioning/)
22+
and [cookie partition](https://developer.chrome.com/docs/privacy-sandbox/chips/).
23+
24+
# Conceptual pages (How To)
25+
This feature depends on [storage partition](https://developer.chrome.com/docs/privacy-sandbox/storage-partitioning/)
26+
and [cookie partition](https://developer.chrome.com/docs/privacy-sandbox/chips/) browser
27+
features which are currently experimental. Before those features are enabled by default,
28+
the application must enable them by ensuring `--enable-features=ThirdPartyStoragePartitioning,PartitionedCookies`
29+
is set in [CoreWebView2EnvironmentOptions.AdditionalBrowserArguments](https://learn.microsoft.com/microsoft-edge/webview2/reference/winrt/microsoft_web_webview2_core/corewebview2environmentoptions#additionalbrowserarguments)
30+
used to create CoreWebView2Environment. If not set, no custom storage partition will be
31+
created and all data will be treated as unpartitioned and stored in the global default
32+
location for the profile.
33+
34+
# Examples
35+
36+
The example below illustrates how to set partition id on WebView and how to clear all
37+
data stored in the custom storage partition.
38+
39+
## Win32 C++
40+
```cpp
41+
// Sets custom storage partition identified by the partitionId, which uniquely
42+
// identifies an application context.
43+
void SetPartitionId(PCWSTR partitionId)
44+
{
45+
CHECK_FAILURE(m_webview->put_CustomStoragePartitionId(partitionId));
46+
}
47+
48+
// Clears all data in custom storage partition identified by the partitionId.
49+
// Called when the application context is removed.
50+
HRESULT ClearPartitionData(PCWSTR partitionId)
51+
{
52+
wil::com_ptr<ICoreWebView2Profile> webView2Profile;
53+
CHECK_FAILURE(m_webview->get_Profile(&webView2Profile));
54+
auto webView2Profile8 = webView2Profile.try_query<ICoreWebView2Profile8>();
55+
CHECK_FEATURE_RETURN(webView2Profile8);
56+
CHECK_FAILURE(webView2Profile8->ClearCustomStoragePartitionData(
57+
partitionId,
58+
Callback<ICoreWebView2StagingClearCustomStoragePartitionDataCompletedHandler>(
59+
[this](HRESULT result) -> HRESULT
60+
{
61+
if (SUCCEEDED(result))
62+
{
63+
AsyncMessageBox(L"Completed", L"Clear Custom Partition Data");
64+
}
65+
else
66+
{
67+
std::wstringstream message;
68+
message << L"Failed: " << std::to_wstring(result) << L"(0x" << std::hex
69+
<< result << L")" << std::endl;
70+
AsyncMessageBox(message.str(), L"Clear Custom Partition Data");
71+
}
72+
return S_OK;
73+
}).Get()));
74+
return S_OK;
75+
}
76+
77+
```
78+
79+
## .NET/WinRT
80+
```c#
81+
// Sets custom storage partition identified by the partitionId, which uniquely
82+
// identifies an application context.
83+
void SetPartitionId(string partitionId)
84+
{
85+
m_webview.CustomStoragePartitionId = partitionId;
86+
}
87+
88+
// Clears all data in custom storage partition identified by the partitionId.
89+
// Called when the application context is removed.
90+
async void ClearPartitionData(string partitionId)
91+
{
92+
await m_webview.Profile.ClearCustomStoragePartitionDataAsync(partitionId);
93+
MessageBox.Show(this, "Completed", "Clear Custom Partition Data");
94+
}
95+
96+
```
97+
98+
# API Details
99+
## Win32 C++
100+
```
101+
interface ICoreWebView2_18 : IUnknown {
102+
/// Gets the `CustomStoragePartitionId` property.
103+
[propget] HRESULT CustomStoragePartitionId([out, retval] LPWSTR* customStoragePartitionId);
104+
105+
/// Sets the `CustomStoragePartitionId` property.
106+
/// This feature requires enabling 2 experimental browser features to work properly.
107+
/// These features will be enabled by default in the future.
108+
/// Before these features are enabled by default, please enable them by ensuring
109+
/// `--enable-features=ThirdPartyStoragePartitioning,PartitionedCookies` is set in
110+
/// `AdditionalBrowserArguments` in `CoreWebView2EnvironmentOptions` used to create
111+
/// CoreWebView2Environment. If these features are not enabled, all data are treated
112+
/// as unpartitioned and stored in the global default location for the profile.
113+
/// When it is set, the page in the WebView will act as if the page were hosted in a
114+
/// top level site uniquely associated with the `partitionId` and have a separate
115+
/// storage partition as described in https://developer.chrome.com/docs/privacy-sandbox/storage-partitioning/
116+
/// and separete cookie partition as described in https://developer.chrome.com/docs/privacy-sandbox/chips/
117+
/// with all cookies partitioned.
118+
/// If `customStoragePartitionId` is nullptr or empty string, the
119+
/// `CustomStoragePartitionId` will be reset and the page inside the WebView
120+
/// will work normally with data treated as unpartitioned.
121+
/// The `customStoragePartitionId` parameter is case sensitive. The default is
122+
/// an empty string.
123+
/// The change of the custom storage partition id will be applied to new
124+
/// page or iframe navigations and not impact existing pages and iframes.
125+
/// To avoid accidentally use new partition id for pending navigations of old page
126+
/// or iframe, it is recommended to create a new WebView for new partition instead
127+
/// of changing partition. If you really have to change partition, it is
128+
/// recommended to navigate to a blank page or call `Stop()` API to stop all
129+
/// navigations and pending resource fetches before setting the new partition
130+
/// id and navigate to a page for the new partition.
131+
///
132+
/// As setting custom storage partition id does not change DOM security
133+
/// model, developers should be very careful for WebViews with opener and
134+
/// opened window relationship, especially when the pages in the WebViews
135+
/// have same origin, like when the opened window is the same site or
136+
/// about:blank. The pages in these WebViews can access each other’s DOM and
137+
/// therefore can potentially access DOM storage and cookies in different
138+
/// partition for the same site. It is recommended to set the same custom
139+
/// storage partition id for these WebViews, unless there is an absolute need
140+
/// to set different partition ids and only trusted code is hosted in them.
141+
///
142+
[propput] HRESULT CustomStoragePartitionId([in] LPCWSTR customStoragePartitionId);
143+
}
144+
145+
interface ICoreWebView2Profile8 : IUnknown {
146+
/// Clears all DOM storage and cookies in the custom storage partition
147+
/// identified by the `customStoragePartitionId`.
148+
/// As DOM storage and cookies in the custom storage partition is also browsing
149+
/// data, they will also be cleared when `ClearBrowsingData`,
150+
/// `ClearBrowsingDataInTimeRange` or `ClearBrowsingDataAll` is called and
151+
/// the clearing condition is met.
152+
///
153+
HRESULT ClearCustomStoragePartitionData(
154+
[in] LPCWSTR customStoragePartitionId,
155+
[in] ICoreWebView2ClearCustomStoragePartitionDataCompletedHandler* handler);
156+
}
157+
158+
interface ICoreWebView2ClearCustomStoragePartitionDataCompletedHandler : IUnknown {
159+
160+
/// Provide the completion status of the corresponding asynchronous method.
161+
HRESULT Invoke([in] HRESULT errorCode);
162+
}
163+
164+
```
165+
166+
## .NET/WinRT
167+
```c#
168+
namespace Microsoft.Web.WebView2.Core
169+
{
170+
171+
class CoreWebView2
172+
{
173+
[interface_name("Microsoft.Web.WebView2.Core.ICoreWebView2_18")]
174+
{
175+
public string CustomStoragePartitionId { get; set; };
176+
}
177+
}
178+
179+
class CoreWebView2Profile
180+
{
181+
[interface_name("Microsoft.Web.WebView2.Core.ICoreWebView2Profile8")]
182+
{
183+
public async Task ClearCustomStoragePartitionDataAsync(string CustomStoragePartitionId);
184+
}
185+
}
186+
```

0 commit comments

Comments
 (0)