@apollosproject/web-embeds

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>

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 and church slug are configurable via env vars:

• 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 from the template.
• GitHub Pages: Set APOLLOS_EMBED_BASE_URL and APOLLOS_EMBED_CHURCH_SLUG in repo Settings → Variables and secrets → Actions. The workflow deploys on push to main when crossroads-test files change. Enable Pages in Settings → Pages → Source: GitHub Actions. The same deploy publishes both index.html (giving page) and giving-history.html (giving history page with Recurring Gifts → modal); use / and /giving-history.html on your Pages URL.

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