Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Welcome to the Beefree SDK technical documentation for developers!
Welcome to the Beefree SDK technical documentation!
We’re thrilled that you’re interested in integrating our embeddable builders into your software. Beefree SDK is a versatile content creation platform that includes three distinct visual content builders, a file management UI, and a series of APIs that help you create engaging, delightful, productive content creation experiences for your customers.
The builders include an Email Builder, a Page Builder, and a Popup Builder. Each of these builders is designed to meet specific content creation needs, allowing you to offer a tailored content creation experience to your customers. They can be easily integrated into your application in a matter of minutes.
In addition to our drag-and-drop editors, we also offer a standalone File Manager application, which can be used alongside any of the builders. The File Manager is specifically designed to simplify the organization and management of digital assets, which might happen outside of a content editing session.
Finally, the Content Services API allows you to perform a number of tasks (e.g. refreshing the HTML for a certain asset) and add features to your application (e.g. converting an email to a PDF document). We continue to release new API methods to help you enrich and personalize the content design experience for your customers.
An email editor that makes building gorgeous, mobile-ready emails a breeze.
A delightful tool to design beautiful, effective landing pages in minutes, without writing a single line of code.
An easy to deploy, true WYSIWYG solution for designing standout popups.
An image and document management UI that can be launched as a standalone application, in order to allow your customers to quickly upload or manage assets, without having to load one of the builders.
These products share the same, unique combination of design flexibility and ease of use. Please note that all of the documentation in this site applies to all builders (and in many cases to the File Manger too), unless otherwise specified.
As you will gradually discover, Beefree SDK also offers great liberty in how you can integrate it with your application, and we are here to support you along the way.
Let’s get started!
Beefree SDK used to be called BEE Plugin. We changed the name to separate our embeddable applications (content builders, file manager, ...) from the rest of our developer tools (APIs, sample code, etc.). You might still see the word "plugin" used at times in the documentation and sample code: if you do, know that it refers to an embeddable application, not the entire set of Beefree developer tools.
Learn how to manage users within the Beefree SDK Developer Console.
You can invite additional users to your Beefree SDK Console. To do so, go to Manage users from the personal menu in the top right.
The user that initially created the account is identified as the account owner and can add users from this page.
Additional users will be identified as admins. The owner may limit access to certain production apps when creating or editing an admin.
The account owner has these additional privileges, compared to admins:
add, edit or delete users, as described above;
change the company’s name, also in Settings & Security.
Learn about the different environments available through Beefree SDK and how to get started to with each.
Development applications are available with any Beefree SDK paid plan.
A development application is a child application that is linked to your parent application within the Beefree SDK console. The purpose of these child applications is to create development, QA, or any other type of applications that you can merge your application’s changes to prior to pushing them to production. This empowers you to test new features, even on a higher plan, within a controlled environment prior to releasing them to your application’s end users.
You can create a development application within your Beefree SDK console. Prior to creating a development application, ensure you have a paid plan with Beefree SDK. This will make the functionality accessible to you.
To create a development application, take the following steps:
Create a new application
Note: This creates a production environment for your application.
Navigate to your dashboard where the new application is located
Click the + next to Add a development instance
Type in the name of your development application, for example “development environment” or “QA environment”
Click Create
View the new development application available in your Beefree SDK dashboard
There are multiple benefits to utilizing development applications. A few of these benefits are the following:
Merge and test changes to your application prior to releasing them to your end users
Create an environment for different contributors in your development cycle, for example QA Engineers, frontend developers, backend developers, and so on
Access next tier Beefree SDK features in your development applications without any additional costs
Create as many child development applications linked to your parent production environment as you’d like
While access to next tier Beefree SDK features in your development applications is available to you, it is important to remember that you cannot push any next tier features in your development application to your production environment. Your production environment should only include the features reflected in your current plan subscription. If you find that you would like to push a next tier feature from your development application to your production application, you need to upgrade to the subscription plan that corresponds to those features.
Beefree SDK allows you to access next tier features within your development application to test them out and see if they are a good fit for your application’s needs. However, it is important to consider that if you plan to push those features to your production environment, that you have the right subscription and permissions to do so.
Development apps inherit the same plan that your production app is on. If you wish to test features that are available on a higher plan, go the application details and click “CHANGE PLAN” in the upper right.
turn on , using tokens provided by mobile apps like Google Authenticator or Authy. 2FA can be enabled either for specific users, or account-wide from the Settings & Security section in the personal area ();
Log in to your
This feature is visible to Beefree SDK account Owners.
We understand that each company has its own unique needs. For that reason, we offer the flexibility of adding multiple Beefree SDK subscriptions within the Developer Console. Through this option, you can take advantage of multiple subscriptions to our product for your teams, business units, and so on.
You can create an additional subscription within the Beefree SDK Developer Console.
To achieve this, take the following steps:
Log in to the Beefree SDK Developer Console
Navigate to your dashboard
Click Add new subscription on the upper right-hand side of the screen
Type a name for your next subscription and click Next
Choose a plan and click Select plan
Confirm the plan you selected
Finalize your additional subscription
Get started with installing the Beefree SDK within your web application.
Congratulations on registering your first application! Now it’s time to install it. The first step is to add the Beefree SDK library to your application. You can use plain HTML or our convenient NPM module.
The embedded application (email builder, page builder, popup builder, file manager) will load into any HTML element on your page.
We recommend starting with an empty div, as follows:
Beefree cares about your security. This is why we use a standard JSON Web Token, or JWT, to authenticate your application.
To authenticate your application, pass your Client ID and Client Secret to our authorization service, and we’ll send your unique token back to you.
We talk about this step in detail here, but here’s a quick example using jQuery:
Now that you have a token, you can initialize the application into your empty div.
To do so, you will call the create
method, which has three parameters:
token
This is the result of the previous step.
config
This contains your settings and event handlers.
callback
This is a function that receives the application instance
Here is an example in plain JavaScript:
The following table shows all of the required configuration settings:
The final step is to start the application, using the start
method.
If the application is one of the builders, do so by loading a template.
If the application is the File Manager, no parameters are needed.
Call the start
method as follows:
The instance method bee.start(template)
does not need to be called immediately after create
. In a SPA (Single Page Application) or React app, you can create
the editor in a hidden global state but then call the start
method when the template is selected and available.
The application loads quickly when all steps are completed consecutively. However, by separating the loading workflow into two parts, the end-user will perceive loading in a fraction of the overall time.
Remember, if the client_id
belongs to a File Manager application, bee.start()
can be called without any parameters.
Learn how to create an application within the Beefree SDK Developer Console.
Create applications (e.g. an email builder and a landing page builder).
Create development apps for all sorts of dev, QA, or staging environments.
Configure them with both server-side and client-side configurations.
Whenever you create a new application, we will ask you to provide some general information so that they are easily recognizable for you in the Console. This only takes a few moments.
For each application, we will also provide you with a Client ID and Client secret, which you will use for authentication when you initialize it.
Attribute | Type | Description |
---|---|---|
The first step to embedding Beefree’s visual builders in your software is to. Once that’s done, you will be able to . That’s where you will:
Go ahead and create your first application in the .
uid
string
An alphanumeric string that identifies the user and allows the embedded application to load resources for that user (e.g. images).
Min length: 3 characters
Can contain letters from a to z (uppercase or lowercase), numbers and the special characters _ (underscore) and – (dash)
It is a string and not a numeric value
It uniquely identifies a user of the Beefree application. When we say “uniquely”, we mean that:
It will be counted as a unique user for monthly billing purposes.
Images (and other files) used by the user when creating and editing messages will be associated with it and not visible to other users (when using the default storage).
container
string
Identifies the id of div element that contains the application
When you load a Beefree application inside the host application, you pass a configuration object with multiple sections that define the characteristics of the UI, UX, and available elements. However, there are cases when you may want to reload this configuration without the need to reload the Beefree application. In these cases, you can use a specific event to update the configuration while the editor is open.
With this event, you can make on-the-fly changes to the user experience. For example:
Updating available categories for Saved rows
Refreshing a Custom header for authorization
Changing Advanced permissions for the current user
Updating settings for the editor’s Content defaults
You can load the configuration changes via a new instance event. Here’s an example:
Note: If initializing a File Manager application, the only supported method is beePluginInstance.start()
without parameters.
Assuming that beePluginInstance
is the instance of your embedded builder application, here are the methods you can call:
If you use a paid plan, you can hide the top toolbar and control the builder from your application’s user interface. For example, it’s up to you at that point to have buttons above or below the builder. Here’s some useful methods for this scenario:
The top toolbar displayed by default within the builder contains buttons that trigger certain actions. These are the callbacks that are triggered when the buttons are clicked.
In user interfaces, a workspace is a parameter that changes the appearance, settings, and widgets available in an builder, to help the user to focus on what matters.
In Beefree SDK, workspaces are an optional parameter that can be used to provide an experience focused on context and purpose, and to facilitate the outcome of an editing session.
You can load the builder with a certain workspace, but workspaces can also be changed by the user when editing, on-the-fly.
Switching between workspaces might change:
content visibility on the stage
tiles availability in the content tab
available previews
outputs when saving a content
…and more!
If no workspace is loaded at launch, the builder starts in its “Default” workspace.
We currently offer 3 additional workspaces, and we are planning to launch more as we evolve BEE and its capabilities.
These 3 workspaces revolve around the use of AMP content, and are provided so that you can tailor the experience of creating AMP emails in Beefree SDK.
Here is an overview of the different workspaces and their differences. Please refer to this page for more information on using AMP in Beefree SDK.
Here is an example of loading Beefree SDK with a “mixed” workspace:
You can implement a workspace selector within your application, so that users can switch between workspaces, by using the loadWorkspace(type)
method.
First, you need to define template files for the workspaces you want to propose, as JSONs:
Then, you can load those workspaces at runtime:
And here is how to create a simple select to switch workspace:
After you load a workspace, the application will trigger one of these three callbacks:
The additional workspaces for AMP (AMP-only and HTML-only) can become helpful if you want to tailor the user experience of creating AMP emails, by adding:
a workflow where users decides if they want to create a standard message or an AMP-powered message (in the first case, AMP components will be hidden in the builder;
an option to switch between the HTML and the AMP editing of a message.
In addition, omitting the workspace, or loading the “default” workspace for certain users, has the effect of disabling AMP for those users, even when AMP content is enabled in the Beefree SDK Console. This way, you can decide to make the feature available to customers of your application:
depending on the subscription plan that they are on (i.e. you could push users to a higher plan based on the ability to use AMP);
depending on the purchase of an optional feature (same);
only if they are “beta” customers, so they see it while keeping it hidden from the rest of your users.
Discover the configuration parameters within Beefree SDK.
Once you have initialized your Beefree application, you can pass a series of configuration parameters to it.
The following code displays an example of a default configuration:
The following table provides a description of the parameters.
The following table provides descriptions of the events and methods:
Beefree SDK Authorization v2 is nearly the same as v1, with an improved endpoint and an extra security layer. We moved the uid from the client-side to the server-side. Additionally, the automatic token refreshing expires, but the host app can “keep alive” the token for 12 hours, as long as the user is active.
Currently, Beefree SDK requires the host application to pass a uid parameter.
In Auth v2, the host app will remove the uid from the client-side configuration and pass it during the server-side login request.
The Beefree SDK system uses OAuth2 as the authorization framework.
We strongly suggest not to put your Beefree SDK credentials in client-side code - they are specific to your account and could be easily read and used by other people.
The Beefree SDK authorization service will return a temporary access token if the authentication is successful. The client application can use the full response that contains the token to start or refresh a Beefree SDK session.
The token you receive from the authorization server should be passed to the BeePlugin.create(...) as it is. We strongly suggest not altering it in any way. Also, don’t rely on the token response's content or structure. If you do, any change to the schema could make your integration stop working.
The token expires after 5 minutes for security reasons. Beefree SDK will refresh an expired token automatically for 12 hours without re-authenticating the application. The Plugin will trigger the onError callback when the token cannot be refreshed automatically.
NOTE: When a refreshable token expires, the plugin receives a 401 error and attempts to refresh it automatically. The 401 errors are nothing to worry about as they are part of this process.
Here is an example of how to call the Beefree SDK endpoint, obtain a token and then start the plugin:
Ensure to call the authorization endpoint server-side to protect your credentials.
The plugin will keep this session alive for 12 hours from the login.
After 12 hours, you have to manage the token expiration, as follows:
Obtain a new token via the new authorization endpoint
Inject the token obtained from step one via the updateToken method (see examples below)
Here is an example of how to inject the token in the current Beefree SDK instance:
Here is an example of how to get the current JSON from the expiration error:
When you set up an onError
callback you will get the error
object as a parameter.
From that object, you can grab the code
property and use it as explained in the table below.
Method | Description |
---|---|
Method | Description |
---|---|
Event | Description | Returned values |
---|---|---|
default | mixed | amp_only | html_only | |
---|---|---|---|---|
Parameter | Description | Required | Default |
---|---|---|---|
Events and Methods | Description | Required | Default |
---|---|---|---|
To initialize your instance of the Beefree SDK builder, call the “loginV2” endpoint shown in the sample code below with your Client ID, Client Secret, and UID. The Client ID and Secret are available on the application details page of the . UID represents your user as described in .
Reference to learn more about UID.
Once you obtain the token, the object is passed to Beefree SDK to set up the options you wish (e.g., setting the editor’s language to “Spanish”).
Then, you can use Beefree SDK methods to on your page.
Code | Message | Detail |
---|
beePluginInstance.start(templateToLoad)
Starts the builder, loading the templateToLoad
JSON string with the template structure (if specified). If using the NPM package, you have additional options to pass here as defined on the NPM page.
beePluginInstance.load(template)
Loads the JSON template string specified in the template
parameter.
beePluginInstance.reload(template)
Loads the JSON template string specified in the template
parameter. Unlike beePluginInstance.load(template)
, the reload method does not trigger a loading dialog. This method helps quickly reload a template seamlessly for specific use cases, such as using a custom undo/redo feature or injecting custom content in real-time.
beePluginInstance.preview()
Triggers the message preview behavior within the builder.
beePluginInstance.togglePreview()
Open/close the message preview behavior within the builder.
beePluginInstance.toggleStructure()
Controls the visibility of the structure outlines in the message editing portion of the builder.
beePluginInstance.save()
Invokes the onSave
callback function. The application will pass two files to the function: a JSON file with the message structure (for later editing) and a ready-to-send HTML file.
beePluginInstance.saveAsTemplate()
Invokes the onSaveAsTemplate
callback function. The application will pass to the function a JSON file with the message structure (for later editing).
beePluginInstance.send()
Invokes the onSend
callback function. The application will pass to the function a ready-to-send HTML file.
beePluginInstance. toggleMergeTagsPreview()
Controls the visibility of sample content for merge tags in the message editing portion of the builder.
onSave
Fired when the Save button is clicked.
JSON and HTML documents
onSaveAsTemplate
Fired when “Save as template” is clicked.
JSON document
onAutoSave
Fired automatically based on autosave
configuration parameter value.
JSON document
onSend
Fired when the “Send a test button” is clicked.
HTML document
onLoad
Fired when the JSON is loaded in the builder.
JSON document
onError
Fired every time an error occurs.
Error message
onPreview
Fired every time the preview button is pressed.
Status (Boolean)
onTogglePreview
Fired every time the preview is opened or closed.
Status (Boolean)
onChange
Fired every time a change on the message is performed.
onComment
Fired every time a thread or comment changes.
onFilePickerInsert
Fired when the “insert” button is clicked. This property must be defined by the host application for the insert button to appear within the user interface. Available for File Manager applications only.
Object with file info
onFilePickerCancel
Fired when the “X” button is clicked. This property must be defined by the host application for the cancel “X” button to appear within the user interface. Available for File Manager applications only.
None
Stage message
HTML content
HTML & AMP content
HTML & AMP content
HTML content
Content tiles
HTML content tiles
HTML & AMP content tiles
HTML & AMP content tiles
HTML content
AMP sidebar properties
No
Yes
Yes
No
Available in preview
HTML content
HTML & AMP content
HTML & AMP content
HTML content
onSave callback files
HTML
HTML & AMP
HTML & AMP
HTML
Loading a template with AMP content
The onWarning is triggered
Template loads
Template loads
Template loads
Loading a template with HTML content only
Template loads
Template loads
Template loads
Template loads
Availability of the hide on AMP/HTML property
Not available
Yes
Yes
Yes
Behavior for hidden for HTML/AMP content
The onWarning is triggered
Both are visible
Only “hidden for HTML” content is visible
Only “hidden for AMP” content is visible
trackChanges
Track message changes in the editor via the “onChange” callback. See “Tracking message changes” for further details.
No
false
specialLinks
An array of custom links that may be used in the message (e.g. unsubscribe). See “extending the editor” for further details.
No
[]
mergeTags
An array of merge tags that may be used in the message (e.g. first name of the recipient). See “extending the editor” for further details.
No
[]
mergeContents
An array of content elements that may be used in the message (e.g. small blocks of HTML). See “extending the editor” for further details.
No
[]
preventClose
Whether an alert should be shown when the user attempts to leave the page before saving.
No
false
editorFonts
Customize the list of available fonts in the editor’s text toolbar and the BODY settings panel. See “Font management” for further details.
No
See “Font management” for the default object.
roleHash
Identifies the user role:
Minimum length is 8, maximum is 30
Alphanumerical string only: No whitespaces, no special characters such as “_” and “-“
See “Roles and permissions” for further details.
No
""
rowDisplayConditions
Allows for conditional statements in email messages. See “Display Conditions” for further details.
No
{}
workspace
Configure the initial workspace for loading the editor. Currently used for AMP content visibility. See “Workspaces” for further details.
No
{type : 'default'}
contentDialog
Allows to exchange data with BEE Plugin using a UI layer you control. See the “Content Dialog” page for the complete reference.
No
{}
defaultForm
This should contain a structure
object with the form data.
See “Passing forms to the builder” for further details.
No
{}
commenting
Enables commenting on content blocks and rows. See Commenting for further details.
No
false
commentingThreadPreview
Enables a pop-over preview on the stage for comments.
No
true
commentingNotifications
Enables notifications of new comments in co-editing.
No
true
disableLinkSanitize
Disables link validation for URLs, including telephone number or SMS to enable merge content use.
No
false
loadingSpinnerDisableOnSave
Controls the visibility of the builder in a loading state.
No
false
loadingSpinnerDisableOnDialog
Controls the visibility of the builder in a loading state.
No
false
5101 | Expired token cannot be refreshed | You need to do a new login and update the token in the current Builder instance using |
5102 | Expired token must be refreshed | You need to do a new login and create a new Builder instance using the new token, Example scenarios:
|
Here is a list of terms used frequently throughout the Beefree SDK technical documentation. Things can get a bit tricky when embedding a software application within another software application, so this page is an attempt to create as much clarity as possible. We hope we find it useful. If anything sounds confusing or if you have any suggestions for improvement, please contact us.
Beefree SDK A toolkit that includes white-label, no-code builders for emails, landing pages, and popups. The toolkit also provides a range of components, APIs, sample code, and support services to help you seamlessly integrate into your software a content creation workflow that your customers will love.
Beefree SDK subscription A subscription to the Beefree SDK. There are different subscription plans, starting with a Free plan. Once you have a subscription, you can create one or more Beefree applications.
Beefree application An instance of any of the no-code tools that can be embedded in your software. They include:
Email Builder
Page Builder
Popup Builder
File Manager
Beefree SDK Console A multi-user administration panel where you can sign up for a Beefree SDK subscription, manage the subscription, and create and configure a Beefree application within a subscription.
Production application An instance of a Beefree application used in your production environment.
Development application An instance of a Beefree application used for development, QA or staging environments. You can create multiple, development applications under a production application.
Host application Your software application, which will host one or more Beefree applications.
Beefree system The backend system that interacts with your Beefree application to provide services such as application authorization.
Content Services API A set of API methods in the Beefree system that allow you to perform a variety of tasks connected to the implementation of a content creation workflow.
uid
An alphanumeric string that identifies the user and allows the plugin to load resources for that user (e.g. images).
Min length: 3 characters
Can contain letters from a to z (uppercase or lowercase), numbers and the special characters _ (underscore) and – (dash)
It is a string and not a numeric value
It uniquely identifies a user of the Plugin. When we say “uniquely”, we mean that:
It will be counted as a unique user for monthly billing purposes.
Images (and other files) used by the user when creating and editing messages will be associated with it and not visible to other users (when using the default storage).
Yes
container
Identifies the id of div element that contains BEE Plugin
Yes
language
4-letter language identifier (e.g. “en-US”, ISO 639-1 format).
Available Languages
No
"en-US"
Setting up two-factor authentication will keep your developer account extra secure. Two-factor authentication means that users will need to provide two different identifications to log in to their Beefree SDK Console: their regular login credentials, and a token generated by a two-factor authentication app.
When 2FA is set up, users will need to:
download a two-factor authentication app to their mobile device (e.g. Authy, Google Authenticator, Authenticator Plus, and others);
use their device and the app to generate a token and log in.
If you’re an account owner (i.e. the user who created the Beefree SDK account), you may require all account users to use two-factor authentication to log in. To do so, go to the Setting & Security section in your personal area and enable Require two-factor authentication at login.
After saving the setting, you will be prompted to scan a QR code with a 2FA application to generate a security token to complete the setup.
When this setting is ON:
every user will need to enter an authentication token, generated with a 2FA mobile app, to log into the account;
when you create a new user, the 2FA toggle will be set to ON by default.
When adding or editing a user, you may also decide to turn on or off 2FA for that user, in order to:
turn on 2FA, when 2FA is OFF at the account level;
turn off 2FA, when 2FA is ON at the account level.
If 2FA is OFF at the account level, additional users, i.e. admins, can turn on 2FA for themselves, for their peace of mind. They can go to the “Profile” section of their personal area and turn it on.
Instead, if 2FA is ON at the account level, admins cannot turn it off from the “Profile” page and must contact their account owner.
The UID parameter:
Has a minimum length of 3 characters.
Can contain letters from a to z (uppercase or lowercase), numbers and the special characters “_” (underscore) and “-” (dash).
Make sure that you pass a string, not a numeric value. So even if your UID is a number, pass "12345"
and not 12345
.
It uniquely identifies a user of the application. When we say “uniquely”, we mean that:
Images (and other files) used by the user when creating and editing messages will be associated with it and not visible to other users (when using the default storage).
It’s entirely up to you – the application that has embedded BEE – when to use a new UID at the time you initialize the editor for your users. In 99% of the cases: one UID = one CLIENT ACCOUNT in your application. Sub-users of a client account typically share the same UID.
A quick example to help you visualize this.
We use the UID in the File Manager to identify where images will be stored
You typically don’t want client ABC to see client XYZ’s images
So you will use a certain UID for client ABC and another UID for client XYZ
If there are 5 users within client ABC account in your application, however, it’s OK that they see the same images, since they are likely collaborating on the same emails or landing pages, so you don’t need to use a different UID: all 5 will share the same UID.
English: | en-US |
---|---|
is based on the concept of unique users of the editor. A unique user is one that is identified by a unique UID, as described below. The system counts unique UIDs within a billing period, and resets the count to zero at the start of the next billing period.
Is an alphanumeric string passed to Beefree SDK in the .
The UID should not be Personal Data, as indicated in the Beefree SDK License Agreement. Further information about how your use of a Beefree SDK service relates to the EU’s General Data Protection Regulation (GDPR) may be found . Our Privacy Policy, which describes the processing activities carried out by Beefree SDK as Data Controller, is available .
It will be counted as a unique user for .
Spanish:
es-ES
French:
fr-FR
Italian:
it-IT
Portuguese:
pt-BR
Indonesian:
id-ID
Japanese:
ja-JP
Chinese:
zh-CN
Traditional Chinese:
zh-HK
German:
de-DE
Danish:
da-DK
Swedish:
sv-SE
Polish:
pl-PL
Hungarian:
hu-HU
Russian:
ru-RU
Korean:
ko-KR
Dutch:
nl-NL
Finnish:
fi-FI
Czech:
cs-CZ
Romanian:
ro-RO
Norwegian (Bokmål):
nb-NO
Slovenian:
sl-SI