What your page must handle
What your page is responsible for once an experience is embedded in it: height, panels, headers, sign-in, security policy and permissions.
For your web developer. Everything inside the frame belongs to the experience; how the frame behaves in your page is yours.
Height
The experience has no fixed height. A form is short, a game fills the screen, and a reward sits somewhere in between. The frame has to follow. Otherwise the visitor gets a scrollbar inside your page, and your footer floats halfway up it.
Two kinds of page take their height in different ways:
| Page | Its height |
|---|---|
| Landing pages, forms, lists and most steps | The experience reports it each time it changes. Your page applies it. |
| Games, and a few full-screen steps such as error pages | They fill whatever height the frame has, and report nothing |
Give the frame a height on every load
A game never reports a height, so a page that waits for one waits forever. Each time a new page loads in the frame, set the frame to the visible screen height, minus your sticky header.
The JavaScript tag handles both kinds for you. A hand-written page needs the messages between the page and the experience.
Panels that open inside the experience
Experiences open panels, such as a reward or a form. A panel lives inside the frame, so on a long page it could open far from where the visitor is looking.
So the experience opens each panel near the visitor's last tap, no taller than the screen. The tag then scrolls your page to centre the panel, below your sticky header. On a hand-written page, your code does that scroll: see Panels.
Your page stays scrollable while a panel is open. The panel is fixed inside the frame, so it moves with your page.
Sticky headers
If your site has a header fixed to the top of the screen, a panel could open underneath it. The tag finds a standard header on its own and keeps panels clear of it. If your header is unusual, point the tag at it: see Sticky headers.
Signing in
When a participant signs in, the sign-in screen takes over the whole tab. Afterwards, the tag brings them back to your page, on the same experience. With your own iframe, your page does that: see A parent page written by hand.
Your page also decides whether the experience starts signed in. With the JavaScript tag, the participant starts signed out each time the page loads. A loginStatus variable changes that: see Sign-in state.
A hand-written frame sends no login, so a participant who signed in before stays signed in. Add login=0 to its address to start signed out, or login=1 to send the visitor through sign-in first.
Your content security policy
If your site sends a content security policy, as most do, it must allow two hosts. Otherwise the embed is blocked, with nothing on screen to explain why:
- the host the tag loads from;
- the host the experience is served from.
The exact values are in What the tag needs from your page. Raise it early: on many sites another team owns the policy, and its approval takes longer than the work.
Browser permissions
Permissions such as the camera are granted to your page, then passed to the frame by its allow attribute. Your site must also be served over HTTPS. If the frame never gets the permission, nothing prompts the visitor, and the game looks broken rather than blocked.
The tag adds no allow attribute to its frame, so an experience that uses the camera or location can't use the tag. Write the iframe yourself, with allow="camera; geolocation". A parent page written by hand has one, with the return from sign-in.