# 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**:

```html
<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:

```html
<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:

```html
<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:

```html
<!-- 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>
```

![Webflow embed example](https://user-images.githubusercontent.com/2528817/231847323-53430bca-f2fd-4d2c-b7ee-90948fb694b5.png)

---

### 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:

```html
<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:

```html
<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>
```

![Auth embed attributes](https://user-images.githubusercontent.com/2528817/231847542-aa13eb07-2d7f-400b-bec5-3983ef3ac559.png)

![FeatureFeed embed attributes](https://user-images.githubusercontent.com/2528817/231847773-9698dc62-3ca8-4814-ad33-63204fb5f625.png)

---

### 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`](https://github.com/ApollosProject/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](https://github.com/ApollosProject/apollos-admin/blob/dc2bb76699dcef8a6cdc67922f63c0b9eb08e594/packages/canvas-ui-web). 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](https://github.com/ApollosProject/apollos-admin/blob/dc2bb76699dcef8a6cdc67922f63c0b9eb08e594/apps/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:

```html
<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](src/client/apollosApiLink.js)

```javascript
'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.

```bash
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:

```html
<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.
