Passing Configurations to Beefree SDK

Once you have initialized your Beefree SDK application, you can pass a series of configuration parameters to it.

The following code displays an example of a default configuration:

var beeConfig = {
    uid: 'CmsUserName', // [mandatory]
    container: 'bee-plugin-container', // [mandatory]
    autosave: 30, // [optional, default:false]
    language: 'en-US', // [optional, default:'en-US']
    trackChanges: true, // [optional, default: false] 
    specialLinks: specialLinks, // [optional, default:[]] 
    mergeTags: mergeTags, // [optional, default:[]]
    mergeContents: mergeContents, // [optional, default:[]]
    preventClose: false, // [optional, default:false]
    editorFonts : {}, // [optional, default: see description]
    contentDialog : {}, // [optional, default: see description]
    defaultForm : {}, // [optional, default: {}]
    roleHash : "", // [optional, default: ""]
    rowDisplayConditions : {}, // [optional, default: {}]
    rowsConfiguration: {},
    workspace: { // [optional, default: {type : 'default'}]
        editSingleRow: false // [optional, default: false]},
    },
    commenting: false, // [optional, default: false]}
    commentingThreadPreview: true, // [optional, default: true]}
    commentingNotifications: true, // [optional, default: true]}
    disableLinkSanitize: true, // [optional, default: false]}
    loadingSpinnerDisableOnSave: false, // [optional, default: false]}
    loadingSpinnerDisableOnDialog: true, // [optional, default: false]}
    onSave: function(jsonFile, htmlFile) { /* Implements function for save */ }, // [optional]
    onChange: function(jsonFile, response) { /* Implements function for change */ }, // [optional]
    onSaveAsTemplate: function(jsonFile) { /* Implements function for save as template (only JSON file) */ }, // [optional]
    onAutoSave: function(jsonFile) { /* Implements function for auto save */ }, // [optional]
    onSend: function(htmlFile) { /* Implements function to send the message */ }, // [optional]
    onLoad: function(jsonFile) { /* Implements function to perform an action once the template is loaded */}, // [optional]
    onError: function(errorMessage) { /* Implements function to handle error messages */ }, // [optional]
    onWarning: function(alertMessage) { /* Implements function to handle error messages */ }, // [optional]
    debug: {
        all: true,                 // Enables all debug features listed below
        inspectJson: true,        // Enables an eye icon on the module/row toolbar to inspect specific JSON portions
        showTranslationKeys: true // Shows translation keys instead of localized strings
    },
    translations: {
        'bee-common-widget-bar': {
            content: 'MODULES',
        },
        // additional translations...
    },
    // other properties...
};

Parameters

The following table provides a list of the required parameters.

Language Parameter

The following table provides a list of the language options for the language parameter. The language parameter is not required and has a default value of en-US.

Available Languages

Parameters

The following table provides a list of the optional parameters and their corresponding descriptions.

Overview

This article will cover steps for the following processes:

Sign up for account in the Developer Console

2. Complete the required information to sign up or login.

   You will be redirected to the dashboard.

3. In the dashboard, click Add new subscription.

   You will be redirected to a page that asks you to provide a name for your new subscription.

4. Type in a name and click Next.

   You will be redirected to a page that asks you to select a subscription plan. If you'd like to subscribe to the Free version, click on the corresponding Select plan button Free plan type. If you'd like to subscribe to a paid plan, select the paid option that works best for your needs.

5. A confirmation message will appear confirming that you selected the Free plan and that you will not be charged anything. Click Confirm to confirm your subscription the the free plan.
6. While the plan is free, ensure that you familiarize yourself with the scenarios in which charges would apply. The following image shows a plan summary displaying instances of when charges apply.

1. Enter and confirm your billing address.

2. Enter and confirm your card information by clicking Place Order.

   You will be redirected your new Free plan subscription.

How to create an application

You will have the option to activate any or all of the following applications:

Take the following steps to create an application:

1. Click the Activate button that corresponds with the application you'd like to create.

2. Type in a name for your new application.

3. Click Create.

Your application will look like the following in the dashboard once it is activated:

You have successfully created an application. Now, you can enter the application Details and obtain your Client ID and Client Secret.

Obtain your Client ID and Client Secret

Click on your application's Details button to view your Client ID and Client Secret. Use these to authenticate when you initialize it.

Reference the following related topics to learn more about customizing your applications, creating development instances, and referencing sample code.

Regenerate Client Secrets

Inside the Beefree Developer Console, you have the option to regenerate the Client Secret for your application. To regenerate your application's Client Secret, take the following steps:

2. Navigate to the application you'd like to update the Client Secret for.

3. Click on the application's Details button.

1. Navigate to Application keys within the application's details.

2. Click Regenerate to generate a new Client Secret.

1. You will be prompted to a modal and asked to confirm your application's name.

2. Complete the App Name field and click Regenerate to complete the action.

Your new Client Secret is now available and ready to use. Your old Client Secret will expire 24 hours after creating the new one. Ensure you replace it in all the necessary environments prior to its expiration.

Overview

Use cases

With this event, you can make on-the-fly changes to the user experience. For example:

How it works

You can load the configuration changes via a new instance event. Here’s an example:

var newConfig = {
  advancedPermissions: {
    // new permissions
  }
}

bee.loadConfig(newConfig)

What is Beefree SDK?

• Template catalog: A design template catalog that integrates industry best practices to support end users in quickly getting across the finish line with their creations and achieving quick design wins.

• AI Writing Assistant: A helpful AI assistant to help end users write their design content.

Quick Start

Take the following steps to get started with Beefree SDK in a few minutes:

5. Add your credentials, the Client ID and Client Secret from step three, inside the placeholders in the code.

Beefree SDK's Embeddable Builders

Learn more about our three embeddable builders.

File Manager

Customize Your Application with AddOns

Learn more about how our builder AddOns can help you customize your application's offerings.

Content Services API and Template Catalog API

The Template Catalog API enables you to incorporate design templates into your application. With this API, you can browse, retrieve, and utilize a variety of pre-designed templates to enhance your user's content creation experience. It gives you the flexibility to offer customized design solutions directly within your platform.

Sample Code

Browse our sample code to experiment and gain hands-on experience. Get up and running quickly with a simple implementation.

Developer Essentials

About this documentation

These products share the same, unique combination of design flexibility and ease of use. Note that the majority of the documentation applies to all builders (and in many cases to the File Manger too), unless otherwise specified.

Instance Methods

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:

Instance Events

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.

Authorization Process Overview

Beefree SDK Client-side Configuration

Beefree SDK Server-side Login

The Beefree SDK system uses OAuth2 as the authorization framework.

Example

The following code sample displays an example JSON response.

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. Beefree SDK will trigger the onError callback when the token can't be refreshed automatically.

The following code sample displays an example of how to call the Beefree SDK endpoint, obtain a token, and then start it.

Ensure to call the authorization endpoint server-side to protect your credentials.

Beefree SDK will keep this session alive for 12 hours from the login. After 12 hours, you have to manage the token expiration, as follows:

1. Obtain a new token via the new authorization endpoint.

2. Inject the token obtained from step one via the updateToken method. Reference examples of this in the following section.

The following code example shows how to inject the token in the current Beefree SDK instance:

The following code example displays how to get the current JSON from the expiration error:

Error Management

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.

Handling error management

The following code samples display how to handle the 5101 and 5102 errors.

Error Responses

Example error response for unsupported media type Only Content-Type: application/json is allowed.

Example error response for disabled apps. Contact support if you encounter this error.

Manage users in the 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.

Properties

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.

Unique identifier

It uniquely identifies a user of the application. When we say “uniquely”, we mean that:

2. 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).

Users, sub-users and client accounts

It’s entirely up to you, as the host application, to determine 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.

Development Applications

uid: 'test1-clientside' // production uid and development application uid

A prototype in 2 minutes

Using this simple, client-side example, you can literally try out Beefree SDK in 2 minutes…

2. Create a new application: you will find your keys in the project’s details page

4. Open index.html with your favorite code editor

5. Locate client_id and replace “YOUR_CLIENT_ID” with yours

6. Locate client_secret and replace “YOUR_CLIENT_SECRET” with yours

7. Save the file

Embedding the builder

Before using the code samples listed below in a production environment, please consider the following:

2. The client-side sample is not safe for a production environment (it was conceived as a quick way for you to test the application). Someone would be able to easily steal your application credentials (just viewing the source code of the page). To keep those credentials safe, authorization must be managed sever-side, as the .NET sample does.

3. These code samples use a limited set of features and configurations: they can be a good starting point to start developing around Beefree SDK, but they are not an exhaustive showcase of everything you can do.

4. All sample code is provided “as is”: it may contain defects, it may not follow best practices (although we try to!), and it should only be considered as point of reference.

GitHub Repositories

Overview

A Release Candidate (RC) Environment is a crucial part of the deployment workflow designed to provide Enterprise customers with additional stability and assurance before a feature reaches full production. Unlike standard releases, which immediately roll out updates to all users, the RC environment acts as an intermediate step. It allows selected customers to access a production-ready version of the latest code before it becomes available to the wider user base. This controlled rollout process mitigates risks associated with unforeseen bugs and ensures a smoother transition. It also mitigates the risk of regressions and rollbacks. By implementing an RC environment, Beefree SDK enables Enterprise customers to conduct their own QA testing on new features, reducing potential disruptions when updates go live.

Benefits of the Release Candidate Environment

The following list includes some of the most commonly referenced benefits of utilizing the Release Candidate Environment.

• Risk Mitigation: Enterprise customers can validate new updates in a stable, production-like setting before they are fully deployed.

• Enhanced Quality Assurance: QA teams can test features in real-world scenarios, catching regressions before broader release.

• Predictable Deployment Schedule: A structured release cadence (RC → General → Delayed) ensures smoother rollouts with fewer surprises.

• Reduced Need for Rollbacks: The phased approach minimizes critical failures in production, lessening the necessity for emergency rollbacks.

• Customer Control: Enterprise customers have additional time to adjust workflows and prepare internal documentation before full adoption.

How the Release Candidate Environment Works

The RC environment operates within a structured release cycle, ensuring that new updates are progressively introduced. When a new feature is ready for release, it is first deployed to the RC environment. Only Developer applications linked to the RC version can access this release. After a one week waiting period—assuming no major regressions are found—the update moves to the stable version, making it available to non-Enterprise customers. After a week, the update reaches the Delayed version, which is linked to Enterprise Production applications. This phased approach ensures that issues are detected early while maintaining a predictable release schedule.

Requirements for Accessing the Release Candidate Environment

Reference the following requirements for accessing the Release Candidate Environment prior to getting started with it.

• Only available to Enterprise plan customers with Developer applications.

• Customers must be aware that while the RC version is production-ready, it is still subject to final testing and potential bug fixes.

How to Use the Release Candidate Environment

This section discusses how to access the release candidate environment and use it.

Instructions

To get the HTML version of a Beefree SDK message in the Release Candidate (RC) environment, you will need the following:

1. The Beefree SDK Support Team will provide you with a username and password (we will need a user’s email address to enable this).

2. A Beefree SDK JSON source file.

3. The ability to perform a call to a REST API. You can do that in different ways:

   • Applications like Postman or Insomnia

   • Use the “curl” command in a shell

   • With a custom script

The call should be addressed to one of the following endpoints, depending on the HTML output that you wish to receive back:

• https://stg-bee-multiparser.getbee.io/api/v3/parser/email - To receive HTML for Email

• https://stg-bee-multiparser.getbee.io/api/v3/parser/pages - To receive HTML for Webpages

• https://stg-bee-multiparser.getbee.io/api/v3/parser/amp4email - To receive AMP for Email

• https://stg-bee-multiparser.getbee.io/api/v3/parser/popup - To receive HTML for Popups

• https://stg-bee-multiparser.getbee.io/api/v3/parser/text - To receive the plain text version of the message

Additional Requirements

Reference the following additional requirements for using the Release Candidate Environment.

• It has to be a POST call.

• The Beefree SDK JSON has to be sent in the body of the REST call.

• It must include a Basic Authentication header in which you specify your username and password.

Upon success, the body of the response will contain the desired output. In case of an error, the response's body will contain the error details.

Please do not use this method in production. This is an RC environment, and it may change its behavior in the future.

Example

curl --request POST \
--url "https://stg-bee-multiparser.getbee.io/api/v3/parser/email" \
--user "USERNAME:PASSWORD" \
--header "Content-Type: application/json" \
--data @"JSON_FILE.json" \
--output "OUTPUT.html"

Legenda

The following fields are required in the example above.

• USERNAME and PASSWORD are your credentials provided by the Beefree SDK team.

• JSON_FILE.json is the Beefree SDK source file.

• OUTPUT.html is the desired output file.

Additional Considerations

The Release Candidate Environment is specifically designed for frontend features, the JSON-to-HTML parser, and the JSON Bumper. Backend services are not currently covered under this process. Bug fixes, while critical, may bypass the RC process when necessary to expedite resolutions. By adopting the Release Candidate process, Beefree SDK provides Enterprise customers with greater predictability, quality assurance, and peace of mind in managing their integrations.

Introduction

Beefree SDK’s embeddable no-code email builder offers a solution that empowers creators to design visually striking, high-converting emails with ease. By removing technical barriers, it enables teams to build, customize, and launch campaigns faster, maximizing results without the need for hard coding. This allows marketers, designers, and content creators to focus more on designing and refining their email strategies, rather than spending time coding emails from scratch.

What is the Email builder?

The email builder within Beefree SDK is a no-code drag-and-drop editor that enables end users to design beautiful emails that resonate with their audiences. Within the email builder, end users have access to both simple email creation tools, such as adding content blocks, and advanced email creation tools, such as dynamic content, merge tags, display conditions, html blocks, and so on. Beefree SDK’s email builder was created with email marketers, copywriters, designers, and other content creators in mind. It provides them with an environment to intuitively create emails without having to write a single line of code, while being able to easily export their design’s HTML code if they ever need it. Overall, Beefree SDK’s email builder democratizes the email creation process by providing a no-code route for your application’s end users to create visually stunning and appealing emails for their audiences.

In the following GIF, you can see an example of differently customized experiences.

Email builder capabilities

On a foundational level, the Email builder includes the capabilities detailed in the following table.

Test out the Email builder

There are various tools you can use to experiment with and test out the Email builder to learn more about it.

The following resources are a great start to learn more:

• • You do not need a Client ID or Client Secret to experiment with the Email builder in this environment.

• • You do not need a Client ID or Client Secret to experiment with the Email builder in this environment.

Integrate the Email builder

To integrate the Email builder, take the following steps:

3. Obtain your Client ID and Client Secret

4. Authenticate

Add JavaScript Library

Introduction

Beefree SDK is an embeddable no-code content builder that enables your end users to build stunning marketing assets, such as emails, landing pages, and popups, without writing a single line of code.

The following list includes a few key features within Beefree SDK:

• Drag-and-drop visual editors

• File manager

• Multi-user collaboration

• Responsive design capabilities

• Extensive template library

• Secure authentication workflow

This guide provides comprehensive instructions and best practices for implementing Beefree SDK.

Getting Started

This section discusses how to get started with Beefree SDK.

Prerequisites

Prior to integrating Beefree SDK, ensure you have:

2. Node.js (v14 or higher) installed.

3. A modern web browser (Chrome, Firefox, Safari, Edge).

Local Development Setup

To test the SDK locally before production deployment:

1. Clone the demo repository:
2. Install dependencies:
3. Configure environment:
4. Start the dev server:
5. Access at http://localhost:8081

Package Installation

Using npm

Using Yarn

Package Details:

• TypeScript Support: Included

• License: Apache-2.0

Authentication Process

This section discusses the authentication process.

Server-Side Authentication

The secure authentication flow requires a server-to-server call to obtain a JWT token. This process ensures your client credentials remain protected.

Authentication Endpoint

Required Parameters

The following table lists and descibes the required authentication parameters.

Example Implementation (Node.js)

JSON Authorization Response

Beefree SDK Initialization

This section discusses how to initialize Beefree SDK.

Container Setup

Create a container element in your HTML where the editor will render:

Configuration Options

Beefree SDK requires a configuration object with the following essential property:

Full Configuration Reference

The following table explains the container property.

Working with Templates

Loading a Template

Initialize the editor with a template JSON object:

Template Management Methods

The following table lists template management methods that are important for getting started.

Advanced Features

Token Refresh Implementation

Implement automatic token refresh to maintain uninterrupted sessions:

How to use:

1. Get a fresh token from your backend

2. Pass it to updateToken()

Collaborative Editing

Enable real-time collaboration with these additional methods:

How to use:

1. Generate a unique session-id on your server

2. Call join() with the same ID for all collaborators

Troubleshooting

The following list includes the most common issues and steps for troubleshooting them.

• Authentication Failures

  • Verify client_id and client_secret

  • Ensure UID matches between auth and config

  • Check network connectivity to auth.getbee.io

• Editor Not Loading

  • Confirm container element exists

  • Verify container ID matches config

  • Check for JavaScript errors in console

• Token Expiration Issues

  • Implement onTokenExpired callback

  • Test token refresh flow

Frequently Asked Questions

Q: Can I use the SDK without server-side authentication? A: While possible for testing, production implementations must use server-side auth for security.

Q: How do I customize the editor's appearance? A: The SDK supports UI customization through configuration options. Refer to the advanced documentation.

Q: What happens when the token expires? A: When your token expires after 12 hours:

1. The editor will become unresponsive

2. You must proactively:
3. Best practice is to refresh tokens before expiration (recommended at 11 hours)

Conclusion

This comprehensive guide covers all aspects of Beefree SDK integration, from initial setup to advanced features.

Remember to:

• Always use server-side authentication

• Implement proper token refresh logic

• Test thoroughly before production deployment

• Monitor for SDK updates and new features

Overview

When 2FA is set up, users will need to:

• use their device and the app to generate a token and log in.

Setup for Account owners

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.

Setup for Account admins

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.

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.

Embedded

The Embedded mode allows video playback inside the page. It requires the URL of a video hosted on YouTube, YouTube Shorts, or Vimeo.

Hosted video

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.

Thumbnail

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.

Supported Video Sources

• 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)

Overview

How to Use

You can pass the debug parameter directly in your beeConfig object when initializing the editor. Alternatively, you can set or update it live using the loadConfig method—no need to refresh the editor.

Example (in beeConfig):

const beeConfig = {
  debug: {
    all: true,                 // Enables all debug features
    inspectJson: true,        // Shows an eye icon to inspect JSON data for rows/modules
    showTranslationKeys: true // Displays translation keys instead of localized strings
  }
};

Set it live (no refresh needed):

beeInstance.loadConfig({
  debug: {
    all: true
  }
});

Parameters

The debug parameter in the Beefree SDK configuration accepts the following parameters:

• all (boolean): Enables all available debug options (inspectJson and showTranslationKeys). Use this during heavy debugging sessions.

When It's Useful

The debug parameter is particularly helpful in the following scenarios:

• You're troubleshooting UI rendering issues tied to configuration JSON.

• You need to inspect what exact data is being used for rows/modules.

• You're working on translations and want to ensure correct keys are being used.

Overview

Frequently used terms

• 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.

Development Applications

Development applications are available with any Beefree SDK paid plan.

What is a Development Application?

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.

How to Create a Development Application

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. Development applications are only available on paid plans.

To create a development application, take the following steps:

1. Create a new application

1. Navigate to your dashboard where the new application is located

2. Click the + next to Add a development instance

1. Type in the name of your development application, for example “development environment” or “QA environment”

1. Click Create

2. View the new development application available in your Beefree SDK dashboard

Benefits of Development Applications

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.

• Create as many child development applications linked to your parent production environment as you’d like.

Important Considerations

Consider the information outlined in this section when working with development applications.

Testing next-tier features in your development application

Beefree SDK lets you explore higher-tier features in your development environment for testing purposes. However, these features cannot be deployed to production unless they are included in your current subscription plan.

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.

Usage-based fees on development applications

Overview

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!

Available workspaces

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.

Starting the builder with a workspace

Here is an example of loading Beefree SDK with a “mixed” workspace:

type ClientConfig = {
  workspace?: {
    type:'default'|'mixed'|'amp_only'|'html_only'
  }
  // ....
}

const beeConfig: ClientConfig = {
  workspace:{
    type:'mixed'
  }
  // ....
}


//Create the instance 
function BeePlugin.create(token, beeConfig, (beePluginInstance) => { 
  //.... 
}

Switching workspaces

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:

{
  "type":"mixed"
}

Then, you can load those workspaces at runtime:

type Workspace = 'default'|'mixed'|'amp_only'|'html_only'

const req = url => fetch(url).then(r => r.json())
const loadWorkspace = async (workspace:Workspace) => {
  const { type } = await req(`https://example.com/workspaces/${workspace}.json`)
  beePluginInstance.loadWorkspace(type) 
}

And here is how to create a simple select to switch workspace:

<select id="workspace" onchange="loadWorkspace(this.value)">
<option selected="selected" value="">WORKSPACE</option>
<option value="default">DEFAULT</option>
<option value="mixed">MIXED</option>
<option value="amp_only">AMP_ONLY</option>
<option value="html_only">HTML_ONLY</option>
</select>

Workspace callbacks

After you load a workspace, the application will trigger one of these three callbacks:

Success

//SUCCESS 
onLoadWorkspace: function (workspace) {
  console.log(`workspace: ${workspace} has been loaded`);
},

Failure

//FAILURE
onError: function (error) {
 console.error('error: ', error);
},

Invalid workspace

{
 code: 1400, 
 name: "Invalid workspace type",
 message: "RANDOM : is not a valid workspace",
 details: "Available workspaces are: [ default,mixed,amp_only,html_only ]"
}

Use cases

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.

• 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.

Manage Subscriptions in the Console

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.

How to Add a New Subscription

You can create an additional subscription within the Beefree SDK Developer Console.

To achieve this, take the following steps:

2. Navigate to your dashboard

3. Click Add new subscription on the upper right-hand side of the screen

4. Type a name for your next subscription and click Next

5. Choose a plan and click Select plan

6. Confirm the plan you selected

7. Finalize your additional subscription

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.

Why Popups?

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.).

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;

Sample workflow

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.

Main features

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.

What you see is what you get...finally for Popups

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.

Designed to fit any configuration workflow

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.

Ready-to-go HTML output

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.

Drop personalized content in popups, in minutes

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.

Speed up the creation process with shared and pre-made assets

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.

Overview

Integration

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.

The Basics

Let’s start by looking at some of the differences between Page Builder and Popup Builder.

• Content Width

• HTML output

Content Width

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.

HTML Output (HTML Partials)

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.

Popup workspace

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!

Common settings

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!

Popup default layouts

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:

Popup default themes

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:

Content area width

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.

Creating an application

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.

Integrating the Popup Builder

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.

HTML output

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.

Developer resources

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.

Overview

Headless Template Creation with AI

• An AI model receives the description and generates a Simple Schema-compatible template.

• This template is passed to the /v1/conversion/simple-to-full-json API endpoint.

• The API returns the complete Beefree JSON for the entire template.

• The template is loaded in the builder, and the end user can start applying edits in a no-code environment.

The following image displays an example UI with a basic AI Email Design Assistant that connects to Simple Schema on the backend. By building your own UI and AI agent, you can leverage Simple Schema on the backend to programmatically build templates and load them in the Beefree SDK builder for your end users to use.

In the following image, the programmatically-created email template is loaded within the Beefree SDK builder, and ready for editing.

Benefits

• AI-ready: A simplified format perfect for machine-generated layouts.

• Headless by default: Build and deploy templates entirely outside the visual builder.

• Production-ready: Easily convert to Beefree JSON with a single API call.

• Efficient: Reduced payload size and faster AI generation.

Simple to Full JSON API Endpoint

This endpoint is essential for converting AI-generated or manually assembled Simple Schema templates into full, builder-compatible Beefree JSON. Learn more about how to use this endpoint in the Content Services API Reference.

Width settings

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:

workspace: {
  popup: {
    contentWidth: 600,
    contentWidthMobile: 300
  }
}

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.

Layout settings

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!

Changing the background

You can easily change the background to make the workspace look like the destination page where your customer will embed the popup.

beeConfig: {
  ...
  workspace: {
    popup: {
      backgroundImage: 'https://.../background.png',
      backgroundImageMobile: 'https://.../background.png',
      ...
    }
  }
}

Applying a preset layout

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.

beeConfig: {
  ...
  workspace: {
    popup: {
      layout: 'bar-top'
    }
  }
}

Here is a complete list of preset layouts:

Building web pages with 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.

Integrating and Testing the Page Builder

The experience

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.

Additional resources

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.

Overview of Tracking Message Changes

This page explores and answers the following questions:

• How can I monitor what my customers do in the builder?

• How can I tell when a message has actually been updated?

Use cases

This section discusses use cases for tracking message changes.

Usage tracking

In today’s software, knowing how customers use an application is essential if you want to provide a good user experience (UX) and eliminate friction points. It’s also a valuable resource to understand where to invest future development effort and build something that customers love.

onChange tracking gives you – the host application – the opportunity to get this information when your customers are creating designs in the builder.

You can use the onChange callback to:

• Understand if your customers are actively working on the message they opened (or if instead they temporarily abandoned that task to work on something else).

• Discover if they are using one of the great new features that your team recently enabled.

• Dismiss or confirm a bug by reproducing a customer’s steps.

Autosave

Now you can invoke the Autosave event only when something has been added or updated, resulting in a better message recovery experience.

History

Why is having a historical log of message changes so important? As with the previous cases, this will allow you to provide a better overall user experience. Creating a good email message or campaign typically involves input from several people or departments before it’s finally ready to send, but that can lead to inadvertent mistakes that might cause hours of work to be lost. Saving the differences between versions of a message created during the email production workflow – and allowing your users to compare & restore them – could be a huge time-saver in those cases.

Content check

When one of your users adds or updates text or images, the onChange callback returns the new input to your application, allowing you to trigger a complementary function based on it.

The use cases change from application-to-application, but the feature is flexible enough to accommodate a wide variety of scenarios. Here are just a few:

• Content suggestions

• Prevent unwanted content

• Link validation

• Link reputation check

• Custom HTML validation

• Set up an alternative workflow when conditional syntax is applied

• …

How it works

When you enable onChange and your end users edit their message, the callback provides you with:

• Information on the new content or section

• The action that was performed on existing content

• The JSON update (as the entire page, as well as JSON patches)

Prerequisites

• Add trackChanges and set it to true.

• The onChange callback, with the related response function.

Enable "onChange" Event

The following code provides an example callback function for onChange.

onRemoteChange

Consider the following when using the onRemoteChange callback:

The following code provides an example callback function for onRemoteChange.

Configure onChange and onRemoteChange

This section discusses how to configure onChange and onRemoteChange.

This parameter defines when the tracking is active in the builder.

onChange Event

The onChange callback is triggered every time the builder tracks a change in the message. It returns the message JSON and a response JSON which contains all the information needed to handle any of the use cases described above.

Callback response schema

Callback Parameters

The following table lists the parameters in the onChange and onRemoteChange callback response schema and their corresponding types and values.

Content Codes

Common Actions

Complete Event Chart

Beefree SDK API Offering

Beefree SDK includes a comprehensive API offering designed to expand upon the builder's capabilities. By leveraging Beefree SDK's APIs, you can extend the builder's functionality into other aspects of your application.

Beefree SDK's API offering includes three APIs. They are the following: