DOC-3215: Docs changes for new onboarding feature.

kemister85 · kemister85 · commit d99a9b0a1a06 · 2025-05-14T13:35:01.000+10:00
diff --git a/modules/ROOT/images/onboarding/onboarding-finish-setting-up-dialog.png b/modules/ROOT/images/onboarding/onboarding-finish-setting-up-dialog.png
diff --git a/modules/ROOT/images/onboarding/onboarding-no-api-key-notification.png b/modules/ROOT/images/onboarding/onboarding-no-api-key-notification.png
diff --git a/modules/ROOT/images/onboarding/onboarding-trial-explore-features.png b/modules/ROOT/images/onboarding/onboarding-trial-explore-features.png
diff --git a/modules/ROOT/pages/7.8.0-release-notes.adoc b/modules/ROOT/pages/7.8.0-release-notes.adoc
@@ -257,14 +257,6 @@ tinymce.init({
 </p>
 ----
 
-// === New `onboarding` option
-// // #TINY-11931
-
-// {productname} {release-version} introduces a new `+onboarding+` option to enhance the developer experience during the 14-day trial period. This option controls the display of a cloud promotion banner highlighting paid features available during the trial. The banner is automatically hidden when the trial ends or when the editor is correctly configured, ensuring a smoother and less intrusive setup experience.
-
-// For more information, see xref:promotions.adoc#onboarding[onboarding].
-
-
 [[bug-fixes]]
 == Bug fixes
 
diff --git a/modules/ROOT/pages/7.9.0-release-notes.adoc b/modules/ROOT/pages/7.9.0-release-notes.adoc
@@ -161,6 +161,13 @@ Previously, {productname} did not offer a separate `disc` styling option for uno
 </ul>
 ----
 
+=== New `onboarding` option
+// #TINY-11931
+
+{productname} {release-version} introduces a new `+onboarding+` option to enhance the developer experience during the 14-day trial period. This option controls the display of a cloud promotion banner highlighting paid features available during the trial. The banner is automatically hidden when the trial ends or when the editor is correctly configured, ensuring a smoother and less intrusive setup experience.
+
+For more information, see xref:promotions.adoc#onboarding[onboarding].
+
 [[changes]]
 == Changes
 
diff --git a/modules/ROOT/pages/changelog.adoc b/modules/ROOT/pages/changelog.adoc
@@ -9,6 +9,8 @@ NOTE: This is the {productname} Community version changelog. For information abo
 === Added
 * Added new `disc` style option for unordered lists.
 // #TINY-12015
+* New `onboarding` option.
+// #TINY-11931
 
 === Improved
 * The resize cursor now points in the correct direction for each resize mode. Patch contributed by link:https://github.com/daniloff200[daniloff200].
@@ -49,8 +51,6 @@ NOTE: This is the {productname} Community version changelog. For information abo
 // #TINY-11748
 * New `extended_mathml_attributes` and `extended_mathml_elements` options.
 // #TINY-11756
-* New `onboarding` option.
-// #TINY-11931
 
 === Improved
 * Focus outline was misaligned with comment card border on saving an edit.
diff --git a/modules/ROOT/pages/cloud-troubleshooting.adoc b/modules/ROOT/pages/cloud-troubleshooting.adoc
@@ -15,12 +15,15 @@ NOTE: The wording of the notifications shown here may differ from the actual not
 [[A-valid-API-key-is-required-to-continue-using-TinyMCE.-Please-alert-the-admin-to-check-the-current-API-key]]
 === "A valid API key is required to continue using {productname}. **Please alert the admin** to check the current API key. xref:invalid-api-key.adoc[Click here to learn more.]"
 
-==== Cause "No API Key"
+==== Cause "no-api-key"
 
 This notification is *only shown* when either:
 
-* An `+apiKey+` is not provided in the script tag.
-* `+no-api-key+` is provided as the API key.
+
+image:onboarding/onboarding-no-api-key-notification.png[no-api-key-notificaiton-banner, width=800, height=auto]
+
+* An `+apiKey+` is not provided in the script tag, which triggers the **"Finish setting up"** dialog.
+* When `+no-api-key+` is provided as the API key inside the script tag.
 
 For example:
 
@@ -29,6 +32,8 @@ For example:
 <script src="{cdnurl}" referrerpolicy="origin"></script>
 ----
 
+In this case, the editor will be in a **read-only** state, and the user will see a **"Finish setting up"** dialog prompting them to add a valid API key, configure their domain, and explore premium features.
+
 ==== Solution
 
 Update the `+src+` URL to include your (website or application developer's) {cloudname} API Key. Your API key should replace the string `+no-api-key+`.
@@ -66,6 +71,63 @@ NOTE: Visit our xref:invalid-api-key.adoc[Invalid API key] page for more informa
 
 '''
 
+[[trial-banner-exploration]]
+== Trial Banner - Explore Features (Valid Trial API Key)
+
+=== "Try out paid features! Explore all of the trial benefits including Premium plugins."
+
+==== Cause
+
+This banner appears when the API key being used is associated with a trial account. The editor is fully functional but includes a banner promoting premium features such as `PowerPaste`, `Export to Word`, and `Templates`.
+
+
+image::onboarding/onboarding-trial-explore-features.png[trial-explore-features-notification-banner, width=400, height=auto]
+
+==== Solution
+
+To disable this banner:
+
+Set the `+onboarding+` option to `+false+` in your {productname} configuration:
+
+[source,javascript]
+----
+tinymce.init({
+selector: 'textarea',
+onboarding: false, // Disables trial banner
+plugins: 'lists link image table',
+toolbar: 'undo redo | bold italic | alignleft aligncenter alignright | bullist numlist | link image',
+});
+----
+
+Alternatively, upgrading your API key to a paid plan will remove the trial messages.
+
+
+[[empty-api-key]]
+== Empty API Key
+
+=== "A valid API key is required to continue using {productname}. Please alert the admin to check the current API key."
+
+==== Cause
+
+This message appears if the API key portion of the `+<script>+` URL is empty, such as:
+
+
+image:onboarding/onboarding-no-api-key-notification.png[no-api-key-notificaiton-banner, width=800, height=auto]
+
+
+[source,html]
+----
+<script src="https://cdn.staging.tiny.cloud/1//tinymce/{productmajorversion}/tinymce.min.js" referrerpolicy="origin"></script>
+----
+
+In this case, the resolved API key is effectively empty, resulting in a `read-only` editor state and the "A valid API key is required to continue using TinyMCE. Please alert the admin to check the current API key. Click here to learn more." message.
+
+==== Solution
+
+Ensure the API key is correctly included in the `+<script>+` URL, without any missing or empty segments.
+
+''''
+
 [[domain-not-registered]]
 == Domain Not Registered
 
diff --git a/modules/ROOT/pages/export-to-pdf-with-jwt-authentication-nodejs.adoc b/modules/ROOT/pages/export-to-pdf-with-jwt-authentication-nodejs.adoc
@@ -29,7 +29,7 @@ Inside the `public` folder where you created the `index.html` file add the HTML
 <head>
   <title>TinyMCE with Export to PDF</title>
   <script 
-    src="https://cdn.tiny.cloud/1/YOUR-API-KEY/tinymce/7/tinymce.min.js"
+    src="https://cdn.tiny.cloud/1/no-api-key/tinymce/7/tinymce.min.js"
     referrerpolicy="origin">
   </script>
   <script>
diff --git a/modules/ROOT/pages/export-to-pdf-with-jwt-authentication-php.adoc b/modules/ROOT/pages/export-to-pdf-with-jwt-authentication-php.adoc
@@ -28,7 +28,7 @@ Inside the `public` folder where you created the `index.html` file add the HTML
 <head>
   <title>TinyMCE with PDF Export</title>
   <script 
-    src="https://cdn.tiny.cloud/1/YOUR-API-KEY/tinymce/7/tinymce.min.js"
+    src="https://cdn.tiny.cloud/1/no-api-key/tinymce/7/tinymce.min.js"
     referrerpolicy="origin">
   </script>
   <script>
diff --git a/modules/ROOT/pages/export-to-word-with-jwt-authentication-nodejs.adoc b/modules/ROOT/pages/export-to-word-with-jwt-authentication-nodejs.adoc
@@ -29,7 +29,7 @@ Inside the `public` folder where you created the `index.html` file add the HTML
 <head>
   <title>TinyMCE with Export to Word</title>
   <script 
-    src="https://cdn.tiny.cloud/1/YOUR-API-KEY/tinymce/7/tinymce.min.js"
+    src="https://cdn.tiny.cloud/1/no-api-key/tinymce/7/tinymce.min.js"
     referrerpolicy="origin">
   </script>
   <script>
diff --git a/modules/ROOT/pages/export-to-word-with-jwt-authentication-php.adoc b/modules/ROOT/pages/export-to-word-with-jwt-authentication-php.adoc
@@ -28,7 +28,7 @@ Inside the `public` folder where you created the `index.html` file add the HTML
 <head>
   <title>TinyMCE with Word Export</title>
   <script 
-    src="https://cdn.tiny.cloud/1/YOUR-API-KEY/tinymce/7/tinymce.min.js"
+    src="https://cdn.tiny.cloud/1/no-api-key/tinymce/7/tinymce.min.js"
     referrerpolicy="origin">
   </script>
   <script>
diff --git a/modules/ROOT/pages/import-from-word-with-jwt-authentication-nodejs.adoc b/modules/ROOT/pages/import-from-word-with-jwt-authentication-nodejs.adoc
@@ -29,7 +29,7 @@ Inside the `public` folder where you created the `index.html` file add the HTML
 <head>
   <title>TinyMCE with Import from Word</title>
   <script 
-    src="https://cdn.tiny.cloud/1/YOUR-API-KEY/tinymce/7/tinymce.min.js"
+    src="https://cdn.tiny.cloud/1/no-api-key/tinymce/7/tinymce.min.js"
     referrerpolicy="origin">
   </script>
   <script>
diff --git a/modules/ROOT/pages/import-from-word-with-jwt-authentication-php.adoc b/modules/ROOT/pages/import-from-word-with-jwt-authentication-php.adoc
@@ -28,7 +28,7 @@ Inside the `public` folder where you created the `index.html` file add the HTML
 <head>
   <title>TinyMCE with Word Import</title>
   <script 
-    src="https://cdn.tiny.cloud/1/YOUR-API-KEY/tinymce/7/tinymce.min.js"
+    src="https://cdn.tiny.cloud/1/no-api-key/tinymce/7/tinymce.min.js"
     referrerpolicy="origin">
   </script>
   <script>
diff --git a/modules/ROOT/pages/migration-from-froala.adoc b/modules/ROOT/pages/migration-from-froala.adoc
@@ -38,10 +38,10 @@ To migrate from a basic Froala 3 configuration to a basic {productname} {product
 +
 [source,html,subs="attributes+"]
 ----
-<script src='https://cdn.tiny.cloud/1/your-api-key/tinymce/{productmajorversion}/tinymce.min.js' referrerpolicy='origin'></script>
+<script src='https://cdn.tiny.cloud/1/no-api-key/tinymce/{productmajorversion}/tinymce.min.js' referrerpolicy='origin'></script>
 ----
 +
-Replace `+your-api-key+` with your link:{accountpageurl}/[{cloudname} API key].
+Replace `+no-api-key+` with your link:{accountpageurl}/[{cloudname} API key].
 * For Self-hosted {productname} deployments:
 +
 [source,html]
diff --git a/modules/ROOT/partials/auth/document-converters/nodejs/configuration-steps.adoc b/modules/ROOT/partials/auth/document-converters/nodejs/configuration-steps.adoc
@@ -2,7 +2,7 @@
 
 === Add Your API Key
 
-* Replace `YOUR-API-KEY` in both files with your actual {productname} API key
+* Replace `no-api-key` in both files with your actual {productname} API key
 * The API key should be the same in both the HTML script source and the JWT payload
 
 === Add Your Private Key
diff --git a/modules/ROOT/partials/auth/document-converters/nodejs/server-setup-jwt.adoc b/modules/ROOT/partials/auth/document-converters/nodejs/server-setup-jwt.adoc
@@ -24,7 +24,7 @@ app.use(express.static(path.join(__dirname, 'public')));
 // JWT token generation endpoint
 app.post('/jwt', (req, res) => {
     const payload = {
-        aud: 'YOUR-API-KEY', // Replace with your actual API key
+        aud: 'no-api-key', // Replace with your actual API key
         iat: Math.floor(Date.now() / 1000), // Issue timestamp
         exp: Math.floor(Date.now() / 1000) + (60 * 10) // Expiration time (10 minutes)
     };
diff --git a/modules/ROOT/partials/auth/document-converters/php/configuration-steps.adoc b/modules/ROOT/partials/auth/document-converters/php/configuration-steps.adoc
@@ -2,7 +2,7 @@
 
 === Add Your API Key
 
-* Replace `YOUR-API-KEY` in both files with your actual {productname} API key
+* Replace `no-api-key` in both files with your actual {productname} API key
 * The API key should be the same in both the HTML script source and the JWT payload
 
 === Add Your Private Key
diff --git a/modules/ROOT/partials/auth/document-converters/php/server-setup-php.adoc b/modules/ROOT/partials/auth/document-converters/php/server-setup-php.adoc
@@ -25,7 +25,7 @@ header("Access-Control-Allow-Headers: Origin, X-Requested-With, Content-Type, Ac
 
 // JWT payload
 $payload = array(
-    "aud" => "YOUR-API-KEY",
+    "aud" => "no-api-key",
     "iat" => time(), // Issue timestamp
     "exp" => time() + 60 * 10 // Expiration time (10 minutes)
 );
diff --git a/modules/ROOT/partials/configuration/onboarding.adoc b/modules/ROOT/partials/configuration/onboarding.adoc
@@ -18,4 +18,8 @@ tinymce.init({
   selector: "textarea",  // change this value according to your HTML
   onboarding: false
 });
-----
+----
+
+
+
+image:onboarding/onboarding-finish-setting-up-dialog.png[onboarding finish setting up dialog, width=500, height=auto]
diff --git a/modules/ROOT/partials/integrations/swing-quick-start.adoc b/modules/ROOT/partials/integrations/swing-quick-start.adoc
@@ -26,11 +26,11 @@ The Swing integration allows the user to select the origin of the {productname}
 ----
 final Config myTinyConfiguration = Config.embedded();
 ----
-* Cloud deployments pull {productname} from the {cloudname}. Use this option by passing your API key and xref:editor-plugin-version.adoc#specifying-the-tinymce-editor-version-deployed-from-cloud[specifying the {cloudname} version].
+* Cloud deployments pull {productname} from the {cloudname}. Use this option by passing your API key and xref:editor-plugin-version.adoc#specifying-the-tinymce-editor-version-deployed-from-cloud[specifying the {cloudname} version]. Ensure you replace `<no_api_key>` with your API key.
 +
 [source,java,subs="attributes+"]
 ----
-final Config myTinyConfiguration = Config.cloud("<my_api_key>", "{productmajorversion}-stable");
+final Config myTinyConfiguration = Config.cloud("<no_api_key>", "{productmajorversion}-stable");
 ----
 * External deployments allow to use a local version of {productname} by giving the address of the location where {productname} is being served.
 +
diff --git a/modules/ROOT/partials/misc/premium-upgrade-promotion-option.adoc b/modules/ROOT/partials/misc/premium-upgrade-promotion-option.adoc
@@ -2,6 +2,6 @@
 
 include::partial$configuration/promotion.adoc[leveloffset=+1]
 
-// == Cloud promotion
+== Cloud promotion
 
-// include::partial$configuration/onboarding.adoc[leveloffset=+1]
+include::partial$configuration/onboarding.adoc[leveloffset=+1]
