> For the complete documentation index, see [llms.txt](https://docs.beefree.io/beefree-sdk/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.beefree.io/beefree-sdk/~/changes/3EjxmC5rAYEIQ0JKR16k/getting-started/readme/installation.md). # Installation and Fundamentals Install Beefree SDK to get started with your implementation. ## Add JavaScript Library Congratulations on [creating your first application](/beefree-sdk/~/changes/3EjxmC5rAYEIQ0JKR16k/getting-started/readme/create-an-application.md)! 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](https://www.npmjs.com/package/@beefree.io/sdk) 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: ```markup
``` ### 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](/beefree-sdk/~/changes/3EjxmC5rAYEIQ0JKR16k/getting-started/readme/installation/authorization-process-in-detail.md), but here’s a quick example: #### Authentication Code Samples ```javascript 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 ```json { "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: ```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](/beefree-sdk/~/changes/3EjxmC5rAYEIQ0JKR16k/getting-started/readme/installation/configuration-parameters.md):
AttributeTypeDescription
uidstring

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).
containerstringIdentifies 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: ```javascript var template = { ... }; // Any valid template, as JSON object bee.start(template); ``` {% hint style="info" %} 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. {% endhint %} --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.beefree.io/beefree-sdk/~/changes/3EjxmC5rAYEIQ0JKR16k/getting-started/readme/installation.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.