Installation and Fundamentals

Learn and understand the core concepts related to how you can install the Beefree SDK npm package, authenticate, and get started with Beefree SDK.

Introduction

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

• Installing the Beefree SDK npm package 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

Note: Reference the React, Angular, or Vue.js Quickstart Guides for a guided walkthrough by framework and sample code using a simple implementations.

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.

Parameter	Type	Description	Example
client_id	string	Your application client ID	"abc123-client-id"
client_secret	string	Your application secret key	"xyz456-secret-key"
UID	string	Unique user identifier	"user-12345"

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

Important Notes:

• The UID must be consistent between authentication and SDK configuration.

• Tokens are valid for 12 hours.

• Ensure client_secret and client_id aren't exposed in the client-side code.

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.

Property	Type	Required	Description
container	string	Yes	DOM element ID for the editor

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.

Method	Description	Example
load(template)	Load new template	bee.load(newTemplate)
reload(template)	Force reload template	bee.reload(updatedTemplate)
save()	Trigger save callback	bee.save()
saveAsTemplate()	Save as template	bee.saveAsTemplate()

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.

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:

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