Tracking Message Changes

This feature is available on Beefree SDK paid plans only.

Overview of Tracking Message Changes

This page discusses how to effectively track message and UI changes in Beefree SDK. It explains how you can use the onChange function to monitor real-time JSON updates, enabling efficient application updates and debugging, if needed. It also covers how to implement the onRemoteChange function to track edits made by other users for Collaborative Editing.

In addition to these, the onViewChange callback offers a way to monitor changes in the SDK’s interface — such as when users open or close the File Manager, Preview, or Image Editor. This allows you to better understand user behavior, enhance session monitoring, and potentially optimize UX flows based on user navigation.

By leveraging these three callbacks — onChange, onRemoteChange, and onViewChange — you can develop a comprehensive workflow for tracking both content and interaction changes your end users make, whether they are within a single session or a collaborative editing session.

Callback Reference for Tracking Changes

The following table provides a quick reference of callbacks related to tracking changes.

Event	Description	Returned Values
onChange	Fired when the message JSON is updated locally.	The new message JSON object.
onRemoteChange	Fired when changes are made to the message by a different user in a collaborative session.	The updated JSON from the remote user.
onViewChange	Fired when the user navigates between different views in the SDK interface (e.g., opening preview).	One of: 'fileManager', 'editor', 'preview', 'imageEditor'.

This page explores and answers the following questions:

• How can I monitor what my customers do in the builder?

• How can I tell when a message has actually been updated?

• How can I tell when a collaborative editing session has been updated?

• How can I track which part of the UI a user is interacting with?

Use Cases for Tracking Message Changes

This section includes use cases for the onChange, onRemoteChange, and onViewChange callbacks.

Usage Tracking

Understanding how users interact with the builder helps improve UX, prioritize development, and identify friction points. The onChange callback lets your app detect when users are actively editing a message, using specific features, or possibly reproducing a reported issue.

Use it to:

• Detect active vs. abandoned editing sessions

• Monitor usage of new features

• Investigate and reproduce bugs

Autosave

Unlike the default autosave (which triggers at fixed intervals regardless of changes), onChange enables saving only when actual edits occur. This reduces false-positive recovery dialogs and improves the message recovery experience.

History

Tracking changes over time allows users to compare and restore previous message versions — especially helpful in collaborative environments where mistakes can lead to lost work.

Content Checks

When users edit text or images, onChange returns the updated content, enabling your app to run validations or custom logic.

Example use cases:

• Content suggestions

• Blocking restricted content

• Validating links and their reputation

• Checking custom HTML

• Handling conditional syntax with custom workflows

Prerequisites

To enable tracking message changes, you need to add the following in the beeConfig:

• Add trackChanges and set it to true.

• The onChange callback, with the related response function.

• (Optional) Add and set the onRemoteChange boolean to true for multi-user message tracking during collaborative editing session.

Enable "onChange" Event

Set the following parameter to true in the beeConfig file to enable onChange.

trackChanges: true, // boolean

onChange

When you enable onChange and your end users edit their message, the callback provides you with:

• Information on the new content or section

• The action that was performed on existing content

• The JSON update (as the entire page, as well as JSON patches)

onChange JSON example

The following JSON displays an example of what you can expect to receive from the onChange callback.

{
    "message": {
        "page": {
            "body": {
                "container": {
                    "style": {
                        "background-color": "#FFFFFF"
                    }
                },
                "content": {
                    "computedStyle": {
                        "linkColor": "#0068A5",
                        "messageBackgroundColor": "transparent",
                        "messageWidth": "500px"
                    },
                    "style": {
                        "color": "#000000",
                        "font-family": "Arial, Helvetica, sans-serif"
                    }
                },
                "type": "mailup-bee-page-properties",
                "webFonts": []
            },
            "description": "Empty template for BEE",
            "rows": [
                {
                    "columns": [
                        {
                            "grid-columns": 12,
                            "modules": [
                                {
                                    "type": "mailup-bee-newsletter-modules-heading",
                                    "descriptor": {
                                        "heading": {
                                            "title": "h1",
                                            "text": "<span class=\"tinyMce-placeholder\">hello</span>",
                                            "style": {
                                                "color": "#555555",
                                                "font-size": "23px",
                                                "font-family": "inherit",
                                                "link-color": "#0068A5",
                                                "line-height": "120%",
                                                "text-align": "center",
                                                "direction": "ltr",
                                                "font-weight": "700",
                                                "letter-spacing": "0px"
                                            }
                                        },
                                        "style": {
                                            "width": "100%",
                                            "text-align": "center",
                                            "padding-top": "0px",
                                            "padding-right": "0px",
                                            "padding-bottom": "0px",
                                            "padding-left": "0px"
                                        },
                                        "mobileStyle": {}
                                    },
                                    "uuid": "e4b98f50-b74c-45a8-a184-e5622cdd62fe",
                                    "locked": false
                                }
                            ],
                            "style": {
                                "background-color": "transparent",
                                "border-bottom": "0px solid transparent",
                                "border-left": "0px solid transparent",
                                "border-right": "0px solid transparent",
                                "border-top": "0px solid transparent",
                                "padding-bottom": "5px",
                                "padding-left": "0px",
                                "padding-right": "0px",
                                "padding-top": "5px"
                            },
                            "uuid": "bb75ccd1-db9a-4c93-9cf4-85644245b25d"
                        }
                    ],
                    "container": {
                        "style": {
                            "background-color": "transparent",
                            "background-image": "none",
                            "background-position": "top left",
                            "background-repeat": "no-repeat"
                        }
                    },
                    "content": {
                        "computedStyle": {
                            "hideContentOnDesktop": false,
                            "hideContentOnMobile": false,
                            "rowColStackOnMobile": true,
                            "rowReverseColStackOnMobile": false,
                            "verticalAlign": "top"
                        },
                        "style": {
                            "background-color": "transparent",
                            "background-image": "none",
                            "background-position": "top left",
                            "background-repeat": "no-repeat",
                            "color": "#000000",
                            "width": "500px"
                        }
                    },
                    "empty": false,
                    "locked": false,
                    "synced": false,
                    "type": "row-1-columns-12",
                    "uuid": "fd68e622-bad7-4cca-84e2-a0315d4ffba7"
                }
            ],
            "template": {
                "name": "template-base",
                "type": "basic",
                "version": "2.0.0"
            },
            "title": "Empty Template"
        },
        "comments": {}
    },
    "changes": {
        "code": "1323",
        "value": "<span class=\"tinyMce-placeholder\">hello</span>",
        "description": "Text edited",
        "patches": [
            {
                "op": "add",
                "path": "/rows/0/columns/0/modules/0",
                "value": {
                    "type": "mailup-bee-newsletter-modules-heading",
                    "descriptor": {
                        "heading": {
                            "title": "h1",
                            "text": "<span class=\"tinyMce-placeholder\">hello</span>",
                            "style": {
                                "color": "#555555",
                                "font-size": "23px",
                                "font-family": "inherit",
                                "link-color": "#0068A5",
                                "line-height": "120%",
                                "text-align": "center",
                                "direction": "ltr",
                                "font-weight": "700",
                                "letter-spacing": "0px"
                            }
                        },
                        "style": {
                            "width": "100%",
                            "text-align": "center",
                            "padding-top": "0px",
                            "padding-right": "0px",
                            "padding-bottom": "0px",
                            "padding-left": "0px"
                        },
                        "mobileStyle": {}
                    },
                    "uuid": "e4b98f50-b74c-45a8-a184-e5622cdd62fe",
                    "locked": false
                }
            }
        ]
    }
}

Note: onChange is also the foundation on which the Undo, Redo & Edit History feature was built on.

Example Function

The following code provides an example callback function for onChange.

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

onRemoteChange

The onRemoteChange callback is a bit different than onChange, because it monitors and tracks the changes of other users (those who are not the primary user) during collaborative editing sessions. Using this callback allows you to monitor the changes of all end users in the same session.

Consider the following when using the onRemoteChange callback:

• onChange and onRemoteChange have the same prerequisites.

• onChange and onRemoteChange have the same callback response schema structure.

The following code provides an example callback function for onRemoteChange.

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

onRemoteChange JSON example

The following JSON displays an example of the onRemoteChange callback response.

{
    "message": {
        "page": {
            "body": {
                "container": {
                    "style": {
                        "background-color": "#FFFFFF"
                    }
                },
                "content": {
                    "computedStyle": {
                        "linkColor": "#0068A5",
                        "messageBackgroundColor": "transparent",
                        "messageWidth": "500px"
                    },
                    "style": {
                        "color": "#000000",
                        "font-family": "Arial, Helvetica, sans-serif"
                    }
                },
                "type": "mailup-bee-page-properties",
                "webFonts": []
            },
            "description": "Empty template for BEE",
            "rows": [
                {
                    "columns": [
                        {
                            "grid-columns": 12,
                            "modules": [
                                {
                                    "type": "mailup-bee-newsletter-modules-heading",
                                    "descriptor": {
                                        "heading": {
                                            "title": "h1",
                                            "text": "<span class=\"tinyMce-placeholder\">I'm a new title block</span>",
                                            "style": {
                                                "color": "#555555",
                                                "font-size": "23px",
                                                "font-family": "inherit",
                                                "link-color": "#0068A5",
                                                "line-height": "120%",
                                                "text-align": "center",
                                                "direction": "ltr",
                                                "font-weight": "700",
                                                "letter-spacing": "0px"
                                            }
                                        },
                                        "style": {
                                            "width": "100%",
                                            "text-align": "center",
                                            "padding-top": "0px",
                                            "padding-right": "0px",
                                            "padding-bottom": "0px",
                                            "padding-left": "0px"
                                        },
                                        "mobileStyle": {}
                                    },
                                    "uuid": "e4b98f50-b74c-45a8-a184-e5622cdd62fe",
                                    "locked": false
                                }
                            ],
                            "style": {
                                "background-color": "transparent",
                                "border-bottom": "0px solid transparent",
                                "border-left": "0px solid transparent",
                                "border-right": "0px solid transparent",
                                "border-top": "0px solid transparent",
                                "padding-bottom": "5px",
                                "padding-left": "0px",
                                "padding-right": "0px",
                                "padding-top": "5px"
                            },
                            "uuid": "bb75ccd1-db9a-4c93-9cf4-85644245b25d"
                        }
                    ],
                    "container": {
                        "style": {
                            "background-color": "transparent",
                            "background-image": "none",
                            "background-position": "top left",
                            "background-repeat": "no-repeat"
                        }
                    },
                    "content": {
                        "computedStyle": {
                            "hideContentOnDesktop": false,
                            "hideContentOnMobile": false,
                            "rowColStackOnMobile": true,
                            "rowReverseColStackOnMobile": false,
                            "verticalAlign": "top"
                        },
                        "style": {
                            "background-color": "transparent",
                            "background-image": "none",
                            "background-position": "top left",
                            "background-repeat": "no-repeat",
                            "color": "#000000",
                            "width": "500px"
                        }
                    },
                    "empty": false,
                    "locked": false,
                    "synced": false,
                    "type": "row-1-columns-12",
                    "uuid": "fd68e622-bad7-4cca-84e2-a0315d4ffba7"
                }
            ],
            "template": {
                "name": "template-base",
                "type": "basic",
                "version": "2.0.0"
            },
            "title": "Empty Template"
        }
    },
    "changes": {
        "code": "1300",
        "description": "Title dropped",
        "patches": [
            {
                "op": "add",
                "path": "/rows/0/columns/0/modules/0",
                "value": {
                    "type": "mailup-bee-newsletter-modules-heading",
                    "descriptor": {
                        "heading": {
                            "title": "h1",
                            "text": "<span class=\"tinyMce-placeholder\">I'm a new title block</span>",
                            "style": {
                                "color": "#555555",
                                "font-size": "23px",
                                "font-family": "inherit",
                                "link-color": "#0068A5",
                                "line-height": "120%",
                                "text-align": "center",
                                "direction": "ltr",
                                "font-weight": "700",
                                "letter-spacing": "0px"
                            }
                        },
                        "style": {
                            "width": "100%",
                            "text-align": "center",
                            "padding-top": "0px",
                            "padding-right": "0px",
                            "padding-bottom": "0px",
                            "padding-left": "0px"
                        },
                        "mobileStyle": {}
                    },
                    "uuid": "e4b98f50-b74c-45a8-a184-e5622cdd62fe",
                    "locked": false
                }
            }
        ],
        "value": ""
    }
}

onViewChange

The onViewChange callback differs from onChange and onRemoteChange because it doesn't track content changes in the message itself — instead, it fires when the user interacts with different interface views inside the Beefree SDK. This includes navigating to the File Manager, opening the Preview mode, or launching the Image Editor. It’s especially useful for understanding user behavior, enhancing user experience analytics, or conditionally triggering application logic based on view changes.

Consider the following when using the onViewChange callback:

• onViewChange does not return a message JSON object like onChange or onRemoteChange.

• It returns a single string representing the current view.

• Typical values include:

  • 'fileManager' – when the File Manager is opened

  • 'editor' – when the user returns to the main editor (including on initial load)

  • 'preview' – when the Preview mode is opened

  • 'imageEditor' – when the Image Editor is opened

The following code provides an example callback function for onViewChange:

onViewChange: function (view) {
  console.log('Current SDK view:', view);
}

Configure onChange and onRemoteChange

Note: This section discusses how to configure both onChange and onRemoteChange. Please keep in mind that the configurations apply to both callbacks.

This section discusses how to configure onChange and onRemoteChange.

This parameter defines when the tracking is active in the builder.

onChange Event

onChange: function (jsonFile, response) { // do something with response... },

The onChange callback is triggered every time the builder tracks a change in the message. It returns the message JSON and a response JSON which contains all the information needed to handle any of the use cases described above.

Callback response schema

{
    "code": "01", // See content and action codes bellow
    "description": "string",
    "value": "string", // See the chart below
    "patches": {...} // JSON patch formatted object
}

Callback Parameters

The following table lists the parameters in the onChange and onRemoteChange callback response schema and their corresponding types and values.

Parameter	Type	Value
code	string	Unique identifier for the event created by combining the content code with the action code.
description	string	A text description of the event in the chosen language. (e.g. Image Block Padding Left: 5px)
value	string	If available, this is the new value. (e.g. If padding changes to 5px, then the value returned is “5px”)
patches	array	An array of patches in the JSON Patch specification. JSON Patch is specified in RFC 6902 from the IETF.

Content Codes

Code	Content
01	Text Block
02	Image Block
03	Button Block
04	Divider Block
05	Social Block
06	Dynamic Content Block
07	HTML Block
08	Video Block
09	Form
10	Icons
11	Menu
14	Row
16	Message
18	Spacer
22	Paragraph
23	List
26	Table

Common Actions

Code	Action
00	Dropped
01	Dragged
02	Deleted
03	Duplicated
04	Changed
05	Opened
06	Closed
07	Locked
08	Saved
09	Restored
10	Content area background color
11	Do not stack on mobile
12	Row background image
13	Background Center
14	Background Repeat
15	Background Full width
16	Row Display condition
17	Reverse stack order on mobile
20	Text color
21	Link color
23	Text edited
24	Line height
25	Content area width
27	Background color
28	Default font
30	Padding All sides
31	Padding Left
32	Padding Right
33	Padding Top
34	Padding Bottom
40	Hide on mobile
41	Video url
42	Play icon type
43	Play icon color
44	Play icon size
50	Align
51	Automatic image resizing
52	Full width on mobile
53	Image width
60	Alternate text
61	Dynamic image src
62	Dynamic image toggle
63	Change image
64	Image link
70	Button Align
71	Button Link type
72	Button width
73	Button Auto width
74	Button Background color
75	Border radius
80	HTML edited
81	Border All sides
82	Border Left
83	Border Right
84	Border Top
85	Border Bottom
90	Divider Line toggle
91	Divider Width
92	Divider Height
93	Divider Align
95	Icon Name
96	Icon Alternate text
97	Icon Url
98	Icon spacing
99	Icon Align
128	Background Video
129	Paragraph Spacing
130	Font Weight
131	List Type
132	Start List
133	List Spacing
134	List Indent
135	List Style Position

Complete Event Chart

Code	Description	Type	Value
0100	Text dropped	module
0101	Text dragged	module
0102	Text deleted	module
0103	Text duplicated	module
0120	Text color {{value}}	string	Hex color code (e.g. #FFFFFF)
0121	Link color {{value}}	string	Hex color code (e.g. #FFFFFF)
0123	Text edited	string	HTML
0124	Line height {{value}}	string	Value as percent (e.g. 150%)
0130	Padding Add sides {{value}}	string	Value in pixels (e.g. 25px)
0131	Padding Left {{value}}	string	Value in pixels (e.g. 25px)
0132	Padding Right {{value}}	string	Value in pixels (e.g. 25px)
0133	Padding Top {{value}}	string	Value in pixels (e.g. 25px)
0134	Padding Bottom {{value}}	string	Value in pixels (e.g. 25px)
0140	Hide on mobile	boolean	true | false
0200	Image dropped	module
0201	Image dragged	module
0202	Image deleted	module
0203	Image duplicated	module
0230	Padding Add sides {{value}}	string	Value in pixels (e.g. 25px)
0231	Padding Left {{value}}	string	Value in pixels (e.g. 25px)
0232	Padding Right {{value}}	string	Value in pixels (e.g. 25px)
0233	Padding Top {{value}}	string	Value in pixels (e.g. 25px)
0234	Padding Bottom {{value}}	string	Value in pixels (e.g. 25px)
0240	Hide on mobile	boolean	true | false
0250	Align {{value}}	string	left | right | center
0251	Automatic image resizing	boolean	true | false
0252	Full width on mobile	boolean	true | false
0253	Image width {{value}}	string	%
0260	Alternate Text	string	text value
0261	Dynamic image	string	Image path
0262	Dynamic image toggle	boolean	false (only triggered when disabled)
0263	Change image	string	Image path
0264	Image link	string	Url
0300	Button dropped	module
0301	Button dragged	module
0302	Button deleted	module
0303	Button duplicated	module
0320	Text color {{value}}	string	Hex color code (e.g. #FFFFFF)
0324	Line height {{value}}	string	Value as percent (e.g. 150%)
0330	Padding Add sides {{value}}	string	Value in pixels (e.g. 25px)
0331	Padding Left {{value}}	string	Value in pixels (e.g. 25px)
0332	Padding Right {{value}}	string	Value in pixels (e.g. 25px)
0333	Padding Top {{value}}	string	Value in pixels (e.g. 25px)
0334	Padding Bottom {{value}}	string	Value in pixels (e.g. 25px)
0340	Hide on mobile	boolean	true | false
0370	Align {{value}}	string	left | right | center
0371	Link type {{value}}	string	Url
0372	Button width {{value}}	string	%
0373	Auto width	boolean	true | false
0374	Background color {{value}}	string	Hex Color Code (e.g. #FFFFFF)
0375	Border radius	string	Value in pixels (e.g. 5px)
0381	Border Add sides {{value}}	string	Value in pixels | Border Style | Hex color (e.g. 1px solid #C7702E)
0382	Border Left {{value}}	string	Value in pixels | Border Style | Hex color 1px solid #C7702E
0383	Border Right {{value}}	string	Value in pixels | Border Style | Hex color 1px solid #C7702E
0384	Border Top {{value}}	string	Value in pixels | Border Style | Hex color 1px solid #C7702E
0385	Border Bottom {{value}}	string	Value in pixels | Border Style | Hex color 1px solid #C7702E
0400	Divider dropped	module
0401	Divider dragged	module
0402	Divider deleted	module
0403	Divider duplicated	module
0430	Padding Add sides {{value}}	string	Value in pixels (e.g. 25px)
0431	Padding Left {{value}}	string	Value in pixels (e.g. 25px)
0432	Padding Right {{value}}	string	Value in pixels (e.g. 25px)
0433	Padding Top {{value}}	string	Value in pixels (e.g. 25px)
0434	Padding Bottom {{value}}	string	Value in pixels (e.g. 25px)
0440	Hide on mobile	boolean	true | false
0490	Line	string	Value in pixels | Border Style | Hex color 1px solid #C7702E
0491	Width {{value}}	string	Value as percent (e.g. 150%)
0492	Height {{value}}	string	Value in pixels (e.g. 25px)
0493	Align {{value}}	string	left | right | center
0500	Social dropped	module
0501	Social dragged	module
0502	Social deleted	module
0503	Social duplicated	module
0530	Padding Add sides {{value}}	string	Value in pixels (e.g. 25px)
0531	Padding Left {{value}}	string	Value in pixels (e.g. 25px)
0532	Padding Right {{value}}	string	Value in pixels (e.g. 25px)
0533	Padding Top {{value}}	string	Value in pixels (e.g. 25px)
0534	Padding Bottom {{value}}	string	Value in pixels (e.g. 25px)
0540	Hide on mobile	boolean	true | false
0595	Name {{value}}	string	Icon Name
0596	Alternate Text {{value}}	string	Icon Alternate text
0597	Image Url	string	Icon Url
0598	Icon spacing {{value}}	string	Value in pixels (e.g. 0 0 5px 15px)
0599	Align {{value}}	string	left | right | center
0600	Dynamic content dropped	module
0601	Dynamic content dragged	module
0602	Dynamic content deleted	module
0603	Dynamic content duplicated	module
0604	Dynamic content changed	string	value
0640	Hide on mobile	boolean	true | false
0700	HTML dropped	module
0701	HTML dragged	module
0702	HTML deleted	module
0703	HTML duplicated	module
0740	Hide on mobile	boolean	true | false
0780	HTML edited	string	HTML
0800	Video dropped	module
0801	Video dragged	module
0802	Video deleted	module
0803	Video duplicated	module
0830	Padding Add sides {{value}}	string	Value in pixels (e.g. 25px)
0831	Padding Left {{value}}	string	Value in pixels (e.g. 25px)
0832	Padding Right {{value}}	string	Value in pixels (e.g. 25px)
0833	Padding Top {{value}}	string	Value in pixels (e.g. 25px)
0834	Padding Bottom {{value}}	string	Value in pixels (e.g. 25px)
0840	Hide on mobile	boolean	true | false
0841	Video url	string	Video Url
0842	Play icon type {{value}}	string	Play icon type (e.g. Round outline)
0843	Play icon color {{value}}	string	light | dark
0844	Play icon size {{value}}	string	Value in pixels (e.g. 25px)
1400	Row dropped	row
1401	Row dragged	row
1402	Row deleted	row
1403	Row duplicated	row
1410	Content background color {{value}}	string	Hex Color Code (e.g. #FFFFFF)
1411	Do not stack on mobile	boolean	true | false
1412	Row background image	string	Image path
1413	Center	boolean	true | false
1414	Repeat	boolean	true | false
1415	Full width	boolean	true | false
1416	Display Condition	object	Display condition object
1417	Reverse stack order on mobile	boolean	true | false
1430	Padding Add sides {{value}}	string	Value in pixels (e.g. 25px)
1431	Padding Left {{value}}	string	Value in pixels (e.g. 25px)
1432	Padding Right {{value}}	string	Value in pixels (e.g. 25px)
1433	Padding Top {{value}}	string	Value in pixels (e.g. 25px)
1434	Padding Bottom {{value}}	string	Value in pixels (e.g. 25px)
1474	Background color {{value}}	string	Hex Color Code (e.g. #FFFFFF)
1481	Border Add sides {{value}}	string	Value in pixels | Border Style | Hex color 1px solid #C7702E
1482	Border Left {{value}}	string	Value in pixels | Border Style | Hex color 1px solid #C7702E
1483	Border Right {{value}}	string	Value in pixels | Border Style | Hex color 1px solid #C7702E
1484	Border Top {{value}}	string	Value in pixels | Border Style | Hex color 1px solid #C7702E
1485	Border Bottom {{value}}	string	Value in pixels | Border Style | Hex color 1px solid #C7702E
1625	Content area width {{value}}	string	Value in pixels (e.g. 25px)
1626	Background color {{value}}	string	Hex Color Code (e.g. #FFFFFF)
1627	Content area background color: {{value}}	string	Hex Color Code (e.g. #FFFFFF)
1628	Default font	string	Font
1529	Link color {{value}}	string	Hex Color Code (e.g. #FFFFFF)
1605	Message opened	page	JSON template
1609	Message restored (e.g. undo or redo history)	page	JSON template
13130	Button Font Weight	string
14128	Row Background Video	string	Video URL
22130	Paragraph Font Weight	string	Font Weight value