Learn more about Custom AddOns, and how to develop and implement your own custom built AddOn.
This feature is available on Beefree SDK Superpowers plan and above. If you're on the Core or Essentials plan, upgrade a development application for free to try this and other Superpowers-level features.
Custom AddOns are useful when there is a feature you'd like to offer within your application that is not available in our AddOn Marketplace within the Developer Console. In these instances, you can develop your own Custom AddOns for your application's end users.
Let’s say you embedded our email editor in your event engagement platform, which has a feature that allows event marketers to insert an event ticket’s QR code in marketing campaigns sent to create more engagement around an event.
You want those marketers, users of your platform, to be able to easily include a QR code in the emails they send to remind people about the event. That way ticket holders can use the QR code to quickly get into the event venue.
So you decide to create a “QR Code” addon: “QR Code” becomes a new tile in the Content tab in the editor.
Marketers drag and drop the tile, click on Select event to indicate which event the QR is for, and use the editor to style that section of the message (e.g. size, padding, etc.).
The QR code is created dynamically by your platform, at the time the email is sent to a ticket buyer.
The feature is specific to your application.
Custom AddOns are an advanced feature. As a result, the feature is available on the following plans:
Superpowers
Enterprise
Of course, there are exceptions to this requirement.
Testing: if you are not yet on a Superpowers or Enterprise plan, and you want to test building a Custom AddOn:
Create a development application.
Request an upgrade to the Superpowers plan.
Test as much as you want. If and when you decide that you wish to deploy your Custom AddOn in production, we will ask you to upgrade your production application to the Superpowers or Enterprise plan.
Development of a Partner AddOn:
You provide features that could be a good fit as an extension of our editors
You are not a Beefree SDK customer
Log into the Beefree SDK Console and locate any application that is on the Superpowers or Enterprise plans. Click on Details to navigate to the application details page. In the lower part of the page, locate the Application configuration section and click on AddOns.
You will be taken to a page that lists the addons that have been installed for this application. Since you are just getting started, the list is likely empty. Click on Create a custom addon to start the process of creating a Custom AddOn.
Refer to the AddOn Development documentation for all the details on building your addon.
Learn more about how to contribute your Custom AddOn as a Partner AddOn in Beefree SDK's Partner AddOns Marketplace.
Partner AddOns can easily be integrated with your application in a matter of minutes by installing them inside of the . You can reference available Partner AddOns inside of the . If the AddOn with the functionality you are looking for is not offered within the Partner Directory, you also have the option to create your own . If you'd like to add your Custom AddOn to Partner AddOn Marketplace within the Beefree SDK Developer Console, you have the option to do that.
Throughout this page, we will discuss at a high-level how you can list the Custom AddOn you created as a Partner AddOns within the Partner AddOn Marketplace.
To get started, you will need to follow the documentation and create a Custom AddOn for a web application that has embedded Beefree SDK.
Please note that because Partner AddOns by definition live outside of the Beefree SDK application that will use them, you must select the external iframe method for development.
You can submit your AddOn to be listed in the Beefree SDK Partner AddOn Directory, so that other applications that have embedded Beefree SDK can take advantage of it.
You will be completely in charge of the business relationship with those companies, who will become your customers. We are not part of that relationship, other than being an enabler of it.
The following is a list of requirements for getting an AddOn listed in the Partner AddOn Directory:
You have signed the Beefree SDK AddOn License and Distribution Agreement. Contact your Account Manager or log in to the and submit a ticket for details.
You have built an AddOn that:
Uses the External iFrame Method (see )
Uses the optional health check endpoint
You have thoroughly tested the AddOn before submitting it to our test for a final review.
You have a demo of the AddOn that we can access.
When you have completed all of the above, contact your Account Manager or log in to the and submit a ticket to complete the review and approval process.
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
