How does a livecard put a page inside a post on X?

What is a livecard?

A livecard is a page of yours that opens inside a post, where people already are, with no click away. clickd hosts ready-made ones at /livecard, and this guide shows how to make any page of your own one.

Under it is X's player card, the one card on X that loads a page of yours in a frame inside a post. X's page about cards lists four kinds: a summary card, a summary card with a large image, an app card, and the player card, "a Card that can display video/audio/media". The other three are a picture and some words.

Two addresses matter. The share address is the link someone posts; X's crawler, Twitterbot, fetches it and reads its tags. The player address is the page X puts in the frame, named by twitter:player. They can be the same page, but a route of its own, such as /in-post, is easier to give the headers and the narrow layout the frame needs.

How does a player card work, step by step?

From the post to the frame there are four steps, and the first two happen once, when the link is posted.

Where the frame shows depends on the client. X's player card reference says that on the web the frame is drawn when the post is expanded, and shown at once on the post's own page, "scaled to fit the appropriate width, maintaining the original aspect ratio". In X's iPhone and Android apps the card shows its image with a play icon in the post's detail view, and a tap opens the player address in a browser inside the app. Other clients show the image and link to the address.

Which tags does a player card need?

These, on the share address, in the page's <head>. The list is X's player card reference; the limits on the title, description and image are from X's cards markup.

<meta name="twitter:card" content="player">
<meta name="twitter:site" content="@acme">
<meta name="twitter:title" content="Hear the first chapter">
<meta name="twitter:description" content="Ten minutes, read by the author.">
<meta name="twitter:image" content="https://acme.example/in-post.png">
<meta name="twitter:player" content="https://acme.example/in-post">
<meta name="twitter:player:width" content="640">
<meta name="twitter:player:height" content="480">

• Every address is absolute and on https. The player reference asks for https for the frame and every asset in the tags.
• One twitter:card. Some frameworks print a second, summary_large_image, from their Open Graph settings; read the page's HTML, not its config.
• Leave out twitter:player:stream. X's markup says it is the "URL to raw video or audio stream", not a page.
• Make the image the frame's size, as the reference asks, since it stands in for the frame. One under 68,600 pixels, such as 262 by 262, "will cause the player card not to render".
• Where a twitter: title, description or image is missing, X's markup says it falls back to og:title, og:description and og:image.

How do you let X, and only X, frame the route?

With one response header on the player route, and nothing else on it that refuses a frame. MDN's page on frame-ancestors explains the rule: it names the sites that may embed a page, it is not supported in a <meta> element, and "if any ancestor doesn't match, the load is canceled", which is why the rule names the subdomains of x.com and twitter.com too.

Content-Security-Policy: frame-ancestors 'self' https://x.com https://*.x.com https://twitter.com https://*.twitter.com

Send no X-Frame-Options on that route. MDN's page on X-Frame-Options says DENY blocks every frame and SAMEORIGIN every frame but the site's own, and that ALLOW-FROM is obsolete: modern browsers ignore the whole header when they meet it. Every other route keeps frame-ancestors 'self' or 'none'.

Read the headers on the live response, not in the config. A site often sets framing in two places, the server and the framework's middleware, and the one that wins elsewhere can still send DENY on the new route.

What does a framed page need?

An embed mode: the same page, told it is in a frame, changed in four ways. X's troubleshooting guide gives the reason in one line: twitter:player "needs to be a simplified web page with only the player on it", since a full website in the frame shows only part of the site.

• Scrolling. In a post's frame the document may not scroll at all. Make the content fit the declared size, or lock the document and scroll an inner element.
• Links. Open every link in a new tab. Sign-in does not work in a frame on another site: sign-in providers refuse to be framed, and the session cookie is a third-party cookie there.
• Overlays. Hide the cookie banner, the chat widget and any floating button; in a small frame they cover the page.
• Weight. The frame loads when someone opens the post, so keep the route light.

html.framed, html.framed body { height: 100%; overflow: hidden; }
html.framed main { height: 100dvh; overflow-y: auto; overscroll-behavior: contain; }

if (window.self !== window.top) document.documentElement.classList.add('framed');

document.addEventListener('click', (event) => {
  if (event.button !== 0 || event.metaKey || event.ctrlKey || event.shiftKey || event.altKey) return;
  const link = event.target.closest?.('a[href]');
  if (!link || link.getAttribute('href').startsWith('#')) return;
  event.preventDefault();
  window.open(link.href, '_blank', 'noopener');
}, true);

The listener runs in the capture phase, so it catches a framework's own links as well as plain ones, and it prevents the default without stopping the event, so click tracking still runs.

How does X keep a card, and how do you change it?

X keeps the card it built for an address. X's troubleshooting guide says its crawler reads a page's card tags again "roughly every seven days", and that images in a card are cached by their address too. A link posted while a tag was wrong can keep the wrong card for days.

So move the route to a new path, or post it with a new query, and give a changed image a new address. The page inside the frame is loaded each time the post is opened, so a fix to the page itself shows on the next open.

What goes wrong, and how do you spot each?

Each failure has a cause you can see from outside. Most of them show in two commands and in clickd's tester.

The two commands, run from your own machine, ask as X's crawler names itself. The first should print the player tags and one twitter:card; the second the frame-ancestors rule and no X-Frame-Options. A CDN, an edge worker or bot protection often answers social crawlers from a path of its own, so pass the user agent every time, and only the live answer counts.

curl -s -A "Twitterbot/1.0" https://acme.example/launch | grep -o '<meta name="twitter:[^>]*>'
curl -s -o /dev/null -D /dev/stdout -A "Twitterbot/1.0" https://acme.example/in-post | grep -i 'content-security\|x-frame'

A checklist for one route

• Give the frame a route of its own, such as /in-post, never the home page.
• Put the player tags on the share address, with one twitter:card and every address absolute and on https.
• Make the image the frame's size, 68,600 pixels or more, under 5 MB, and not SVG.
• On the player route only, send the frame-ancestors rule for x.com and twitter.com, and no X-Frame-Options.
• Give the framed page an embed mode: inner scrolling, links in new tabs, overlays hidden.
• Fetch the share address and the player route as Twitterbot, and test the link with the tester.
• Post it from a spare account, open it on the web and in X's apps, and post a new address if anything was wrong.

How do you check it with clickd?

The free X card tester takes the link you will post. It reads robots.txt first, as for Twitterbot, then the card tags as clickd's crawler is served them, measures the image, and for a player card reads the player route's headers host by host. Where the route lets any site frame it, it runs the page in a frame of the declared shape. Where it lets only X, the tester shows the image instead, since clickd.com is not X: that is the rule working. Its second half makes the tags and the header from a few values.

clickd fetches under its own name and never as X's crawler, so it cannot see what an edge layer answers Twitterbot with. The tester gives the two commands above for the link you typed.

For the site's own repository there is a skill for your agent. It picks the route, writes the tags, opens framing to X on that route alone, gives the page its embed mode, fetches the live route as Twitterbot, and reports what it found, the policy among it.

mkdir -p .claude/skills/clickd-livecards/references && curl -fsSL https://clickd.com/skills/livecards/SKILL.md -o .claude/skills/clickd-livecards/SKILL.md && curl -fsSL https://clickd.com/skills/livecards/references/card-tags.md -o .claude/skills/clickd-livecards/references/card-tags.md && curl -fsSL https://clickd.com/skills/livecards/references/framing-headers.md -o .claude/skills/clickd-livecards/references/framing-headers.md && curl -fsSL https://clickd.com/skills/livecards/references/embed-mode.md -o .claude/skills/clickd-livecards/references/embed-mode.md && curl -fsSL https://clickd.com/skills/livecards/references/troubleshooting.md -o .claude/skills/clickd-livecards/references/troubleshooting.md

mkdir -p .agents/skills/clickd-livecards/references && curl -fsSL https://clickd.com/skills/livecards/SKILL.md -o .agents/skills/clickd-livecards/SKILL.md && curl -fsSL https://clickd.com/skills/livecards/references/card-tags.md -o .agents/skills/clickd-livecards/references/card-tags.md && curl -fsSL https://clickd.com/skills/livecards/references/framing-headers.md -o .agents/skills/clickd-livecards/references/framing-headers.md && curl -fsSL https://clickd.com/skills/livecards/references/embed-mode.md -o .agents/skills/clickd-livecards/references/embed-mode.md && curl -fsSL https://clickd.com/skills/livecards/references/troubleshooting.md -o .agents/skills/clickd-livecards/references/troubleshooting.md

mkdir -p .cursor/skills/clickd-livecards/references && curl -fsSL https://clickd.com/skills/livecards/SKILL.md -o .cursor/skills/clickd-livecards/SKILL.md && curl -fsSL https://clickd.com/skills/livecards/references/card-tags.md -o .cursor/skills/clickd-livecards/references/card-tags.md && curl -fsSL https://clickd.com/skills/livecards/references/framing-headers.md -o .cursor/skills/clickd-livecards/references/framing-headers.md && curl -fsSL https://clickd.com/skills/livecards/references/embed-mode.md -o .cursor/skills/clickd-livecards/references/embed-mode.md && curl -fsSL https://clickd.com/skills/livecards/references/troubleshooting.md -o .cursor/skills/clickd-livecards/references/troubleshooting.md

What do people ask about X player cards?

Sources

Where the figures come from. Every figure on this page is X’s own or MDN’s, from the pages listed under Sources, as archived on the dates shown. None is counted by clickd, and nothing here says X will show a card. A score or a rule passed says pages are well formed. It does not say an assistant cites the site.