App Wiring Diagram: 5 Screens & APIs to Deliver a Paywall‑Safe Playable Demo
Written by AppWispr editorial
Return to blogAPP WIRING DIAGRAM: 5 SCREENS & APIS TO DELIVER A PAYWALL‑SAFE PLAYABLE DEMO
This is a prescriptive wiring diagram for founders and product leads who want an indexable, paywall‑safe playable demo that you can hand to a contractor and ship in 72 hours. It lists the five screens you need, the backend endpoints and token flows that protect paid content, the JSON‑LD and prerender rules that make the demo indexable, plus pasteable code snippets and acceptance criteria for QA and handoff.
Section 1
The five screens (what to build first)
Ship a narrow, testable surface: five focused screens map the core demo experience and keep implementation time to a minimum. Each screen below has a single responsibility so a contractor can wire UI to API quickly.
Design note: keep the initial HTML response rich with real H1/H2 copy and three short bullets describing the demo so crawlers and AI scrapers see meaningful content before any interaction. Use prerender or server render for this shell. This ensures indexability even if the playable area is client‑heavy.
- 1. Landing / Teaser — static HTML shell with H1, 2–3 sentence summary, 3 feature bullets, visible 'Play demo' CTA, and <script type="application/ld+json"> for SoftwareApplication/HowTo metadata.
- 2. Playable Canvas Screen — the interactive area (canvas, iframe, or WebGL) hidden behind an explicit reveal action; accessible role region and keyboard operable controls.
- 3. Sandbox Controls Panel — small UI to change demo inputs (predefined presets only), uses client-side state and does not accept uploads or private credentials.
- 4. Result / Snapshot Screen — shows a generated, shareable snapshot (image + immutable slug) of the demo state; snapshot URLs must be indexable and scrubbed of PII.
- 5. Convert / CTA Screen — lightweight signup or 'Request full access' flow that collects email only and links to pricing; keep paywall and purchase flows off the indexable demo path.
Sources used in this section
Section 2
APIs and token flows (paywall‑safe, minimal backend)
Build three small API endpoints that enforce demo safety and keep paid content behind the paywall: /demo/session, /demo/render, and /demo/snapshot. Use short‑lived, single‑use tokens (JWT or opaque tokens) issued from /demo/session and validated by render/snapshot endpoints. Never expose real customer data or billing state in demo payloads.
Token rules: issue tokens scoped to a demo preset, with an expiry of 5–15 minutes and a one‑time use claim. On the server validate token signature, scope, and that the demo preset is allowed. This prevents scraping from replaying a full experience that would otherwise bypass paywalls.
- POST /demo/session — request: { presetId, seed? } → response: { demoToken } (short lived, 5–15m).
- POST /demo/render — headers: Authorization: Bearer demoToken → returns signed render payload or precomputed assets (no user PII).
- POST /demo/snapshot — headers: Authorization: Bearer demoToken → creates an immutable snapshot record { id, url } where url is public but contains no private data.
- Server checks: token signature, expiry, one‑use flag, allowed preset; deny tokens used more than once or from unrecognized IPs if abuse detected.
Section 3
JSON‑LD hooks and prerender rules for indexability
Indexability depends on the static shell. Include JSON‑LD (SoftwareApplication plus a concise HowTo or potentialAction) in the initial HTML so search engines and generative scrapers understand the demo's purpose without executing JavaScript. The structured data must reflect page content and images used on the page.
Prerendering: either server‑render the shell or use a prerender service for crawler user‑agents. Avoid returning an empty body with only client code — crawlers and many AI systems will miss the demo entirely. Follow Google's Structured Data policies: keep JSON‑LD truthful and consistent with visible content.
- Place <script type="application/ld+json"> with @context https://schema.org/ and @type SoftwareApplication (name, url, description, image).
- Add a HowTo or potentialAction describing the demo steps; include a RegisterAction only on the signup CTA page, not on the indexable demo route.
- Ensure all image URLs in JSON‑LD are crawlable and the text in JSON‑LD matches visible H1/H2 content.
Section 4
Pasteable code snippets — minimal examples
Below are compact, ready‑to‑paste examples for the JSON‑LD shell and a minimal /demo/session endpoint. These are intentionally small so you can copy into your repo and iterate.
Acceptance criteria: each snippet must render as valid HTML, JSON‑LD must pass Google's Rich Results Test, and /demo/session must return a signed token that the frontend can use to call /demo/render.
- JSON‑LD shell (paste into <head>): <script type="application/ld+json">{"@context":"https://schema.org/","@type":"SoftwareApplication","name":"MyApp Demo","url":"https://example.com/demo","description":"Try MyApp in your browser — no install.","image":"https://example.com/demo-thumb.png"}</script>
- Minimal session endpoint (Node/Express pseudocode): app.post('/demo/session', (req,res)=>{ const { presetId }=req.body; if(!allowed[presetId]) return res.status(400).end(); const token = signJWT({ presetId, oneUse: true }, { expiresIn: '10m' }); storeOneUse(token); res.json({ demoToken: token }); })
- Frontend flow: fetch /demo/session → receive demoToken → call /demo/render with Authorization: Bearer demoToken → render returned assets in the interactive canvas.
Section 5
Acceptance criteria and contractor handoff checklist
Turn the wiring diagram into a deliverable: include acceptance tests for each screen and endpoint, plus telemetry events to validate the experiment without leaking conversion funnels. Keep paywall and billing flows out of the demo path — the demo must never return protected content or payment tokens.
Provide the contractor with these checklist items and a short QA script. Each acceptance check is binary: pass/fail. If anything fails, the contractor returns a PR with fixes and documented test runs.
- Landing / Teaser: page returns 200 with visible H1 and three bullets; JSON‑LD script present and passes the Rich Results Test.
- Play reveal: clicking or keyboard activating 'Play demo' reveals the interactive region and loads the demo without triggering full page navigation.
- /demo/session: returns demoToken (JWT) signed by your key, expires <= 15m, contains presetId claim.
- /demo/render: accepts demoToken and returns demo assets; returns 401 for invalid/expired/used tokens.
- /demo/snapshot: returns public URL with no PII; snapshot page renders static preview and indexable meta tags.
- Telemetry: events for demo_open, demo_play, demo_snapshot created, demo_signup_clicked — do not send email or payment data in demo telemetry.
Sources used in this section
FAQ
Common follow-up questions
How do I keep the demo 'paywall‑safe' while still being useful?
Expose only simulated or precomputed outputs in the demo and never real customer data. Use scoped, short‑lived demo tokens that expire in minutes and are one‑time use. Put purchase and billing flows on a separate conversion path and do not return payment artifacts or credentials in demo responses.
Will JSON‑LD make the demo show up in search results?
JSON‑LD helps search engines understand the page and can improve eligibility for rich results, but it does not guarantee ranking. The critical step is ensuring the initial HTML shell contains meaningful H1/H2 content, descriptive copy, and crawlable images alongside JSON‑LD. Use Google's Rich Results Test to validate.
Can I accept uploads or user prompts in the demo?
Avoid accepting uploads or private credentials in an indexable demo — these inputs often produce unique content that crawlers can't reproduce and may leak data. If you need variable input, offer a small set of curated presets or client‑side-only simulators.
How should I measure whether the demo is working after launch?
Track a short event set (demo_open, demo_play, demo_snapshot, demo_signup_clicked). Validate that tokens issued by /demo/session are used exactly once and that /demo/render returns 401 for reused or expired tokens. Confirm the JSON‑LD passes Rich Results Test and that the landing shell is indexed in search within a few days.
Sources
Research used in this article
Each generated article keeps its own linked source list so the underlying reporting is visible and easy to verify.
AppWispr
Playable Demo SEO Playbook — 6 Indexable Demo Patterns + JSON‑LD Checklist
https://www.appwispr.com/blog/playable-demo-seo-playbook-6-indexable-accessible-demo-patterns-plus-a-pasteable-json-ld-checklist
General Structured Data Guidelines | Google Search Central
https://developers.google.com/search/docs/appearance/structured-data/sd-policies?version=published
AppWispr
Schema‑First Playable Checklist for Indexable Playables
https://www.appwispr.com/blog/schema-first-playable-checklist-ship-indexable-playables-that-convert-without-breaking-launch-metrics
AppWispr
SEO‑First Playable Testing Kit — Prerender, JSON‑LD & Safe A/B Rules
https://www.appwispr.com/blog/seo-first-playable-testing-kit-run-indexability-accessibility-experiments-without-breaking-launch-metrics
SeoBoosty
Crawlable demo page: earn backlinks without leaking data
https://seoboosty.com/blog/crawlable-demo-page-backlinks-sandbox
Next step
Turn the idea into a build-ready plan.
AppWispr takes the research and packages it into a product brief, mockups, screenshots, and launch copy you can use right away.