Skip to content

Commit 64e8560

Browse files
committed
Added a section on immersive navigation to the explainer
Replaces #256 and compliments #382
1 parent 055e57d commit 64e8560

File tree

1 file changed

+24
-0
lines changed

1 file changed

+24
-0
lines changed

explainer.md

+24
Original file line numberDiff line numberDiff line change
@@ -936,6 +936,29 @@ function drawScene() {
936936
}
937937
```
938938
939+
### Immersive Nagivation
940+
941+
There are several scenarios in which a user may want to navigate to a page in such a way that it immediately begins displaying immersive WebXR content. This is known as "Immersive Navigation". Some potential cases that may trigger immersive navigation are:
942+
943+
* Navigating from within an immersive WebXR session with the `window.location` attribute or `window.history` API.
944+
* Opening a page from a shortcut that has been added to a homescreen, bookmarks, or other "deep link" context.
945+
* Opened within a native app.
946+
947+
It's up to the UA which immersive navigation scenarios it will support (although there are security and privacy considerations that all UAs should take into account, see below.) As a result, pages should never exclusively rely on immersive navigation as their only method for displaying immersive content. For a far more thorough look at the criteria that should be examined for determining when immersive navigation is appropriate and other considerations surrounding it, see the [Navigation Explainer](https://github.com/immersive-web/webxr/pull/382).
948+
949+
A page enables immersive navigation by calling `requestImmersiveNavigationSession` on the `navigator.xr` object. This call is passed an `XRSessionCreationOptions` dictionary like `XRDevice`'s `requestSession` function, but the `immersive` option is ignored, since "immersive navigation" implies that the receiving session must be immersive. This call must be made prior to the `window`'s `load` event has completed, or the promise will reject immediately. Additionally if the page is not eligible for immersive navigation or the `XRSessionCreationOptions` specified are not compatible with the session navigated from the promise will also reject.
950+
951+
```js
952+
window.addEventListener('load', () => {
953+
// { immersive: true } is implicit in this call, because navigations between
954+
// immersive sessions is the only context in which this makes sense.
955+
navigator.xr.requestImmersiveNavigationSession({ outputContext: ctx }).then((session) => {
956+
xrDevice = session.device;
957+
OnSessionStarted(session);
958+
});
959+
});
960+
```
961+
939962
## Appendix A: I don’t understand why this is a new API. Why can’t we use…
940963
941964
### `DeviceOrientation` Events
@@ -980,6 +1003,7 @@ partial interface Navigator {
9801003
[SecureContext, Exposed=Window] interface XR : EventTarget {
9811004
attribute EventHandler ondevicechange;
9821005
Promise<XRDevice> requestDevice();
1006+
Promise<XRSession> requestImmersiveNavigationSession(optional XRSessionCreationOptions parameters);
9831007
};
9841008

9851009
//

0 commit comments

Comments
 (0)