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

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>

5. Customizing Embeds with Attributes

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

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>

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.

Publishing Updates / Cache Busting

This package is automatically deployed on merge to master. If you wish to manually deploy:

1. cd apps/web-embeds
2. Bump the version (patch by default): yarn bump (or yarn bump:minor / yarn bump:major). You may want to consult NPM to check on the last deployed version (it will be different than the version in package.json).
3. Publish the package: npm publish --access public (automatically runs prepublishOnly/build)
4. After npm shows the new version, purge jsDelivr so @latest updates immediately: yarn flush
5. (Optional) Hit https://cdn.jsdelivr.net/npm/@apollosproject/canvas-embeds@latest/widget/index.js to verify the new bundle is served

Skipping the publish step means users will still download the previous version even if the repo contains newer code, and skipping the flush step delays propagation until jsDelivr expires its cache.

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

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.