# @apollosproject/web-embeds 中文文档

规范地址：https://npmcn.com/package/%40apollosproject/web-embeds/

版本：0\.1\.2050
npm 元数据更新时间：2026-11-07T05:54:47.586Z
中文译文更新时间：2026-11-06T11:01:21.473Z
软件包许可：MIT

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40apollosproject/web-embeds
原文对照：https://npmcn.com/package/%40apollosproject/web-embeds/?lang=original
项目主页：https://github.com/ApollosProject/apollos-admin#readme
源码仓库：https://github.com/ApollosProject/apollos-admin

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：224 kB，3 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：3 个
- 首次发布：2026-01-30T18:56:45.397Z
- 最新版本发布：2026-11-07T05:54:47.421Z
- 近 30 天下载量：67627（2026-10-07 至 2026-11-05，npm 官方下载统计）
- 已发布版本数：2050（近 12 个月 2050 个）

## 中文简介

阿波罗斯下一代可嵌入部件系统

## 安装

```sh
npm install @apollosproject/web-embeds
```

也可以使用：`pnpm add @apollosproject/web-embeds`、`yarn add @apollosproject/web-embeds`、`bun add @apollosproject/web-embeds`

## README

# 阿波罗网络嵌入 v2

下一代可嵌入的阿波罗系统,使教会能够立即为他们的会众提供对教堂资源的访问,AI动力搜索,以及直接从他们的网站上进行的关键动作.

## 快速启动

### 安装

关闭前添加以下脚本标签 `</body>` 标签 :

```html
<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://cdn.jsdelivr.net/npm/@apollosproject/web-embeds@latest/widget/embed.js"
  );

  apollos("init", {
    slug: "your-church-slug",
  });
</script>
```

### 链接截取( 初始使用大小写)

使用嵌入式最简单的方法是通过自动链接截取. 您网站上任何指向您教会的阿波罗URL的链接都会在嵌入地自动打开:

```html
<a href="https://apollos.com/your-church/give">Give Now</a>
<a href="https://apollos.com/your-church/events">View Events</a>
```

### 移民调查`personOriginId`(中文(简体) )

`personOriginId` (可选):访客的CMS人物代号(如: Rock RMS) `${CurrentPerson.Id}`) (中文(简体) ). 启用任何页面上的预登录迁移检测 运行嵌入层:隐藏 `/{slug}/_embed` 探测器 iframe 检查服务器侧 游客是否有经常迁徙的天赋,在一次袭击中,显示 开通了迁移流的上层烤面包 当访客没有时就不要 阿波罗会话与否 `personOriginId` 通过.

```js
// Before
apollos("init", { slug: "your-church-slug" });

// After (with migration detection — Rock RMS example)
apollos("init", {
  slug: "your-church-slug",
  personOriginId: "${CurrentPerson.Id}",
});
```

如果身份不明的话 `init` 时间,嵌入层还读到 `personoriginid` 从内线属性给以iframe, 每次主机页面设置时都会捡取 它(例如一旦Rock/GTM解决了访客)—— `init` 配置值需要 两者同时存在时优先.

## 发展

```bash
# Install dependencies
npm install

# Start dev server (runs inject-config first, then Vite)
npm run dev

# Build for production
npm run build
```

### 十字路口测试页

这个 `public/crossroads-test/` 目录包含一个演示赠出页面。 嵌入基座 URL,教堂 sult, 和嵌入脚本 URL 通过 Env vars 可配置并注入到 `*.template.html` 文件 :

-   **本地 dev :** 创建 `.env` 内 `apps/web-embeds-v2/` (见 `.env.example`) (中文(简体) ). 运行 `npm run inject-config` 或者说 `npm run dev` 生成 `index.html` 编号 : `giving-history.html` 从模板。 生成的 `*.html` 文档被表示出——只有 `*.template.html` 消息来源已承诺.

## 演示网站(托管)

演示页 `public/` 通过 **维塞尔**,这也为每一个触及此应用程序的拉出请求创建了预览部署.

-   **部署什么:** 全文 `public/` 文件夹( 这样添加的文件会被自动取出) 外加新文件夹 `dist/embed.js` 由该分支所建——所以PR预览反映了变化的实际嵌入行为. 这个 `crossroads-test` 模板在构建时注入.
-   **构建 :** `yarn build:site` 运行 `inject-embed-config.js` → `vite build` → `scripts/build-demo-site.mjs`,它组装 `site/` 输出目录( 模仿 dev- server 版式 : `public/` 网络根的文件,部件在 `/dist/embed.js`) (中文(简体) ). `site/` 被点燃了.
-   **页: 1** `/` 菜单( e)`public/index.html`)链接到每个演示- `/demo.html` (嵌入式操场), `/crossroads-test/` (给予), `/crossroads-test/giving-history.html` (经常赠与 ) 当您向菜单添加新主机页面时添加链接 `public/`。 。 。 .

**一次性Vercel项目设置** (磁盘,按 [Vercel 单行道克](https://vercel.com/docs/monorepos):

1.  **新项目** □ 导入此还原□ set **根目录** 改为 `apps/web-embeds-v2`。 。 。 .
2.  框架预设 : **其它** (建造/安装/产出来自 `vercel.json`) (中文(简体) ).
3.  添加 **环境变量** (制作+预览):
    -   `APOLLOS_EMBED_BASE_URL`:网络应用程序来源于嵌入点(例如. `https://apollos.com`) (中文(简体) ). `apollos.app` 重写为 `apollos.com` 在注入时间,因为主机重定向,并会打破高握手.
    -   `APOLLOS_EMBED_CHURCH_SLUG` ——示范教堂弹道(如:. `apollos-demo`(中文(简体) )
    -   `APOLLOS_EMBED_SCRIPT_URL` - 离开作为 `/dist/embed.js` 来使用此部署上构建的捆绑,或者设置一个 CDN URL 来固定一个已发布的版本.
4.  在设置 ~ Git 下, 启用 **"只有在"根目录"有变化时才能建设"** 所以不相关的承诺 不要重新部署.

生产 `main` 分支)是持久的 URL;每个 PR 都会得到自己的预览 URL 对 PR 的评论.

> 说明: `demo.html` 编号 : `search-demo.html` 在主机站点上 它们只会完全针对同一来源的后端 这个 `crossroads-test` 页面是完全配置的展示(后端通过上方的env vars接线).

## 出版

此应用程序发布到 npm 软件包 **`@apollosproject/web-embeds`** (从 `@apollosproject/canvas-embeds`) (中文(简体) ).

**CDN URL : (中文(简体) )**  
`https://cdn.jsdelivr.net/npm/@apollosproject/web-embeds@latest/widget/embed.js`

### 自动部署

继续前进 `main`, GitHub 工作流程同步 npm( 如果有的话) 发布的版本, 缓冲该版本( 默认 patch) , 运行 `npm publish` (会触发) `prepublishOnly` ),并清理 jsDelivr 缓存 `@apollosproject/web-embeds`。 。 。 .

### 手动部署

从还原根( 后) `yarn` 安装 :

1.  `cd apps/web-embeds-v2`
2.  可选同步到最后一个已发布的版本 : `yarn version --immediate "$(npm show @apollosproject/web-embeds version)"`
3.  弹出版本 : `yarn bump` (patch 默认,或 `yarn bump:prerelease` (预释)
4.  发布 : `npm publish` (运行) `prepublishOnly` 建立和核实)
5.  清洗 jsDelivr 缓存 : `yarn flush`

跳过发布步骤意味着用户仍然会得到上一个版本;跳过冲出步骤会延迟传播直到jsDelivr的缓存过期.

## 文档

见全 [产品要求文件](https://npmcn.com/package/docs/PRD-web-embeds-v2.md) 详细规格.

## 许可证

麻省理工学院

## 常见问题

### @apollosproject/web-embeds 是什么？

阿波罗斯下一代可嵌入部件系统

### 如何安装 @apollosproject/web-embeds？

在项目目录运行 npm install @apollosproject/web-embeds，或使用 pnpm add / yarn add / bun add。

### @apollosproject/web-embeds 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @apollosproject/web-embeds 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @apollosproject/web-embeds 可以商用吗？

@apollosproject/web-embeds 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @apollosproject/web-embeds 的下载量有多少？

根据 npm 官方下载统计，@apollosproject/web-embeds 在 2026/10/07 – 2026/11/05 这 30 天内被下载 67,627 次，日均约 2,254 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @apollosproject/web-embeds 还在维护吗？

最新版本 0\.1\.2050 发布于 2026/11/07（今天）；至今共发布 2050 个版本，其中过去 12 个月发布了 2050 个；首次发布于 2026/01/31。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。