Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Learn how to create an application within the Beefree SDK Developer Console.
The first step to embedding Beefree’s visual builders in your software is to sign up for a Beefree SDK account. Once that’s done, you will be able to log into the Beefree SDK Console. That’s where you will:
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.
Go ahead and create your first application in the Beefree SDK Console.
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:
Log in to your Beefree SDK Developer Console
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.
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.
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:
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
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.
Log in to the
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 ();
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.
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:
Attribute | Type | Description |
---|---|---|
Parameter | Description | Required | Default |
---|
Events and Methods | Description | Required | Default |
---|
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:
uid | An alphanumeric string that identifies the user and allows the plugin to load resources for that user (e.g. images).
It uniquely identifies a user of the Plugin. When we say “uniquely”, we mean that:
| 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 |
|
trackChanges | Track message changes in the editor via the “onChange” callback. See “Tracking message changes” for further details. | No |
|
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 |
|
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:
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 |
|
contentDialog | No |
|
defaultForm | No |
|
commenting | No |
|
commentingThreadPreview | Enables a pop-over preview on the stage for comments. | No |
|
commentingNotifications | Enables notifications of new comments in co-editing. | No |
|
disableLinkSanitize | Disables link validation for URLs, including telephone number or SMS to enable merge content use. | No |
|
loadingSpinnerDisableOnSave | Controls the visibility of the builder in a loading state. | No |
|
loadingSpinnerDisableOnDialog | Controls the visibility of the builder in a loading state. | No |
|
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.
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 Beefree SDK developer portal. UID represents your user as described in How the UID parameter works.
The Beefree SDK system uses OAuth2 as the authorization framework.
Reference How the UID parameter works to learn more about UID.
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.
Once you obtain the token, the configuration parameters 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 start your instance and display the editor on your page.
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.
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.
Beefree SDK Email Builder aims to be the best email editor on the market, ready to be embedded and bring awesome email creation inside web applications. It features a unique combination of design flexibility and ease of use, coupled with great freedom in how you can integrate it into your application.
When 2FA is set up, users will need to:
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.
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 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.
English: | en-US |
---|
Allows to exchange data with BEE Plugin using a UI layer you control. See the “” page for the complete reference.
This should contain a structure
object with the form data.
See “” for further details.
Enables commenting on content blocks and rows. See for further details.
Code | Message | Detail |
---|---|---|
Method | Description |
---|---|
Method | Description |
---|---|
Event | Description | Returned values |
---|---|---|
default | mixed | amp_only | html_only | |
---|---|---|---|---|
Beefree SDK started out in 2015 as an embeddable, drag-&-drop email editor. It was first embedded in and then in hundreds of SaaS applications around the globe, across all sorts of industries: from marketing automation to event engagement; from restaurant management to a CRM for dentists. 🙂
In 2020, guided by the same principles, we launched , another embeddable product for creating beautiful, responsive landing pages, without writing a single line of code.
Now Beefree SDK is both an Email and a Page Builder: as these two products share the same core capabilities and features, the documentation in this site applies to both, unless otherwise specified. If this is your first approach to our builders, just follow the .
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 : their regular login credentials, and a token generated by a two-factor authentication app.
download a two-factor authentication app to their mobile device (e.g. , , , and others);
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 .
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 .
Beefree SDK subscription A subscription to the Beefree SDK. There are different , starting with a Free plan. Once you have a subscription, you can create one or more Beefree applications.
Content Services API A set of in the Beefree system that allow you to perform a variety of tasks connected to the implementation of a content creation workflow.
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 |
5101
Expired token cannot be refreshed
You need to do a new login and update the token in the current Builder instance using updateToken
method.
5102
Expired token must be refreshed
You need to do a new login and create a new Builder instance using the new token, BeePlugin.create()
and the current JSON template present in this event
Example scenarios:
The version is outdated
Beefree SDK releases a security fix and every client must refresh
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
An overview of page builder within Beefree SDK.
Beefree SDK Page Builder will help your customers create beautiful, responsive landing pages, complete with forms and embedded videos. Combined with our Email Builder, you’ll have the power to deliver to your customers a single, optimized user experience for designing both emails and web pages.
With the Page Builder, your customers can create landing pages and one page sites with
In addition, you will find exclusive features that make sense for web pages, such as forms, embedded videos, and the ability to paste scripts, like an embeddable SurveyMonkey or Typeform survey.
Here are a few examples of web pages your customers can build with:
Product showcase or teaser
Disclaimer (e.g. age verification)
Registration (e.g. events, gated content)
Newsletter subscription
Customer survey
Booking request
Portfolio
They can also create fantastic one page websites, i.e. sites where all the content usually spread in different pages fits nicely into an easy-to-scroll page, complete with menu and anchors to navigate it.
We are constantly improving the user experience: we see the Page Builder as a long-term, ongoing project at Beefree SDK.
When you create an application in the Beefree SDK Console, you’ll be asked to select either Page or Email Builder. Paid applications allow you to create child development applications, to ease new feature testing, development, and maintenance.
Page and Email builders share the same core functionalities, including authentication and configuration. If you already integrated our Email builder, you can re-use most of your work by using the same configuration and callbacks. If this is your first approach to our builders, just follow the Installation section in our documentation. All the documentation in this site applies to both products, except where noted.
All builders are available to Beefree SDK customers under the same all-in-one pricing. Please contact your Customer Success Manager for more details.
We aim to provide the foundations needed to build a delightful page building experience. We started with the basic features that are already provided to design awesome email messages and tweaked them to work for Web pages.
Once launched as Page Builder, an application will have a few but noticeable differences from the Email builder experience:
width for pages can be expanded up to 1440px;
the stage can be scrolled horizontally;
the sidebar can be collapsed to provide more workspace – useful when working with larger widths;
there’s a new 6-columns row layout, to take advantage of larger widths;
the preview includes viewport resize, to test responsiveness on various screen sizes;
the HTML block allows using scripts, for improved compatibility with embedded content like surveys. This also includes Javascript, although it cannot be executed within the builder.
If you’re on a paid plan, you will also get support for forms and embedded videos.
You can define and pass forms to the builder, and use the form content block to retrieve and style those forms.
You can use the video content block to embed and playback videos hosted on Youtube and Vimeo, or point to a hosted video in MP4 format.
Managing forms with the Page Builder
A quick primer on how to include forms in a web page.
Our Github account hosts useful resources, including sample code to quick start your integrations.
Many digital marketing campaigns start with an attention-grabbing popup. In fact, many such campaigns include a popup, a landing page, and one or more emails.
A cool popup highlights something that the reader may be interested in
A landing page provides more information and includes some sort of signup form
Emails are sent to follow up.
Emails, pages, popups: three pillars of all sorts of digital marketing initiatives. Since Email Builder and Page Builder were already part of the Beefree SDK family, the natural next step was to create a Popup Builder. So here it is! This new version of the builder brings effortless popup creation inside your application.
A popup is a small window that appears on a website visitor’s screen, asking for an email address in the most basic interaction or other actionable messages when using more sophisticated strategies (targeted promotions, social evidence messages, shopping cart recovery, etc.).
Popups are one of the most used online marketing tools. When done right, they capture visitors’ attention at the right moment, and push them forward in the customer journey. Despite attracting criticism in the past because they create a barrier between visitors and content, there’s plenty of evidence that they work. They will continue to play a strong part in any modern-day marketing strategy. Read our blog entry if you’re interested in learning more.
With this in mind, we have developed an embeddable solution for designing popups that you can easily deploy because:
it’s built from the ground up to integrate seamlessly with your application;
it’s easy to use, offers tons of design flexibility, and builds upon the same UX your customers already know from our Email & Page Builders;
all data stays in your application, and you don’t have to ask your customers to use 3rd party tools for building popups. You can leverage our Form block to add forms to popups
In terms of packaging the final output, Beefree SDK takes care of the Popup design and returns a solid HTML output ready to be injected on a website. On top of that, you can enrich the building experience by creating a workflow that will add to that output:
Showing/closing behavior (e.g. display after N seconds, exit intent)
“Additional” styles, for things like
Close button
Border radius
Drop shadows
The good thing: you can pass additional styles to your application, so they will reflect into the editing experience. You will then take the HTML produced by Beefree SDK and apply these styles for the final output.
Our drag&drop experience, loved by millions of users
There are over 4,500,000 sessions of our drag-n-drop email & landing page builders every month, across hundreds of applications around the world. Popup builder brings the same, great user experience that transforms non-designers in masterful content creators.
You can load your customers' website home page as a background, so they can design a popup in the exact context where it will be used. And with Mobile design mode, your users are one click awaying to seeing and perfecting how the popup looks on mobile devices.
Position, size, background color, and more. Customize the builder each time to match how your customer configured their popup inside your application. What this means for you is flexibility, peace of mind, and implementation speed.
Get a solid HTML output ready to be injected on your customer’s website. Your application controls the display and behavior conditions, Beefree SDK takes care of the content.
Personalization is the secret weapon to attract any audience. With Merge tags and Display conditions your customers can show the right message at the right time, with use cases like product recommendations and personalized discount codes.
Your customers will never have to recreate the same content over and over again. They can apply the same saved rows already available for emails, landing pages or other popups. Plus, you may also provide custom rows with ready-made dynamic content like coupon codes and best-selling items.
The Page Builder includes an expanded Video content block for optimized usage of videos on web pages. Videos are added inside an iframe via the HTML5 video tag.
There are multiple ways to add a video to a page built with Beefree SDK. Additional settings allow the video progress bar and loop playback to be turned on or off.
The Embedded mode allows video playback inside the page. It requires the URL of a video hosted on YouTube, YouTube Shorts, or Vimeo.
Same as the embedded option, but the URL provided must point to a self-hosted video in MP4 format. Settings for hiding controls and loop playback apply as well. Please note that the player interface your visitors will experience might slightly vary based on the browser they use.
As a fallback, you may also use the video block for generating a thumbnail, the same way the block works when building emails. Just enter the URL for a video hosted on YouTube, YouTube Shorts, or Vimeo. A thumbnail linked to the video will be created. You may also style the overlay play icon.
YouTube (16:9 aspect ratio)
Public Videos
Unlisted Videos
Videos starting at a certain time
YouTube Shorts (16:9 aspect ratio)
Vimeo
Public Videos
Unlisted Videos
Cinemascope (21:9 aspect ratio)
Just head over to the “Popup Builder Application” section and click on Activate.
All builders share the same core functionalities, including authentication and configuration. If you have already integrated our Email builder, you can re-use most of your work using the same configuration and callbacks.
Loading Popup Builder with no additional settings will give the end-user a beautifully designed popup and workspace to design their content. However, Popup Builder comes with an additional, robust set of configuration options to customize the workspace. This allows the host application to build a workspace that matches their popup’s look and feel and that of the destination page.
For example, the host app can customize…
The popup workspace background to view how the popup will look “in context” on the destination page.
The theme and position of the popup for both desktop and mobile design modes.
Continue reading to learn more on how to customize the workspace, starting with the common settings and working up to a full custom layout.
In Email and Page Builder, the Beefree SDK HTML parser service converts your template into an HTML document customized for email or pages, respectively. However, the Popup Builder will not return a full HTML page because the host application is the final destination. In addition, Beefree SDK Popup Builder doesn’t provide the scripts to control the popup’s behavior, such as opening and closing. Rather, Popup Builder provides the HTML “partials” to embed within your popup’s content area or body.
The HTML partial will come with all the CSS required to look as it did in the preview mode. The parser service will wrap the content with a special container to clear all the host application styles and prevent style conflicts. The HTML output is designed to be embedded into any popup framework or application and still render the way it appears in the builder.
Our Github account has some resources that might help you out when testing and integrating the Popup Builder.
Examples of different implementations and configurations that you can draw from to speed up your development.
A collection of ready-made templates that you can use right away and add to your application.
Let’s start by looking at some of the peculiarities of the Popup builder.
In Email and Page Builder, the content area width is saved in the template. For example, if you start with an empty template, a default width that works for most scenarios is chosen, but the designer can adjust the message width slider. If you start with an existing template, the content width was chosen by the template’s designer using the message width slider in the builder Settings tab.
With Popup Builder, the same template may have multiple contexts, and each context will likely have specific size requirements. For example, an exit-intent popup may have a max-width of 600px on a desktop with a classical layout centered on the screen. On the other hand, the host app may display the same template on mobile in the bar style docked at the bottom of the screen with a restricted width of 300px.
Since the content area’s width is tightly coupled to the context and layout, no one size fits all width is saved in the template. Instead, the host app will specify the width settings when the builder loads, based on the context of using the template. Here is a quick example:
Two final notes:
Popup Builder does not currently support fluid 100% width content.
If you don’t specify a width, the application will apply a default one.
As mentioned before, you will receive a ready-to-go design experience when no settings are provided. The default layout is a classic centered modal with a fixed width.
If the default popup style and layout suit your needs, then your customers are all set to start designing! You can load the builder without additional configuration and use the same standard controls and callbacks to access the HTML and JSON template.
What if you like most of the defaults but want to do some minor adjustments? We have you covered!
You can easily change the background to make the workspace look like the destination page where your customer will embed the popup.
One of the most common needs is changing the popup’s default-centered position to better match the end-user’s use case. Out-of-the-box, the Popup Builder comes with many of the most common popup layouts preconfigured. You can use any available presets “as is” or use them as starting points that you can fine-tune to your satisfaction.
Here is a complete list of preset layouts:
Loading Popup Builder with no additional settings will give the end-user a beautifully designed popup and workspace to design their content. However, Popup Builder comes with an additional, robust set of configuration options to customize the workspace. This allows the host application to build a workspace that matches their popup’s look and feel and that of the destination page.
For example, the host app can customize…
The popup workspace background to view how the popup will look “in context” on the destination page.
The theme and position of the popup for both desktop and mobile design modes.
The following sections will look at how to customize the workspace, starting with the common settings and working up to a full custom layout.
Let’s start by looking at some of the differences between Page Builder and Popup Builder.
Content Width
HTML output
In Email and Page Builder, the content area width is saved in the template. For example, if you start with an empty template, a default width that works for most scenarios is chosen, but the designer can adjust the message width slider. If you start with an existing template, the content width was chosen by the template’s designer using the message width slider in the the builder’s Settings tab.
With Popup Builder, the same template may have multiple contexts, and each context will likely have specific size requirements. For example, an exit-intent popup may have a max-width of 600px on a desktop with a classical layout centered on the screen. On the other hand, the host app may display the same template on mobile in the bar style docked at the bottom of the screen with a restricted width of 300px.
Since the content area’s width is tightly coupled to the context and layout, no one size fits all width is saved in the template. Instead, the host app will specify the width settings when the builder loads, based on the context of using the template. You’ll find an example in the common settings section below.
Popup Builder does not support fluid 100% width content.
In Email and Page Builder, the Beefree SDK HTML parser service converts your template into an HTML document customized for email or pages, respectively. However, the Popup Builder will not return a full HTML page because the host application is the final destination. In addition, Beefree SDKPopup Builder doesn’t provide the scripts to control the popup’s behavior, such as opening and closing. Rather, Popup Builder provides the HTML “partials” to embed within your popup’s content area or body.
The HTML partial will come with all the CSS required to look as it did in the preview mode. The parser service will wrap the content with a special container to clear all the host application styles and prevent style conflicts. The HTML output is designed to be embedded into any popup framework or application and still render the way it appears in the builder.
Now that we covered the basic differences between Popup Builder and our other applications let’s discuss what you should expect when the builder starts.
As mentioned above in the Getting Started section, you will receive a ready-to-go design experience if no settings are provided. The default layout is a classic centered modal with a fixed width.
If the default popup style and layout suit your needs, then you are all set to start designing! You can load the builder without additional configuration and use the same standard controls and callbacks to access the HTML and JSON template.
What if you like most of the defaults but want to make some minor adjustments? We have you covered!
Easily change the background to make the workspace look like the destination page where you’ll embed the popup.
If this option is not set, then we will provide a default skeleton layout. It’s worth noting at this point that you can apply every setting for both desktop and mobile design modes. That means you can have a different background when editing in Mobile Design Mode. We’ll show you how later!
One of the most common needs is changing the popup’s default-centered position to better match the end-user’s use case. Out-of-the-box, the Popup Builder comes with many of the most common popup layouts preconfigured. You can use any available presets “as is” or use them as starting points that you can fine-tune to your satisfaction.
Here is a complete list of preset layouts:
Another useful preset available is changing the popup’s styles from the default to better match the end-user’s use case. For example, if you’re using the popular Bootstrap CSS framework, you can select the “Bootstrap Theme” as your default. As with the default layouts, you can use any of the available preset themes “as is” or use them as starting points that you can fine-tune to your satisfaction.
Here is a complete list of preset themes:
As mentioned above, the content area’s width is tightly coupled to the layout, no one size fits all width is saved in the template. All Popup Builder preset layouts come with a default width, which you can override with the following configuration settings.
This feature is available on Beefree SDK only.
When you log into the you can immediately see what type of applications you have already created under your Beefree SDK subscriptions.
Once created, head over to “Details” for all server-side configurations. Paid applications allow you to create child , to ease new feature testing, development, and maintenance.
Out-of-the-box, the setup and configuration are the same as . This section will cover the settings specific to Popup Builder. Check out our if you’re new to Beefree SDK or unfamiliar with the configuration basics (as seen in the example below).
If this option is not set, then we will provide a default skeleton layout. It’s worth noting at this point that you can apply every setting for both desktop and mobile design modes. That means you can have a different background when editing in .
Name | Value | Description |
---|
This section provides the information you need to get started integrating in your SaaS applications. For more advanced settings, see .
Out-of-the-box, the setup and configuration are the same as Email and Page Builder. This section will cover the settings specific to Popup Builder. Check out our if you’re new to Beefree SDK or unfamiliar with the configuration basics (as seen in the example below).
Name | Value | Description |
---|
Name | Value | Description |
---|
Continue to if you’d like to customize more than the position, background, and content area width.
Classic Popup |
| This is our default layout and works great for alerts and exit intents. |
Drawer or Slide-in panel |
| Side panels, or drawers, can be used to design menus or display ads. |
Bar or Docker |
| This is great for cookie approval dialogs. |
Classic Popup |
| This is our default layout and works great for alerts and exit intents. |
Drawer or Slide-in panel |
| Side panels, or drawers, can be used to design menus or display ads. |
Bar or Docker |
| This is great for cookie approval dialogs. |
Custom |
| This is our default layout and works great for alerts and exit intents. |
Bootstrap |
| This will a popup that looks like the popular Bootstrap CSS modal. |
jQuery |
| This will be a popup that looks like the popular jQuery modal. Many of the latest CSS systems use a style similar to the original jQuery. |
Material |
| This will be a popup that looks like the popular Material CSS modal. |
What if the default styles and standard settings aren’t enough? No worries! In the following sections, we will look at styling your popup to make it look and feel more like the one real visitors will interact with.
A theme is simply a set of custom styles that give the popup its look and feel. Separate from your layout, Popup Builder comes with some preset themes. The primary is our default theme that is loaded when no settings are specified. We also provide an empty theme that has no styles, which you can use a blank canvas to create your own theme. This is one of the most powerful features of Popup Builder, and we’ll be covering custom styles in depth below.
Here is a preview of the configuration:
To understand the best way to apply your styles, let’s start by inspecting the underlying HTML structure so you can view where the system will map your styles.
Here is a quick break down of what each div does:
This is where you will apply any styles related to how the popup looks, such as border-radius, drop shadows, background colors, or padding.
The header is sometimes used to add a close icon to a popup or display a title.
The div that holds the editable content of your Beefree application.
You can use this div to show a traditional footer for your popup or position some icons outside the popup container (e.g., a close button).
The above HTML structure is represented in your bee config as the following JSON object.
Add styles to the JSON section that corresponds to the HTML element you want to style.
For example, if you want to apply styles to the div with id popup-container, then you would add the styles to the following JSON:
We’ll go deeper into styling in the following sections.
You may be wondering at this point if you have to design an entire theme to get started. Well, you can if you want to, but thanks to the order of operations, you don’t have to. You can start with our default theme and pass in the styles that you want to override. Any style you provide will take priority over any of the defaults.
We said that you could start from scratch if you want, and the easiest way to do that is by using our theme parameter. This allows you to avoid overriding every default style and gives you an empty canvas to build your own theme.
Now that you have seen what the HTML looks like and have some idea where to apply your styles, let’s look at how you get your styles into the editor. The best way to show you is by example, so let’s get started with some common use cases!
Using the schema JSON above and your HTML structure knowledge, you probably guessed that the border is defined on the popup container. So here’s what that would look like:
Example:
After looking at a couple of samples, you may notice these parameters are looking familiar. That’s because every layer of our schema maps to a layer of HTML with the same name AND can be styled with any valid CSS property.
Basically, CSS properties are the same as CSS used by web developers in style sheets, but instead of dashes to separate words, it uses a camel case.
Example:
The CSS property of the style box-shadow would be boxShadow.
Why not use CSS styles as defined by CSS3 specification directly? Well, simply put, CSS properties are better suited for JSON and can easily be shared with any FE application using the popular React framework.
We covered the default layout settings in Setting layout and size section. To recap, the layout determines the type of popup (e.g., a bar) and its location on the screen (e.g., bottom, top, or side). Our research team looked into it, and it turns out, nearly all popups fall into one of the most popular layouts, which we’ve included as presets. But, when that’s not enough, the configuration option customLayout can be used to make minor adjustments to a preset layout or create an entirely new layout from scratch.
Here is a preview of the configuration:
The popup is positioned in the workspace using divs and CSS flexbox. We created a layout structure that mimics an HTML page to map your page’s styles to the workspace.
Layout HTML:
Here is a quick break down of what each div does:
We will apply the styles placed here to the document HTML tag.
We will apply the styles placed here to the HTML body tag
This is the main container div of the workspace.
The wrapper of the popup is used entirely for positioning the popup within the workspace main div.
Example:
The File Manager can be launched as a standalone application. This means that users can access the File Manager directly, without having to first launch the builder application. This is useful for situations where a user needs to quickly upload or manage assets, but doesn’t need to create a full email, landing page, or popup.
Instead of having to switch between different applications or tools, they can access everything they need from one centralized location. This can make the asset management process more streamlined and efficient, which can ultimately help users be more productive.
When you create an application in the Beefree SDK Console, you’ll have the option to create a File Manager application.
Paid applications also include the option to create child development applications. These child applications can be used for new feature testing, development, and maintenance. By creating a child application, developers can easily test and iterate on new features without affecting the main application. This can help to minimize downtime and reduce the risk of introducing bugs or errors into the production environment.
The child applications can also be used for ongoing maintenance and updates. Instead of making changes directly to the production environment, developers can make updates and improvements in the child application, test them thoroughly, and then deploy the changes to the main application once they have been fully vetted. This can help to ensure that the main application remains stable and functional, even as new features and updates are introduced.
File manager applications share the same core functionalities as all other builders. These functionalities include authentication and configuration, which are necessary for the development process. If you have already integrated another builder into your workflow, you can easily re-use most of your work by using the same configuration for the file manager application.
For those who are new to our platform, our documentation includes a comprehensive Getting Started section that provides detailed instructions on how to set up and use our builders. This section is applicable to all products.
File Manager and all builders are available to customers under the same all-in-one pricing. Please contact your Customer Success Manager for more details.
This section outlines steps to add the “Insert” and “X” buttons to your application’s user interface. These steps are specifically for the file manager.
Take the following steps to define the `onFilePickerInsert` and `onFilePickerCancel` properties to enable an “Insert” button and “X” button in the file manager user interface:
Ensure that you have initialized the Beefree SDK and have a reference to the SDK instance (`bee`).
Define the `onFilePickerInsert`
property with a callback function that will be invoked when the user wants to insert a file. This function will receive the selected file data as the only parameter. You can use this data to perform any necessary actions, such as inserting the file into the editor or displaying a preview.
Here is an example of how the callback function can be defined:
IMPORTANT: This callback provides the host application with the file’s metadata and URL. If this callback is not implemented, the “Insert” button will not be displayed.
Define the `onFilePickerCancel`
property with a callback function that will be invoked when the user wants to cancel the file picker. This function does not receive any parameters. You can use this callback to perform any cleanup actions or provide feedback to the user.
Here’s an example of how the callback function can be defined:
IMPORTANT: This callback provides the host application with the control to close the workflow. If the callback is not implemented, the “X” button will not be displayed.
Assign the defined `onFilePickerInsert`
and `onFilePickerCancel`
callbacks to the corresponding properties in the Beefree SDK configuration. Make sure to include these properties when initializing the Beefree SDK.
Here is an example:
By following these steps, you will be able to define the `onFilePickerInsert`
and `onFilePickerCancel`
properties in the Beefree SDK configuration and enable the “Insert” and “X” buttons in the file manager user interface. You can customize the callback functions to suit your specific needs and perform any desired actions with the selected file data or when the file picker is canceled.
The following list shows which specific mime types are mapped to our group names for custom limitations on File manager.
Besides the client-side configuration parameters that you can set for your instance of Beefree SDK, you also can specify some server-side configuration options.
In the application’s details page, locate the area called Application configuration.
Manage roles is used to manage user roles. For details on this feature, see “user roles and permissions“.
Click on Open configuration to manage the server-side settings like:
Toolbar options: affect the UI of the editor
Storage options: determine where the File Manager will store & retrieve images
Content options: define whether certain content elements (e.g. HTML block) are active or inactive
Service options: define whether additional services (e.g. photo search) are active or inactive
Learn more about .
To access server-side configurations, log into your and select the application that you wish to configure.
In this box, you can enable additional content blocks that will appear in the Content panel inside the editor.
Currently, you can manage these content blocks:
If you’re configuring a Page Builder application, there are a few differences in what these blocks allow:
the HTML Block also allows script and iframe tags;
the Video block allows for video playback, either embedding a YouTube, YouTube Shorts, or Vimeo video or pointing to a hosted video (read more). Supported video formats are:
YouTube (16:9 aspect ratio)
Public Videos
Unlisted Videos
Videos starting at a certain time
YouTube Shorts (16:9 aspect ratio)
Vimeo
Public Videos
Unlisted Videos
Cinemascope (21:9 aspect ratio)
the Menu block allows menu items to be set as “internal links,” pointing to any content block in the page that is configured as a “block identifier.”
There is also an additional option for turning on the Form block.
Please note that you need to implement one of the two methods indicated in this article for the Form tile to appear in the Content tab of the editor:
The default form method is available for all plans, including free
The content dialog method is available for paid plans only.
You can enable AMP blocks that will become available in the “Content” tab of your application's Email Builder. To enable this feature, toggle on Enable AMP Carousel in the AMP Content section of your application's configuration options.
We currently provide an AMP Carousel content block. After enabling the toggle, you will need to configure an AMP-compatible workspace.
Please note that AMP content is not available for Page Builder.
When you configure a builder application, you have four options for image & file storage:
Beefree SDK storage: unless you select another option, images will be hosted in Beefree SDK’s own AWS S3 bucket. See below for details about potential fees associated with this option.
An existing builder application: to connect the selected application’s storage to an already existing application. After selecting this option the two applications will share their storage.
Your own AWS S3 bucket: instead of using Beefree SDK’s AWS S3 bucket to store & deliver files, you can use your own. See Configuring your own S3 bucket.
Your own file system: if your application already has a place where images and other assets are stored, you can leverage it. This option is only available on Beefree SDK paid plans. See using your file system.
End users of the builder can upload not just images, but also PDF files and other documents via File Manager. For example, they could link a button to downloading a PDF report.
End-user documentation on the File Manager can be found here.
If you need more control on what files users should be able to upload, you may activate file manager limitations in the Privacy & Security section of your app’s configuration. In alternative, you may consider connecting the builder to your file system.
By default, images used in emails and pages created with the builder are stored in Beefree SDK’s file storage system. Beefree SDK uses Amazon Web Service’s S3 service for storage, and leverages Amazon’s Content Delivery Network (CloudFront) for fast content delivery.
There are no charges for storing images & other documents.
There are no charges for delivering images & other documents up to a total of 5TB of delivery traffic per 30-day period.
Above 5TB of data traffic recorded in a 30-day period, you will be billed $0.01 per GB of data transferred.
Beefree SDK customers that exceed 50 GB of image data traffic on the Free plan in a given month will be moved to our Essentials plan.
When you use the Beefree SDK S3 storage, your images are delivered via a Content Delivery Network (AWS Cloudfront), and AWS bills us based on the traffic generated by those assets when you send emails or publish web pages created with Beefree SDK. A large amount of monthly traffic (5TB) is included in your Beefree SDK paid subscription at no charge.
If you exceed the 5TB monthly traffic allotment, we ask you to cover the cost of the service (for a few of our customers that generate a lot of image data traffic, that cost has grown to exceed their Beefree SDK subscription fee). Also, note that this scenario is quite rare: it applies to less than 3% of our customers.
If you’re on a paid plan, billed monthly, the counter will reset on the same days as your UIDs and CSAPI calls, i.e., on the day your subscription to Beefree SDK is renewed.
If you’re on a paid plan, billed yearly, the counter will reset on the 1st day of each month.
If you’re on a free plan, the counter will reset on the 1st day of each month.
You can always see when the current period starts and ends in your application details, in the Statistics widget:
You’ll be billed annually by summing up any paid traffic you may have accumulated during the past 12 months, unless such total were to exceed $1,000. In that case, we will send you an invoice. The same is true for additional user fees (UIDs) and additional API calls.
For the moment, only subscriptions on paid plans will be notified by our Customer Success team. If you’re on a free plan, you may check your usage by logging into the Beefree SDK Console, and going into the application details, in the Statistics widget.
You can switch to using your S3 storage or connect your file storage.
All traffic generated is charged to the shared storage. E.g.: an Email Builder application shares its storage with a Popup and a Page applications. In this case, the Email Builder application will be charged for the traffic generated by Email + Popup + Page.
It’s not possible to link a development app to a production app.
An app can be linked to another just once.
The same shared storage can be shared across different applications within the same subscription
No, this is not possible. You can either connect production apps included in the same subscription or dev apps included in the same subscription.
Please contact your account manager for this. If you are not sure how to do this, please log into the Beefree SDK Console and submit a support ticket asking for your usage history.
This feature is only available on Beefree SDK paid plans.
Custom S3 Bucket is a Beefree application configuration feature that allows you to easily connect your own Amazon Web Services S3 bucket to your Beefree application.
By leveraging this feature, you will be able to store and manage your customers’ assets without having to build a new File System Provider, but rather by providing a compliant folder structure and filling out a simple form.
Our default file system provider uses two first level folders to manage assets:
Images folder – It defines where the user’s images will be stored.
Thumbnails folder – Is used by our API to store the thumbnails of the uploaded images.
These folders can be root folders or can be part of a more complex directory structure.
A few notes and recommendations:
These folders should not be parents/children between themselves.
Their name is restricted by AWS standard naming restrictions.
For performance reasons, you should use a dedicated bucket and place these folders in the root.
The S3 bucket must be publicly accessible.
The S3 bucket Access Control List (ACL) should ensure “List objects, Write objects, and Write bucket permissions” are disabled for the Everyone user.
As an additional configuration option, you can provide shared files to your users, something that we do in the free version of the Beefree editor at beefree.io. These images are shown to all your customers as read-only assets.
The most common use case is providing sample images for the user’s first experience with the editor. Other use cases include providing application-specific images or documents that must not be deleted by the user.
To use this option you need to set-up two additional folders:
Shared images folder – This is the folder that your users will browse through the file manager.
Shared thumbnails folder – While the user images thumbnails are created when the images are uploaded, there is no automatic thumbnail creation for shared images. You must provide your own thumbnails using these settings:
200px as max. width/height (this guarantee a correct preview in the file manager)
Name: original_image_name.ext_thumb.png (so the thumbnail for cat.jpg must be cat.jpg_thumb.png)
PNG: use only PNG as image format
To use an S3 bucket and configure a policy with the “Policy Generator,” follow these steps:
Configure Bucket Policy using the “Policy Generator”:
In the S3 bucket dashboard, click on the “Permissions” tab.
Under the “Bucket policy” section, click on the “Edit” button.
In the “Edit bucket policy” dialog box, click on the “Policy Generator” button.
Set Policy Generator Options:
Type: Set the type to “s3 Bucket Policy.”
Effect: Set the effect to “Allow.”
Principal: Set the principal to “”, allowing any AWS user or service to access the resources.
AWS Service: Set AWS service to “Amazon S3.”
Actions: Set Action to “GetObject.”
Amazon Resource Name (ARN): Set the ARN to “arn:aws:s3:::myBucketName/” (Replace “myBucketName” with your actual bucket name).
Conditions: Add specific conditions under “Conditions”, such as requiring secure transport and TLS version 1.2.
Review and Generate Policy: After configuring the policy parameters in the “Policy Generator,” review the generated policy to ensure it matches your requirements.
Add the Generated Policy: Click on the “Add Statement” button to add the generated policy to your bucket’s policy.
Save Changes: After adding the statement, click the “Save changes” button to apply the updated policy to your S3 bucket.
Test the configured policy by attempting to access objects within the bucket using both secure and non-secure connections to verify that the policy is working as intended. Once verified, you have successfully configured your Amazon S3 bucket with a policy using the “Policy Generator” in the AWS Management Console. This policy allows any AWS user or service to retrieve objects from the specified bucket under the specified conditions.
Once you have set up a compliant folder structure, you can use the form in the Beefree SDK Console to connect your application. It’s one of the available server-side configurations for your Beefree application (Application details > Open configuration > Storage options).
This is a description of the form fields and what information you will need to provide in each of them:
Please note that the Custom url configuration is not retroactive, so messages and pages saved before this configuration is added will keep the assets under the old URLs.
Example using single folders in the bucket root:
Example using single nested folders:
The button will become active once all required fields have been correctly filled out. It allows you to test your settings before saving the updated configuration. We recommend that you do so before saving any changes.
Remember to save your changes with the SAVE button at the top.
If you’ve just linked your custom bucket, you may find that you need to create your own thumbnails. Thankfully, this is an easy process.
For starters, the thumbnails in the File Manager are PNG files that are resized to 200×200 px.
Here is an example of thumbnail generation with image magick:
As a quick example, we’ll be using this custom bucket configuration:
bucket_name : my-custom-bucket
path_images : /path/to/images/
path_thumbnails : /path/to/thumbnails/
…And starting the editor with this UID:
uid : my-uid
When uploading image1.jpg
in root dir, this key will be created in the custom bucket: s3://my-custom-bucket/path/to/images/my-uid/image1.jpg
. Following that, a thumbnail will be generated with name image1.jpg_thumb.png
with key: s3://my-custom-bucket/path/to/thumbnails/my-uid/image1.jpg_thumb.png
.
And one more example:
When uploading image2.jpg
in mydir
inside the root dir, this key is created in the custom bucket: s3://my-custom-bucket/path/to/images/my-uid/mydir/image2.jpg
. Similarly to above, a thumbnail will be generated with name image2.jpg_thumb.png
with key: s3://my-custom-bucket/path/to/thumbnails/my-uid/mydir/image2.jpg_thumb.png
.
If your Beefree application is currently using the default S3 bucket, you wish to switch to your own bucket, and you have files that you want to transfer between the two, please please log into the Beefree SDK Console and submit a support ticket.
When changes are detected, a compact Undo widget displays in the bottom left corner of the stage:
The widget displays 3 actions:
Undo and Redo arrows that offer the classic pattern to move back and forth between changes.
A history icon that expands a timeline of the latest changes:
The timeline allows the user to browse through the most recent changes.
All the steps display:
An icon to identify the content element type (an image, text, etc.)
A description of what changed, giving the new property value (if any)
The exact time it happened
All these details provide enough information for users to understand what modification was applied, and, if desired, rewind the message to that state:
When the user selects a previous step, the content or row that triggered the history record displays as the selected item, providing further context.
The timeline for more recent changes is still available, allowing the user to move forward without losing any changes:
The Undo widget currently displays the last 15 edits in the timeline, but users can always rewind to the Message opened state to undo all changes since the message was initially opened in the builder.
We are also doing additional testing to see if the number of recent edits can be increased beyond 15 without negatively impacting the browser’s performance. We will update this section if the number is increased.
The last saved edits are only available at the session level, so they reset every time the builder is loaded. If you need to provide a complete message history, you can build a custom one based on the onSave and onChange events (see below).
A new feature becomes available in the File Manager when this is active.
It leverages an integration with popular stock photo services to offer users of the builder the ability to search through a large repository of high-quality images.
The images are free to use under the Creative Commons Zero (CC0) license.
When this is active, adds a toggle to the toolbar that allows a user to simulate the current design in dark mode.
When this is active, advanced users of the builder can set an image as background when editing a row.
When this is active, advanced users of the builder can set a video as the background when editing a row.
Requires “Row background video” to be enabled.
Enables the possibility for users to upload videos.
Requires “Row background video” to be enabled.
Enables a user to search for free stock videos to use in the File Manager.
When enabled, adds a new row option to keep the horizontal layout on mobile devices. Useful when working with nav bars, icons, and other horizontal design elements.
When enabled, it adds a new property in the “Content properties” section of any content block that supports it. This widget allows users to hide a content block either on mobile or on desktop devices.
When you enable Custom Social Icons in the Social module, users will be able to upload their own social media icons as a new “Add a custom icon” feature will now be available in the Social content block’s property panel.
When enabled, it will give users the ability to Undo or Redo any changes that have been made to the email, including the ability to rewind and fast-forward to any point in their recent edit history.
When enabled, an editor to apply image effects and transformations is available in the image module and row background images.
When enabled, adds a new row option to revert the stacking order of columns on mobile. Useful for layouts with alternating visual & text: applying it will ensure that, on mobile, images are consistently on top of their accompanying copy.
We use third-party tools to aggregate anonymous usage data. It helps us develop a better product by assessing locations, devices, browsers, etc.
This can be turned off if necessary.
When you disable the HTML sanitization service, you’re removing all restrictions on what users of the builder can add inside the Custom HTML content block.
The sanitize service checks and ‘cleans up’ custom HTML, which can be an important measure to prevent the inadvertent introduction of unsafe content or the usage of HTML tags that may impact the message delivery rate. However, it can also have an undesired side effect when the host application needs custom HTML tags or attributes to manage specific scenarios.
Please use caution when disabling this service.
Specifically, when HTML sanitization is disabled, we strongly recommend that you add an alternative code review process. To that extent, the onChange event can help the host application intercept the content as soon as it is inserted, and perform a check on it before the user exits the builder. Alternatively, you can use the onSave event to trigger an HTML review on your end at the time the HTML is saved in your system.
The client-side configuration exposes a parameter to override the global setting in the control panel. You cannot disable the HTML sanitization service in the client-side configuration, due to security reasons, but you can enable it per user via the forceSanitizeHTML parameter.
The sanitization service allows the following tags and attributes:
a, abbr, acronym, address, b, bdo, big, blockquote, button, caption, center, cite, code, colgroup, dd, del, dfn, dir, div, dl, dt, em, fieldset, font, form, h1, h2, h3, h4, h5, h6, i, ins, kbd, label, legend, li, map, menu, ol, optgroup, option, p, pre, q, s, samp, select, small, span, strike, strong, sub, sup, table, tbody, td, textarea, tfoot, th, thead, u, tr, tt, u, ul, var, video, source, style, img, br, hr, area, base, basefont, input, link, meta, col, iframe
In this section, you can activate restrictions for the file manager:
Specify which file formats your users can upload in File Manager.
Set a maximum allowed size, different from the default of 20MB.
Please note that the first option will not ask for file extensions, but will instead present file categories such as image, video, text, etc. We have mapped these categories to the most used MIME types that can be referenced in HTML documents.
In the Toolbar Options tab you can:
control individual settings that affect the top toolbar in the builder
decide whether to hide the toolbar completely
The toolbar contains all the actions not related directly with content edition, like save, send a test or preview.
You can decide the inner elements from it, from hiding our brand to removing the save button, to create the builder version that better fits in your application.
Not enough? Remove the toolbar completely and offer all the actions with your own UI elements.
For example, in our MailUp App for Shopify, we hide the toolbar completely and control the builder (Show preview, Send test, Save) from buttons in the app UI (not in the builder). Here is how it looks.
As you may have noticed, when you create a new Beefree application, it comes with a default cloud storage option for files (images or files that the message uses or links to). This approach may fit well for applications that offer content creation for the first time, especially if they don’t need to share these files with other areas of the host application.
If you do want users to be able to access the same image and file directories that they use elsewhere in your application, we have a solution.
It can be built with your preferred technology: just be sure to follow our instructions to ensure successful communication between the two systems.
Once successfully connected, when a user uploads a file or creates a new folder in the Beefree File Manager, this API will perform these actions in your storage, instead of our default cloud storage. Directories permissions, root directory to use, how thumbnails for images are generated, etc.: you decide.
In order to let your Beefree application consume your FSP (File system provider) API, you will need to provide a Base URL to reach the API.
Base URL: https://myfsp.com/path/to/your/base/endpoint
Note that:
the Base URL must not end with a trailing slash (/)
it must be hosted on the HTTPS protocol
In the event of a successful response, the API returns a “success” status code (ex. 200 OK
) and a JSON object such as the following:
In the event an unexpected error occurred during request processing (i.e. missing mandatory request data), the API returns an “error” status code and a JSON object such as the following:
Authentication is managed using Basic Authentication type. The Beefree SDK system’s resource server works as a proxy for FSP (File system provider) and consumes FSP API endpoints adding the following fields to HTTP Request Headers. Please note that the API must use HTTPS to grant secure connections and safe data transfer.
You can enable the move icon for files within the File manager. This move icon allows your end users to move their files between folders, locations, and so on within the File manger. They can access the move icon directly on the file within the File manager. The move icon is a folder with an arrow pointing right inside it. End users click this icon to initiate the process of relocating the corresponding file to a new destination.
Complete the following tasks to enable the move files feature for your custom FSP:
This section will show samples of successful requests to FSP (File system provider) API. A response contains metadata about directory and files.
In this section, we define the following types of metadata:
The following table lists the fields, descriptions, types and examples for the FSP API response common meta.
The following table lists the fields, descriptions, notes and examples for the FSP API response file-specific meta.
The following table lists the fields, descriptions, notes and examples for the FSP API response directory-specific meta.
Description: Use this to list the directories within the File manager.
The following code shows an example request for listing directories.
The following code shows an example response for listing directories.
Each resource returned by the API has a meta
field with metadata. Directory content is returned into items
field as array of metadata of contained resources.
Some notes about resources access management in the previous example:
/shared/
cannot be renamed, because it is contained in a ro
directory
/mydir/
cannot be renamed, because it is contained in a ro
directory
user cannot “CRUD” resources in /shared/
, because it is ro
user can “CRUD” resources in /mydir/
, because it is rw
Description: This response tells the user interface (UI) whether or not to show the move icon for files within the File manager.
The can-move
property controls whether or not the move button is visible within the user interface (UI).
Take the following steps to display the move icon for file within the File manager:
In the response of the listing endpoint, add a new field named can-move
within the extra
object for each file item.
The can-move
field has a boolean value indicating whether the file can be moved. You can set this value to true
or false
.
The following code shows an example request for listing directory content.
The following code snippet shows an example of the can-move
property set to true.
The following table shows the response metadata and its corresponding type and description.
Description: When the move button is pressed, the "move dialog" appears and the usual listing URL is called.
The following image shows an example of the move dialog. This dialog appears after the end user clicks on the move icon for a file. In the image, you can see that the move dialog includes a list of directories for the end user to select from in order to relocate the file.
The following code shows an example of the GET
request that occurs when the move icon is pressed within the File manager and the "move dialog" appears. This GET
request includes the x-bee-fsp-flags: move
header, which is responsible for this behavior.
The move dialog only shows folders. The GET
request will return the full response, including the folders and the files. However, the response will only show items with "mime-type": "application/directory"
. The File System Provider recognizes this call by the x-bee-fsp-flags: move
header.
For the move dialog to work effectively, it is important that you limit the size of the response. Ensure that the response to this request only contains folders and not any files.
Description: Use this when creating a new directory within the File manager.
The following code shows an example request for creating a new directory.
The following code shows an example response for creating a new directory.
in order for the create directory operation to succeed, the containing directory must exist, and the contained (new) directory must not exist
directory names will match the following regular expression: [ a-zA-Z0-9._- \(\)]+
Description: You can only delete empty directories. Use this to delete a directory when it is empty.
The following code shows an example request for deleting a directory.
The following code shows an example response for deleting a directory.
Description: Use this method when uploading a file to the File manager.
The following code shows an example request for uploading a file.
The following code shows an example response for uploading a file.
in order for the upload file operation to succeed, the containing directory must exist
if the uploaded file already exists, it’s in charge of FSP API do decide if:
silently overwrite old file with the new one;
create a new file with a different name, in this case returned metadata must be coherent with the new file created;
return a 403 FORBIDDEN error;
uploads are proxied by Beefree’s resource APIs, which are in charge of enforcing the maximum file size (20 Mb) and the maximum image size.
uploads from stage will be POSTed to “/editor_images/{filename}”
uploads from page builder favicons will be POSTed to “/favicon_images/{filename}”
the name of files uploaded from stage will match the following regular expression: [ a-zA-Z0-9._- \(\)]+
Description: Use this to delete a file within the File manager.
The following code shows an example request for deleting a file.
The following code shows an example response for deleting a file.
Description: When the move icon is clicked in the File manager, the File System Provider (FSP) will receive this call. It is a PATCH on the URL of the file to move.
An example of a conflict is when you are moving a file from one folder to another, but the destination folder has an existing file with the same name as the file being moved to that folder. For example, you want to move a pizza.jpg file to a folder that already contains a pizza.jpg file. In this scenario, there is a conflict because both files cannot have the same name.
The PATCH Method enables you set a conflict_strategy
that resolves scenarios like these when they occur.
The following code shows an example of this method.
This is the response you will see in the event that a file was not successfully moved to a new location, and an error occurred.
In the event a name conflict occurs, the File manager displays a dialog to the user. You have three options to select from to resolve this conflict using the conflict_strategy
which is passed to the FSP.
These three conflict resolution options are the following:
cancel ( "conflict_strategy": "" ): nothing happens
keep both ( "conflict_strategy": "keep" ): move the file, in order to keep both files our implementation appends a suffix to the new one. For example, the pizza.jpg file will become pizza_1.jpg ( _2 , _3 , ...)
replace ( "conflict_strategy": "replace" ): move the file, it overwrites the old file with the new one
The trailing slash (/) on the request matters!
The FSP API uses the trailing slash (/) on the resource path to understand if the required resource is a file (no trailing slash) or a directory (with trailing slash).
For example, if the FSP API receives a GET
request for /sample.jpg
it will return sample.jpg
file metadata, whereas if it receives a GET request for /sample.jpg/
it will return a list of the content located in the sample.jpg
directory.
The FSP (File system provider) API uses standard HTTP status codes to manage success and error responses. Status codes include:
In case of errors, the API returns a JSON object structured like this:
Thumbnail generation is up to the developer of the file system provider.
The thumbnail
field is optional, so if you don’t want a thumbnail for your file, do not pass the field and the Beefree system will show you a generic icon based on the mime type you passed.
The thumbnail image must be contained in a 200px by 200px virtual square (see pictures below).
Block | Description | Availability | User guide |
---|---|---|---|
Parameter | Description | Required |
---|---|---|
Your users will have the ability to rewind and fast-forward to any point in their recent edit history. Once Undo is enabled in the , the application immediately begins tracking changes. Behind the scenes, this is accomplished via a new callback event – – which can also be used “stand-alone” without enabling Undo. No client-side configuration is required to use this feature. Continue reading to learn how to activate and use Undo. And if you can’t wait to try it yourself, you can immediately do so at
The Undo option is available at the application level in the . Select your application from the list and open the Application configuration in the bottom-right. The option to enable this widget is available in the Services list:
The widget uses the information to work. However, it doesn’t need a client-side configuration for the callback: once Undo is enabled, the application starts tracking changes even if the is not set in .
Please note that server-side configurations are only available on .
When toggled on, this option scales the background image to fit the background dimensions of the entire document. This feature is best used with high-resolution images. More information .
For and .
When this setting is enabled, users of the builder can specify both a static placeholder image and a dynamic image URL when adding an image content block. This allows for scenarios such as personalized birthday cards, countdown timers, dynamic ads, and many other user cases in which an image is built dynamically at the time it is served. .
When enabled, the display conditions widget will show as a row option. The widget can be used to apply the conditions created by the host applications or to add new syntax manually. .
More on
This will allow users to select a row in the current message and save it for later use. More .
When enabled, adds an option in the file manager to import images from different social networks and storage services. We use for this feature. Filestack may log the user’s IP address. If this is in conflict with your privacy policy, turn the feature off.
This feature allows users to leave comments and start discussion threads inside an email or page, to collaborate asynchronously. .
Element | Attributes |
---|
Learn more about for custom limitations on File manager.
Please note that server-side configurations are only available on .
If you decide to go this route, use the to control the builder from your UI.
Option | Description |
---|
We created a way to connect to a custom file system provider, allowing you to use your own file storage, no matter which technology you use. A custom file system provider is an API that will allow a Beefree SDK application to perform actions with files outside of the Beefree SDK system, connecting your file system to the .
The API uses JSON as the input and output data format: Responses are .
In the event a request fails, the API returns the error codes described in the .
User information is segmented by .
Field | Description |
---|
Ensure you save the username
, password
, and base URL
in the Configuration section of the .
Add a can-move
field in the extra
object in the . Reference the Listing Directory Content section for steps on how to complete this.
Modify the listing response to limit its content when the request includes the x-bee-fsp-flags: move
header. Reference the for steps on how to complete this.
Implement a PATCH method for file URLs with conflict_strategy
management. Reference the for steps on how to complete this.
Field | Description | Type | Example |
---|
Field | Description | Notes | Type |
---|
Field | Description | Notes | Type |
---|
Metadata | Type | Description |
---|
The final step in activating the within your File manager is to configure a conflict resolution strategy. This strategy is triggered when there is a file conflict within the File manager.
The following response is the same as the . This is the response you will see in the event that a file was successfully moved to a new location.
Action | On success | On error | On failure |
---|
To read the full list of possible errors, please refer to .
In case you don’t want to develop your own thumbnail generation procedure, you can use a service like to create a thumbnail URL.
HTML
Allows your users to include their own HTML code
Paid plans only
Menu
Allows users to create simple, text-based navigation elements
All plans, including free
Title
Allows users to add text with H1,H2,H3 tags, for email and web accessibility, and for SEO on web pages.
All plans, including free
List
Allows users to create easy numbered and bullet lists with Paragraph’s upgrades and list type, spacing, and identation support.
All plans, including free
Paragraph
Allows users to write text with support for multiple font weights, copy/paste support, easier reformatting, and more.
All plans, including free
Text
Legacy text block. Please refer to title, paragraph and list.
All plans, including free
Video
Helps users include a visual link to video content
Paid plans only
Icons
Enables users to create icon-based layouts, such as star ratings, bullet lists, properties
All plans, including free
Spacer
Allows users to add a space between content
All plans, including free
Table
Allows users to add a table to their design
All plans
Custom url
The hostname – typically a CDN – that will be prefixed to resources URLs referenced in the JSONs created with BEE.
No
Bucket name
The name you assigned to the bucket when you created it.
Yes
Access key & Access secret key
You can provide AWS Root Account Credentials or IAM User Credentials (we recommend the second option for security reasons). The provided account must have read and write access to the given bucket. More about AWS credentials.
Yes
Select Region
AWS region where you created the bucket. Uses EU as the default setting.
Yes
Images Path
The relative path (from the bucket root) to the images folder described above (use “/” symbol as path delimiter).
Yes
Thumbnails Path
The relative path (from the bucket root) to the thumbnails folder described above (use “/” symbol as path delimiter).
Yes
Shared images path
The relative path (from the bucket root) to the shared images folder described above. Cannot be the bucket root (use “/” symbol as path delimiter).
No
Shared thumbnails Path
The relative path (from the bucket root) to the shared thumbnails folder described above. Cannot be the bucket root (use “/” symbol as path delimiter).
No
general attributes | style, id, class, data-*, title |
a | href, name, target |
img | align, alt, border height, hspace, src, vspace, width, usemap |
table | align, bgcolor, border, cellpadding, cellspacing, width |
tbody | align, valign |
td | align, bgcolor, colspan, height, rowspan, valign, width |
tr | align, bgcolor, valign |
tfoot | align, valign |
th | align, bicolor, colspan, height, rowspan, valign, width |
thead | align, valign |
li | type |
map | name |
area | alt, coords, href, shape, target |
div | itemscope, itemtype |
meta | itemprop, content |
video | autoplay, controls, height, loop, muted, poster, preload, src, width |
source | media, src, type |
Authorization | Authentication used is Basic. A string formatted as username:password and encoded in base64 is passed |
X-BEE-ClientId | The ClientId (to identify the integrator) |
X-BEE-Uid | The uid (ex. useful to identify the user of an integrator) |
| application/directory for directories and specific mime-type for files |
| “application/directory”, “images/png”, … |
| resource name |
| “my file.jpg” |
| absolute path to resource in FSP |
| “/absolute/path/to/my file.jpg”, “/absolute/path/to/my directory/”, … |
| UNIX time with (milliseconds) of last modification of this resource |
|
|
| size (in byte) of the resource, this is zero (0) for directories |
|
|
| defines the access grants to the resource, can be |
|
|
| generic extra data (for future extensions) |
|
| Public url of this file | This field must be url-encoded |
|
| Public url of the thumbnail of this file | This field is optional and must be url-encoded |
|
| number of contained items (directories + files) | This parameter is optional, if you don’t have this data, feel free to pass zero |
|
| string | File name. |
| string | File path. |
| number | The date that the file was last modified. |
| string | The permissions for the file. |
| string | The file mime type. |
| number | The size of the file. |
| string | The public-url to access the file. |
| string | The thumbnail URL. |
| object | The object that contains the |
| boolean | A boolean key within the extra object that displays the move button on a file in the File manager when set to |
List directory |
|
|
|
Create directory |
|
|
|
Delete directory |
|
|
|
Get file metadata |
|
|
|
Upload file |
|
|
|
Delete file |
|
|
|
Learn more about injecting custom JS libraries into your Beefree SDK integration.
Enterprise customers can request to inject external JavaScript libraries, like FullStory or Heap, into Beefree SDK when the integration is initialized as part of the server-side configuration.
Custom JavaScript requires a complete technical evaluation by the Beefree SDK development team. The assessment will undergo security, technical and compatibility assessments.
Contact our Sales team and ask to run a script to get started with custom JS libraries injection. Once you contact us, we will take the following steps to complete your request:
Our representative will forward your request to our development team
The development team will review the script and approve it
The script is enabled by our development team
Show toolbar | Is the main option: if is not active, the elements listed bellow get hidden |
Show Beefree SDK logo | Show our logo and links our site |
Show preview | Trigger the preview window |
Show send test | Trigger the function for sending a test |
Show save as template | Is used to save only the editable version of the message |
Show save button | If you don’t have a external one, better not to hide this 🙂 |
Show auto-save icon | This tiny icon alert the user every time the auto-save works |
Show help link | This option is special, because you can also introduce your custom help URL |
Show Multi-Language Templates |
Advanced options are available with Beefree SDK. Learn more about the advanced options you can integrate within your web application. Beefree SDK's advanced options include the following:
The builder’s color palette gathers a list of the default colors to display from multiple sources in order to create a convenient palette of color selections when the editor loads.
Specifically, colors are gathered as follows:
3 colors from the body (message background, content background, link) + black (#000000)
custom colors (as many as customers want)
7 most recently used colors
Use the options outlined below to customize the default color palette.
The builder allows you to configure a custom color palette (per user), by modifying the client-side configuration. This, for instance, allows you to provide users with easy access to their company’s brand colors.
If no color profile is provided, then the builder will continue to suggest a color palette based on the colors used in the template that is being loaded.
The builder will remember recently selected colors and add them to your color palette. If the browser’s privacy settings allow it, the color picker history will be saved in the browser’s local storage.
If you want the color palette to be static such that recently selected colors are not included, then you can disable the history in your configuration.
The builder by default adds colors found in the template’s body section to the color palette.
If you want the color palette to only show the colors you pass in via the bee config document, then you must disable the base colors.
It’s all good until things scale up. For example…
Since the Beefree builders are used in hundreds of applications, and since each of them is facing different user experience challenges like the examples mentioned above, we decided that this was really a case where one size does not fit all.
So we engineered a solution that puts you in control and provides a large amount of flexibility.
If your users want to insert a merge tag or a display condition, you control how that will happen. You can overlay a window on top of the editor, for example, and display a simple search box, a list of categories to browse, or a complex configurator to build an advanced conditional statement.
We call this feature Content Dialog.
Content Dialog allows you to build user interfaces for your users to locate & insert merge tags, links, conditional statements, and more. It lets you establish an interaction layer between the editor and your application (e.g. you show a pop-up window) that allows your users to locate/build/insert specific content (merge tags, links, conditional statements, etc.). And you’re in full control of the UI.
For example, imagine you want your customers to be able to quickly locate a link to a product page and assign that link to a button, image, or text. Content Dialog will let you build the right user experience.
Here is a visual example of what you could accomplish in that find a product link scenario.
The user experience in this interaction layer is entirely up to you. In the example above, the user clicked on “Find a product” (or alike) in the editor, and a modal window was shown, with a search box in it. Since you decide what the user experience will be like, you are fully in control of how users will select and insert:
For each type of content, you can define the action that will be triggered in your application (e.g. display a modal window), and the text that will be displayed in the Beefree SDK editor’s UI to trigger that action (e.g. “Locate a merge tag”), keeping a consistent UX with other areas of your application.
Content Dialog introduces new call-to-actions in the editor UI.
Depending on the type of content, the call-to-action will be rendered as a button, a link, or a drop-down choice (see below a detailed list of UI changes).
The text for the action is defined by the host application, so you can use your own wording to provide a better experience.
An example of a possible workflow when the user clicks on a content dialog action:
The editor will start waiting mode (same as when the save action is triggered)
This mode prevents users from further editing and keeps the focus on the user selection
The waiting mode is interrupted if the host application cancels the action
The host application will display to the user a UI element to select or define a content item
When the selection is done, the host application closes the UI and passes it to the editor
The editor receives from the host application the selected content and exits waiting mode
The content is applied to the selected item
The same example applied to special links (link to a product) in a text selection:
The editor starts waiting mode
The host application displays an overlay that hides the editor and lists the categories of products to link. The user browses them to find the desired product and selects it.
The editor receives the link and exits waiting mode
The link is applied to the selected text
To set up content dialogs you will need to add the contentDialog
object to beeConfig
:
For rowDisplayConditions
, there is a third parameter called currentCondition
. Use this parameter to return a row's current display condition. This parameter returns an object with the following format:
Note: You do not have to name the parameter currentCondition
. You can use any name that works best for your application and workflow.
You can add all the dialogs, some of them or only one. Is up to your application to create them for all the users or a segment, as there are no related server-side settings, you can customize them for each editor start.
All the dialogs use the same pattern, but the returned object must match the element pattern (described in the following section).
Defines the text displayed in the editor UI.
A resolve or reject call is mandatory. If you miss this step, the editor will remain in waiting mode. Error management on the host application must call the reject function to unblock the editor.
A very simple example of how to apply a Special link.
When the user clicks on Add an Example Link, the URL http://www.example.com is applied to the selection (a button, an image or a text).
The waiting mode will not be perceived, and there is no cancel action.
Same as the previous example, but the waiting mode will display for two seconds before applying the URL.
In this example the openMySpecialLinkDialog()
should be replaced with a function that opens a modal window (or other element) of the host application, where the user can select or build a link.
The selection is then returned as the value of specialLink
to the resolve()
function.
A cancel action will trigger the reject()
function instead.
Values must use the same pattern used in the beeConfig
object.
The returned object is validated against the expected format.
If the validation fails, an error will be returned in the browser console:
E.g., Error getting content rowDisplayConditions, the item is malformed.
These errors will not trigger any visible notification in the UI.
You can add a new action, available in the text toolbar, and associated with the merge tag element:
Your application has a high number of placeholders and needs to provide a categorization or search form
Placeholder availability depends on options that the user can select while building the message
You want to display the same UI your users already know and use in your application
You need to separate merge tags from other text placeholders
The name parameter may be later displayed if the user selection is saved and loaded in beeConfig on subsequent requests.
Links are applied to different contents, so, when you define a link dialog action, it will be displayed in:
The text-toolbar, as happens with merge tags
An image or button action
Apply links to products or news using a categories pattern, a search form, or a visual browser
Apply special parameters or configuration to certain links with a wizard or form
You want to display the same UI your users already know and use in your application
The type parameter may be lately displayed if the user selection is saved and loaded in beeConfig
on later requests.
The content dialog adds a button to the merge content list:
Set up the content and/or layout for a product recommendation
Set up the content and/or layout for a dynamic advertising
Set up the content and/or layout for another type of targeted content
A new button will be available in the display condition widget. In this example, the button says “Open builder”, which is the label
shown in the JSON configuration file shown above.
Display a condition builder or form to target a segment of recipients
Display a form to create a loop with the row dynamic contents, as product recommendations
The type parameter may be later displayed if the user selection is saved and loaded in beeConfig
on subsequent requests.
In this example, a window is shown to users when they click on the button to open the builder.
The UI is entirely up to the hosting application. Here, the developer decided to offer some fields at the top where the Display Condition can be named and described, an area below it where parameters, values, and operators can be selected, and a preview on the right.
When users click on “Confirm”, the information is passed back to the editor and shown in the properties panel.
The content dialog adds a new item, using your text label, in the Rows drop-down:
Import a set of products or news, as custom rows, using a categories pattern, a search form, or a visual browser
Set up the row layout for a set of predefined contents
Set up rows with dynamic content to build dynamic sections that provide product recommendations, QR or bar codes, advertising content, etc.
This response will:
Create a new drop-down choice with the provided name
Display the rows provided by the URL in the rows panel
Notice that in the rows list, names returned by the content dialog display as highlighted elements to give them further visibility over starting choices.
The content dialog can be used as many times as the user needs and, depending on the response, the behavior may change:
This overwrites the existing results, keeping the same name in the drop-down. This behavior perfectly matches our example above, where the host application returns “Your search results” every time the content dialog is resolved.
This creates a new drop-down choice, keeping the previous results as selectable elements. Previous results are available directly in the drop-down. Usage example:
The label
, description
and notPermittedDescription
fields handle the wording related to the “Edit synced row” call-to-action/button. Here’s how and where they are used:
label
: Label related to the sidebar button that triggers the content dialog
description
: Description of the action on top of the button
Here’s an example of what label
and description
would look like:
And here’s an example of what notPermittedDescription
would look like:
Unlike the rest of content dialog configurations, Save rows doesn’t use the label
parameter as the UI element is a save icon displayed on the selected row (and in the row’s properties panel):
The args
object in the handler function returns to the host application metadata already applied to the selected row.
The row name is the only required metadata and it’s displayed as the row title in the Rows panel:
A string of plain text that identifies the row.
Displayed in the row card when the row is shown in the Rows panel.
Used for text searches within the Rows panel
If you want to have total control on the forms that a Beefree application displays and renders, you can use this forms Content Dialog rather than passing a single form to the Beefree application.
The forms Content Dialog works the same way as the previous Content Dialog for the saved rows – but in this case, the resolve
function should return the structure for the desired form.
The args
object in the handler function returns to the host application the form object already applied. With this information, the application can decide what to display to the user (e.g., edit the current form, suggest a similar form, etc.).
If your end users need to apply custom attributes to the links and images in their content, you can completely customize the user experience and workflow for adding those attributes with a Content Dialog that will take over the editor’s UI. The dialog will need to return the attribute to apply.
It is possible to leverage the Content Dialog method to add videos from custom sources – other than YouTube and Vimeo.
You can use the addVideo
Content Dialog modal, which will take over the builder’s UI. The video will be added as a thumbnail in the content area.
The user must fill out the video URL from a custom source, the image used as a thumbnail, and an alt text/title by implementing a custom modal window (optional). When the user clicks on the video thumbnail, it will open videoSrc
in a new tab/window.
Smart merge tags provide a better way for your customers to leverage personalization when creating content with Beefree SDK.
With Smart merge tags, users can:
quickly identify merge tags through a specific highlighting
see human-friendly names instead of the raw syntax – e.g., Customer Name instead of {%customer.name%}.
select, replace, and style merge tags with just one click
get sample content for each merge tag, both during editing and preview.
After enabling Smart merge tags, the builder will:
highlight merge tags with a dotted border
display the tag name you passed instead of the raw syntax
When users click on a tag, its border will become solid to signify that it has been selected. After selection, users can style, replace, or delete the merge tag with just one click.
Smart merge tags are easier to identify inside the content you’ve created and will save users tons of time. Furthermore, hiding the syntax will make it impossible for a user to break it while interacting with the overall text element.
On top of this, you can pass sample content for each merge tag, so that users can see an example of the data that will take the place of the merge tags when the web content is rendered:
Smart merge tags are disabled by default. If your application doesn’t have Smart merge tags, you need to activate it. It takes just a few clicks:
Click Details next to the application you want to configure
We recommend you first familiarize yourself with this feature under a DEV or QA application
Click view more under Application configuration.
Under the Services section, toggle Enable Smart merge tags ON and click the Save button.
The optional previewValue
parameter is used to pass to the editor a sample content (text string) for every merge tag.
The value of this new parameter will replace the merge tag in the editor preview, meaning that there’s no need to build a custom preview to display the final result of an email or landing page with rich personalization strings.
Sample content strings are not limited to the preview, but can be displayed in the editor’s stage as mentioned above.
In this case, you can simply enable the option “Show ‘Merge tag preview’ in toolbar” mentioned above.
When this option is active, the toolbar displays a new action to the user:
The option works as a toggle that alternates between displaying the previewValue
and the name parameter inside the merge tag UI.
Use this method to replicate the behavior described for the standard toolbar.
In Beefree SDK we introduced the idea that some content may be editable by some users and not others. For example, you may want the header and footer section of an email newsletter to be locked, so that it cannot be inadvertently modified when creating the latest version of your weekly news digest.
Internally, we’ve been calling this feature “Restricted editing”. Others refer to it as “locked regions”, “blocked content”, and more.
To allow for this, we created ways for the application hosting the builder to define user roles and set their permissions. Let’s take a look at how the feature works first and then show you how to configure your application to take advantage of it.
The user roles that you create (e.g. Brand Manager, Senior Editor, Junior Editor, etc.) can have different permissions. You can create as many or few user roles as you wish. The permissions that you can assign to them refer to:
Locking content (entire rows or specific content blocks)
Editing locked content
Specifically, the permission settings that can be configured for each role are:
Can lock rows (if active, all other permissions are granted)
Can lock modules
Can edit locked rows
Can edit locked modules
Can select Display Conditions
Can edit Display Conditions
Can remove Display Conditions
For example, a Brand Manager all four permissions checked, whereas a Senior Editor might have editing access to rows and modules, but won’t be able to lock rows and modules. Let’s take a look at a few scenarios.
If the user has this permission, locking a row is very easy to do. That user will simply select the row they would like to lock and click on the lock/unlock radio button in the row properties panel.
If a user does not have the permissions needed to edit a locked row, they will see a friendly error when they attempt to select the row, notifying them that the row can’t be edited:
Likewise, they will not be able to drag & drop any content blocks on the locked row, as shown here:
You can restrict access to layout changes while granting access to content modifications by using user roles and permissions.
This allows you to give your users editing access to the content, while ensuring that the overall layout of the message is not altered, and that specific content blocks that should not be modified are left “as is”. This way, for example, a junior member of the marketing team could focus on updating text & images, without worrying about potentially modifying the structure of the message in an unwanted and/or unauthorized way.
Or, as shown in the example below, the same user could update social media icons and links in the footer of an email, without altering legal language and dynamic fields used in the same footer. That’s accomplished by setting us a social media module that’s editable (unlocked), but in a row that’s locked.
When users without the proper permissions try to edit, move or remove the row, they are told that they may not do so.
Similarly, if they try to edit any content is the row that has not been specifically unlocked, they are told that they are not able to do so. In this case, for instance, the user is not able to edit the merge tags used in the footer of the email.
However, when they click on the social media icons, they are able to edit it.
To accomplish the above, a user with higher permissions needs to:
Open the message in the builder
Lock a row
Unlock one or more specific pieces of content within the row.
In the Manage Roles section you’ll be able to create different user roles and set their permissions. For example, your user roles could be Brand Manager, Account Manager, Junior Editor, etc depending on your needs and nomenclature. For each user role you create, you can set and restrict editing permissions, such as the ability to lock or edit rows and content blocks, as you can see below:
Once you create your user roles you’ll be able to see them listed:
While Role Name is a friendly description of that user role, Role Hash is the parameter that identifies that particular role in Beefree SDK. It must be an alphanumeric string between 8 to 30 characters: it can contain letters and numbers, but cannot contain spaces or special characters (such as “-“, “_”, etc.). You will need to save these role hashes in your application, at the user level – or at the user role level, if you have the concept of “roles” in your application – so that you can retrieve them and pass them to the application when you initialize the builder for that specific user.
The property name is: roleHash
.
For user roles to become active in the builder , you will need to add this new property to your Beefree SDK configuration when you configure the builder for a specific user. You will pass:
roleHash: "roleSpecified"
for each of the user, depending on its role. For example, if the Role Hash for a “Junior Editor” is “juniorEditor”, the application configuration will include:
roleHash: "juniorEditor"
This section goes in more details about the various combinations of permissions. It might help you understand how to best put this feature to work in Beefree SDK with regard to locking & unlocking rows and content blocks.
First, we created some hypothetical roles by using all application combinations of the available user permissions at the row/content level.
Then, we created a table with a number of possible “actions” and see which user role would have access to which actions. This allows you to map a certain combination of permissions (from above) to a specific task carried out in the Beefree SDK builder.
Use this to enable a custom top bar that allows the end user to .
This feature is available on Beefree SDK only.
This feature is available on Beefree SDK only.
When designing a message or a landing page with Beefree’s editors, there might be cases in which users of your application insert a , add a link to an image, or apply a .
What if you have 400 merge tags? You can to the editor, but that’s not going to cut it.
What if it’s a 6,000 product database? How will they locate the right one? is not the right fit.
And what if a needs to be built on-the-fly?
a text placeholder ()
a dynamic link or a link to specific content ()
a markup placeholder ()
a conditional statement ().
Is a function with a -like signature.
This function lets you use your own logic to retrieve the desired value.
Once the value is available, you must call the resolve(value)
function to pass it to the editor.
In case you want to cancel the operation, call the reject()
function.
Notice that, to display the Dynamic content tile in the contents panel, you must configure in with at least one predefined item.
Of course, it can be edited in the editor like any other Display condition, if the user has the .
Reference our to learn more about managing the visibility of the Add Condition and Edit Condition buttons.
notPermittedDescription
: Description of the action when the button is hidden from the dedicated
The Save rows content dialog is a mandatory step in the workflow.
The resolve
function must return metadata for the selected row. The section of the rows schema allows you to keep track of row-specific information.
This response will provide metadata that is added to the row in the asset (email, page, popup) before it’s provided through the .
Check the for further details on recommended metadata.
To understand how this data is structured, refer to the on this website.
This feature is available on Beefree SDK and above. If you're on the Essentials plan, for free to try this and other Core-level features.
Notice that, at this point, you will be prompted to enable the merge tag preview in the toolbar. You can skip this option when your integration is not using the or you’re not passing sample content for your .
After enabling Smart merge tags from your developer account, you need to apply a minor change to the merge tags’ .
The way to do this depends on how your integration manages the .
As with all the actions available in the toolbar, to control this option from your own UI:
This feature is available on Beefree SDK only.
Using
Log into the and click on Manage roles under Application configuration for the selected application:
Please refer to for more details.
Role | Lock rows | Edit locked rows | Lock modules | Edit locked modules |
---|
Description | admin | designer | designer2 | copy | modules | rows | user |
---|
If you use in your builder application, then you can use additional user roles to control the access users have to creating and editing .
admin |
designer |
designer2 |
copy |
modules |
rows |
user |
Lock/unlock a module | widget not provided | widget not provided | widget not provided | widget not provided |
Lock/unlock a row | widget not provided | widget not provided | widget not provided | widget not provided | widget not provided | widget not provided |
Add a module to locked row (the module is automatically locked) | can’t drop modules in locked rows | can’t drop modules in locked rows | can’t drop modules in locked rows |
Move a locked module from an unlocked row to a locked one | can’t drop modules in locked rows | can’t drop modules in locked rows | module handler not provided |
Move a locked module from a locked row to a locked one | module handler not provided | module handler not provided | module handler not provided |
Move a locked module from a locked row to an unlocked one | module handler not provided | module handler not provided | module handler not provided |
Move a locked module from an unlocked row to an unlocked one | module handler not provided |
Move an unlocked module from an unlocked row to a locked one | can’t drop modules in locked rows | can’t drop modules in locked rows | can’t drop modules in locked rows |
Move an unlocked module from a locked row to a locked one | module handler not provided | module handler not provided | module handler not provided |
Move an unlocked module from a locked row to an unlocked one | module handler not provided | module handler not provided | module handler not provided |
Move an unlocked module from an unlocked row to an unlocked one |
Move a locked row | row handler not provided | row handler not provided | row handler not provided |
Move an unlocked row |
Delete/duplicate a locked module in locked row | show warning | show warning | show warning |
Delete/duplicate an unlocked module in locked row | show warning | show warning | show warning |
Delete/duplicate a locked module in unlocked row | show warning |
Delete/duplicate an unlocked module in unlocked row |
Delete/duplicate unlocked row containing locked modules | show error | show error |
Delete/duplicate locked row | show warning | show warning | show warning |
Change properties of a locked module | show warning | show warning |
Change properties of an unlocked module |
Change text of a text/button locked module | show warning | show warning |
Change text of a text/button unlocked module |
Add an image to a locked image module | show warning | show warning |
Add an image to an unlocked image module |
Change properties of a locked row | show warning | show warning | show warning |
Change properties of an unlocked row |
The default configuration returned by the system can be extended by using additional configuration objects such as:
Special links are links that your system generates dynamically when the message is sent, typically because they include the message ID, the recipient’s email, or some other variable. The most common one is probably the unsubscribe link.
The type
parameter will be used to group related links in the UI and simplify the user selection.
Technically, special links are passed to the application in the configuration file as follows:
and here’s an example of what the user will see in the builder UI, starting from the above code:
As mentioned above, when you initialize the application, in the configuration file you can submit both “merge tags” and “merge content”.
Really, they are the same thing: some syntax that your system will replace with some meaningful content at the time the email is sent. They differ in the way they are presented to the user.
Merge tags help dynamically insert text into a paragraph, such as the very common scenarios of “Dear {first_name}”.
Merge content, instead, helps the user insert special syntax as content element in other sections of the message that are not text, such a list of recommended products.
Currently it is not possible to group merge tags and merge contents as it is for special links.
Here is an example of adding mergeTags
and mergeContents
in the configuration file:
You can now use the Content Dialog feature to allow users to search for additional Merge Tags and Merge Content, beyond those passed in the configuration file.
Merge tags can be inserted into a text block by clicking on the “Merge tags” button in the expanded text block toolbar. The button is not shown if no merge tags were submitted in the configuration file.
Merge tags also become available to the user by pressing the @ key on the keyboard while editing a text block.
Here is an example: the user wants the date of the last order to be inserted after “[…] placing an order on …”, so he/she presses the @ key and selects “Last order date” from the list of merge tags found by the builder in the configuration file.
After inserting the merge tag, the text block now shows the placeholder for the last order date.
You can load Merge Tags in the builder when it is initialized by adding a mergeTags
node to the JSON configuration file. For example:
… or you can allow users to search and insert a merge tag by using the flexible Content Dialog feature. This is especially useful when the number of merge tags is large, and picking from a list would not provide an optimal user experience.
You can use a combination of both approaches, loading frequently used merge tags at the time the builder is initialized, and then allowing users to look for additional merge tags using Content Dialog.
The syntax used for Merge Tags is entirely up to you. Curly brackets, square brackets, ... you name it. The builder is agnostic to the syntax that your system employs for these dynamic fields. The same is true for Merge Contents.
Merge content differs from merge tags in that it allows the user to drag and drop instances of it as a content element available in the Content panel.
For example, let’s say you have a section of an email where you want to display some recommended products: Merge Content allows you to insert some syntax into the message that your application will replace with the recommended products at the time the email is sent.
When Merge Content elements are submitted to the builder in the configuration file, a new tile is displayed in the Content panel.
The user can drag and drop it into the message just like any other content element.
Once dropped in position, the settings panel will display the instances of merge content available for selection.
In the example below, the user wants to insert some banner ads into the email, using a service such as LiveIntent. An array of Merge Content elements were submitted to the builder in the configuration file, so the user has several banner ads to choose from (i.e. some syntax that will be replaced with HTML when the email is sent).
To create another instance of merge content, the user can either drag and drop it again from the Content tab, or duplicate the existing content element…
… choose another instance of merge content from the available selections…
… and then drag it elsewhere in the message.
Just like with Merge Tags, you can load Merge Content in the builder at the time it is initialized by adding a mergeContents
node to the JSON configuration file. For example:
… or you can allow users to search for additional instances of Merge Content by using the Content Dialog feature.
Here too, you can certainly use a combination of both approaches, loading frequently used Merge Content at the time the builder is initialized, and then allowing users to look for additional Merge Content using Content Dialog.
NOTE: if what you need for your users is a way to load a dynamic image into the message or page (e.g. a countdown clock), you don't need to use Merge Content. Beefree SDK can handle dynamic images with a feature that was created specifically for that task. See: letting your users add dynamic images.
Merge tags are meant to be placeholders that will be replaced at the time an email is sent, or the web content is generated for visitors.
You cannot use HTML code in the text strings passed to the builder because – if you do – it will be encoded and will not function correctly in the source code of the message. Of course, you can replace the tag with HTML code at the time of saving or sending the message.
Standard merge tags do not support sample placeholder content, for now. The syntax will be displayed in the builder as your users design the message or page.
If you want to provide a better experience when working with Merge tags, including using a friendly name instead of the syntax and generating sample content, we recommend to check out Smart merge tags.
Additionally, there are some other limitations that are specific to the Merge Content feature. Among them:
Users cannot see & edit the content: what’s in it, the style used, the layout, etc..
Not seeing it, they could select the wrong content from the list of available Merge Content.
The HTML might be created outside of Beefree SDK, which could lead to rendering issues when it’s inserted into the message.
Since the HTML is created elsewhere, and it’s not part of the document created by Beefree SDK, it must be managed separately.
Due to these additional limitations, we now recommend an alternative approach to Merge Content in order to handle dynamic content in Beefree SDK: utilizing Custom Rows with Merge Content & Display Conditions.
You can use the Content Dialog feature to introduce an interactive layer between the builder and your application, and through it extend Merge Tags, Merge Content, Special Links, and Display Conditions.
This feature is available on Beefree SDK Core plan and above. If you're on the Essentials plan, upgrade a development application for free to try this and other Core-level features.
With Custom Attributes, your end users can easily append additional information to HTML tags in emails and web pages, at the same moment they are creating their content in Beefree SDK. These attributes can be applied to links, both in text blocks and buttons, and images, and they serve a variety of scenarios: personalization, segmentation, styling, accessibility, etc.
Custom attributes enable a wide array of use cases, depending on your application’s capabilities and your users’ needs. Here are a few examples:
flagging specific links so that user activity for those won’t be tracked (e.g. clicktracking="off”
in SendGrid);
handling internal statistical segmentation or reporting (e.g. data-reportingname="October_promo" data-reportingtags="promo,iphone"
);
adding conditions to a single content element (using an attribute such as condition="customer_exists"
);
embedding a single image by adding an attribute like embedded="true"
, processed when the message is sent;
adding custom CSS classes for custom CSS;
adding WAI-ARIA attributes for accessibility requirements.
The host application can provide the editor with a list of attributes that will be available to the user through the UI. How the attribute value is formatted impacts how the builder UI displays it and how the user interacts with it.
Custom attributes can be applied to:
Links in text blocks
Links in buttons
Images (including thumbnails generated by the Video block)
For images and buttons, these attributes will be visible in the editor sidebar, under the new “ATTRIBUTES” section.
For links in text blocks, they will be part of the dialog window for creating a link.
You can provide the editor with a list of attributes that will be available to the user through the UI. How the attribute value is formatted impacts how the builder UI displays it and how the user interacts with it.
Depending on how custom attributes are implemented, users may:
add a custom attribute from a list of attributes already defined, and specify the value of the attribute, if appliable:
from a predefined list
in a text input
defining a boolean property (yes/no, true/false, etc.)
add a “custom” custom attribute by manually specifying both name and value
open an additional interface, through a content dialog, where users have complete freedom on how to build custom attributes.
Regardless of how a custom attribute is added, it will be included in the a
or img
tag when HTML is generated for an email/page, like the segment attribute in this hyperlink:
Custom attributes are a client-side configuration that needs to be passed when initializing the editor. There are different shades of implementation complexity, based on the outcome you want to obtain. These approaches can be combined as preferred.
The easiest implementation is to just pass a simple configuration at startup:
With this setup, users can indicate a “Custom” custom attribute by manually specifying Name and Value. Please note that users must know exactly what they are doing, as there will be no guidance in the editor.
You can pass the necessary custom attributes in the initial configuration. Those attributes will be available in the interface, and the user will be able to specify the value for these attributes, if possible.
Let’s look through the attributes defined in the example above, and how they will look like in the builder.
The Deeplink
attribute has a single, predefined value, so when added in the builder it will look like this:
The Segment
attribute has two possible values, which can be selected by the user:
The Class
attribute has no defined value, so the user can enter anything in a text input:
You can totally customize the UX of adding attributes by invoking a Content Dialog that will take over the editor’s UI. The dialog will need to return the attribute that needs to be applied.
This feature is available on Beefree SDK paid plans only.
You can now customize the list of fonts available in the editor’s text toolbar and the BODY settings panel.
This new feature allows you (or users of your app) to:
Expand the list of available fonts, adding web fonts from popular services, such as Google fonts, font library.org or alike.
Reduce the list of fonts to a limited number of options, removing some or all our default fonts.
Unlike other premium features, fonts are part of the client-side configuration, so they can be defined each time the editor is started.
This flexible approach will help you to use this feature in a variety of scenarios. For example:
You want your users to customize the list of fonts loaded in the builder when they edit designs. You can now create an interface in your app to do so, and instruct the editor accordingly (see below).
You have multiple levels of users, and you want “contributors” to only see a subset of approved fonts, while “editors” have access to a larger list.
You are a digital marketing agency, and you want to customize the list of fonts in the editor depending on the client/brand for which the email message is being designed.
For instance, in our hosted email design suite (Beefree), we leveraged this Beefree SDK feature to create a “Brand styles > Brand fonts” area where an agency or marketing team can select which fonts have been approved by that brand. Only the selected fonts will be loaded in the builder when an application is initialized. Here is a screenshot.
This object, passed as part of the builder configuration, tells the editor which fonts to load in any drop-down where a list of fonts is shown. It defines the availability of the default fonts and provides a list of additional, custom fonts.
In this example default fonts are loaded, and two new fonts are added: a web safe font (Comic Sans) and a Google hosted web font (Lobster).
Here is a more detailed description on how the editorFonts object is built:
When we add a set of custom fonts, we can decide between system fonts and web fonts. Let’s see some details on what you need to know:
System fonts are installed on the operative systems and don’t need any external resource to work, so we can skip the url parameter.
Web fonts are hosted online and need to be loaded by the email client when the email is opened. Beefree SDK accepts only the CSS font embedding method, and the CSS file must be hosted in HTTPS protocol. You can use services like Google fonts, that provides host, font stacks and a well formatted CSS file.
We want the editor to work with only 2 fonts when creating a message, we want that only Lobster and Cabin fonts are available when editing this message:
In the following example, instead, we don’t want to add new fonts but restrict the default ones to our own selection:
Notice that if you want to change the default set of fonts, you need to disable them and use custom fonts to indicate the new set, including the URL parameter for web fonts.
This is the complete list of the default fonts in the application and its configuration, including the external URL for web fonts:
In this example, we want to add font weight options to our list:
We open a saved template that uses fonts that are not available:
System fonts will display normally in the editor and the text can be edited, but the font-family is not available in the font selector.
Web fonts will fallback to a system font. Text can be edited and the font-family is not available on the font selector.
We are able to save the message that already uses unavailable fonts.
With Commenting, teams using your application can collaborate asynchronously on the same email, page or popup, in order to get their work done more quickly and reach approval for going live more efficiently.
When Commenting is enabled, your end-users (or contributors, as we’ll call them in this context) can:
Add a new comment in any content block or row, so that the context of the discussion is always visible;
Reply to an existing comment and start a thread;
Mark existing threads as resolved, and reopen solved threads if necessary.
Copy the text of a comment, and paste it back to the content area
Preview comments by hovering over the comment icon
Automatically highlight the row where a thread is posted
Receive a notification straight in the builder when a new comment is added during a co-editing session (Superpowers users only).
With Commenting, you enable asynchronous, visual collaboration when multiple collaborators are creating, editing, and reviewing content in the Beefree builders. This collaborative feature can prove extremely beneficial in different contexts, regardless if contributors are in the same team, in separate teams, or even in different companies (e.g. digital marketing agencies collaborating with their clients):
have a single source of truth for feedback and requests on the content created with the builders;
cut time-to-publish, reducing back and forth conversations, both online and offline;
get sign-off for going live for email and web campaigns more efficiently.
Commenting – like most other features – is made available to Beefree SDK customers in an OFF state by default, and must be activated in the Beefree SDK Console.
To do so:
Click Details next to the application you want to configure
We recommend you first familiarize with Commenting in a Development or QA application
Learn more about Production vs. Development application here
Click view more under Application configuration.
Toggle Enable commenting ON and click the Save button to activate Commenting for the application.
To activate Commenting when launching your Beefree application, you will need to pass a username
, userHandle
, and a userColor
in the configuration parameters. See this example:
When opening an email, a landing page or a popup, a contributor can add a new comment to a content block or a row by clicking the “Balloon” icon, available in two spots:
in the row or block outline, inside the editing stage
in the header of the Row properties or Content properties
Clicking one of these two icons will activate the commenting panel, which takes over the editor sidebar. From there, the user can insert a new comment. After the first comment, another contributor can start a thread by adding a second comment.
If you have implemented mentions, users can type @ to bring up a list of contributors and tag them in the comment. If the user starts typing, the list will be filtered If you’ve built a notification system around Commenting, you can use this piece of information to trigger a notification towards the mentioned person.
If you added a Content dialog for mentions, the action will be triggered by the button at the end of the list. You will define the CTA for this button as part of the Content dialog configuration (in this case, “Send an invite”).
If there has already been some activity, the editing stage shows whether a content block or row has any comments by displaying a small comment icon. The sidebar instead indicates the number of existing comments for the selected row or content block, three in this case.
Activating the Commenting panel will bring up the thread. In this case, it will show the three comments.
Existing comments can be edited or deleted by the contributor that added them. Contributors may also resolve comments when they have reached a consensus and completed any pending task.
Improved accessibility to in-line threads. Hover the mouse over the comment icon to see a preview of the last comment added.
Clicking on < All comments in the top section will bring up a list of all comment threads, indicating which ones have been resolved and which ones are still open. Contributors can search inside comments and filter out solved threads, or threads that were part of deleted content. Deleted and hidden comments will be filtered automatically.
To go back to the editor sidebar, contributors can close the Commenting panel by clicking the X icon in the upper right, or they can just click on another row or content block in the stage.
Quickly reopen resolved threads by adding a new comment, expand threads with a click, and show a comment thread preview straight from the content area.
Suggest edits in seconds, and save time with the copy/paste feature. Copy text from the comment body and paste it directly into the content area.
If you subscribed to a Superpowers plan, and have co-editing enabled, your users will never lose a new comment again with the new notification system. Users will receive real-time notifications whenever a new comment is added to the document straight in the builder.
By clicking on the notification, they will be able to quickly open the comment, and highlight the element where the conversation is taking place. The toast notification can be styled with custom CSS to match your application look-and-feel.
If you want to learn how to implement co-editing in your application, check the related documentation article here.
With the Reviewer role, you can now allow users to collaborate on your projects without changing the design. This role helps provide peace of mind by allowing inexperienced users to work with the team on their designs, without fear of accidentally changing it.
In short, this new role has the following characteristics:
Can’t apply changes to the message
Can add comments and start threads
Can edit their own comments
Can view other comments
This new role can be easily enabled by passing the following parameter in your configuration:
Once you turn on the feature in the Beefree SDK Console, you may want to disable Commenting for some customers. You can do so via the client-side configuration document that you feed to your Beefree application when initializing the editor.
Why? Because you may 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 Commenting);
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.
Here’s how to do so:
Enable Commenting in the Beefree SDK console, as mentioned above.
Add the configuration parameter commenting to the beeConfig document
Set it to false for all users that cannot comment.
Here is a simple example:
You can build a notification system around commenting by triggering a callback for events in the Commenting layer. When these events happen, the Beefree system triggers the onComment
callback.
You can react to that callback by taking the information provided in it (e.g. the user that created the comment, the text of the comment, any mentioned user, date & time of the comment, etc.) and send notifications.
You are free to define:
which events will trigger a notification
how it is sent (e.g. Email, In-app, Slack, etc.)
what exactly it says
Again, remember that the Beefree platform only triggers the callback, and it’s up to you to react, if you want. Below you can find the technical details on the comments schema and the onComment
callback.
We’ve put together a sample code that illustrates how to send email notifications, triggered by a mention in a comment. This code shows how to:
Define an array to hold the list of mentioned users in the comment payload.
Loop through the comment payload and add any strings matching a regex to the array
Compare each value in the array with the ‘handle’ property of each user (as defined by the host application), to grab the active users
Loop through your array and pull the respective email address for the handle matches (for use in notifications)
Send the notification through email (via ajax), slack, etc… (you decide and implement how to send the notification)
The following JSON is saved as part of the template:
You may want to save multiple copies of a template, e.g. to create a history/revision or a draft feature.
In such cases, you may decide to store the comments in a database, and add the schema back to the template when it’s loaded. Alternatively, you can keep the comments inside the template, and it will become a static part of the history.
Comments can also be added dynamically, but it’s an advanced task, which requires matching the comment schema to the target content by its “elementId”.
When a thread or comment changes, the Beefree system triggers the onComment
callback. The callback returns the following details:
JSON contains all the details on the change
JSON array of the entire comments schema, as described in the previous section.
JSON contains the contributors
array with all users in a thread.
NEW_COMMENT
COMMENT_THREAD_RESOLVED
COMMENT_THREAD_REOPENED
COMMENT_EDITED
COMMENT_DELETED
JSON contains all the details of the change
You can activate a mention dialog for comments by adding a data source to the Beefree application configuration. You can use the “Hooks” data source method to fetch data from your application and pass it to the Beefree system in real-time.
To configure a hook data source, define the hooks
section in your bee config and implement the getMentions
method.
You can also extend the default mention dialog via Content Dialog. For example, you can enable end-users to to invite an external user not available in the data source.
To configure a hook content dialog, define the contentDialog
section in your Beefree application configuration and implement the getMention
method.
You can generate a link to a specific comment, which can be used to notify the user. Common use cases include sending a link via email, Slack, API, or via in-app messaging. To implement this action use the onComment
callback combined with a new instance method called showComment
.
The onComment
callback contains the comment’s id and a new section called “mentions” containing an array of mentioned users’ uid values.
With the uid
, your application can look-up the user’s contact details. The Beefree platform does not track any sensitive information, such as user emails!
Similarly, since mentions can trigger events and the uid
can generate notifications, you can match uid
to userHandle
.
Next, using the comment’s id, your app can generate a link back to the email containing the comment. The new showComment
instance method can be invoked from Beefree’s onLoad
callback to send the user directly to the comment as soon as the editor is fully loaded and ready.
Note: In the sample below, getParameterByName
is a function that takes the commentId
from the browser’s URL query string.
Display conditions allow you to change the content that is shown to a recipient of an email depending on who the recipient is.
Your users will have the ability to pick a condition (or write one from scratch if they are technically savvy), apply it to a row, and thus show different content based on who the recipient (or viewer) is.
The feature provides a number of benefits, including:
Display conditions allow anyone that is using the builder to easily create personalized messages without writing a line of code.
Use whatever syntax your application understands. The feature is language agnostic: it can be used with whatever syntax matches your tech stack. Does your sending engine understand the Liquid markup? Then you can use Liquid. Does it use a proprietary templating language? No problem.
Restrict access to some of the functionality based on user roles. For example, some users may be able to edit the syntax of the conditional statements, while others may not. Use this flexibility to simplify the UI or promote upselling.
As the application hosting the builder, you can now pass an array of conditions.
Those conditions become available for users of the editor to select, assuming the feature is turned on and the user has permissions to apply a condition to a row.
They will do so by browsing through categories or searching by keyword. For example…
The condition that they pick is applied to the row and displayed when the row is selected.
It can be changed (i.e. the user decides to apply another condition) or edited (if the user has the technical skills to do so, and its user role has been granted those permissions).
When the Preview feature is accessed, users can now simulate what recipients in a certain segment will see by toggling Display conditions on and off.
When active, the feature is available to all users by default. You can manage who can see and/or do what by leveraging user roles and permissions.
When the feature is ON, new permissions are available for you to configure when you create or edit a Role.
A basic set up allows you to have 3 user levels:
Can only view & preview
None of the above options are selected
No widget will be shown unless the loaded message has display conditions assigned to one or more rows
If conditions are applied:
They are shown as ready-only
They can be applied in the Preview
Can only select
Only Can select conditions option is selected in the role settings (remove will be automatically selected too)
The widget shows and the user can select and apply any of the conditions specified in the editor configuration
The user cannot add a new condition
The user cannot edit a selected condition
Full control
All permissions are selected
The user can select and edit conditions (if provided) or add a new condition
Note: if there are no Display conditions passed in the configuration, and the user has the rights to access the feature, the editor will only show the Add condition action, which allows users to apply a new condition to a row by manually adding the condition’s syntax.
It’s easy to identify a row to which a display condition has been applied. A bifurcation icon is added to the row’s “Structure” tag, which is shown as you mouse over the row. Here’s an example:
When a default Display condition is edited – by a user that has permissions to do so – it becomes a custom condition. Custom conditions are easy to recognize because:
A blue dot is added next to the condition’s name
The “Change condition” button is no longer available: a custom condition can only be removed
The cancel icon is replaced by a trash button because an edited condition, once remove, is lost: it cannot be re-added.
Why these different behaviors for custom conditions? Because Beefree SDK does not save them to the configuration (you passed that configuration to the application: we don’t have access to the repository where you save that information). So, custom conditions do not exist in the array of conditions that the user can search and/or browse.
Conditional syntax and row content are isolated from each other in the HTML generated by Beefree SDK, so your system can delete, repeat or change elements inside the row without impacting other parts of the message. For example, the HTML of a row might look like this:
Here is an example of a custom builder of Display Conditions.
You may now override the default Beefree SDK language file by providing a URL to your own translations. This is an advanced feature and will replace all languages used by the editor with the languages defined in the custom file.
With Meta Tags, you can now apply various tags to your HTML that can greatly benefit your SEO and accessibility needs.
These Meta Tags include:
Title
Description
Subject
Preheader
Language Attributes
For the Email Builder, Meta Tags promote improved deliverability performance. For the Page Builder, Meta Tags promote greater customization and improved search engine results.
The following image displays the Title and Description fields from within the page builder.
A page title, also known as a Title tag, is a short description of a webpage that appears at the top of a browser window and in SERPs (Search engine results page). This is an important element of an optimized SEO page, as it affects the page ranking in search engines. The title tag will be located within the <title> element of a page’s HTML output, and its value will be saved inside the JSON template.
Here is an example of what a Title Tag inside Beefree SDK’s HTML output might look like:
The description tag is located within the <meta> tag element of a page’s HTML, and it has a limit of 190 characters. The tag will be located within the <meta> element of the page’s HTML output, and its value will be saved inside the JSON template.
Here is an example of what a description tag inside Beefree SDK’s HTML output might look like:
The following code snippet is an example of what the Meta Tags will look like inside the JSON.
The following image displays the Subject and Preheader fields from within the email builder.
The subject field has a maximum of 190 characters. Here is an example of what a subject tag inside Beefree SDK’s HTML output might look like:
The preheader field has a maximum of 130 characters. Here is an example of what a preheader tag inside Beefree SDK’s HTML output might look like:
The following code snippet is an example of what the Meta Tags will look like inside the JSON.
The HTML lang attribute is used to identify the language of text content on the web. This information helps search engines return language-specific results, and it is also used by screen readers that switch language profiles to provide the correct accent and pronunciation for accessibility purposes.
When loading the builder, the host application can specify in the configuration a list of languages for their users to choose from (e.g. en-US), see the example below where the only option “Italian, it-IT” is provided. If there are no values provided via configuration file, a standard list of common languages will be provided.
Here is an example of what a language attribute inside Beefree SDK’s HTML output might look like:
Parameter | Description |
---|---|
This feature is available on Beefree SDK and above. If you're on the Essentials plan, for free to try this and other Core-level features.
Please note that the Display conditions are disabled by default. You can turn this feature on by enabling it under the . You must be on a paid plan (Core subscription and above) to enable this feature.
Reference our to learn more about managing the visibility of the Add Condition and Edit Condition buttons.
You can extend this feature and allow users of the editor to build their own Display Conditions, on the fly, using a UI that you control. It’s part of the functionality. This is an advanced feature that requires some development on the side of the hosting application, but that provides fantastic flexibility.
You can choose one of for the visual builder's UI when initializing the builder. If you want to use custom language strings, however, you will need to use a Custom Language. This feature is available on Beefree SDK and above. If you're on the Essentials plan, upgrade a for free to try this and other Core-level features.
The easiest method to override specific text labels is to , which contains the segments of the language file you want to override.
Check out our Github repository for in all supported languages.
Meta Tags are available for and .
This feature is available on Beefree SDK Superpowers plan and above. If you're on the Core or Essentials plan, upgrade a development application for free to try this and other Superpowers-level features.
This feature allows the host application to pass custom headers when it triggers a call to their services. The custom headers are added to FSP calls and to Custom Rows calls.
For example, this could be useful for the security teams of , which would like to pass a JWT (JSON Web Token) when the user, through the file manager, triggers a call to their Custom File System Provider API.
It may be also be used to protect application or customer-hosted content delivered to the editor, such as custom rows or other host app-specific content. The extra token helps the host application to apply an authentication layer to the contacted endpoints.
To activate this feature, the host application must add a specific element to the Configuration object:
Please note that all custom headers will be prefixed with “X-BEE-“ identifier. For instance, in the example above, the header will be sent to the host app as X-BEE-Authorization
.
Please note that custom headers must be whitelisted by our team before using them. Please open a support ticket via the Beefree SDK Console if you’re planning to use this feature.
showDefaultsFonts
This boolean parameter indicates if the entire list of default fonts is available or not. When the value is false, only the fonts added as custom fonts will be active in the editor.
customFonts
When the default font parameter is true, the custom fonts declared inside this object will be added to the list of default fonts: both are loaded into the editor. Otherwise, only custom fonts will be shown.
Each customFonts
element can have the following properties:
Beefree SDK enables you to customize the appearance of a variety of elements. Reference the following sections to learn more about how you can customize appearance:
This feature is available on Beefree SDK Superpowers plan and above. If you're on the Core or Essentials plan, upgrade a development application for free to try this and other Superpowers-level features.
This feature allows you to have your own file picker for choosing files (images) in Beefree SDK's Editor, to make its integration in your platform look even more seamless. It leverages Beefree SDK’s Content Dialog feature. To set it up you will need to add the corresponding entry to the configuration object:
The handler
function lets you use your own logic to retrieve the desired value, and it has a Promise-like signature.
If data from Beefree SDK is available, it will be sent in the args
parameter (see below). Once the value is available, you must call the resolve(value)
function to pass it to the editor. In case you want to cancel the operation, call the reject()
function.
Please note that a resolve
or reject
call is mandatory. If you miss this step, the editor will remain in waiting mode – and the error management on the host application must call the reject()
function to unblock the editor.
The args
parameter is where the File Picker’s Content Dialog will receive additional data.
Images dragged onto an image block or edited via the “apply effects and more” button will be passed to the image storage per your app’s file storage settings. To prevent images from passing through Beefree SDK’s file storage, the file upload can be disabled via advanced permissions.
Values must use the same pattern used in the configuration object: the returned object is validated against the expected format. If the validation fails, an error will be returned to the browser console, eg: Error getting content filePicker value, the item is malformed
The following is the most basic example, which returns an image URL immediately after clicking the “Browse” button. This example does not open a file picker.
In a real-world scenario, the host application would display a file picker UI and let the user search for and locate the file before finally returning the file’s location (URL) to Beefree SDK:
The following is a list of all modules that are sent as part of the args parameter:
With Advanced permissions, you can tailor permissions for users of your Beefree application by hiding or locking UI elements related to:
content tiles
content settings
layout settings
row & content actions (clone, delete, drag, save)
basically anything in the editor!
These advanced permissions grant total customization of the experience you want to present. Since you set them in the configuration parameters passed to your Beefree app after you’ve initialized it, they could be different each time the editor starts, and have different setups for different users.
You can create roles that can act only on a content type. For example, you may want a “copywriter” role for people in an organization that only need to touch copy for editing or translation purposes. To do so, you can:
hide any action that doesn’t involve working on the copy of an email or page.
limit style options for the text itself, by
locking/hiding the side tab;
hiding specific settings in the text toolbar.
You can limit how users upload and manage images and files inside the plugin; for example, you want some users – e.g., external collaborators – to select pre-approved images and files uploaded by “admin” users. You can do so by:
disabling drag-and-drop of images onto the stage;
When customers of your applications are structured businesses, typically with a headquarter and a locally-deployed organization (e.g., Real Estate, Travel, Retail), their administrators can create custom, secondary roles to match any internal policy they might have. In this scenario, admins typically want to reduce disruptions of centrally-deployed templates for external communication, while allowing a specific degree of freedom.
Initialize different versions of the editor
By combining multiple permissions, you can load the plugin with radically different experiences, based on the user that starts it. For example:
a “stripped-down” version of the content builder for lower-level subscribers;
a “simplified” version of the builder for new users of an account.
To set up the advanced permissions, you will need to add the advancedPermissions
object to beeConfig
:
You can add all the permissions, some of them, or just one. It is up to your application to create them for all users or a segment, as there are no related server-side settings. You may have a different setup each time the editor starts.
All the permissions use a similar pattern, but the object must match the content schema for the type of content (described in the following section).
Each content type below contains a parameter for “behaviors” and “properties”. The behaviors control what someone can, or can’t, do. The properties parameter is an array of sidebar property widgets (e.g., the width slider), and each widget has its default permissions.
All sidebar property widgets (e.g. width slider, alignment, color, etc.) accept the following basic permissions:
Let’s look at an example of these permissions applied to an image module. The following example will hide the image width property widget and lock the text alignment widget. We’ll cover more of the available settings below.
All contents and rows (e.g. image module, video module, stage row, etc.) accept the following basic behaviors:
Let’s look at an example of these behaviors applied to an image module. The following example will hide the image content tile on the sidebar. We’ll cover more of the available settings below.
To assign permissions, you can make use of the addon’s ID. Based on the type of addon, you can assign relevant permissions. For instance, if your addon is an image type, you can assign permissions specific to the image content block. The advanced permissions structure will be as follows:
The following code shows an example config for how you can display or hide these buttons using advanced permissions.
To hide the buttons, set the CanEditDisplayConditions
and CanSelectDisplayConditions
properties to false
.
We’ve put together a few JSON templates of custom roles created with Advanced permissions, so you can get started experimenting with this powerful feature.
You can choose whether to display the builder sidebar on the left or on the right side of the screen.
Available positions:
left
right
Here is the same sample application, with the same template and same content element selected, and the sidebar displayed on the left…
… and on the right.
The configuration document needs the following, new parameter:
Parameter | Description |
---|---|
Modules |
---|
Social Module Icon |
---|
Icons Module Icon |
---|
Text Module Link |
---|
Image module URL |
---|
Title module link |
---|
Row background image URL |
---|
Row background video URL |
---|
Special links: Text module toolbar |
---|
Special links: Sidebar |
---|
This feature is available on Beefree SDK and above. If you're on the Core or Essentials plan, for free to try this and other Superpowers-level features.
The absolute flexibility of these permissions makes it easy to address specific needs, not achievable with the feature that is available in the Beefree SDK Console.
limit actions in the file manager (either the built-in one or your ) by disabling actions like upload, import, and create a folder.
Another interesting case for using advanced permissions is the possibility to set a maximum size for uploads, per user. The maximum size set per user must not exceed the custom limitation size set on the . The default limit is 20 Mb unless otherwise stated. When this permission is configured, the system will check if a file exceeds the set size before uploading it; if so, the plugin will return an error message, which you may customize using .
Name | Type | Value |
---|
Name | Type | Value | Description |
---|
You can choose to display or hide the "Add Condition" and "Edit Condition" buttons when using the with .
You can find them in our
This feature is available on Beefree SDK only.
name
This string will be shown in the font dropdown list. You can use the term you prefer and we suggest the usage of common font names, but you can go creative and use semantic names that fit on your application. Long strings may impact the interface, so we recommend to keep it short. The characters { } [ ] : ” / \ | ? * are invalid.
fontFamily
Describes the CSS font stack that will be applied to the final HTML. Is important that you provide at least one fallback font to ensure that the text is not displayed using an unwanted font family. Is important that you use single quote marks with the font names instead of double quotation marks to maintain a correct JSON syntax.
url
This parameter is used only when we work with web fonts. Is important that the URL points to a CSS file with the @font-face properties, and not directly to the font files. To work, the CSS must be hosted in HTTPS.
fontWeight
Adds a new option in the dropdown of the content block’s settings for title, button, paragraph, and list blocks (e.g. 100: Thin). If not defined, only Regular (400) and Bold (700) will be available.
sidebar.link
buttonModule.link
imageModule.link
iconsModule.link
menuModule.link
socialModule.src
iconsModule.src
textModule.link
imageModule.src
titleModule.link
row.backgroundImage
backgroundVideo.src
toolbar.specialLink
sidebar.specialLink
locked | boolean | true or false |
show | boolean | true or false |
| boolean | true or false | Can select a row or module to edit its properties |
| boolean | true or false | Can drag and drop the content tile or row onto the stage |
| boolean | true or false | Can view the content in the sidebar |
| boolean | true or false | Can clone a content or row on the stage |
| boolean | true or false | Can drag content to another location on the stage |
| boolean | true or false | Can remove the content or row from the stage |
| boolean | true or false | Can reset mobile style for content properties that make use of it |
This feature is available on Beefree SDK paid plans only.
The default Beefree SDK theme is grayscale and generally can be used with any color scheme. In v3, you can now choose between a dark and light theme for the loading animation, so it can better fit the host application’s UI. If you would like to change the loading icon and/or have more granular control of the loading theme, please view our article about using custom CSS.
Available themes:
light
dark
This feature is available on Beefree SDK Core plan and above. If you're on the Essentials plan, upgrade a development application for free to try this and other Core-level features.
The Content Tile Sorting option allows the host application to change the order of the content tiles in the editor’s sidebar. This allows the host application to display the content blocks that are most important for their users first, and even provide additional visibility for a Custom Addon.
To use this feature, the host application must simply pass in the preferred order inside the configuration passed at initialization, like so:
The host application can pass as many or as few content blocks as they want. If only one content tile is specified, then only that content tile will be placed at the top, and the rest of the content tiles will follow the default order.
For Custom/Partner AddOns, the host application passes the “Content Title” value found in the Addon section of the Beefree SDK Console Application Configuration.
This feature is available on Beefree SDK Superpowers plan and above. If you're on the Core or Essentials plan, upgrade a development application for free to try this and other Superpowers-level features.
The Content Tile Grouping option allows the host application to group content tiles in the editor’s sidebar. This allows the host application to display the content blocks into distinct groups.
Content Tile Grouping supports:
Text labels
Special Characters
Emojis
Please note that emoji support may be determined by the OS or browsers used. Some browsers do not support, or may display emojis incorrectly.
To display custom groups, the application must pass the groups settings in the configuration at initialization, like so:
Custom groups can be collapsed and opened by default by changing the collapsable
and collapsedOnLoad
values.
Ungrouped tiles will be gathered at the bottom of the list under a group with no label.
Duplicated tiles are not allowed, e.g., you can’t have a tile twice in the sidebar.
An onWarning
notification is triggered whenever an unknown tile is added to the configuration.
If you want to organize or include AddOns, and Custom AddOns under a custom group, mention the name used in the Beefree SDK Console.
Please note, the AddOn needs to be enabled to appear in the sidebar.
This feature is available on Beefree SDK paid plans only.
With Content Defaults, you can define how content looks when dragged into an email or page.
When adding new content elements through the Content tab, you may want a default style that matches one of these options:
your application’s color scheme;
your user’s branding guidelines;
the look & feel of the template used to create the message or page.
For example, here is how a button dragged into the stage looks by default:
The background color is always light blue (HEX code #3AAEE0).
The font size is always 16px.
The font is Arial, unless a different Default font was set for the template loaded in the editor.
The border radius is set at 4.
The CTA is a formally correct, but laconic “Button”.
Instead, when applying Content defaults, the button dragged by your users could look out of the box like this:
We’ve used a dark grey color (HEX code #555555), an Ubuntu font at 22px in Bold, with a border radius of 10 and a nice “READ MORE” call-to-action.
Content Defaults are part of the Configuration parameters passed to your Beefree application during startup, so you can have different sets of them for different users.
By setting up your Content defaults, you’ll be able to address styling and branding needs for you and your customers.
If your application uses dark grey for the primary CTA, then you probably would want a default button in the Beefree builders to follow that style.
If your application has brand settings that are used for your app’s UI or for assets managed in your application, you may want those to apply also to default content in the Beefree editors.
If you’ve customized how the editor looks like, either through Themes or Custom CSS, you may want default content to adhere to the same style.
Since the Social block is one of the available Content defaults, you can define what social platforms – either present in the Beefree editors or added by you – are included when a social block is added to a message or page. For example, you can have a default social block with three platforms defined in the Beefree system and a fourth, custom one (Messenger):
To set up the content styles you will need to add the contentDefaults
object to beeConfig
:
You can add all the content styles, some of them or just one. It is up to your application to create them for all the users or for a segment, as there are no related server-side settings; basically you can customize them each time the editor starts.
All the contents use the same pattern, but the object must match the content schema for the type of content (described in the following section).