Add JavaScript Library

NPM

Use the command npm i @beefree.io/sdk to install the Beefree SDK library into your project.

npm i @beefree.io/sdk

Initialize the application

Take the steps outlined in this section to initialize your application.

Step 1. Create a container

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:

<div id="bee-plugin-container"></div>

Step 2. Authentication

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.

Authentication Code Samples

var req = new XMLHttpRequest();
req.onreadystatechange = function() {
  if (req.readyState === 4 && req.status === 200) {
    // Obtain token
    var token = req.responseText;
    // Call create method and pass token and beeConfig to obtain an instance of BEE Plugin
    BeePlugin.create(token, beeConfig, function(beePluginInstance) {
	// Call start method of bee plugin instance
	beePluginInstance.start(template); // template is the json to be loaded in BEE
    });
  }
};

// This is a sample call to YOUR server side application that calls the loginV2 endpoint on BEE the side
req.open(
	'POST', 	// Method
	'/YOUR_BACKEND_TOKEN_ENDPOINT', // your server endpoint
	false 		// sync request
);

JSON Authorization Response

{
    "access_token": "...",
    "v2": true
}

Step 3. Create an application

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:

// Define a global variable to reference the application instance
// Tip: Later, you can call API methods on this instance, e.g. bee.load(template)
var bee;
 
// Define a simple Beefree SDK application configuration...
var config = {
    uid: 'string',
    container: 'string'
}

// Call the "create" method:
// Tip:  window.BeePlugin is created automatically by the library...
window.BeePlugin.create(token, config, function(instance) {
    bee = instance;
    // You may now use this instance...
});

Step 4. Start the application

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:

var template = { ... }; // Any valid template, as JSON object
 
bee.start(template);

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.

What is Beefree SDK?

Beefree SDK is a toolkit that offers a comprehensive set of features to enable your application's end users to achieve their design goals. Through embedding Beefree SDK into your application, you'll provide your end users with access to a full suite of design features that include the following and more:

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.

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

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. This will make the functionality accessible to you.

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 without any additional costs

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

Important Considerations

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.

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)

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.

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.

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.

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.

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

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.

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)

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]}
    maxRowsDisplayed: 35, // // [optional, set this to any number to define the maximum number of rows that a category should display]}
    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]
    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

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.

Instead, if 2FA is ON at the account level, admins cannot turn it off from the “Profile” page and must contact their account owner.

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:

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.

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.

Here is a complete list of preset layouts:

Overview

We added a new function to track message changes in the builder. This powerful new feature answers two important questions:

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

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

When onChange is enabled and your customers edit their message – the callback provides you valuable information on the new content or section, the kind of action that was performed on existing content, and the JSON update (as the entire page, as well as JSON patches).

Use cases

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

• The configuration option

• The onChange callback, with the related response function

Configuration

Enable "onChange" Event

trackChanges: true, // boolean

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

onChange Event

onChange: function (jsonFile, response) { // do something with response... },

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

{
    "code": "01", // See content and action codes bellow
    "description": "string",
    "value": "string", // See the chart below
    "patches": {...} // JSON patch formatted object
}

Callback Parameters

Content Codes

Common Actions

Complete Event Chart

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 of Form Block

The Form Block within Beefree SDK allows you to easily create and integrate customizable forms into your application. This feature is particularly useful for capturing user information, feedback, and other data directly through interactive forms. With various pre-built templates and customization options, the Form Block is easy to integrate for developers and intuitive to use for end users.

The Form Block supports a wide range of input types, such as text fields, radio buttons, checkboxes, and dropdown menus. This flexibility ensures that end users can gather the exact type of information they need from the form. Additionally, form submissions can be easily configured to trigger actions, such as email notifications or data storage, providing a robust and integrated data collection solution.

Learn more about to use and integrate Form Block in the following section:

Providing forms

You can load forms in the builder with two methods:

If you successfully implement either method, you’ll see a new Form content tile in the builder Content tab.

Let’s see in detail how these methods work.

Default form in starting configuration

defaultForm: {
  // Form
},

The default form will load when the user drags the form tile from the “Content” tab into the stage.

Here is an example of a typical login form:

defaultForm: {
  structure: {
    title: 'Form title',
    fields: {
      email: {type: 'email', label: 'Email'},
      password: {type: 'password', label: 'Password'},
      submit: {type: 'submit', label: ' ', attributes: {value: 'Login'}},
    },
    layout: [
      ['email', 'password', 'submit']
    ]
  }
},

The default form you pass to a Beefree SDK application may consist of a simple form (e.g., the most used one), or a longer form that the user can customize using the options in the form content properties, as pictured here:

The flexibility of these properties allows you to cover multiple form building capabilities, even when implementing just a default form. Let’s see how.

For higher flexibility and better user experience, the form can be customized with the optional canBeModified, canBeRemovedFromLayout, and removeFromLayout attributes.

Disable editing for a field

This attribute can be used to turn off the “Edit field” dialog for a field. If set to false, the configuration for that field will be locked to the one defined in the form JSON you passed to the application, except for the label.

If unspecified, it will be applied as true, allowing the user to edit the field using the builder UI.

Indicate when a field can be toggled off

This attribute indicates that a field can be toggled off by the user. If unspecified, it will be applied as true, allowing the user to switch it on or off in the builder UI.

It’s a best practice to add canBeRemovedFromLayout: false to mandatory fields (e.g., the email address field in a sign-up form) so that they can’t be excluded in the HTML form.

Toggle off a field when loading a form

This attribute indicates that a field is toggled off by default when the form is loaded. This behavior is quite useful to simplify the first experience when working with forms:

1. you can use a single form with all the possible fields, so there is no form selection step;

2. you can hide less common fields to load the most used combination at first, and keep the starting point simple, or even empty;

3. the user than can explore available fields with the form properites and build their custom form

Here is an example:

defaultForm: {
    "structure": {
        "fields": {
            "name": {
                "type": "text",
                "label": "Name",
                "removeFromLayout": true,
                "canBeRemovedFromLayout": true
            },
            "surname": {
                "type": "text",
                "label": "Surname",
                "removeFromLayout": true,
                "canBeRemovedFromLayout": true,
            },
            "email": {
                "type": "email",
                "label": "Email *",
                "canBeRemovedFromLayout": false,
                "attributes": {
                    "required": true
                }
            },
            "notes": {
                "type": "textarea",
                "label": "Notes",
                "removeFromLayout": true,
                "canBeRemovedFromLayout": true
            },
			"privacy": {
                "type": "checkbox",
                "label": "Accept privacy policy. [Read it here](http://example.com)",
                "canBeModified": false,
                "canBeRemovedFromLayout": false,
                "attributes": {
                    "required": true
                }
            },
            "submit_button": {
                "type": "submit",
                "label": "",
                "canBeRemovedFromLayout": false,
                "attributes": {
                    "value": "SEND DATA",
                    "name": "submit_button"
                }
            }
		}
	}
},

When added, the form shows the minimum fields for submtting an email, e.g. for subscribing to a newsletter:

but then, the user can toggle on the available fields to transform it:

Implementing a content dialog

The content dialog allows you to build a user interface for selecting a form, on top of the builder. It can be a simple list with prebuilt forms, a search through categorized forms, a small form configurator or wizard, or even a complete form builder tailored for your application’s data.

For detailed information about this feature, please check the content dialog section.

The object that defines the form content dialog is the following:

 manageForm: {
            label: 'Change form',
            handler: async (resolve, reject, args) => { 
              // Your function
            } 
          },

As with most content dialog objects, the label is used within the interface to trigger the function:

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

An example of the content dialog object in beeConfig that handles special links and forms:

contentDialog: {
  specialLinks: {
    label: 'Custom text for links',
    handler: function(resolve, reject) {
      openMySpecialLinkDialog() // Replace this with your application function
        .then(specialLink => resolve(specialLink))
        .catch(() => reject())
    }
  },
  manageForm: {
    label: 'Edit form',
    handler: async (resolve, reject, args) => { 
      const structure = await onHandleManageForm(args)
      structure ? resolve(structure) : reject()
      } 
  },
},

Overview

A form is defined through the structure object, which includes its main properties.

This is the object that the host application passes to Beefree SDK, and it includes fields, layout, and attributes along with a title and a description string values that you can use. The appearance of the form, in terms of styling of labels / fields / buttons (spacing, colors, etc…) is handled directly in the application and is saved in the design’s JSON file. Therefore, the same form can be used in different designs, and have message-specific styles.

Let’s now examine the anatomy of a Beefree SDK form structure.

{
    "structure": {
        "attributes": {},
		"fields": {},
        "layout": [],
        "title": "Form title",
        "description": "Form description"
    }
}

Attributes

This object contains the general form attributes as strings: all of them are standard HTML5 attributes.

Fields

If you want to use a single form, you can use the optional canBeRemovedFromLayout and removeFromLayout attributes to determine (respectively) if that specific field can be removed from the layout by the user, and if it should appear in the stage when the form is dragged in.

Indicate when a field can be toggled off

This attribute indicates that a field can be toggled off by the user. If unspecified, it will be applied as true, allowing the user to switch it on or off in the builder UI.

It’s a best practice to add canBeRemovedFromLayout: false to mandatory fields (e.g., the email address field in a sign-up form) so that they can’t be excluded in the HTML form.

Toggle off a field when loading a form

Layout

If you want to leverage the full power of Beefree SDK forms and use a content dialog to feed the form to the editor’s stage, the layout array will determine how the fields will appear to the user.

Each layout element is an array itself and represents a single line of fields. This allows different layout dispositions, including multi-column.

Probably the best way to represent this is with an example:

Title and description

The form title is a string value. It is not displayed to the user while working in the editor but provides extra information that can be used later for troubleshooting. Likewise, description as a string value that is not displayed to the user while working in the editor, but provides extra information that can be used later for troubleshooting or internal reference.

Using reCAPTCHA

To embed Google ReCaptcha in a Form you need a Google API key for ReCaptcha, the key has to be enabled for a specific website URL or domain; this is crucial because otherwise the script will load but will fail its validation, returning API key errors.

Here’s what’s needed in the submit action when passing a form configuration:

"class": "g-recaptcha"
"data-action": "submit"
"data-sitekey": "___YOUR_RECAPTCHA_API_KEY___"
"data-callback": "onSubmit" (this can be optional, check reCaptcha docs)

In addition, you have to add an HTML block that imports the reCaptcha library inside the template that encapsulates the form:

<script src="https://www.recaptcha.net/recaptcha/api.js" async defer></script>

Here’s a sample JSON config for the submit button:

"submit": {
  "attributes": {
    "class": "g-recaptcha",
    "data-action": "submit",
    "data-callback": "onSubmit",
    "data-sitekey": "___YOUR_RECAPTCHA_API_KEY___",
    "value": "Login"
  },
  "label": " ",
  "type": "submit"
}

Ensure you keep the following in mind:

• Make sure HTML sanitize is OFF (this is the default value).

• Remember that the reCaptcha UI elements will be visible neither in the Beefree SDK work area nor in the Preview, but they will be integrated when the page will be published. Furthermore, the page has to be hosted on the domain that was enabled on the Google Developers Console when setting the reCaptcha.

How it Works

You can enable your users to add forms in Beefree SDK with two methods: