Overview

Here is a list of terms used frequently throughout the Beefree SDK technical documentation. Things can get a bit tricky when embedding a software application within another software application, so this page is an attempt to create as much clarity as possible. We hope we find it useful. If anything sounds confusing or if you have any suggestions for improvement, please contact us.

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 SDK subscription A subscription to the Beefree SDK. There are different subscription plans, starting with a Free plan. Once you have a subscription, you can create one or more Beefree applications.

• Beefree application An instance of any of the no-code tools that can be embedded in your software. They include:

  • Email Builder

  • Page Builder

  • Popup Builder

  • File Manager

• Beefree SDK Console A multi-user administration panel where you can sign up for a Beefree SDK subscription, manage the subscription, and create and configure a Beefree application within a subscription.

• Production application An instance of a Beefree application used in your production environment.

• Development application An instance of a Beefree application used for development, QA or staging environments. You can create multiple, development applications under a production application.

• Host application Your software application, which will host one or more Beefree applications.

• Beefree system The backend system that interacts with your Beefree application to provide services such as application authorization.

• Content Services API A set of API methods in the Beefree system that allow you to perform a variety of tasks connected to the implementation of a content creation workflow.

What is Beefree SDK?

Beefree SDK is an embeddable no-code builder that gives your end users the freedom to design stunning emails, landing pages, and popups—without writing a single line of code. It’s easy to configure, intuitive to personalize, and built to scale with your needs—whether you're a startup or an enterprise. Built with both developers and end users in mind, it’s designed to integrate easily into your application, scale as your product grows, and provide a flexible, white-label design experience.

For developers, Beefree SDK is easy to work with. You can personalize the design experience by adding simple configuration parameters. Want to enable or disable a feature? Just check a box in the Developer Console, hit save, and the changes are immediately reflected on the frontend. No complicated setup required.

For your end users, Beefree SDK is an intuitive drag-and-drop editor with everything end users need to bring their creative ideas to life—whether they’re creating an email campaign, a landing page, or an attention-grabbing popup. Content blocks like titles, images, lists, tables, buttons, and more are all available right out of the box.

Beefree SDK includes the following features and more:

• Email builder: A creation environment that helps end users quickly create beautiful emails. This environment supports your end users in following email creation best practices recommended by industry experts.

• Page builder: A creation environment that empowers end users to build visually stunning landing pages. They can use a landing page as a link for a call-to-action (CTA) inside emails, to embed forms and capture information, or to create standalone pages.

• Popup builder: The that provides end users with the tools they need to build compelling popups that capture attention.

• AI-generated templates: With both and the , you can build a custom AI-generated content creation experience (for assets such as emails, landing pages, or popups) for your end users.

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

• File manager: A tool to (images, PDFs, and so on).

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

• API offering: Extend the functionality of any of the builders with our comprehensive .

This site discusses the technical capabilities of Beefree SDK, and how to embed it into your web application. To learn more about the end user experience, and how your end users will interact with Beefree SDK on the frontend of your application, reference the . Markdown files for this guide are available in this , which you can clone and use as a starting point for building a knowledge base for your end users.

Explore Beefree SDK in Codepen

You can explore a simple implementation of Beefree SDK in to see how the builder works. To visualize the integration below, you can:

• Click Run Pen to see the builder.

• Navigate between the HTML and JS tabs to see the code.

• Use the JS tab to edit the beeConfig, which you can add to. This helps you customize the builder's functionality based on features you are exploring.

• If you'd like to stay on this page, and not redirect to , you can zoom in and out of the embedded Codepen using 1x, 0.5x, and 0.25x options.

Start a Simple Implementation

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

1. Create an account to access the and obtain your credentials.

2. to get started. Beefree SDK offers a generous Free plan that includes each builder type mentioned in the previous section.

3. Create an application and .

4. Clone the , which includes the code for email and popup builder implementations.

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

6. Once the email builder, or popup builder, depending on which environment you chose, opens, you can start experimenting with the SDK's configuration by customizing the in the beeConfig section of the code.

7. You can also customize the SDK's configuration inside the under the of the application you created.

Note: Visit the for a comprehensive list of features and the plan type they correspond to.

Quickstart Guides by Framework

Reference Quickstart Guides specific to your tech stack:

Beefree SDK's Embeddable Builders

Learn more about our three embeddable builders.

File Manager

In addition to our drag-and-drop editors, we also offer a standalone application, which can be used alongside any of the builders. The File Manager is designed to simplify the organization and management of digital assets. It is an image and document management user interface that can be launched as a standalone application. This allows your customers to quickly upload or manage assets, without having to load one of the builders.

Learn more about our and .

Developer Essentials

Create a free account and obtain your Client ID and Client Secret in the to get started. Set up a local environment to experiment with customizing a configuration. Watch the configuration changes and customizations come to life on the frontend.

Sample Code

Learn more about Beefree SDK through available sample code and example projects in .

Videos

Learn more about Beefree SDK through . Explore , , and .

Contribute to the Docs

The Beefree SDK technical documentation is available at docs.beefree.io/beefree-sdk and in the .

You can contribute feedback to the documentation in one of the following ways:

• On docs.beefree.io/beefree-sdk use the Was this helpful? emoji option on the right hand side of each page. After selecting an emoji, you'll have the option to submit written feedback on what you'd like to see in the documentation. This feedback goes directly to the documentation team and is integrated frequently.

• Creating a pull request using the . Use this option in the event you find a typo, broken link, or small fix.

Overview

Setting up two-factor authentication will keep your developer account extra secure. Two-factor authentication means that users will need to provide two different identifications to log in to their : their regular login credentials, and a token generated by a two-factor authentication app.

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

• download a two-factor authentication app to their mobile device (e.g. , , , and others);

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

Overview

The debug parameter in the beeConfig is an optional object that enables internal debugging features within the Beefree SDK editor. It's designed to help developers inspect configurations, , and more easily during development.

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

Set it live (no refresh needed):

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.

• inspectJson (boolean): Adds an eye icon in the toolbar that allows you to inspect the specific JSON used for that element. Useful for understanding how your configuration is being rendered.

• showTranslationKeys (boolean): Replaces localized strings with their translation keys throughout the UI. This is especially helpful when debugging i18n issues or checking for missing .

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

When you load a Beefree application inside the host application, you pass a configuration object with multiple sections that define the characteristics of the UI, UX, and available elements. However, there are cases when you may want to reload this configuration without the need to reload the Beefree application. In these cases, you can use a specific event to update the configuration while the editor is open.

Use cases

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

• Updating available categories for Saved rows

• Refreshing a Custom header for authorization

• Changing Advanced permissions for the current user

• Updating settings for the editor’s Content defaults

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)

Manage users in the Console

You can invite additional users to your Beefree SDK Console. To do so, select Manage users from the personal menu in the top right corner of the screen.

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 Account Owner has the following additional privileges, compared to Admins:

• Add, edit or delete users, as described above.

• Turn on , using tokens provided by mobile apps like Google Authenticator or Authy. 2FA can be enabled either for specific users, or account-wide from the Settings & Security section in the personal area ().

• Change the company’s name, also in Settings & Security.

Pricing for Beefree SDK is based on the concept of unique users of the editor. A unique user is one that is identified by a unique UID, as described below. The system counts unique UIDs within a billing period, and resets the count to zero at the start of the next billing period.

Properties

The UID parameter:

• Is an alphanumeric string passed to Beefree SDK throughout the server-side authorization process.

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

• The UID should not be Personal Data, as indicated in the Beefree SDK License Agreement. Further information about how your use of a Beefree SDK service relates to the EU’s General Data Protection Regulation (GDPR) may be found here. Our Privacy Policy, which describes the processing activities carried out by Beefree SDK as Data Controller, is available here.

Unique identifier

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

1. It will be counted as a unique user for monthly billing purposes.

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

UIDs in production are counted separately from UIDs in a development application. For example, if you have the following UID in both a production and development application, the unique UID will be counted twice toward your plan's allotment.

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

In this scenario, Beefree SDK will treat these as two distinct users, and count this UID twice—once for each environment. Reference Usage-based fees for more information on Beefree SDK plan types and their corresponding uid allotments.

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:

1. Log in to the Beefree SDK Developer Console

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

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. Log in to your Beefree SDK Developer Console

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.

To use higher-tier features in production, you must upgrade to the appropriate 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

While setting up a development application is a feature on paid plans, please note that usage-based fees still apply. If, in your development application, you're using any of the Beefree SDK features that generate usage-based fees, that usage will count towards your plan's monthly allotment. You'll be charged usage-based fees if your usage (across production and development applications) exceeds your plan's allotment. Learn more about usage-based fees. You can view usage statistics for your development applications by logging into the Beefree SDK Developer Console, locating the development application you are working with, and looking at the Statistics widget on the application details page.

Overview

In this article, we will discuss how to sign up for an account in the , create an application, and obtain your Client ID and Client Secret.

This article will cover steps for the following processes:

Sign up for a Developer Console account

The first step to experimenting with and embedding Beefree SDK's visual builders is to.

Take the following steps to sign up for a Beefree SDK account:

1. Navigate to the .

   1. Complete the required fields to create an account.

   2. Once the form is complete, click Sign up to embed Beefree SDK.

1. Check your inbox and verify your email address.

   1. Once it is successfully verified, you'll be redirected to the . Enter your email and password to login.

2. You'll be redirected to a page with an active free subscription called MyFirstSubscription. Under this subscription, there are four applications you can activate: Email Builder, Page Builder, Popup Builder, and File manager. You can activate one or all of them if you'd like.

   1. Click the Activate button corresponding to the application type you'd like to start experimenting with. Once it is activated, you'll notice Client ID appears.
3. Click Details to obtain your Client Secret and add any Application configurations you'd like to start exploring.

How to create an application

Once that’s done, you will be able to . Your dashboard will look like the following image.

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.

With your Client ID and Client Secret, you can use our to experiment with a simple integration of Beefree SDK. You can also get started with .

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:

1. Log in to the .

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.

• Create

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.

Here is an overview of the different workspaces and their differences. Please refer to this page for more information on using AMP in Beefree SDK.

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.

In addition, omitting the workspace, or loading the “default” workspace for certain users, has the effect of disabling AMP for those users, even when AMP content is enabled in the Beefree SDK Console. This way, you can decide to make the feature available to customers of your application:

• depending on the subscription plan that they are on (i.e. you could push users to a higher plan based on the ability to use AMP);

• depending on the purchase of an optional feature (same);

• only if they are “beta” customers, so they see it while keeping it hidden from the rest of your users.

Authorization Process Overview

The Authorization Process is an important step throughout your . This step validates your Beefree SDK credentials and provides you with a token. Take the steps outlined in this document to ensure you accurately complete the authorization process.

Beefree SDK NPM Package

Prior to getting started with the authorization process, ensure you reference the . Reference both the and the to get the latest information.

Package Installation

You can install Beefree SDK using either or :

Using npm

Using Yarn

Package Details:

• TypeScript Support: Included

• License: Apache-2.0

• Repository:

Beefree SDK Client-side Configuration

Beefree SDK requires the host application to pass a container parameter in the This is the only required parameters for the configuration.

The following code sample shows an example of this parameter in the .

Beefree SDK Server-side Login

To initialize your instance of the Beefree SDK builder, call the /loginV2 endpoint shown in the sample code below with your Client ID, Client Secret, and UID. The Client ID and Secret are available on the application details page of the . UID represents your user as described in .

The Beefree SDK system uses .

Example

Reference to learn more about UID.

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

You can reference /loginV2 examples in the following Quickstart Guides:

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

Once you obtain the token, the object is passed to Beefree SDK to set up your customization options, for example setting the editor’s language to “Spanish”.

Then, you can use Beefree SDK methods to on your page.

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:

Error Management

When you set up an 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.

Error Responses

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

Example error response for an invalid UID. Look at the properties of .

Example error response for invalid credentials. Obtain your credentials using the .

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

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 = {
    container: 'beefree-sdk-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]
    titleDefaultStyles: {...}
    titleDefaultConfig: {...}
    titleMaxLevel: 'h6' // 'h3' default (min 'h1', max 'h6')
    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 parameter for initializing Beefree SDK.

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.

Instance Methods

Assuming that beeInstance 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.

Introduction

This page discusses the core concepts related to installing Beefree SDK within your application. These core concepts are the following:

• Installing the within your application.

• Understanding the Authorization process and how to successfully authenticate server-to-server.

• Adding the required Beefree SDK configuration to your application.

By the end of this guide, you'll understand the core concepts related to how you can install the package, authenticate, and get started with Beefree SDK. You'll have working a local environment set up on your machine to experiment with.

For a quick start, visit our React, Angular, and Vue.js Quickstart guides, which each include complete sample code by framework.

Prerequisites

Prior to integrating Beefree SDK, ensure you have completed the following:

1. Signed up for a Beefree SDK Developer Console account.

   1. Created an application within the Developer Console

   2. Obtained a Client ID and Client Secret for that application

2. Node.js installed.

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

Core Concepts

This section covers the core concepts for installing Beefree SDK within your application and launching a local environment.

The concepts covered in this section are the following:

• npm package installation

• Authentication Process

• Beefree SDK Initialization

Package Installation

You can install Beefree SDK using either npm or yarn:

Using npm

npm install @beefree.io/sdk --save

Using Yarn

yarn add @beefree.io/sdk

Package Details:

• TypeScript Support: Included

• License: Apache-2.0

• Repository: Beefree SDK GitHub

Authentication Process

This section discusses the authentication process. It explains important concepts related to how to successfully authenticate using a server-to-server call.

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

At a high level, the steps you need to take throughout the authentication process are the following:

1. Secure Credentials

   1. Never expose client_id or client_secret in frontend code.

   2. Store them in backend environment variables (.env).

2. Backend Proxy Setup

   1. Set up a server-to-server call.

   2. Forward the complete response access_token and v2 to the frontend.

3. Auth Request from Backend

• Call Beefree SDK’s loginV2 and include the following required parameters:

  • client_id

  • client_secret

  • uid

1. Frontend Handling

   1. Fetch token only from your proxy.

   2. Extract access_token from response.

   3. Initialize SDK: new BeefreeSDK(access_token).

Authentication Endpoint

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

Required Parameters

The following table lists and describes the required authentication parameters.

Example Implementation (Node.js)

async function initializeBeefreeEditor(templateJson, beeConfig) {
  try {
    const response = await fetch('http://localhost:3001/proxy/bee-auth', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({ uid: 'demo-user' }) // customize UID if needed
    });

    if (!response.ok) {
      throw new Error('Failed to fetch token from proxy server');
    }

    const { token } = await response.json();

    const BeefreeSDKInstance = new BeefreeSDK(token);
    await BeefreeSDKInstance.start(beeConfig, templateJson, "", { shared: false }); // templateJson is your design content

  } catch (error) {
    console.error('Error initializing Beefree SDK:', error);
  }
}

JSON Authorization Response

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

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:

<div id="beefree-sdk-container" style="width: 100%; height: 800px;"></div>

Configuration Options

Beefree SDK requires a configuration object with the required container property. Optional parameters are also available to customize the builder, but container is the only required one for initializing Beefree SDK.

The following code snippet shows an example of this:

var config = {
    container: 'string'
}

Full Configuration Reference

The following table explains the container property.

Working with Templates

Loading a Template

Initialize the editor with a template JSON object:

// After successful initialization
const template = {
  // Your template JSON here
  // Sample templates available at:
  // https://github.com/BeefreeSDK/beefree-sdk-assets-templates
};

bee.start(template);

Reference the beefree-sdk-assets-templates repository in GitHub for example templates.

Template Management Methods

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

Additional Features

Token Refresh Implementation

Implement automatic token refresh to maintain uninterrupted sessions:

// Refresh expired token (call before 12-hour expiration)
bee.updateToken(newToken); 

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:

// Join a co-editing session
bee.join({ uid: "user-123" }, "shared-session-id"); 

How to use:

1. Generate a unique session-id on your server

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

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. While the Configuration parameters provides a high level example, there are several configuration options outlined throughout the comprehensive technical 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:

   Copy

   // 1. Get a fresh token from your backend
   const newToken = await fetch('/refresh-token');
   
   // 2. Update the SDK instance
   bee.updateToken(newToken);

3. Best practice is to refresh tokens before expiration (recommended at 11 hours)

Q: Where can I find sample templates? A: Visit our template repository for examples.

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 Beefree SDK updates and new features