1 /*
2  * Copyright 2025 The Android Open Source Project
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  *      http://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 package androidx.webkit;
18 
19 import androidx.annotation.RequiresOptIn;
20 
21 import org.jspecify.annotations.NonNull;
22 
23 import java.lang.annotation.ElementType;
24 import java.lang.annotation.Retention;
25 import java.lang.annotation.RetentionPolicy;
26 import java.lang.annotation.Target;
27 
28 /**
29  * Page identification and lifecycle APIs. This class provides callbacks to identify the
30  * different stages of navigation.
31  * For more information about the navigation lifecycle, please see the
32  * <a href="https://docs.google.com/presentation/d/1YVqDmbXI0cllpfXD7TuewiexDNZYfwk6fRdmoXJbBlM">Life of a Navigation Presentation</a>.
33  * <p>
34  * Note: These navigation callbacks only fire for navigations happening on the main frame.
35  * <p>
36  * Navigation lifecycle events:
37  * <ul>
38  * <li>{@code onNavigationStarted}</li>
39  * <li>Potentially zero or more {@code onNavigationRedirected} events</li>
40  * <li>{@code onNavigationCompleted}</li>
41  * <li>If the navigation commits and is not a same-document navigation, potentially any
42  * combination and order of zero or one of each of:
43  * <ul>
44  * <li>{@code onPageLoadEvent}</li>
45  * <li>{@code onPageDomContentLoaded}</li>
46  * <li>{@code onFirstContentfulPaint}</li>
47  * </ul>
48  * </li>
49  * </ul>
50  */
51 @WebNavigationClient.ExperimentalNavigationCallback
52 public interface WebNavigationClient {
53     /**
54      * Fired when a navigation starts, including same-document navigations.
55      * <p>
56      * Note: These navigation callbacks only fire for navigations happening on the main frame.
57      *
58      * @param navigation The Navigation object representing the started navigation.
59      */
onNavigationStarted(@onNull Navigation navigation)60     void onNavigationStarted(@NonNull Navigation navigation);
61 
62     /**
63      * Fired when a navigation is redirected.
64      *
65      * @param navigation The Navigation object representing the redirected navigation.
66      */
onNavigationRedirected(@onNull Navigation navigation)67     void onNavigationRedirected(@NonNull Navigation navigation);
68 
69     /**
70      * Fired when a navigation completes.
71      * <p>
72      * The navigation might not have actually committed (e.g., results in 204/download/cancelled).
73      *
74      * @param navigation The Navigation object representing the completed navigation.
75      */
onNavigationCompleted(@onNull Navigation navigation)76     void onNavigationCompleted(@NonNull Navigation navigation);
77 
78     /**
79      * Fired when any Page is evicted/destroyed. This can occur immediately
80      * on navigation, or later if the page is BFCached and subsequently evicted.
81      *
82      * @param page The Page that was evicted or destroyed.
83      */
onPageDeleted(@onNull Page page)84     void onPageDeleted(@NonNull Page page);
85 
86     /**
87      * Fired when the `window.load` event is fired for the current page.
88      *
89      * @param page The Page for which the `window.load` event fired.
90      */
onPageLoadEventFired(@onNull Page page)91     void onPageLoadEventFired(@NonNull Page page);
92 
93     /**
94      * Fired when the `DOMContentLoaded` event is fired for the current page.
95      *
96      * @param page The Page for which the `DOMContentLoaded` event fired.
97      */
onPageDomContentLoadedEventFired(@onNull Page page)98     void onPageDomContentLoadedEventFired(@NonNull Page page);
99 
100     /**
101      * Fired when the page achieves "First Contentful Paint".
102      *
103      * <p>See <a href="https://web.dev/articles/fcp">First Contentful Paint (FCP)</a>
104      * for a definition.</p>
105      *
106      * @param page The Page for which the First Contentful Paint occurred.
107      */
onFirstContentfulPaint(@onNull Page page)108     void onFirstContentfulPaint(@NonNull Page page);
109 
110     /**
111      * Denotes {@link Navigation}, {@link Page} and {@link WebNavigationClient} API surfaces are
112      * experimental.
113      * <p>
114      * It may change without warning and should not be relied upon for non-experimental purposes.
115      */
116     @Retention(RetentionPolicy.CLASS)
117     @Target({ElementType.METHOD, ElementType.TYPE, ElementType.FIELD})
118     @RequiresOptIn(level = RequiresOptIn.Level.ERROR)
119     @interface ExperimentalNavigationCallback {
120     }
121 }
122