From c9d0e9f28e57cd7efd7078d4fe1b9385b6fce000 Mon Sep 17 00:00:00 2001
From: Karl Kemister-Sheppard <karlkemistersheppard@gmail.com>
Date: Mon, 19 Oct 2026 11:55:18 +1000
Subject: [PATCH 1/2] TINYDOC-3659: Add an example of tracking editor loads
 with init_instance_callback.

---
 .../pages/understanding-editor-loads.adoc     | 27 ++++++++++++++++++-
 1 file changed, 26 insertions(+), 1 deletion(-)

diff --git a/modules/ROOT/pages/understanding-editor-loads.adoc b/modules/ROOT/pages/understanding-editor-loads.adoc
index 0bc516fa4d..c5ce63db6d 100644
--- a/modules/ROOT/pages/understanding-editor-loads.adoc
+++ b/modules/ROOT/pages/understanding-editor-loads.adoc
@@ -1,7 +1,7 @@
 = Understanding editor loads
 :navtitle: Understanding editor loads
 :description: Relevant information for Tiny Cloud users to help understand editor loads for {productname}.
-:keywords: invalid-api-key, API, {productname}, cloud, frequently asked questions
+:keywords: invalid-api-key, API, {productname}, cloud, frequently asked questions, editor loads, init, init_instance_callback, setup, analytics, track editor loads
 
 == Understanding editor loads for {productname}
 
@@ -28,6 +28,31 @@ An editor load is counted each time a new {productname} editor instance complete
 
 Each individual editor instance on a page is counted as one editor load. For example, if a page has ten editors, a single refresh of that page results in ten editor loads.
 
+[[how-can-i-track-editor-loads]]
+== How can I track editor loads?
+
+To record editor loads in an external analytics or logging service, use the xref:editor-important-options.adoc#init_instance_callback[`+init_instance_callback+`] option. The callback runs once for each editor instance, immediately after the editor dispatches the `init` event, so each call corresponds to one editor load.
+
+[source,js]
+----
+tinymce.init({
+  selector: 'textarea', // change this value according to your HTML
+  init_instance_callback: (editor) => {
+    // Replace myService with the analytics or logging service used by the application.
+    // The object passed to the service can contain any data the application needs to track.
+    myService.log({
+      event: 'editor-load',
+      editorId: editor.id,
+      page: window.location.pathname
+    });
+  }
+});
+----
+
+The `+editor.id+` value is the `+id+` attribute of the element the editor replaces. When that element has no `+id+`, the editor uses its `+name+` attribute if no other element on the page has that `+id+`, and otherwise generates an identifier such as `+mce_0+`. Generated identifiers can change between page loads, so assign a unique `+id+` to each target element to track loads for a specific editor.
+
+The same result can be achieved by binding a listener to the `init` event in the xref:editor-important-options.adoc#setup[`+setup+`] option, for example `+editor.once('init', () => myService.log({ editorId: editor.id }))+`. The `+init_instance_callback+` option is simpler when the only requirement is to record the load.
+
 == What can contribute to a high number of editor loads?
 
 The most obvious scenario is using multiple editors on a single page (see above). For example:

From c3889b812687b4ff7ec919ab39f306d7838328dc Mon Sep 17 00:00:00 2001
From: Karl Kemister-Sheppard <karlkemistersheppard@gmail.com>
Date: Tue, 20 Oct 2026 16:45:02 +1000
Subject: [PATCH 2/2] TINYDOC-3659: Note that the callback receives the full
 Editor instance and link to its properties.

---
 modules/ROOT/pages/understanding-editor-loads.adoc | 4 +++-
 1 file changed, 3 insertions(+), 1 deletion(-)

diff --git a/modules/ROOT/pages/understanding-editor-loads.adoc b/modules/ROOT/pages/understanding-editor-loads.adoc
index c5ce63db6d..604b83918c 100644
--- a/modules/ROOT/pages/understanding-editor-loads.adoc
+++ b/modules/ROOT/pages/understanding-editor-loads.adoc
@@ -39,7 +39,7 @@ tinymce.init({
   selector: 'textarea', // change this value according to your HTML
   init_instance_callback: (editor) => {
     // Replace myService with the analytics or logging service used by the application.
-    // The object passed to the service can contain any data the application needs to track.
+    // Add any other editor properties the application needs to track.
     myService.log({
       event: 'editor-load',
       editorId: editor.id,
@@ -49,6 +49,8 @@ tinymce.init({
 });
 ----
 
+The callback receives the xref:apis/tinymce.editor.adoc[Editor] instance, so the object sent to the service can include any of the editor's xref:apis/tinymce.editor.adoc#properties[properties]. The example uses `+editor.id+` because it identifies which editor on the page loaded.
+
 The `+editor.id+` value is the `+id+` attribute of the element the editor replaces. When that element has no `+id+`, the editor uses its `+name+` attribute if no other element on the page has that `+id+`, and otherwise generates an identifier such as `+mce_0+`. Generated identifiers can change between page loads, so assign a unique `+id+` to each target element to track loads for a specific editor.
 
 The same result can be achieved by binding a listener to the `init` event in the xref:editor-important-options.adoc#setup[`+setup+`] option, for example `+editor.once('init', () => myService.log({ editorId: editor.id }))+`. The `+init_instance_callback+` option is simpler when the only requirement is to record the load.