Apollos React embed widgets
npm install @apollosproject/canvas-embedsApollos 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.
---
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:
``html`
href="https://cdn.jsdelivr.net/npm/@apollosproject/canvas-embeds@latest/widget/index.css"
/>
src="https://cdn.jsdelivr.net/npm/@apollosproject/canvas-embeds@latest/widget/index.min.js"
>
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:
`html`
src="https://cdn.jsdelivr.net/npm/@apollosproject/canvas-embeds@latest/widget/index.min.js"
data-apollos-route="/apollos"
>
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:
`html`
src="https://cdn.jsdelivr.net/npm/@apollosproject/canvas-embeds@latest/widget/index.min.js"
data-apollos-modal="true"
>
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:
`html
data-type="FeatureFeed"
data-church="example_church"
>
data-type="Search"
data-hide-apollos-auth="true"
data-church="example_church"
data-search-profile-size="365px"
>
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"
>
---
$3
Use
(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:
`html
data-type="FeatureFeed"
data-church="example_church"
data-feature-feed="FeatureFeed:unique-id"
data-modal="true"
>Example for a Donation embed:
html
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"
>---
$3
Church slugs uniquely identify the organization whose content is displayed. If you're unsure of your slug, contact a developer or administrator.
> [!NOTE]
> Replace
with your church's unique identifier (or slug). Contact a developer if you need assistance obtaining a church slug.---
For Developers
$3
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.$3
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.---
$3
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:
`html
data-church="apollos_demo"
data-feature-feed="FeatureFeed:caf294f0-cd0e-4486-95e7-fa11bd5fb1c5"
data-modal="true"
class="apollos-widget"
>To test changes, open
in your browser.---
$3
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): (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 to verify the new bundle is servedSkipping 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.
---
$3
To test caching in local development, modify the Apollo client configuration by commenting out the
x-cache-me-not header in:`javascript
'x-cache-me-not': 1,
`$3
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.
bash
yarn flush
`---
$3
#### Supported Embeds and Attributes
| Embed Type | Key Attributes |
| -------------- | -------------------------------------------------------- |
|
| 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:`html
`Notes:
- Ask posts to your Admin app’s