@apollosproject/canvas-embeds

Apollos Embeds

Apollos React Embeds are pre-built, reusable components designed to integrate seamlessly into third-party websites such as Webflow. These widgets provide functionality for authentication, content feeds, and search features, creating a unified and engaging user experience across platforms.

Getting Started with Apollos Embeds

1. Adding Script Tags to Your Website

To enable the Apollos Embeds, include the following scripts and stylesheets in your website's code. For Webflow users, add them to the Custom Code section under Footer Code:

<link
  rel="stylesheet"
  href="https://cdn.jsdelivr.net/npm/@apollosproject/canvas-embeds@latest/widget/index.css"
/>
<script
  defer
  src="https://cdn.jsdelivr.net/npm/@apollosproject/canvas-embeds@latest/widget/index.min.js"
></script>

3. Understanding Embed Modes

There are three primary modes in which Apollos Embeds can be used:

• Apollos Site Mode
• Container Mode
• Legacy Modal Mode

Apollos Site Mode

In the Apollos Site Mode, all embeds link to the external Apollos site. This mode is recommended for users who want to maintain a consistent user experience across platforms, and it is the default mode for all embeds.

Container Mode

In the Container Mode, embeds are displayed within a container on the host website. This mode is recommended for users who want to keep users on their website while providing Apollos functionality. This mode also enables the user to cleanly integrate Apollos content into their website, while also applying custom styles.

To enable the Container Mode, add the data-apollos-path="/apollos" attribute to the script tag:

<script
  defer
  src="https://cdn.jsdelivr.net/npm/@apollosproject/canvas-embeds@latest/widget/index.min.js"
  data-apollos-route="/apollos"
></script>

On the host website, visiting any feed or content will navigate to the /apollos path on the host website. This path (which is customizable) should contain a div with the ID apollos-widget-container to display the embed content. This container should be styled to match the host website's design.

Legacy Modal Mode

In the Legacy Modal Mode, embeds are displayed in a modal window on the host website. This mode is recommended for users who want to keep users on their website while providing Apollos functionality. All embeds will be displayed in a modal window, with navigation state being tracked via URL search params.

To enable the Legacy Modal Mode, add the data-apollos-modal="true" attribute to the script tag:

<script
  defer
  src="https://cdn.jsdelivr.net/npm/@apollosproject/canvas-embeds@latest/widget/index.min.js"
  data-apollos-modal="true"
></script>

4. Add Embed Containers

Navigate to your site builder (e.g., Webflow) and add a div element for each embed you plan to use. Supported embeds:

• Auth — user authentication
• FeatureFeed — curated content feeds
• Search — classic Algolia search and profile UI
• Ask — AI Q&A assistant (separate from Search)
• Donation — Stripe-powered giving

Each div must include the apollos-widget class.

Example:

<!-- Auth -->
<div class="apollos-widget" data-type="Auth" data-church="example_church"></div>

<!-- FeatureFeed -->
<div
  class="apollos-widget"
  data-type="FeatureFeed"
  data-church="example_church"
></div>

<!-- Search (Algolia) -->
<div
  class="apollos-widget"
  data-type="Search"
  data-hide-apollos-auth="true"
  data-church="example_church"
  data-search-profile-size="365px"
></div>

<!-- Ask (AI assistant) -->
<div class="apollos-widget" data-type="Ask" data-church="example_church"></div>

<!-- Donation -->
<div
  class="apollos-widget"
  data-type="Donation"
  data-church="example_church"
  data-amount="50"
  data-frequency="monthly"
  data-campus="main"
  data-fund="general"
  data-message="Support our mission and make a difference today."
  data-width="500px"
  data-height="700px"
></div>

5. Customizing Embeds with Attributes

Use data-attributes (or Custom Attributes in Webflow) to customize the behavior and appearance of each embed.

Attribute	Description
data-type	One of: Auth, FeatureFeed, Search, Ask, Donation.
data-church	Church slug (e.g., bayside).
data-search-profile-size	(Search) Width of the profile modal.
data-hide-apollos-auth	(Search) Hides the profile/auth UI.
data-feature-feed	(FeatureFeed) ID of the feed to show.
data-amount	(Donation) Default donation amount.
data-frequency	(Donation) one-time, monthly, or yearly.
data-campus	(Donation) Campus for the donation.
data-fund	(Donation) Fund for the donation.
data-message	(Donation) Message above the form.
data-width	(Donation) Width (e.g., 400, 100%).
data-height	(Donation) Height (e.g., 600, 100vh).
data-display-logo	(Donation) Show logo (true/false, default true).
data-title	(Donation) Custom title (empty hides title).
data-display-header	(Donation) Show header (true/false, default true).

Example for a FeatureFeed embed:

<div
  class="apollos-widget"
  data-type="FeatureFeed"
  data-church="example_church"
  data-feature-feed="FeatureFeed:unique-id"
  data-modal="true"
></div>

Example for a Donation embed:

<div
  class="apollos-widget"
  data-type="Donation"
  data-church="example_church"
  data-amount="50"
  data-frequency="monthly"
  data-campus="main"
  data-fund="general"
  data-message="Support our mission and make a difference today."
  data-width="500"
  data-height="700"
  data-title="Support Our Ministry"
  data-display-logo="true"
  data-display-header="true"
></div>

6. Understanding Church Slugs

Church slugs uniquely identify the organization whose content is displayed. If you're unsure of your slug, contact a developer or administrator.

[!NOTE] Replace [INSERT_CHURCH_SLUG_HERE] with your church's unique identifier (or slug). Contact a developer if you need assistance obtaining a church slug.

For Developers

Background

This package was originally part of the apollos-embeds repository and involved significant duplication of frontend code, components, and GraphQL queries. To unify our web frontend development, we created canvas-ui-web as a component library. The apollos-embeds project has been moved into this repository to coexist with our other web platforms.

The original version of web-embeds was heavily dependent on modal presentation. This new package retains selective use of modals while encouraging users to navigate to Apollos microsites, which run on New Web.

How It Works

Embeds are bundled as index.js and index.css in the /widget folder and distributed via jsDelivr. By including these on the webpage, users can access these embeds. Placing an apollos-widget div on the page triggers the web embed functionality.

Local Development

To work on this package locally, ensure you have a valid Feature Feed ID. Use index.html for testing with examples. Keep in mind that embeds from different churches on the same page may cause conflicts, so ensure you only use one church per page. You should be running apollos-cluster as well as this entire repo by running yarn dev.

Testing Embeds Locally

Use the index.html file for testing. Open http://localhost:5174 in your browser to view changes.

Example embed for testing:

<div
  data-type="FeatureFeed"
  data-church="apollos_demo"
  data-feature-feed="FeatureFeed:caf294f0-cd0e-4486-95e7-fa11bd5fb1c5"
  data-modal="true"
  class="apollos-widget"
></div>

To test changes, open http://localhost:5174 in your browser.

Caching

To test caching in local development, modify the Apollo client configuration by commenting out the x-cache-me-not header in:

src/client/apollosApiLink.js

'x-cache-me-not': 1,

jsDelivr Cache Busting

If you need to force jsDelivr to fetch the latest version of a file, you can manually purge the cache by accessing the purge subdomain of the file's URL. This command clears the cached version of the file from jsDelivr's CDN.

yarn flush

Advanced Configuration

Supported Embeds and Attributes

Embed Type	Key Attributes
Auth	data-church
FeatureFeed	data-church, data-feature-feed
Search	data-church, data-search-profile-size
	data-hide-apollos-auth
Ask	data-church
Donation	data-church, data-amount, data-frequency
	data-campus, data-fund, data-message
	data-width, data-height
	data-display-logo, data-title, data-display-header

Path Routing

For advanced routing options, use:

• data-use-path-router="true" for enabling path-based routing.
• data-apollos-id-param="true" for custom ID handling.

Ask Embed

The Ask experience now lives in its own embed. Use data-type="Ask" to render the AI assistant separate from Search:

<div class="apollos-widget" data-type="Ask" data-church="example_church"></div>

Notes:

• Ask posts to your Admin app’s /api/:church/ask endpoint using a simple POST (no custom headers), so CORS preflights are avoided.
• In Modal or Container mode, Ask renders within the same shell as other embeds.