Skip to content
Jami3D
Developer docs menu

Mobile and iOS fullscreen

How the player behaves on phones: fullscreen on iPhone, safe areas, sound, and how many players run at once.

The page

Give the page a responsive viewport with viewport-fit=cover: the player keeps its controls clear of the notch and the home bar with the safe-area insets, and in fullscreen on iPhone the SDK hands it the insets the iframe cannot read itself.

index.html
<!-- viewport-fit=cover: the notch and the home bar's insets reach the player's controls -->
<meta name="viewport" content="width=device-width, initial-scale=1, viewport-fit=cover" />

Size the player by its container: a container with a height is filled, one without takes the 16 / 9 of aspectRatio. Held upright, a phone gets the stage on top with the transport and the panels below it; held sideways, or in a small embed, the stage fills the player and the panels slide over it.

The picture keeps the frame the experience was made for. Held upright, the stage takes that frame's shape; a container of another shape shows bars in the experience's letterbox colour, or crops the frame's edges, as fit says: letterbox keeps the whole frame, fill covers the container, and balanced, the default, crops as far as the creator allows.

Fullscreen on iPhone

iPhone Safari has no fullscreen for an element inside a cross-origin iframe. There the player asks the SDK, and the SDK makes the player's container cover the viewport — pseudo-fullscreen — without ever moving the iframe, which would reload it:

  • the container goes to the browser's top layer (the Popover API), above any transformed, clipped or stacked ancestor of your page;
  • without the Popover API it falls back to position: fixed, which a transform on an ancestor breaks — keep transforms off the player's ancestors if you support such browsers;
  • the page stops scrolling and gets its scroll position back exactly;
  • the back gesture, Escape and the player's own button all leave it, through one history entry.

Android browsers and desktops use the real fullscreen inside the iframe, through its allow="fullscreen".

Sound, voice and taps

Phones start sound only after a tap. autoplay: "muted" starts silent with a "Tap to unmute"; play() from your own button answers whether the story runs and whether sound does (audio: "suspended" until the viewer taps the player).

lesson.ts
import { createPlayer } from "jami3d";

const player = createPlayer("#stage", {
  projectId: "0199c4a0-0000-7000-8000-0000000000a1",
  publishableKey: "pk_test_…",
  lazy: "viewport", // the iframe mounts when the player scrolls into view
  exclusivePlayback: true, // one story plays at a time on this page
});

// A tap is what unlocks sound on a phone: play() says whether it runs yet.
document.querySelector("#start")?.addEventListener("click", async () => {
  const { playing, audio } = await player.play();
  if (playing && audio === "suspended") console.log("the viewer taps the player for sound");
});

Voice is push-to-talk: the viewer holds Talk. The browser asks for the microphone the first time, for your site — it is your page's permission, so your Permissions-Policy must let the embed host use it.

Several players on one page

Each player holds a WebGL context, and browsers share a small budget of them between frames and tabs. The SDK runs at most two players at once on a phone (four on a desktop): starting another suspends the one used least recently, which keeps its last frame and its place and resumes when the viewer plays it. A player is also suspended after 60 seconds out of view or 30 seconds in a hidden tab, and wakes when it comes back.

exclusivePlayback: true pauses the page's other players when one starts.

Browsers

The SDK needs Promise.withResolvers (Safari and iOS 17.4, Chrome 119, Firefox 121). In an older browser the facade shows a card with a link to watch the experience on jami.live instead.