Skip to main content

Immersive project plugin

The immersive project plugin lets a Brightspot site host self-contained static microsites, called immersive projects, that are built outside the CMS and uploaded as a .zip file. A CMS page acts as a shell for the project: it serves the uploaded HTML at its own permalink, injects platform scripts and metadata into that HTML, and hands off requests for the project's static assets (JavaScript, CSS, images) to cloud storage.

This lets a separate team—a data journalism unit, an agency, or an internal interactive team—build and test a project independently of the CMS, then hand off a single .zip file for publishing.

Key capabilities​

  • Upload a project as a .zip file through the CMS, or push one from a CI/CD pipeline through an authenticated upload API.
  • Serve the project from any CMS page by implementing a single interface on the page's content type.
  • Pin a page to a specific uploaded version, or let it always serve the latest one.
  • Point a page at a single HTML file inside a project instead of the project root, for projects that contain multiple sub-pages.
  • Inject platform-provided scripts, links, and other content into the project's HTML through placeholder and block-substitution syntax, without the project depending on the CMS at build time.
  • Override per-sub-page SEO and social-share metadata from the CMS.
  • Choose how static assets are served—rewritten to direct CDN URLs, or routed through Brightspot with a cache-busting version parameter—per project or site-wide.

How it works​

A page's content type implements ImmersiveProjectLinkable and is assigned an immersive project through a picker field. When a request comes in for that page's permalink (or for a path beneath it), a servlet filter recognizes the page as an immersive project host, reads the matching HTML file directly from cloud storage, runs it through a chain of transformation extension points to inject platform content and rewrite metadata, and writes the result to the response. Requests for the project's non-HTML assets are redirected to their cloud storage location instead of being streamed through Brightspot.

Uploads are processed asynchronously: publishing a version (from the CMS) or posting to the upload API (from CI/CD) queues a background job that extracts the .zip, uploads its contents to the configured storage backend, and records a file inventory used to populate CMS pickers.

Use cases​

Data journalism and interactive storytelling​

An editorial interactive team builds a scrollytelling piece with its own build tooling, then hands the production build's output folder, zipped, to an editor. The editor uploads the .zip to an Immersive Project Version record and links it to an article page. The story renders at the article's normal URL, appears in search and feeds like any other article, and the interactive team never has to touch the CMS or wait on a deploy to publish an update—they upload a new .zip and publish the version.

Marketing microsites for campaign launches​

A marketing team ships a multi-page campaign microsite (landing page plus a few sub-pages) as a single build. The hosting CMS page uses the Sub Page picker to point visitors at a specific HTML file within the project for a given URL, and per-sub-page metadata overrides give each section its own SEO title, description, and share image without the project needing any CMS awareness at build time.

CI/CD-driven publishing​

An engineering team wants immersive project deploys to happen the same way as their other static site deploys. Their pipeline computes an HMAC over the built .zip and posts it to the /immersive-project-upload endpoint with an API client's credentials and the target project's internal identifier. Each deploy creates a new version automatically, with no manual CMS step required.

Ad-supported or sponsor-branded projects​

A project includes an ad slot that should show a house ad when the .zip is opened as a static file locally, but pull a live, targeted ad when served through Brightspot. The project's HTML wraps the ad markup in IMMERSIVE-SUB comment delimiters; a custom HtmlBlockSubstitution implementation supplies the live ad markup when the page is served through the CMS, and the fallback remains visible when the file is opened directly in a browser.

Who this documentation is for​

Was this page helpful?

This site is protected by reCAPTCHA and the Google Privacy Policy and Terms of Service apply.