Add example demonstrating navigator.presentation usage to property documentation

[low-perry]

Description

This pull request adds an example to demonstrate the usage of the navigator.presentation property in the documentation. The example checks if the browser supports the Presentation API, retrieves the navigator.presentation object, and logs it to the console. If the API is unavailable, an error message is displayed.

Motivation

Additional details

Related issues and pull requests

[github-actions]

Preview URLs

• /en-US/docs/Web/API/Navigator/presentation

(comment last updated: 2025-04-09 17:31:17)

[Josh-Cena]

Thanks but I don't think this is a useful demo. I would prefer an actual usage example that invokes at least one method on the presentation object.

[low-perry]

@Josh-Cena I'll try to improve the example.

[Josh-Cena]

IMO this is still not a useful example because it doesn't pertain to navigator.presentation: you are just using it for feature testing but then going to something else. I understand all of this is very hard because MDN's documentation on Presentation API is extremely bad (#4025). Is there a motivation for adding this example? A lot of these global singletons don't have examples anyway because you can just go to the Presentation interface page.

[low-perry]

Thanks for your feedback! From what I understand, navigator.presentation is just a read-only attribute of the Navigator interface that serves as a gateway to the Presentation API, with no methods to use on it. That’s why my first example focused on checking if the browser supports the Presentation API. The idea was simply to show navigator.presentation in action—demonstrating that it exists and providing a basic example of its usage.

[Josh-Cena]

The Presentation object seems to contain two properties. I have no idea what they do though.

[low-perry]

The defaultRequest represents a PresentationRequest object that can be used to start a presentation, mainly to establish a connection to an external display. However, it’s not fundamentally different from directly instantiating a PresentationRequest (like in my second example), since you still need to create the object before setting it as the defaultRequest. This redundancy might explain why the W3C specification doesn't emphasize defaultRequest much—it’s simply another way to associate a PresentationRequest with navigator.presentation.

[low-perry]

I explored a little bit more and I understand the attributes of the presentation object a little bit better. Here i found the following statement:

In a controlling browsing context, the default presentation request, which is initially set to null, represents the request to use when the user wishes to initiate a presentation connection from the browser chrome.

The defaultRequest property is particularly useful for launching a presentation through the browser’s cast menu. In the example below, initiating the presentation from the browser menu will open presentation.html, whereas clicking the UI button with an id of "startPresentation" will launch presentation2.html.

const presentationRequest = new PresentationRequest(["presentation.html"]);
const presentationRequest2 = new PresentationRequest(["presentation2.html"]);

navigator.presentation.defaultRequest = presentationRequest;

document.getElementById("startPresentation").addEventListener("click", () => {
  presentationRequest2.start().then(session => {
    console.log("Presentation started with session:", session);
  }).catch(error => {
    console.error("Error starting presentation:", error);
  });
});

The receiver attribute is exclusively available in the receiving browsing context. This means it can only be used on the device or window that is displaying the presentation, not on the controlling side where the presentation is initiated.

For the purpose of the navigator.presentation example, I think the code I presented the first time is good enough to show a use case. Alternatively we can just use the following code:

if ("presentation" in navigator) {
      const presentationRequest = new PresentationRequest(["https://example.com/presentation.html"]);
      // Use the default presentation if available, otherwise manually create one
       navigator.presentation.defaultRequest = presentationRequest;
    } else {
      console.error("Presentation API is not available in this browser.");
    }

This will launch a presentation by using the browser's cast menu. Let me know what you think! (I tested all the code I'm presenting on chrome and edge).