Commit b0efcfaa authored by Allen Robinson's avatar Allen Robinson Committed by Commit Bot

Update OT documentation to reference RuntimeEnabled

Bug: 934451
Change-Id: I62b2969964b1f38d1e066f842ef5635286dcea27
Reviewed-on: https://chromium-review.googlesource.com/c/chromium/src/+/1671407Reviewed-by: default avatarJason Chase <chasej@chromium.org>
Commit-Queue: Allen Robinson <arobins@chromium.org>
Auto-Submit: Allen Robinson <arobins@chromium.org>
Cr-Commit-Position: refs/heads/master@{#672052}
parent c72d689c
# Integrating a feature with the Origin Trials framework # Integrating a feature with the origin trials framework
To expose your feature via the origin trials framework, there are a few code To expose your feature via the origin trials framework, there are a few code
changes required. changes required.
...@@ -13,11 +13,10 @@ First, you’ll need to configure [runtime\_enabled\_features.json5]. This is ...@@ -13,11 +13,10 @@ First, you’ll need to configure [runtime\_enabled\_features.json5]. This is
explained in the file, but you use `origin_trial_feature_name` to associate your explained in the file, but you use `origin_trial_feature_name` to associate your
runtime feature flag with a name for your origin trial. The name can be the runtime feature flag with a name for your origin trial. The name can be the
same as your runtime feature flag, or different. Eventually, this configured same as your runtime feature flag, or different. Eventually, this configured
name will be used in the Origin Trials developer console (still under name will be used in the origin trials developer console. You can have both
development). You can have both `status: experimental` and `status: experimental` and `origin_trial_feature_name` if you want your feature
`origin_trial_feature_name` if you want your feature to be enabled either by to be enabled either by using the `--enable-experimental-web-platform-features`
using the `--enable-experimental-web-platform-features` flag **or** the origin flag **or** the origin trial.
trial.
You may have a feature that is not available on all platforms, or need to limit You may have a feature that is not available on all platforms, or need to limit
the trial to specific platforms. Use `origin_trial_os: [list]` to specify which the trial to specific platforms. Use `origin_trial_os: [list]` to specify which
...@@ -60,17 +59,21 @@ an origin trial. You can use either mechanism, or both, as appropriate to your ...@@ -60,17 +59,21 @@ an origin trial. You can use either mechanism, or both, as appropriate to your
feature implementation. feature implementation.
1. A native C++ method that you can call in Blink code at runtime to expose your 1. A native C++ method that you can call in Blink code at runtime to expose your
feature: `bool OriginTrials::myFeatureEnabled()` feature: `bool RuntimeEnabledFeatures::MyFeatureEnabled(ExecutionContext*)`
2. An IDL attribute \[[OriginTrialEnabled]\] that you can use to automatically 2. An IDL attribute \[[RuntimeEnabled]\] that you can use to automatically
generate code to expose and hide JavaScript methods/attributes/objects. This generate code to expose and hide JavaScript methods/attributes/objects.
attribute works very similarly to \[RuntimeEnabled\].
``` ```
[OriginTrialEnabled=MyFeature] [RuntimeEnabled=MyFeature]
partial interface Navigator { partial interface Navigator {
readonly attribute MyFeatureManager myFeature; readonly attribute MyFeatureManager myFeature;
} }
``` ```
**NOTE:** Your feature implementation must not persist the result of the enabled
check. Your code should simply call
`RuntimeEnabledFeatures::MyFeatureEnabled(ExecutionContext*)` as often as
necessary to gate access to your feature.
### Web Feature Counting ### Web Feature Counting
Once the feature is created, in order to run the origin trial you need to track Once the feature is created, in order to run the origin trial you need to track
...@@ -94,11 +97,11 @@ enum WebFeature { ...@@ -94,11 +97,11 @@ enum WebFeature {
3. Increment your feature counter in c++ code. 3. Increment your feature counter in c++ code.
```c++ ```c++
#include "third_party/blink/renderer/core/frame/use_counter.h" #include "third_party/blink/renderer/platform/instrumentation/use_counter.h"
// ... // ...
if (OriginTrials::myFeatureEnabled()) { if (RuntimeEnabledFeatures::MyFeatureEnabled(context)) {
UseCounter::Count(context, WebFeature::kMyFeature); UseCounter::Count(context, WebFeature::kMyFeature);
} }
``` ```
...@@ -108,7 +111,7 @@ enum WebFeature { ...@@ -108,7 +111,7 @@ enum WebFeature {
1. Add \[[Measure]\] IDL attribute 1. Add \[[Measure]\] IDL attribute
``` ```
partial interface Navigator { partial interface Navigator {
[OriginTrialEnabled=MyFeature, Measure] [RuntimeEnabled=MyFeature, Measure]
readonly attribute MyFeatureManager myFeature; readonly attribute MyFeatureManager myFeature;
``` ```
...@@ -127,14 +130,9 @@ enum WebFeature { ...@@ -127,14 +130,9 @@ enum WebFeature {
}; };
``` ```
**NOTE:** Your feature implementation must not persist the result of the enabled
check. Your code should simply call `OriginTrials::myFeatureEnabled()` as often
as necessary to gate access to your feature.
## Limitations ## Limitations
What you can't do, because of the nature of these Origin Trials, is know at What you can't do, because of the nature of these origin trials, is know at
either browser or renderer startup time whether your feature is going to be used either browser or renderer startup time whether your feature is going to be used
in the current page/context. This means that if you require lots of expensive in the current page/context. This means that if you require lots of expensive
processing to begin (say you index the user's hard drive, or scan an entire city processing to begin (say you index the user's hard drive, or scan an entire city
...@@ -182,7 +180,7 @@ If you cannot set command-line switches (e.g., on Chrome OS), you can also ...@@ -182,7 +180,7 @@ If you cannot set command-line switches (e.g., on Chrome OS), you can also
directly modify [chrome_origin_trial_policy.cc]. directly modify [chrome_origin_trial_policy.cc].
### Web Tests ### Web Tests
When using the \[OriginTrialEnabled\] IDL attribute, you should add web tests When using the \[RuntimeEnabled\] IDL attribute, you should add web tests
to verify that the V8 bindings code is working as expected. Depending on how to verify that the V8 bindings code is working as expected. Depending on how
your feature is exposed, you'll want tests for the exposed interfaces, as well your feature is exposed, you'll want tests for the exposed interfaces, as well
as tests for script-added tokens. For examples, refer to the existing tests in as tests for script-added tokens. For examples, refer to the existing tests in
...@@ -192,7 +190,7 @@ as tests for script-added tokens. For examples, refer to the existing tests in ...@@ -192,7 +190,7 @@ as tests for script-added tokens. For examples, refer to the existing tests in
[chrome_origin_trial_policy.cc]: /chrome/common/origin_trials/chrome_origin_trial_policy.cc [chrome_origin_trial_policy.cc]: /chrome/common/origin_trials/chrome_origin_trial_policy.cc
[generate_token.py]: /tools/origin_trials/generate_token.py [generate_token.py]: /tools/origin_trials/generate_token.py
[Developer Guide]: https://github.com/jpchase/OriginTrials/blob/gh-pages/developer-guide.md [Developer Guide]: https://github.com/jpchase/OriginTrials/blob/gh-pages/developer-guide.md
[OriginTrialEnabled]: /third_party/blink/renderer/bindings/IDLExtendedAttributes.md#_OriginTrialEnabled_i_m_a_c_ [RuntimeEnabled]: /third_party/blink/renderer/bindings/IDLExtendedAttributes.md#RuntimeEnabled_i_m_a_c
[origin_trials/webexposed]: /third_party/blink/web_tests/http/tests/origin_trials/webexposed/ [origin_trials/webexposed]: /third_party/blink/web_tests/http/tests/origin_trials/webexposed/
[runtime\_enabled\_features.json5]: /third_party/blink/renderer/platform/runtime_enabled_features.json5 [runtime\_enabled\_features.json5]: /third_party/blink/renderer/platform/runtime_enabled_features.json5
[trial_token_unittest.cc]: /third_party/blink/common/origin_trials/trial_token_unittest.cc [trial_token_unittest.cc]: /third_party/blink/common/origin_trials/trial_token_unittest.cc
......
Markdown is supported
0%
or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment