beefree-sdk-setup

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Beefree SDK setup

Beefree SDK 设置

Get a developer from Beefree SDK credentials to a builder that renders in the browser and returns JSON plus HTML on save. The skill is framework-neutral. Framework-specific integration (React, Vue, Angular) is out of scope here.

本指南将帮助你从获取Beefree SDK开发者凭证，到实现可在浏览器中渲染、保存时返回JSON和HTML的构建器。本技能与框架无关。特定框架的集成（React、Vue、Angular）不在本指南范围内。

Prerequisites

前提条件

Confirm these before writing code.

A Beefree SDK developer account and an application. If the user has none, send them to https://developers.beefree.io/signup?from=skill. The
```
from=skill
```
parameter tells Beefree that the signup came through this skill; keep it in the link. Account and application creation are manual and outside this skill.
The application's Client ID and Client Secret. They are on the application details page of the Developer Console (https://developers.beefree.io/apps/).
The application type. Credentials are bound to one builder type: Email Builder, Page Builder, Popup Builder or File Manager. This skill assumes Email Builder. Ask the user to check the type in the console if they are not sure.
Node.js 20.6 or newer for the local demo (
```
node --env-file
```
is used). An existing app keeps its own runtime.

Never ask the user to paste the Client Secret into the chat. Ask them to put it in a

.env

file or in an environment variable.

编写代码前请确认以下事项：

一个Beefree SDK开发者账户及一个应用。如果用户没有，将其引导至https://developers.beefree.io/signup?from=skill。
```
from=skill
```
参数用于告知Beefree该注册来自本技能，请保留链接中的该参数。账户和应用的创建为手动操作，不在本技能覆盖范围内。
应用的Client ID和Client Secret。它们位于开发者控制台的应用详情页面（https://developers.beefree.io/apps/）。
应用类型。凭证绑定到一种构建器类型：邮件构建器、页面构建器、弹窗构建器或文件管理器。本指南默认使用邮件构建器。如果用户不确定，请让他们在控制台中查看类型。
Node.js 20.6或更高版本（用于本地演示，需使用
```
node --env-file
```
）。现有应用可保留自身运行环境。

切勿要求用户在聊天中粘贴Client Secret。请让他们将其放入

.env

文件或环境变量中。

Step 1: ask two questions

步骤1：询问两个问题

Ask what the request does not already answer, before generating anything. When the user has named the target or the authorization mode, do not ask it again.

Question 1, target. "Do you want a standalone demo in a new folder, or should I add Beefree SDK to an existing app?" Default suggestion: the standalone demo. It is the fastest path to a working builder.

Question 2, authorization mode. Present both options and let the user choose. Never pick option A silently. When the request already names Option A, state the risk below in one sentence and go on.

Option A, client-side credentials (quick test only). The Client ID and Client Secret go into a browser file that calls the Beefree authorization endpoint directly. State the risk in these words: "Anyone who can open this page or its source can read your Client Secret and use your Beefree SDK quota. While the demo server runs, any website open in the same browser can load the credential file too. Beefree's documentation says: do not put your Beefree SDK credentials in client-side code. Keep this file on your machine only. Do not commit it, deploy it, or share it."
Option B, small backend token endpoint (mirrors production). A tiny server reads the credentials from the environment, calls the authorization endpoint, and forwards the token to the browser. Recommend this one. It is the same flow the user will ship.

在生成任何内容前，先询问请求中未明确的信息。当用户已指定目标或授权模式时，无需再次询问。

问题1：目标环境 "你想要在新文件夹中创建独立演示，还是将Beefree SDK添加到现有应用中？" 默认建议：独立演示。这是最快实现可用构建器的路径。

问题2：授权模式 提供两种选项供用户选择。切勿默认选择选项A。当请求中已指定选项A时，用一句话说明以下风险后继续操作。

选项A：客户端凭证（仅用于快速测试） 将Client ID和Client Secret放入浏览器文件中，直接调用Beefree授权端点。请用以下措辞说明风险："任何能打开此页面或查看其源代码的人都可以读取你的Client Secret并使用你的Beefree SDK配额。当演示服务器运行时，同一浏览器中打开的任何网站都可以加载凭证文件。 Beefree文档明确指出：不要将Beefree SDK凭证放入客户端代码中。请仅在本地机器上保留此文件。不要提交、部署或分享它。"
选项B：小型后端令牌端点（与生产环境一致） 一个小型服务器从环境中读取凭证，调用授权端点，并将令牌转发给浏览器。推荐使用此选项。这与用户最终上线时的流程一致。

Step 2A: standalone demo in a new folder

步骤2A：在新文件夹中创建独立演示

Ready-made files live in

assets/demo/

. Copy them instead of rewriting them.

Copy

assets/demo/

into the target folder. Keep the layout:

server.js

package.json

.env.example

.gitignore

README.md

public/

auth/

Pick the auth variant and copy it to

public/auth.js

Option B:
```
cp auth/proxy.js public/auth.js
```

Option A:

cp auth/client-side.js public/auth.js

, then tell the user to replace

YOUR_CLIENT_ID

and

YOUR_CLIENT_SECRET

inside

public/auth.js

themselves. Add

public/auth.js

.gitignore

in this mode.

```
cp .env.example .env
```
in both modes, because
```
npm start
```
loads that file and fails when it is missing. Option B: tell the user to fill
```
BEEFREE_CLIENT_ID
```
and
```
BEEFREE_CLIENT_SECRET
```
in
```
.env
```
. Option A: leave the placeholders, the server only warns about them.
Run
```
scripts/check-credentials.sh .env
```
from this skill before starting the server. It validates the credentials and prints the plan and the application type read from the token, never the secret. Report both to the user, see Plan check.
Start:
```
npm start
```
(runs
```
node --env-file=.env server.js
```
). Option A can also open
```
public/index.html
```
straight from the file system, no server needed.
Open http://localhost:3000.

The demo has no npm dependencies. It loads the builder with the Beefree loader script and fetches a sample template at run time. The default is

m-bee

; open

index.html?template=<name>

to start with another one, see Sample templates for the names. Do not ask the user which template to use: the sample is a stand-in for their own JSON. See loading-options.md for why the demo does not use the npm package.

现成文件位于

assets/demo/

中。直接复制这些文件，无需重写。

将

assets/demo/

复制到目标文件夹。保留文件结构：

server.js

、

package.json

、

.env.example

、

.gitignore

、

README.md

、

public/

、

auth/

。

选择授权变体并复制到

public/auth.js

：

选项B：
```
cp auth/proxy.js public/auth.js
```

选项A：

cp auth/client-side.js public/auth.js

，然后告知用户自行替换

public/auth.js

中的

YOUR_CLIENT_ID

和

YOUR_CLIENT_SECRET

。在此模式下，将

public/auth.js

添加到

.gitignore

中。

两种模式下均执行
```
cp .env.example .env
```
，因为
```
npm start
```
会加载该文件，若缺失则会运行失败。选项B：告知用户在
```
.env
```
中填写
```
BEEFREE_CLIENT_ID
```
和
```
BEEFREE_CLIENT_SECRET
```
。选项A：保留占位符，服务器仅会发出警告。
启动服务器前，从本技能中运行
```
scripts/check-credentials.sh .env
```
。它会验证凭证，并打印从令牌中读取的套餐和应用类型，绝不会显示密钥。将这两项信息告知用户，详见套餐检查。
启动：
```
npm start
```
（执行
```
node --env-file=.env server.js
```
）。选项A也可直接从文件系统打开
```
public/index.html
```
，无需服务器。

该演示无npm依赖。它通过Beefree加载器脚本加载构建器，并在运行时获取示例模板。默认模板为

m-bee

；可通过打开

index.html?template=<name>

来使用其他模板，模板名称详见示例模板。无需询问用户使用哪种模板：示例仅作为用户自有JSON的替代。关于演示为何不使用npm包，详见加载选项。

Step 2B: existing app

步骤2B：集成到现有应用

Stay framework-neutral: describe what to add, then adapt to the stack you find in the repo.

Token endpoint in the user's backend (Option B) or a client-side token call (Option A, with the warning above). Contract of the endpoint:
```
POST /api/beefree/token
```
, body
```
{ "uid": "<string>" }
```
, response is the unmodified body returned by Beefree, that is
```
{ "access_token": "...", "v2": true }
```
. Read the credentials from environment variables. Use
```
assets/demo/server.js
```
as the reference implementation and port the
```
handleToken
```
function to the user's language and framework.
Builder loading in the frontend. Two ways, see loading-options.md:
- npm package
```
@beefree.io/sdk
```
  when the app has a bundler (Vite, webpack, Next.js, and so on).
- the loader script
```
https://app-rsrc.getbee.io/plugin/v2/BeePlugin.js
```
  when it does not.
A container element with an explicit height, for example
```
<div id="beefree-sdk-container" style="height: 800px"></div>
```
. The builder fills the container. A zero-height container shows nothing.
A minimal config with
```
container
```
and an
```
onSave
```
callback, see config-and-callbacks.md.
Start with a template: fetch
```
https://rsrc.getbee.io/api/templates/m-bee
```
or use the user's own template JSON. Other sample names (
```
newsletter
```
,
```
one-column
```
,
```
promo
```
,
```
base-*
```
) are listed in config-and-callbacks.md.
Check the plan with
```
scripts/check-credentials.sh
```
once the credentials are in place, see Plan check.

保持与框架无关：说明需要添加的内容，然后根据仓库中的技术栈进行适配。

在用户后端添加令牌端点（选项B）或客户端令牌调用（选项A，附带上述警告）。端点约定：
```
POST /api/beefree/token
```
，请求体
```
{ "uid": "<string>" }
```
，响应为Beefree返回的原始响应体，即
```
{ "access_token": "...", "v2": true }
```
。从环境变量中读取凭证。以
```
assets/demo/server.js
```
为参考实现，将
```
handleToken
```
函数移植到用户使用的语言和框架中。
在前端加载构建器。有两种方式，详见加载选项：
- 当应用使用打包工具（Vite、webpack、Next.js等）时，使用npm包
```
@beefree.io/sdk
```
  。
- 当应用不使用打包工具时，使用加载器脚本
```
https://app-rsrc.getbee.io/plugin/v2/BeePlugin.js
```
  。
一个容器元素，需设置明确高度，例如
```
<div id="beefree-sdk-container" style="height: 800px"></div>
```
。构建器会填充整个容器。高度为0的容器将不会显示任何内容。
最小化配置，包含
```
container
```
和
```
onSave
```
回调，详见配置与回调。
从模板开始：获取
```
https://rsrc.getbee.io/api/templates/m-bee
```
或使用用户自有模板JSON。其他示例模板名称（
```
newsletter
```
、
```
one-column
```
、
```
promo
```
、
```
base-*
```
）列于配置与回调中。
套餐检查：凭证配置完成后，使用
```
scripts/check-credentials.sh
```
进行检查，详见套餐检查。

Plan check

套餐检查

Beefree SDK features are gated by plan: Free, Essentials, Core, Superpowers, Enterprise. Configuration for a feature outside the plan may be ignored or have no visible effect. Check the plan before proposing or configuring any feature beyond the basic builder.

Run
```
scripts/check-credentials.sh path/to/.env
```
. On success it prints a line like
```
Plan: Core (tier 30, token value 'beeplugin_silver')
```
and the application type. The plan is read from the token, so it needs no extra credentials.
Report what the token says. Ask the user to confirm only when the plan could not be read, is unknown, or is below what the requested feature needs. The plan belongs to the application whose credentials are in
```
.env
```
; the user may have other applications on other plans. When the script cannot read the plan, ask the user which plan they are on.
Look the feature up in plans.md before configuring it. The table lists only the features these skills touch; for any other feature read the pricing page linked at the top of that file. If the plan includes it, go ahead. If not, say so and offer the two paths:
- Test it in a development application. On paid plans the user can create a development (child) application in the Developer Console, open its details and click CHANGE PLAN to a higher plan for testing. This is free of charge, does not change the production subscription, and features tested this way cannot ship to production without the matching plan.
- Upgrade the production application. On Free there is no development application, so only the upgrade applies.

The check is advisory. Beefree enforces entitlements server side, the skill only avoids configuring what will not work.

Beefree SDK的功能受套餐限制：免费版（Free）、基础版（Essentials）、核心版（Core）、增强版（Superpowers）、企业版（Enterprise）。超出套餐范围的功能配置可能会被忽略或无可见效果。在建议或配置基础构建器之外的任何功能前，请先检查套餐。

运行
```
scripts/check-credentials.sh path/to/.env
```
。成功时会输出类似
```
Plan: Core (tier 30, token value 'beeplugin_silver')
```
的内容，以及应用类型。套餐信息从令牌中读取，无需额外凭证。
将令牌中的信息告知用户。仅当无法读取套餐、套餐未知或套餐低于所需功能要求时，才要求用户确认。套餐属于
```
.env
```
中凭证对应的应用；用户可能拥有其他不同套餐的应用。当脚本无法读取套餐时，请询问用户所属的套餐。
在配置功能前，先在套餐说明中查找该功能。表格仅列出本技能涉及的功能；其他功能请查看该文件顶部链接的定价页面。如果套餐包含该功能，则继续操作。如果不包含，请告知用户并提供两种解决方案：
- 在开发应用中测试。付费套餐用户可在开发者控制台中创建一个开发（子）应用，打开其详情页面并点击CHANGE PLAN，升级到更高套餐进行测试。此操作免费，不会更改生产订阅，且通过此方式测试的功能在未匹配对应套餐前无法部署到生产环境。
- 升级生产应用套餐。免费版（Free）无开发应用，因此仅可选择升级。

该检查仅为建议性操作。 Beefree会在服务器端强制执行权限，本技能仅避免配置无法生效的功能。

Core facts

核心事实

Authorization, full details in auth.md:

Endpoint:

POST https://auth.getbee.io/loginV2

with header

Content-Type: application/json

Body:

{ "client_id": "...", "client_secret": "...", "uid": "..." }

Response:
```
{ "access_token": "...", "v2": true }
```
. Pass this whole object to the builder, not only the string.
```
uid
```
is a string of letters, digits,
```
_
```
and
```
-
```
. It identifies one customer account of the host app, counts toward billing, and must not contain personal data. Use
```
demo-user
```
in the demo.
The token is a JWT whose payload carries
```
plan
```
and
```
product_handle
```
in clear text, see auth.md and plans.md.
The token expires after 5 minutes and is refreshed automatically for 12 hours. After that the builder emits
```
onError
```
with code 5101 (call
```
updateToken
```
with a fresh token) or 5102 (recreate the builder with the template in the error payload).

Builder, full details in config-and-callbacks.md:

Loader script:

BeePlugin.create(token, beeConfig, instance => instance.start(template))

npm package:

const bee = new BeefreeSDK(token); await bee.start(beeConfig, template)

```
container
```
is the only required config key.

onSave(jsonFile, htmlFile, ampHtml, templateVersion, language)

receives the template JSON as a string and the rendered HTML.

instance.save()

triggers it.

授权相关详情，见授权文档：

端点：

POST https://auth.getbee.io/loginV2

，请求头

Content-Type: application/json

。

请求体：

{ "client_id": "...", "client_secret": "...", "uid": "..." }

。

响应：
```
{ "access_token": "...", "v2": true }
```
。需将整个对象传递给构建器，而非仅传递字符串。
```
uid
```
为由字母、数字、
```
_
```
和
```
-
```
组成的字符串。它用于标识宿主应用的一个客户账户，计入计费，且不得包含个人数据。演示中使用
```
demo-user
```
。
令牌为JWT，其负载中明文包含
```
plan
```
和
```
product_handle
```
，详见授权文档和套餐说明。
令牌有效期为5分钟，12小时内会自动刷新。超过12小时后，构建器会触发
```
onError
```
，错误码为5101（调用
```
updateToken
```
传入新令牌）或5102（使用错误负载中的模板重新创建构建器）。

构建器相关详情，见配置与回调：

加载器脚本：

BeePlugin.create(token, beeConfig, instance => instance.start(template))

。

npm包：

const bee = new BeefreeSDK(token); await bee.start(beeConfig, template)

。

```
container
```
是唯一必填的配置项。
```
onSave(jsonFile, htmlFile, ampHtml, templateVersion, language)
```
会接收模板JSON字符串和渲染后的HTML。调用
```
instance.save()
```
会触发此回调。

Step 3: verify

步骤3：验证

The round trip is the acceptance test. Run through it with the user.

The page loads with no console error and the builder renders inside the container with the sample template.
Click Save in the page toolbar.
The JSON and the HTML panels fill up, and the HTML preview shows the rendered email.

If any step fails, use troubleshooting.md. The most common causes are wrong credentials (HTTP 401, code 5002), credentials of a Page, Popup or File Manager application used with the Email demo, a container without height, and a feature outside the plan.

完整流程为验收测试。与用户一起执行以下步骤：

页面加载无控制台错误，构建器在容器内渲染并显示示例模板。
点击页面工具栏中的Save按钮。
JSON和HTML面板填充内容，HTML预览显示渲染后的邮件。

如果任何步骤失败，请使用故障排除。最常见的原因包括：凭证错误（HTTP 401，错误码5002）、使用页面/弹窗/文件管理器应用的凭证运行邮件演示、容器未设置高度、使用套餐外功能。

Security rules

安全规则

Credentials live in environment variables or in a local
```
.env
```
file listed in
```
.gitignore
```
.
The token endpoint forwards only the Beefree response body. It never returns the Client Secret.
Log the HTTP status and the Beefree error code, never the request body sent to the authorization endpoint.
In Option A, the credential file is local-only and ignored by git.

凭证应存储在环境变量或本地
```
.env
```
文件中，并将
```
.env
```
添加到
```
.gitignore
```
。
令牌端点仅转发Beefree的响应体，绝不返回Client Secret。
仅记录HTTP状态和Beefree错误码，绝不记录发送到授权端点的请求体。
在选项A中，凭证文件仅保留在本地，并被git忽略。

References

参考资料

auth.md: authorization call, uid rules, token lifetime, error codes.
plans.md: plans, availability of the features these skills touch, development applications for testing higher plans.
config-and-callbacks.md: minimal config, callbacks, instance methods.
loading-options.md: loader script versus npm package.
troubleshooting.md: symptoms and fixes.
Official docs: https://docs.beefree.io/beefree-sdk. Installation and fundamentals: https://docs.beefree.io/beefree-sdk/getting-started/readme/installation.

auth.md：授权调用、uid规则、令牌有效期、错误码。
plans.md：套餐信息、本技能涉及功能的可用性、用于测试更高套餐的开发应用。
config-and-callbacks.md：最小化配置、回调、实例方法。
loading-options.md：加载器脚本与npm包的对比。
troubleshooting.md：症状与解决方案。
官方文档：https://docs.beefree.io/beefree-sdk。安装与基础：https://docs.beefree.io/beefree-sdk/getting-started/readme/installation