Apollos Web Embeds v2

Next-generation embeddable widget system for Apollos that enables churches to provide their congregation with instant access to church resources, AI-powered search, and key actions directly from their website.

Quick Start

Installation

Add the following script tag before the closing </body> tag:

<script>
  (function (w, d, s, o, f, js, fjs) {
    w["ApollosEmbed"] = o;
    w[o] =
      w[o] ||
      function () {
        (w[o].q = w[o].q || []).push(arguments);
      };
    js = d.createElement(s);
    fjs = d.getElementsByTagName(s)[0];
    js.id = o;
    js.src = f;
    js.async = 1;
    fjs.parentNode.insertBefore(js, fjs);
  })(
    window,
    document,
    "script",
    "apollos",
    "https://embed.apollos.com/v2/embed.js"
  );

  apollos("init", {
    slug: "your-church-slug",
  });
</script>

Link Interception (Primary Use Case)

The simplest way to use the embed is through automatic link interception. Any link on your website pointing to your church's Apollos URL will automatically open in the embed:

<a href="https://apollos.com/your-church/give">Give Now</a>
<a href="https://apollos.com/your-church/events">View Events</a>

Migration detection (personOriginId)

personOriginId (optional): the visitor's CMS person id (e.g. Rock RMS ${CurrentPerson.Id}). Enables pre-login migration detection on any page running the embed: a hidden /{slug}/_embed probe iframe checks server-side whether the visitor has a recurring gift to migrate and, on a hit, shows a top-center toast that opens the migration flow. No-op when the visitor has no Apollos session and no personOriginId is passed.

// Before
apollos("init", { slug: "your-church-slug" });

// After (with migration detection — Rock RMS example)
apollos("init", {
  slug: "your-church-slug",
  personOriginId: "${CurrentPerson.Id}",
});

If the id isn't known at init time, the embed also reads a personoriginid attribute off the inline give iframe and picks it up whenever the host page sets it (e.g. once Rock/GTM resolves the visitor) — the init config value takes precedence when both are present.

Development

# Install dependencies
npm install

# Start dev server (runs inject-config first, then Vite)
npm run dev

# Build for production
npm run build

Crossroads test page

The public/crossroads-test/ directory contains a demo giving page. The embed base URL, church slug, and embed script URL are configurable via env vars and injected into the *.template.html files:

• Local dev: Create .env in apps/web-embeds-v2/ (see .env.example). Run npm run inject-config or npm run dev to generate index.html / giving-history.html from the templates. The generated *.html files are gitignored — only the *.template.html sources are committed.

Demo site (hosted)

The demo pages in public/ are deployed to a persistent URL via Vercel, which also creates a preview deployment for every pull request that touches this app.

• What's deployed: the entire public/ folder (so any file added there is picked up automatically) plus a fresh dist/embed.js built from that branch — so PR previews reflect the actual embed behavior of the change. The crossroads-test templates are injected at build time.
• Build: yarn build:site runs inject-embed-config.js → vite build → scripts/build-demo-site.mjs, which assembles the site/ output directory (mirrors the dev-server layout: public/ files at the web root, the widget at /dist/embed.js). site/ is gitignored.
• Pages: / is a menu (public/index.html) linking to each demo — /demo.html (embed playground), /crossroads-test/ (giving), /crossroads-test/giving-history.html (recurring gifts → modal). Add a link to the menu whenever you add a new host page to public/.

One-time Vercel project setup (dashboard, per the Vercel monorepo docs):

1. New Project → import this repo → set Root Directory to apps/web-embeds-v2.
2. Framework Preset: Other (build/install/output come from vercel.json).
3. Add Environment Variables (Production + Preview):
   • APOLLOS_EMBED_BASE_URL — the web-app origin the embeds point at (e.g. https://apollos.app)
   • APOLLOS_EMBED_CHURCH_SLUG — demo church slug (e.g. apollos-demo)
   • APOLLOS_EMBED_SCRIPT_URL — leave as /dist/embed.js to use the bundle built on this deploy, or set a CDN URL to pin a published version.
4. Under Settings → Git, enable "Only build when there are changes in the Root Directory" so unrelated commits don't redeploy.

Production (the main branch) is the persistent URL; each PR gets its own preview URL commented on the PR.

Note: demo.html / search-demo.html are dev harnesses that resolve the embedded web app from the page's own origin, so on the hosted site they'll only render fully against a same-origin backend. The crossroads-test pages are the fully-configured showcase (backend wired via the env vars above).

Publishing

This app publishes to the npm package @apollosproject/web-embeds (separate from @apollosproject/canvas-embeds).

CDN URL:
https://cdn.jsdelivr.net/npm/@apollosproject/web-embeds@latest/widget/embed.js

Automatic deploy

On push to main, the GitHub workflow syncs the published version from npm (if any), bumps the version (patch by default), runs npm publish (which triggers prepublishOnly to build), and purges the jsDelivr cache for @apollosproject/web-embeds.

Manual deploy

From the repo root (after yarn install):

1. cd apps/web-embeds-v2
2. Optionally sync to the last published version: yarn version --immediate "$(npm show @apollosproject/web-embeds version)"
3. Bump the version: yarn bump (patch by default, or yarn bump:prerelease for prerelease)
4. Publish: npm publish (runs prepublishOnly to build and verify)
5. Purge jsDelivr cache: yarn flush

Skipping the publish step means users will still get the previous version; skipping the flush step delays propagation until jsDelivr’s cache expires.

Documentation

See the full Product Requirements Document for detailed specifications.

License

MIT