Installation and Fundamentals

Install Beefree SDK to get started with your implementation.

Add JavaScript Library

Congratulations on creating your first application! Now it’s time to install it. The first step is to add the Beefree SDK library to your application. You can use our convenient NPM module to add it.

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.

We talk about this step in detail here, but here’s a quick example:

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

The following table shows all of the required configuration settings:

Attribute	Type	Description
uid	string	An alphanumeric string that identifies the user and allows the embedded application to load resources for that user (e.g. images). Min length: 3 characters Can contain letters from a to z (uppercase or lowercase), numbers and the special characters _ (underscore) and – (dash) It is a string and not a numeric value It uniquely identifies a user of the Beefree application. When we say “uniquely”, we mean that: It will be counted as a unique user for monthly billing purposes. Images (and other files) used by the user when creating and editing messages will be associated with it and not visible to other users (when using the default storage).
container	string	Identifies the id of div element that contains the application

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

The instance method bee.start(template) does not need to be called immediately after create. In a SPA (Single Page Application) or React app, you can create the editor in a hidden global state but then call the start method when the template is selected and available. The application loads quickly when all steps are completed consecutively. However, by separating the loading workflow into two parts, the end-user will perceive loading in a fraction of the overall time. Remember, if the client_id belongs to a File Manager application, bee.start() can be called without any parameters.