Beefree SDK Guidelines

Guidelines and best practices for building applications with Beefree SDK, including installation, authentication, configuration, customization, and template management.

Installation Guidelines

Package Installation

Install the Beefree SDK package using npm or yarn:

npm install @beefree.io/sdk
# or
yarn add @beefree.io/sdk

Dependencies

Beefree SDK requires the following core dependencies:

{
  "dependencies": {
    "@beefree.io/sdk": "^9.0.2-fix-optional-url-config.0",
    "axios": "^1.10.0",
    "express": "^5.1.0",
    "cors": "^2.8.5",
    "dotenv": "^17.2.0"
  }
}

Environment Setup

Create a .env file in your project root with your Beefree credentials:

BEE_CLIENT_ID=your_client_id_here
BEE_CLIENT_SECRET=your_client_secret_here

Authentication Guidelines

Proxy Server Setup

ALWAYS use a proxy server for authentication to protect your credentials

Create a proxy server file (e.g., proxy-server.js) to handle authentication:

import express from 'express';
import cors from 'cors';
import axios from 'axios';
import dotenv from 'dotenv';

dotenv.config();

const app = express();
const PORT = 3001;

app.use(cors());
app.use(express.json());

const BEE_CLIENT_ID = process.env.BEE_CLIENT_ID;
const BEE_CLIENT_SECRET = process.env.BEE_CLIENT_SECRET;

// V2 Auth Endpoint
app.post('/proxy/bee-auth', async (req, res) => {
  try {
    const { uid } = req.body;
    
    const response = await axios.post(
      'https://auth.getbee.io/loginV2',
      {
        client_id: BEE_CLIENT_ID,
        client_secret: BEE_CLIENT_SECRET,
        uid: uid || 'demo-user'
      },
      { headers: { 'Content-Type': 'application/json' } }
    );
    
    res.json(response.data);
  } catch (error) {
    console.error('Auth error:', error.message);
    res.status(500).json({ error: 'Failed to authenticate' });
  }
});

app.listen(PORT, () => {
  console.log(`Proxy server running on http://localhost:${PORT}`);
});

Authentication Process

Use the V2 authentication endpoint: https://auth.getbee.io/loginV2
Pass the ENTIRE API response to the Beefree SDK, not just the token

Example authentication call:

const token = await fetch('http://localhost:3001/proxy/bee-auth', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ uid: 'demo-user' })
}).then(res => res.json());

Container Setup Guidelines

HTML Container

Create a dedicated container element for the Beefree SDK:
```
<div id="beefree-sdk-container"></div>
```

CSS Styling

Style the container to ensure proper display:

#beefree-sdk-container {
  position: absolute;
  top: 0px;
  bottom: 0px;
  left: 0px;
  right: 0px;
  height: 600px;
  width: 90%;
  margin: 20px auto;
  border: 1px solid #ddd;
  border-radius: 8px;
}

React Container

For React applications, the following code snippet shows an example using refs to manage the container:

const containerRef = useRef<HTMLDivElement>(null);

return (
  <div
    id="beefree-react-demo"
    ref={containerRef}
    style={{
      height: '600px',
      width: '90%',
      margin: '20px auto',
      border: '1px solid #ddd',
      borderRadius: '8px'
    }}
  />
);

Configuration Guidelines

Required Configuration Parameters

ALWAYS include the container parameter in your configuration:

const beeConfig = {
  container: 'beefree-sdk-container', // Required
  language: 'en-US'
};

Optional Configuration Parameters

Customize your SDK with optional parameters:

const beeConfig = {
  container: 'beefree-sdk-container', // Required
  language: 'en-US',
  specialLinks: [
    {
      type: "unsubscribe",
      label: "Unsubscribe",
      link: "http://[unsubscribe]/",
    },
    {
      type: "subscribe",
      label: "Subscribe",
      link: "http://[subscribe]/",
    },
  ],
  mergeTags: [
    {
      name: "First Name",
      value: "[first_name]",
    },
    {
      name: "Last Name",
      value: "[last_name]",
    },
    {
      name: "Email",
      value: "[email]",
    },
  ]
};

Callback Functions

Implement essential callback functions for proper functionality:

const beeConfig = {
  container: 'beefree-sdk-container',
  onSave: function (jsonFile, htmlFile) {
    console.log("Template saved:", jsonFile);
    // Implement custom save logic here
  },
  onAutoSave: function (jsonFile) {
    console.log("Auto-saving template...");
    localStorage.setItem("email.autosave", jsonFile);
  },
  onSend: function (htmlFile) {
    console.log("Email ready to send:", htmlFile);
    // Implement custom send logic here
  },
  onError: function (errorMessage) {
    console.error("Beefree SDK error:", errorMessage);
    // Handle errors appropriately
  }
};

SDK Initialization Guidelines

Basic Initialization

Initialize the Beefree SDK with proper error handling:

async function initializeBeefree(authResponse) {
  try {
    const bee = new BeefreeSDK(authResponse);
    bee.start(beeConfig, {});
    console.log('Beefree SDK initialized successfully');
  } catch (error) {
    console.error('Failed to initialize Beefree SDK:', error);
  }
}

React Integration

For React applications, the following code snippet shows an example using useEffect for initialization:

useEffect(() => {
  async function initializeEditor() {
    const beeConfig = {
      container: 'beefree-react-demo',
      language: 'en-US',
      onSave: (pageJson: string, pageHtml: string, ampHtml: string | null, templateVersion: number, language: string | null) => {
        console.log('Saved!', { pageJson, pageHtml, ampHtml, templateVersion, language });
      },
      onError: (error: unknown) => {
        console.error('Error:', error);
      }
    };

    const token = await fetch('http://localhost:3001/proxy/bee-auth', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({ uid: 'demo-user' })
    }).then(res => res.json());

    const bee = new BeefreeSDK(token);
    bee.start(beeConfig, {});
  }

  initializeEditor();
}, []);

Template Loading Guidelines

Loading Templates

Use the start() method with template data to load existing templates:

// Load template from localStorage
const selectedTemplate = JSON.parse(localStorage.getItem('currentEmailData'));

if (selectedTemplate) {
  beefreeSDKInstance.start(selectedTemplate);
  console.log('Loaded template from localStorage');
} else {
  // Start with empty template
            beefreeSDKInstance.start();
        console.log('Started with empty template');
}

Template Storage

Store templates in localStorage for persistence while testing:

// Save template data
localStorage.setItem('currentEmailData', JSON.stringify(templateData));
localStorage.setItem('currentEmailName', emailName);

// Load template data
const emailData = localStorage.getItem('currentEmailData');
const emailName = localStorage.getItem('currentEmailName');

Autosave Functionality

Implement autosave to prevent data loss:

onAutoSave: function (jsonFile) {
  console.log("Auto-saving template...");
  localStorage.setItem("email.autosave", jsonFile);
}

HTML Import Guidelines

HTML Importer API

Use the HTML Importer API to convert existing HTML templates to Beefree SDK format
API endpoint: https://api.getbee.io/v1/conversion/html-to-json
Reference: HTML Importer API Documentation

Import Process

Convert HTML templates to Beefree SDK's native JSON format:

const response = await fetch('https://api.getbee.io/v1/conversion/html-to-json', {
  method: 'POST',
  headers: {
    "Authorization": "Bearer Enter Dev Console API Key as Bearer token",
    "Content-Type": "text/html"
  },
  body: "<!DOCTYPE html><html><body><h1>Hello World</h1></body></html>"
}); 
const data = await response.json();

Loading Imported Templates

Load imported templates into the Beefree SDK:

const importedTemplate = await importHtmlTemplate(htmlContent);
beefreeSDK.start(importedTemplate);

Error Handling Guidelines

onError Callback

ALWAYS implement the onError callback to handle SDK errors:

onError: function (errorMessage) {
  console.error("Beefree SDK error:", errorMessage);
  // Display user-friendly error message
  document.getElementById('beefree-sdk-container').innerHTML = 
    '<div class="error">Error loading Beefree SDK: ' + errorMessage.message + '</div>';
}

Authentication Error Handling

Handle authentication failures gracefully:

function getBeeToken(callback) {
  fetch('/api/beefree/auth', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
      client_id: 'your_client_id',
      client_secret: 'your_client_secret',
      uid: beeConfig.uid
    })
  })
  .then(response => {
    if (!response.ok) throw new Error('Auth failed: ' + response.status);
    return response.json();
  })
  .then(data => {
    callback(data);
  })
  .catch(error => {
    console.error('Error getting Beefree token:', error);
    document.getElementById('beefree-sdk-container').innerHTML = 
      '<div class="error">Failed to authenticate with Beefree. Please check your credentials and try again.</div>';
  });
}

Template Change Tracking Guidelines

Track Message Changes

Implement template change tracking to monitor changes made by end users
Reference: Track Message Changes Documentation

Change Detection

Use the onChange callback to track template changes:

onChange: function (jsonFile, response) {
console.log('json', jsonFile);
console.log('response', response);
  },

Customization Guidelines

UI Customization

Customize the Beefree SDK appearance with:

Language Customization

Set the language for internationalization:

const beeConfig = {
  container: 'beefree-sdk-container',
  language: 'en-US', // or 'es-ES', 'fr-FR', etc.
};

Merge Tags and Special Links

Configure merge tags and special links for email personalization:

const beeConfig = {
  container: 'beefree-sdk-container',
  mergeTags: [
    { name: "First Name", value: "[first_name]" },
    { name: "Last Name", value: "[last_name]" },
    { name: "Email", value: "[email]" },
    { name: "Company", value: "[company]" }
  ],
  specialLinks: [
    { type: "unsubscribe", label: "Unsubscribe", link: "http://[unsubscribe]/" },
    { type: "subscribe", label: "Subscribe", link: "http://[subscribe]/" },
    { type: "webview", label: "View in Browser", link: "http://[webview]/" }
  ]
};

Other Customizations

Reference the official Beefree SDK technical documentation for a comprehnsive reference of possible customizations.

Best Practices

Performance Optimization

Initialize the Beefree SDK only when it is actually needed in your application.
Properly clean up SDK resources when they are no longer required (e.g., when navigating away or closing the editor).
Handle errors gracefully to prevent application crashes or unexpected behavior.

Security

Never expose your Beefree SDK client credentials in any frontend or public code.
Always use a secure backend or proxy server to handle authentication and sensitive operations.
Validate and sanitize all user inputs before passing them to the SDK to prevent security vulnerabilities.

User Experience

Show appropriate loading indicators while the SDK is initializing or performing operations.
Display clear and helpful error messages to users if something goes wrong.
Implement automatic saving or progress tracking to prevent data loss.

Code Organization

Keep SDK configuration separate from initialization and business logic for better maintainability.
Use strong typing (e.g., TypeScript or similar) where possible to improve code safety and clarity.
Ensure robust error handling throughout your integration, regardless of the tech stack or framework used.

Examples

Complete React Component

Reference the full project at beefree-react-demo.

import { useEffect, useRef } from 'react';
import BeefreeSDK from '@beefree.io/sdk';

export default function BeefreeEditor() {
  const containerRef = useRef<HTMLDivElement>(null);

  useEffect(() => {
    async function initializeEditor() {
      const beeConfig = {
        container: 'beefree-react-demo',
        language: 'en-US',
        onSave: (pageJson: string, pageHtml: string, ampHtml: string | null, templateVersion: number, language: string | null) => {
          console.log('Saved!', { pageJson, pageHtml, ampHtml, templateVersion, language });
        },
        onError: (error: unknown) => {
          console.error('Error:', error);
        }
      };

      const token = await fetch('http://localhost:3001/proxy/bee-auth', {
        method: 'POST',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify({ uid: 'demo-user' })
      }).then(res => res.json());

      const bee = new BeefreeSDK(token);
      bee.start(beeConfig, {});
    }

    initializeEditor();
  }, []);

  return (
    <div
      id="beefree-react-demo"
      ref={containerRef}
      style={{
        height: '600px',
        width: '90%',
        margin: '20px auto',
        border: '1px solid #ddd',
        borderRadius: '8px'
      }}
    />
  );
}

Complete HTML Implementation

Reference the complete project at Beefree SDK multiple-versions-concept.

<!DOCTYPE html>
<html lang="en">
  <head>
    <title>Beefree SDK - Email Builder</title>
    <meta charset="utf-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1" />
    <style type="text/css">
      #beefree-sdk-container {
        position: absolute;
        top: 0px;
        bottom: 0px;
        left: 0px;
        right: 0px;
      }
    </style>
  </head>
  <body>
    <div id="beefree-sdk-container"></div>
    <script src="https://app-rsrc.getbee.io/plugin/BeefreeSDK.js"></script>
    <script type="text/javascript">
      const beeConfig = {
            container: 'beefree-sdk-container',
    uid: 'demo-user-' + Date.now(),
    language: 'en-US',
        onSave: function (jsonFile, htmlFile) {
          console.log("Template saved:", jsonFile);
        },
        onError: function (errorMessage) {
          console.error("Beefree SDK error:", errorMessage);
        }
      };

      function getBeeToken(callback) {
        fetch('/api/beefree/auth', {
          method: 'POST',
          headers: { 'Content-Type': 'application/json' },
          body: JSON.stringify({
            client_id: 'your_client_id',
            client_secret: 'your_client_secret',
            uid: beeConfig.uid
          })
        })
        .then(response => response.json())
        .then(data => callback(data))
        .catch(error => {
          console.error('Error getting Beefree token:', error);
        });
      }

      function initializeBeefree(authResponse) {
        BeefreeSDK.create(authResponse, beeConfig, function (beefreeSDKInstance) {
          console.log('Beefree SDK initialized successfully');
          beefreeSDKInstance.start();
        });
      }

      getBeeToken(initializeBeefree);
    </script>
  </body>
</html>