Shield (Facebook Instant overlays)

FRVR.shield is a Facebook Instant Games–specific layer for drawing overlay UI that satisfies Meta’s compliance rules — leaderboards, end‑of‑session splashes, social rails — from your game code.

Since Meta’s Network‑Enabled Zero‑Permissions Games change, Shield is also the only way to render the current player’s display name and photo on Facebook Instant. Meta supplies those fields to Shield‑rendered UI even when the raw values are hidden from your JS. See Profile.

Enable it

FRVR.config.shield = true;   // or self‑host with { xmlPath, cssPath }
// (set this before FRVR.init() in your app's startup — no extra init() needed here)

Create an overlay

const overlay = await FRVR.shield.createOverlay(
  'layouts/endscreen.xml',              // Shield XML layout
  'styles/endscreen.css',               // Shield stylesheet
  document.getElementById('game-root'), // container element (optional)
  'width:100%;height:100%;',            // inline style (optional)
  { score: 10000, playerName: 'Alex' }, // payload bound into the layout (optional)
);

if (!overlay) {
  // Shield unavailable (wrong channel, load failure). Fall back to your own UI.
}

The overlay is shown automatically on creation. Keep a reference if you need to tear it down or communicate with it later.

Rendering player identity

Any layout that binds {{player.name}} or {{player.photo}} will receive Meta‑supplied values, even though FRVR.profile.name() / .photo() return undefined under the zero‑permissions model. For a player‑info card, end‑of‑match recap, or social rail on Facebook Instant, Shield is the intended path.

When to use it

• On Facebook Instant: for any overlay that shows player identity (name/photo), leaderboard snippets, share rails, or end‑of‑session screens. It’s the only compliant way to surface Meta‑hosted player data now.
• On other channels: FRVR.shield.createOverlay() returns null without error. Cross‑channel UI should live in your own render layer — keep Shield for Facebook Instant specifically.