Welcome to the Beefree SDK AddOn development documentation!
This document is for anyone that wants to start creating AddOns for Beefree SDK users.
Before you get started, you may want to review these frequently asked questions.
Happy coding!
First, create a development application so that you are not testing your new AddOn with a production application.
Development applications inherit the plan of the production application to which they are connected. You can only build AddOns when you are on the Superpowers plan or above. If you are not on one of those plans:
Create a development application
Request an upgrade
Once you have a development application on the Superpowers plan or above, proceed to the next step.
The process all starts in the Beefree SDK Console:
Log into the Console at developers.beefree.io
If you have not done so yet, create a development app as indicated above
Click the Details link next to any application on the Superpowers plan or above
Click the AddOns link, under Application configuration
Click the Create a custom AddOn button
When you create a new Custom AddOn, you will be prompted to enter some information through the AddOn setup form. Depending on the method that you choose, the number of fields in the form will change.
Name: The name of the AddOn is saved in the dashboard. This is not the name used for the tile in the Beefree editor’s Content tab but rather the internal name visible to other developers. In other words, it will not be shown to end-users of the editor.
Enable toggle: A toggle element to enable and disable the AddOn. When toggled OFF, the AddOn is not visible to end-users of the editor in your application (the host application).
Type: The type of content that the AddOn will create. Currently, the following content types are available:
Image
HTML
Mixed
Row
Paragraph
Button
Title
List
Menu
Icon
Handle: A unique identifier for this AddOn. This value will be the future reference between the AddOn and its content dialog. Additionally, it will be used to override settings per user or build a content dialog for the AddOn.
Method: This is an important selection and is covered in detail in the section below.
External iframe: Choose this option if the AddOn is hosted outside the host application. If this is an AddOn that will be made available to other Beefree SDK applications via the Partner AddOn directory, then it is by definition hosted outside of the host application, and therefore you must select this method.
Content Dialog: Choose this option for AddOn that lives inside the host application (e.g., internal AddOn). You cannot choose this method if you plan to make your AddOn available to others by listing it in the Partner AddOn directory.
Icon: Upload an image from your local computer that will become the icon associated with the tile shown in the editor’s Content tab. We recommend a 64 x 64 pixel SVG file.
Labels:
Content Title: This is the name that will be used for the tile in the BEE editor’s Content tab (e.g., “Countdown timer,” “Product Recommendation,” etc.).
Content button: The label for the call-to-action button (e.g., “Select a Countdown Timer”), which opens the content dialog or iframe.
Placeholder message: This is the message shown in the editor’s stage when the tile is first dropped.
If you are using the iFrame method, some additional fields are shown on the form.
Iframe URL – Required The URL that will be loaded inside the Iframe.
API Key – Optional The API Key optionally authorizes the application to load the URL provided above. If authorization is not needed, this field can be left empty.
Authentication URL – Optional The endpoint that handles the optional authorization request. If authorization is not needed, this field can be left empty.
Healthcheck URL – Optional, but required for Partner AddOns This URL will be contacted when the editor is started to verify the status of the AddOn. In the case of AddOn downtime, the editor hides it in the UI. Please note: if you are building a Partner AddOn, this is a required field as it will allow applications that have installed your AddOn to protect the quality of their end-users experience if your service is unavailable.
Once you have entered all the details, click Save, and you should immediately find your AddOn visible within the Beefree SDK platform. However, your AddOn is not completed until the configuration steps described below are done.
One of the important choices you will make is in regard to how your content creation AddOn loads.
The general rule of thumb is that if your AddOn lives within the host application, you can use a content dialog.
If your AddOn lives on another website outside of the host application or will be listed in the Partner AddOn directory, then you must select the external iframe method.
The AddOn can be built using any technology stack. There are no specific rules about how your AddOn functions internally.
However, you will need to implement the following:
JavaScript API
Protocol to communicate between iframe and the Beefree application.
Server API
Conditional health check endpoint
Optional authentication endpoint
Don’t worry about the fine details just yet! We’ll revisit each of these methods in more detail in the following sections.
Superpowers and Enterprise applications have the option to create their own, custom AddOn with content dialogs.
This option is convenient when the AddOn and host applications are hosted under the same domain.
You don’t need to implement a JavaScript API or Server API when using the content dialog.
An AddOn can only return one type of content. The type you choose will determine which sidebar properties are shown when your AddOn is selected.
Currently, you may choose between the following content types:
Image: Will insert an image module on the stage, and show the properties of an image content block in the sidebar. Adjusting the properties allows for customization of the content type.
HTML: Will insert an HTML module on the stage, and show the properties of a custom HTML content block in the sidebar, except the HTML text input will be hidden. That’s because the HTML cannot be edited outside of the content dialog or iframe made available by your AddOn.
Mixed: Will insert a module on the stage that allows for loading of different content blocks with a single action.
Row: Will insert a row module on the stage, and show the row properties in the sidebar. The row is pre-built with a specific use case in mind. For example, a row that serves of the purpose of allowing end users to add products to their builders.
Paragraph: Will insert a paragraph module on the stage, and show the properties of a paragraph content block in the sidebar.
Button: Will insert a button module on the stage, and show the properties of a button content block in the sidebar. This simplifies offering pre-built buttons to your end users.
Title: Will insert a title module on the stage, and show the properties of a title content block in the sidebar.
List: Will insert a list module on the stage, and show the properties of a list content block in the sidebar.
Menu: Will insert a menu module on the stage, and show the properties of a menu content block in the sidebar. This simplifies offering pre-built menus to your end users.
Icon: Will insert an icon module on the stage, and show the properties of an icon content block in the sidebar.
Mixed Content AddOns are a new type of content tile that allows the host application to load multiple content modules at once. This grants you greater flexibility with how you want your custom AddOn to interact with your customers and data; for example, you could create a mixed content AddOn to drop a product image in your template, along with a title, description, and more.
To utilize this feature:
Create a new custom AddOn of type “Mixed Content” from developers.beefree.io, as described in the “Getting started” section of this article;
Add the integration code required by custom AddOns (for example, if the user chose the “Content Dialog” method, it might look something like this):
The host application should return a valid response as the parameter of the “resolve” callback.
A valid response that the hosting application should send to the Beefree app when the contents of a Mixed Content AddOn are selected must have the following structure:
If the response is not valid, an error is raised, and onError is called.
For each module type, here is the list of allowed properties.
Unless otherwise specified, the properties are optional.
The following code calls a function named resolve with an object argument. This object defines a heading element with characteristics such as type, text content, alignment, font size, boldness, text color, and link color. The resolve function handles or returns the constructed heading element.
The following table displays a list of properties in the resolve function, and each of its respective value types and whether or not they are mandatory.
The following sample code defines an image element with various attributes.
The following table displays a list of properties in the resolve function, and each of its respective value types and whether or not they are mandatory.
The following sample code defines a button element with various attributes.
The following table displays a list of properties in the resolve function, and each of its respective value types and whether or not they are mandatory.
The following sample code defines a paragraph element with various attributes. The mergeTags property contains a list of merge tags, which can be used for dynamic content insertion.
The following table displays a list of properties in the resolve function, and each of its respective value types and whether or not they are mandatory.
The following sample code defines an HTML element with various attributes.
The following table displays a list of properties in the resolve function, and each of its respective value types and whether or not they are mandatory.
The code defines a menu structure with a list of items. Each item has text content (e.g., “Menu item”) and a link associated with it. The link includes a title, URL (href), and a target attribute, demonstrating that it generates a menu with clickable items that open the specified links in the same browser window or tab when clicked.
The following table displays a list of properties in the resolve function, and each of its respective value types and whether or not they are mandatory.
The following code snippet calls the resolve function to generate a list element defined by the type property set to 'list'. The value object specifies the list's characteristics, including the list tag ('ol'), HTML content, alignment, text formatting options like underline, italic, bold, and colors for text and links. This configuration allows you to customize list elements when creating custom addons for your host application using Beefree SDK.
The following table displays a list of properties in the resolve function, and each of its respective value types and whether or not they are mandatory.
The following code snippet defines an icons component for your application using Beefree SDK. It specifies an array of icon objects, including properties such as image URL, text, dimensions, and positioning. You can customize each icon with optional attributes like alt, title, and hyperlink details.
The following table displays a list of properties in the resolve function, and each of its respective value types and whether or not they are mandatory.
This feature expands the capabilities of Custom AddOns by including:
additional integrations (e.g. a Product Block integrated with client’s e-commerce)
domain-specific contents (e.g Event Block for an application that offers event engagement)
.. and much more
To take advantage of this new feature, you have to:
Create a new custom AddOn of type “Row” from developers.beefree.io, as described in the “Getting started” section of this article;
Add the integration code required by custom AddOns (for example, if the user chose the “Content Dialog” method, it might look something like this):
The host application should return a valid response as the parameter of the “resolve” callback.
A valid response that the hosting application should send to the Beefree app when the contents of a Row AddOn are selected must have the following structure:
The content dialog configuration, required for this custom AddOn is the same configuration used by the other AddOns. Please see the Content Dialog method paragraph.
The purpose of the contentDialog object in the code snippet is to handle different types of content that can be added to a dialog. It has a handler function that resolves with an image or HTML content based on the provided contentDialogId.
To set up the content dialogs you will need to add the contentDialog object to beeConfig. For more details about the content dialog, please review Content Dialog: How it works.
This is optional. Should you feel the need to add custom fields when resolving, we created a “customFields” key allowing to you place any additional custom fields inside of that object.
Your application receives the full schema, but we expect it to provide the Simplified Schema. When an end user reopens the Custom AddOn Content Dialog, the Beefree SDK sends your application the row's content and metadata. This feature allows your application to track user changes without needing a restart each time the dialog is reopened. The new properties in the Simplified Schema enhance the flexibility for designing Custom Rows and AddOns.
The JavaScript API allows an application inside of an external iframe to communicate with the host application that’s embedded a Beefree app. If you use the content dialog option, there is no need to implement the JavaScript API.
This section describes the communication protocol between a Beefree app and an external AddOn (i.e. an AddOn that is loaded into an iframe inside a Beefree app).
The communication takes place using postMessage, which is a standard way of communicating between Window objects.
The data object sent in the messages exchanged between the Beefree app and the AddOn has a standardized form:
The application inside the iframe may trigger the following actions:
onCancel
onSave
The application inside of the iframe may listen for the following events:
loaded
init
load
The Beefree app creates an iframe for the AddOn and then expects it to start the conversation by sending the loaded action:
The AddOn may also pass optional arguments to define the shape and style of the modal dialog that will contain the AddOn. If no arguments are provided the modal will fill the screen with no border.
The following parameters are available for the loaded method:
isRounded: Boolean true or false value. If true, the modal will have rounded corners.
hasTitleBar: Boolean true or false value. If true, the modal will display a title bar.
showTitle: Boolean true or false value. If true, the name of the AddOn will display in the title bar.
width: The width of the modal in pixels. If not provided, the modal will be 100% width.
height: The height of the modal in pixels. If not provided, the modal will be 100% height.
The following is a full example of a fixed-size modal with rounded corners, no title, and no close button. In this case, a custom close button is provided by the AddOn using the onCancel method.
The Beefree app then responds with an init message that contains the current locale of the editor and any pass-through data defined by the host application:
This message may be followed by an optional load message from the Beefree app in case the user has already defined the content of this AddOn in a previous session:
Any further action is then on the AddOn. In case the user cancels the edit, it is expected to send an onCancel message:
And if the user finishes editing and clicks on the save (or OK) button, the AddOn is expected to send an onSave message:
The Server API is only for use with external iframe applications. The application inside of the iframe must implement at least one API endpoint for a health check, but may also implement an optional endpoint for authentication. If you use the content dialog option, there is no need to implement the Server API.
The health check endpoint is mandatory for apps that will be posted to the partner directory but otherwise optional. If your AddOn is for internal use (i.e. a custom AddOn), then you can perform your own health checks inside of the host application. If the application is offline, then you can use the configuration settings to disable it. If you choose to implement the health endpoint, simply ensure it returns a 200 for all GET requests.
An application is not required to use any authentication. For example, the Giphy AddOn by Beefree is FREE for all users and therefore has no need for authentication.
However, authentication can be enabled for applications of any kind, if you want to identify or authorize the user to access your resources.
To enable authentication, simply add the optional parameters to your AddOn in the Beefree SDK Console:
API Key: This is any globally unique identifier that can be used to identify the customers, but usually, this would be a bearer token or JWT.
Authentication URL: This is the URL of your authentication endpoint. More on this below.
With authentication enabled, a specific protocol follows:
Before the Beefree app creates an iframe for the AddOn, it performs a proxied GET request to the authentication URL.
The following HTTP Headers are passed to the AddOn’s endpoint.
x-real-ip: The IP Address of the host application
authorization: It contains the API Key (e.g. bearer token), which you provided to the host application.
x-bee-clientid: It contains the client id of the host application.
x-bee-uid: It contains the uid defined in the BEE configuration.
The iframe application uses the Authorization Header to validate the user permissions.
In the event of success, the application returns a URL to load within the iframe. The URL is provided as plain text with a 200 status code, no JSON formatting is needed.
In the event of unauthorized, the application returns a 403 status code.
The Beefree app creates an iframe for the AddOn using the URL returned from the authorization endpoint.
The AddOn application loads the application or performs additional authentication.
Once you have initialized the Beefree app, you can pass a series of configuration parameters to it.
The AddOn section of the configuration allows you to override the parameters you configured at the application level, on a per-user basis.
See: Adding client-side configuration parameters for AddOns.
| Property | Value | Mandatory |
|---|---|---|
| Property | Value | Mandatory |
|---|---|---|
| Property | Value | Mandatory |
|---|---|---|
| Property | Value | Mandatory |
|---|---|---|
| Property | Value | Mandatory |
|---|---|---|
| Property | Value | Mandatory |
|---|---|---|
| Property | Value | Mandatory |
|---|---|---|
| Property | Value | Mandatory |
|---|---|---|
title
String
No
text
String
Yes
align
String
No
size
Integer
No
bold
Boolean
No
color
String
No
linkColor
String
No
alt
String
Yes
href
String (URL)
Yes
src
String (URL)
Yes
dynamicSrc
String (URL)
No
target
String
No
label
String
Yes
href
String
No
target
String
No
color
String
No
background-color
String
No
html
String (HTML content)
Yes
underline
Boolean
No
italic
Boolean
No
align
String
No
size
Number
No
bold
Boolean
No
color
String
No
linkColor
String
No
html
String (HTML content)
Yes
items
Array of objects
Yes
text
String
No
link
Object
No
title
String
No
href
String (URL)
No
target
String
No
html
String (HTML content)
Yes
tag
String ('ol' or 'ul')
No
underline
Boolean
No
italic
Boolean
No
align
String ('left', 'center' or 'right')
No
size
Integer
No
bold
Boolean
No
color
String
No
linkColor
String
No
icons
Array of objects
Yes
image
String (URL)
Yes
width
String
Yes
height
String
Yes
textPosition
String ('left', 'right', 'top', or 'bottom')
Yes
text
String
No
title
String
No
alt
String
No
href
String (URL)
No
target
String (_blank, _self, or _top)
No
