1 | /*
|
2 | * Copyright 2022 Google LLC
|
3 | *
|
4 | * Licensed under the Apache License, Version 2.0 (the "License");
|
5 | * you may not use this file except in compliance with the License.
|
6 | * You may obtain a copy of the License at
|
7 | *
|
8 | * https://www.apache.org/licenses/LICENSE-2.0
|
9 | *
|
10 | * Unless required by applicable law or agreed to in writing, software
|
11 | * distributed under the License is distributed on an "AS IS" BASIS,
|
12 | * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
|
13 | * See the License for the specific language governing permissions and
|
14 | * limitations under the License.
|
15 | */
|
16 |
|
17 | import {onBFCacheRestore} from './lib/bfcache.js';
|
18 | import {bindReporter} from './lib/bindReporter.js';
|
19 | import {initMetric} from './lib/initMetric.js';
|
20 | import {
|
21 | DEFAULT_DURATION_THRESHOLD,
|
22 | processInteractionEntry,
|
23 | estimateP98LongestInteraction,
|
24 | resetInteractions,
|
25 | } from './lib/interactions.js';
|
26 | import {observe} from './lib/observe.js';
|
27 | import {onHidden} from './lib/onHidden.js';
|
28 | import {initInteractionCountPolyfill} from './lib/polyfills/interactionCountPolyfill.js';
|
29 | import {whenActivated} from './lib/whenActivated.js';
|
30 |
|
31 | import {INPMetric, MetricRatingThresholds, ReportOpts} from './types.js';
|
32 |
|
33 | /** Thresholds for INP. See https://web.dev/articles/inp#what_is_a_good_inp_score */
|
34 | export const INPThresholds: MetricRatingThresholds = [200, 500];
|
35 |
|
36 | /**
|
37 | * Calculates the [INP](https://web.dev/articles/inp) value for the current
|
38 | * page and calls the `callback` function once the value is ready, along with
|
39 | * the `event` performance entries reported for that interaction. The reported
|
40 | * value is a `DOMHighResTimeStamp`.
|
41 | *
|
42 | * A custom `durationThreshold` configuration option can optionally be passed to
|
43 | * control what `event-timing` entries are considered for INP reporting. The
|
44 | * default threshold is `40`, which means INP scores of less than 40 are
|
45 | * reported as 0. Note that this will not affect your 75th percentile INP value
|
46 | * unless that value is also less than 40 (well below the recommended
|
47 | * [good](https://web.dev/articles/inp#what_is_a_good_inp_score) threshold).
|
48 | *
|
49 | * If the `reportAllChanges` configuration option is set to `true`, the
|
50 | * `callback` function will be called as soon as the value is initially
|
51 | * determined as well as any time the value changes throughout the page
|
52 | * lifespan.
|
53 | *
|
54 | * _**Important:** INP should be continually monitored for changes throughout
|
55 | * the entire lifespan of a page—including if the user returns to the page after
|
56 | * it's been hidden/backgrounded. However, since browsers often [will not fire
|
57 | * additional callbacks once the user has backgrounded a
|
58 | * page](https://developer.chrome.com/blog/page-lifecycle-api/#advice-hidden),
|
59 | * `callback` is always called when the page's visibility state changes to
|
60 | * hidden. As a result, the `callback` function might be called multiple times
|
61 | * during the same page load._
|
62 | */
|
63 | export const onINP = (
|
64 | onReport: (metric: INPMetric) => void,
|
65 | opts?: ReportOpts,
|
66 | ) => {
|
67 | // Set defaults
|
68 | opts = opts || {};
|
69 |
|
70 | whenActivated(() => {
|
71 | // TODO(philipwalton): remove once the polyfill is no longer needed.
|
72 | initInteractionCountPolyfill();
|
73 |
|
74 | let metric = initMetric('INP');
|
75 | let report: ReturnType<typeof bindReporter>;
|
76 |
|
77 | const handleEntries = (entries: INPMetric['entries']) => {
|
78 | entries.forEach(processInteractionEntry);
|
79 |
|
80 | const inp = estimateP98LongestInteraction();
|
81 |
|
82 | if (inp && inp.latency !== metric.value) {
|
83 | metric.value = inp.latency;
|
84 | metric.entries = inp.entries;
|
85 | report();
|
86 | }
|
87 | };
|
88 |
|
89 | const po = observe('event', handleEntries, {
|
90 | // Event Timing entries have their durations rounded to the nearest 8ms,
|
91 | // so a duration of 40ms would be any event that spans 2.5 or more frames
|
92 | // at 60Hz. This threshold is chosen to strike a balance between usefulness
|
93 | // and performance. Running this callback for any interaction that spans
|
94 | // just one or two frames is likely not worth the insight that could be
|
95 | // gained.
|
96 | durationThreshold: opts!.durationThreshold ?? DEFAULT_DURATION_THRESHOLD,
|
97 | });
|
98 |
|
99 | report = bindReporter(
|
100 | onReport,
|
101 | metric,
|
102 | INPThresholds,
|
103 | opts!.reportAllChanges,
|
104 | );
|
105 |
|
106 | if (po) {
|
107 | // If browser supports interactionId (and so supports INP), also
|
108 | // observe entries of type `first-input`. This is useful in cases
|
109 | // where the first interaction is less than the `durationThreshold`.
|
110 | if (
|
111 | 'PerformanceEventTiming' in self &&
|
112 | 'interactionId' in PerformanceEventTiming.prototype
|
113 | ) {
|
114 | po.observe({type: 'first-input', buffered: true});
|
115 | }
|
116 |
|
117 | onHidden(() => {
|
118 | handleEntries(po.takeRecords() as INPMetric['entries']);
|
119 | report(true);
|
120 | });
|
121 |
|
122 | // Only report after a bfcache restore if the `PerformanceObserver`
|
123 | // successfully registered.
|
124 | onBFCacheRestore(() => {
|
125 | resetInteractions();
|
126 |
|
127 | metric = initMetric('INP');
|
128 | report = bindReporter(
|
129 | onReport,
|
130 | metric,
|
131 | INPThresholds,
|
132 | opts!.reportAllChanges,
|
133 | );
|
134 | });
|
135 | }
|
136 | });
|
137 | };
|