From 34bec600d95e671c98ef8c5abefed62b3279e7ab Mon Sep 17 00:00:00 2001 From: Karl Kemister-Sheppard Date: Tue, 30 Jan 2024 14:24:08 +1000 Subject: [PATCH 1/3] DOC-2240: add new `understanding-editor-loads.adoc` to `how-to-guide` section (#3047) * DOC-2240: add new understanding-editor-loads.adoc to how-to-guide section. * Update modules/ROOT/pages/understanding-editor-loads.adoc * Update modules/ROOT/pages/understanding-editor-loads.adoc Co-authored-by: Andrew Herron * Update modules/ROOT/pages/understanding-editor-loads.adoc Co-authored-by: Andrew Herron * Update modules/ROOT/pages/understanding-editor-loads.adoc * Update modules/ROOT/pages/understanding-editor-loads.adoc removed this for future updates * Update changelog.md --------- Co-authored-by: Andrew Herron --- changelog.md | 4 ++ modules/ROOT/nav.adoc | 1 + .../pages/understanding-editor-loads.adoc | 48 +++++++++++++++++++ 3 files changed, 53 insertions(+) create mode 100644 modules/ROOT/pages/understanding-editor-loads.adoc diff --git a/changelog.md b/changelog.md index 47e6264c40..6316131d1d 100644 --- a/changelog.md +++ b/changelog.md @@ -7,6 +7,10 @@ The format is loosely based on [Keep a Changelog](https://keepachangelog.com/en/ ### Unreleased +### 2024-01-30 + +- DOC-2240: add new `understanding-editor-loads.adoc` to `how-to-guide` section. + ### 2023-01-15 - DOC-2235: changes and updates to `invalid-api-key.adoc` page. diff --git a/modules/ROOT/nav.adoc b/modules/ROOT/nav.adoc index f1c21463ad..1aaeeaadc8 100644 --- a/modules/ROOT/nav.adoc +++ b/modules/ROOT/nav.adoc @@ -215,6 +215,7 @@ ** xref:migration-from-5x.adoc[Migrating from TinyMCE 5] ** xref:migration-from-froala.adoc[Migrating from Froala] ** xref:generate-rsa-key-pairs.adoc[Generate public key pairs] +** xref:understanding-editor-loads.adoc[Understanding editor loads] * xref:examples.adoc[Examples] ** xref:examples.adoc#general-examples[General examples] *** xref:basic-example.adoc[Basic example] diff --git a/modules/ROOT/pages/understanding-editor-loads.adoc b/modules/ROOT/pages/understanding-editor-loads.adoc new file mode 100644 index 0000000000..7719b0e6ec --- /dev/null +++ b/modules/ROOT/pages/understanding-editor-loads.adoc @@ -0,0 +1,48 @@ += 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 + +== Understanding editor loads for {productname} + +[IMPORTANT] +This information is only relevant to Tiny Cloud users. Users who self-host the open source version of {productname} are not subject to editor load restrictions, but must comply with the https://github.com/tinymce/tinymce/blob/master/LICENSE.TXT[open source license]. + +An editor load is the event that occurs each time {productname} is initialized in your application. The editor dispatches the 'init' event to indicate a successful load. For example, if 100 users load {productname} 10 times each, the result would be 1,000 editor loads. + +The process of initializing an editor involves several steps. + +. The integrator initializes one or more editors on the webpage, commonly accomplished through the `tinymce.init({ ... })` method. ++ +. The `selector` property of the `init` method determines which elements should be replaced with editor instances. For example: if the selector is `textarea` and there are 5 textarea elements on the page, 5 editor instances will be created. ++ +Each editor instance performs the same initialization sequence and then dispatches an `init` event. This event is dispatched even if the the editor is not visible. ++ +. **The 'init' event serves as the conclusive indicator that the editor has completed its loading process**. At this point, the editor has been successfully initialized and is ready for user interaction. + +== How are editor loads counted? + +An editor load is counted each time a new {productname} editor instance completes the initialization sequence and dispatches an `init` event. + +== What happens if I have multiple editors on a page? + +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. + +== 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: + +* An email building app that has a {productname} editor embedded in multiple sections +* A publicly available page on a high traffic website with multiple editor instances + +== How can I get unlimited editor loads? + +You can get unlimited editors loads one of three ways: + +* The open-source version of {productname} can be self hosted, and is not subject to editor load restrictions. +* The open-source version of {productname} is also available via third party-hosted CDNs and is not subject to editor load restrictions. +* For the Enterprise version of Tiny MCE with Premium features, https://www.tiny.cloud/contact/[get in touch with our Sales team] for a custom quote. + +== I have an annual plan. Are my editor loads calculated monthly or over the entire year? + +If you have an annual plan, your editor loads are calculated on a monthly basis within the structure of your annual plan. Similar to our monthly plans, you have a set monthly editor load limit and are automatically charged $40 USD per every block of 1,000 editor loads over the plan limit. From 4873c49b3d1a9169cbab30ca29eeb0b7f526771b Mon Sep 17 00:00:00 2001 From: Karl Kemister-Sheppard Date: Wed, 31 Jan 2024 09:27:30 +1000 Subject: [PATCH 2/3] DOC-2275: updates to `cloud-troubleshooting.adoc` with new links to `invalid-api-key.adoc` page. (#3055) * updates to with new links to page. * make it clearer that there are two causes and solutions for the first issue * undo previous commit 01fbca71d7247959d6706f65518c34120f6f72f9 * DOC-2275: fixing up heading levels and document styling. * Update changelog.md --------- Co-authored-by: Farzad Hayatbakhsh --- changelog.md | 4 ++ modules/ROOT/pages/cloud-troubleshooting.adoc | 51 ++++++++++++------- 2 files changed, 37 insertions(+), 18 deletions(-) diff --git a/changelog.md b/changelog.md index 6316131d1d..72385fceb7 100644 --- a/changelog.md +++ b/changelog.md @@ -7,6 +7,10 @@ The format is loosely based on [Keep a Changelog](https://keepachangelog.com/en/ ### Unreleased +### 2024-01-31 + +- DOC-2275: updates to `cloud-troubleshooting.adoc` with new links to `invalid-api-key.adoc` page. + ### 2024-01-30 - DOC-2240: add new `understanding-editor-loads.adoc` to `how-to-guide` section. diff --git a/modules/ROOT/pages/cloud-troubleshooting.adoc b/modules/ROOT/pages/cloud-troubleshooting.adoc index a76ad6f9fa..84d80737ef 100644 --- a/modules/ROOT/pages/cloud-troubleshooting.adoc +++ b/modules/ROOT/pages/cloud-troubleshooting.adoc @@ -7,26 +7,30 @@ When {cloudname} detects a problem, it will show an editor notification containi NOTE: The wording of the notifications shown here may differ from the actual notifications from {cloudname}. -[[A-valid-API-key-is-required-starting-2024-to-continue-using-TinyMCE.-Please-alert-your-admin-to-sign-up-to-get-your-free-API-key.]] -== "A valid API key is required, starting 2024, to continue using TinyMCE. Please alert your admin to sign-up to get your free API key." +[[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 +=== Scenario (one) + +==== Cause 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. -Such as: +For example: [source,html,subs="attributes+"] ---- ---- -=== Solution +==== 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+`. -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+`. For example, if your API is `+abcd1234+`: +For example: if your API is `+abcd1234+`: [source,html,subs="attributes+"] ---- @@ -37,10 +41,9 @@ To retrieve your API key, or to sign up for an API key, visit: link:{accountsign NOTE: Visit our xref:invalid-api-key.adoc[Invalid API key] page for more information on how to fix a `invalid API key` with {productname}. -[[A-valid-API-key-is-required-starting-2024-to-continue-using-TinyMCE.-Please-alert-your-admin-to-check-the-current-API-key]] -== "A valid API key is required, starting 2024, to continue using TinyMCE. Please alert your admin to check the current API key." +=== Scenario (two) -=== Cause +==== Cause This notification is shown when the API key provided cannot be found on the {cloudname} server. @@ -50,7 +53,7 @@ The `+apiKey+` must be: * comprised of certain characters, and * created with a {cloudname} account on the link:{accountsignup}/[{accountpage} page]. -=== Solution +==== Solution Check the `+apiKey+` provided in the script tag: @@ -60,10 +63,14 @@ Check the `+apiKey+` provided in the script tag: NOTE: Visit our xref:invalid-api-key.adoc[Invalid API key] page for more information on how to fix a `invalid API key` with {productname}. -[[This-domain-is-not-registered-with-Tiny-Cloud.-To-continue-using-TinyMCE-a-registered-domain-is-required-starting-2024.-Please-alert-your-admin-to-review-the-approved-domains-and-add-this-one-if-required.]] -== "This domain is not registered with Tiny Cloud. To continue using TinyMCE, a registered domain is required, starting 2024. Please alert your admin to review the approved domains and add this one if required." +''' + +[[This-domain-is-not-registered-in-the-TinyMCE-Customer-Portal.-Please-alert-the-admin-to-add-it-to-the-approved-domains-to-continue-using-TinyMCE.]] +== "This domain is not registered in the {productname} Customer Portal. **Please alert the admin** to add it to the approved domains to continue using {productname}. xref:invalid-api-key.adoc[Click here to learn more.]" + +=== Scenario -=== Cause +==== Cause This notification is shown when the https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Referer[*Referer*] of the page does not match the list of approved domains stored against your `+apiKey+`. {cloudname} verifies the domain {productname} is loading from by checking the domain portion of the *Referer* header in the network request. You can view a list of your approved domains on your link:{accountpageurl}/[{accountpage}]. @@ -76,20 +83,24 @@ Sometimes the domain in the *Referer* header does not match with the URL in the In the section called *Request Headers* there should be a field for *Referer*. This is the value that {productname} is checking against your approved domains. It must match one of your approved domains listed on your link:{accountpageurl}/[{accountpage}]. -=== Solution +==== Solution If the `+Referer+` is correct for the site, ensure that the domain is included in your list of approved domains on link:{accountpageurl}/[{accountpage}]. If the `+Referer+` is not what you are expecting, you may need to adjust your application's https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Referer[*Referer* header] settings. +''' + [[were-unable-to-check-your-domain-because-the-referer-header-is-missing-please-read-the-guide-on-how-to-ensure-your-referer-header-is-present-so-we-can-then-customize-your-editor-experience]] == "We’re unable to check your domain because the referer header is missing. Please read the Guide on how to ensure your referer header is present, so we can then customize your editor experience." -=== Cause +=== Scenario + +==== Cause This notification is shown if the https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Referer[*Referer* header] is absent for the network request when loading {productname} from {cloudname}. {cloudname} verifies the domain {productname} is loading from by checking the domain of the *Referer* header in the network request. _Referer_ headers are sometimes removed by browser settings or browser extensions. {cloudname} only needs the domain in the *Referer* header, so for improved performance and privacy {companyname} recommends setting the `+referrerpolicy+` to `+origin+` when requesting {cloudname} resources. -=== Solution +==== Solution Identify which browser setting or extension is responsible for blocking the *Referer* being sent. A common extension is `+Referer Control+`: @@ -98,16 +109,20 @@ Identify which browser setting or extension is responsible for blocking the *Ref Once you have identified the setting or extension, modify it to allow just the `+Origin+` of the `+Referer+` to be sent. Alternatively, disable the extension or setting for any pages using {cloudname}. +''' + [[the-___-premium-plugin-is-not-enabled-on-your-api-key-upgrade-your-account]] == "The ___ premium plugin is not enabled on your API key. Upgrade your account." -=== Cause +=== Scenario + +==== Cause This notification is shown when your API key does not have access to the premium plugin being requested. This could be the result of a trial expiring, and your {productname} configuration attempting to load premium plugins you can no longer access. You may also be seeing this notification if you are using the wrong API key. Ensure that you are using the API key that has the right entitlements. -=== Solution +==== Solution Either remove the premium plugin from your {productname} configuration, or upgrade your subscription to provide access to that premium plugin. From 12a5d491e2fc14d288a4ba4985f2c7c5d0ce8de1 Mon Sep 17 00:00:00 2001 From: Karl Kemister-Sheppard Date: Mon, 5 Feb 2024 09:59:18 +1000 Subject: [PATCH 3/3] DOC-2276: updates to `cloud-troubleshooting.adoc` with new `read-only` ref and links to `invalid-api-key.adoc` page. (#3056) * DOC-2276: updates to with new ref and links to page. * Update modules/ROOT/pages/cloud-troubleshooting.adoc * Update changelog.md --- changelog.md | 3 + modules/ROOT/pages/cloud-troubleshooting.adoc | 105 +++++++++++++----- 2 files changed, 80 insertions(+), 28 deletions(-) diff --git a/changelog.md b/changelog.md index 72385fceb7..a692512c20 100644 --- a/changelog.md +++ b/changelog.md @@ -6,6 +6,9 @@ The format is loosely based on [Keep a Changelog](https://keepachangelog.com/en/ ### Unreleased +### 2024-02-05 + +- DOC-2276: updates to `cloud-troubleshooting.adoc` with new `read-only` ref and links to `invalid-api-key.adoc` page. ### 2024-01-31 diff --git a/modules/ROOT/pages/cloud-troubleshooting.adoc b/modules/ROOT/pages/cloud-troubleshooting.adoc index 84d80737ef..29beec92cc 100644 --- a/modules/ROOT/pages/cloud-troubleshooting.adoc +++ b/modules/ROOT/pages/cloud-troubleshooting.adoc @@ -7,12 +7,15 @@ When {cloudname} detects a problem, it will show an editor notification containi NOTE: The wording of the notifications shown here may differ from the actual notifications from {cloudname}. -[[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.]" +''' -=== Scenario (one) +[[invalid-api-key-cloud-troubleshooting]] +== Invalid API Key -==== Cause +[[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" This notification is *only shown* when either: @@ -41,9 +44,7 @@ To retrieve your API key, or to sign up for an API key, visit: link:{accountsign NOTE: Visit our xref:invalid-api-key.adoc[Invalid API key] page for more information on how to fix a `invalid API key` with {productname}. -=== Scenario (two) - -==== Cause +==== Cause "Invalid API Key" This notification is shown when the API key provided cannot be found on the {cloudname} server. @@ -55,20 +56,21 @@ The `+apiKey+` must be: ==== Solution -Check the `+apiKey+` provided in the script tag: +Check the `apiKey` provided in the script tag: -* Remove any leading or trailing spaces. -* Any other characters that are not in your API key. If you are using variable substitution, ensure that the variable is substituting properly. -* Matches the API key shown at {accountpageurl}. +* Remove any leading or trailing spaces +* Remove any other characters that are not in your `apiKey`. If you are using variable substitution, ensure that the variable is substituting properly +* Ensure the `apiKey` matches the API key shown at {accountpageurl}. NOTE: Visit our xref:invalid-api-key.adoc[Invalid API key] page for more information on how to fix a `invalid API key` with {productname}. ''' -[[This-domain-is-not-registered-in-the-TinyMCE-Customer-Portal.-Please-alert-the-admin-to-add-it-to-the-approved-domains-to-continue-using-TinyMCE.]] -== "This domain is not registered in the {productname} Customer Portal. **Please alert the admin** to add it to the approved domains to continue using {productname}. xref:invalid-api-key.adoc[Click here to learn more.]" +[[domain-not-registered]] +== Domain Not Registered -=== Scenario +[[This-domain-is-not-registered-in-the-TinyMCE-Customer-Portal.-Please-alert-the-admin-to-add-it-to-the-approved-domains-to-continue-using-TinyMCE.]] +=== "This domain is not registered in the {productname} Customer Portal. **Please alert the admin** to add it to the approved domains to continue using {productname}. xref:invalid-api-key.adoc[Click here to learn more.]" ==== Cause @@ -76,10 +78,10 @@ This notification is shown when the https://developer.mozilla.org/en-US/docs/Web Sometimes the domain in the *Referer* header does not match with the URL in the browser's address bar. To check the *Referer* header: -. Open your browser's _Developer's Tools_. -. Open the _Network_ tab. -. Find and select the request being made to load {productname} from {cloudname} with your API key. -. Click on the *Headers* tab. +* Open your browser's _Developer's Tools_. +* Open the _Network_ tab. +* Find and select the request being made to load {productname} from {cloudname} with your API key. +* Click on the *Headers* tab. In the section called *Request Headers* there should be a field for *Referer*. This is the value that {productname} is checking against your approved domains. It must match one of your approved domains listed on your link:{accountpageurl}/[{accountpage}]. @@ -89,16 +91,16 @@ If the `+Referer+` is correct for the site, ensure that the domain is included i ''' -[[were-unable-to-check-your-domain-because-the-referer-header-is-missing-please-read-the-guide-on-how-to-ensure-your-referer-header-is-present-so-we-can-then-customize-your-editor-experience]] -== "We’re unable to check your domain because the referer header is missing. Please read the Guide on how to ensure your referer header is present, so we can then customize your editor experience." +[[referer-heading-missing]] +== Referer Heading Missing -=== Scenario +[[were-unable-to-check-your-domain-because-the-referer-header-is-missing-please-read-the-guide-on-how-to-ensure-your-referer-header-is-present-so-we-can-then-customize-your-editor-experience]] +=== "We’re unable to check your domain because the referer header is missing. Please read the Guide on how to ensure your referer header is present, so we can then customize your editor experience." ==== Cause -This notification is shown if the https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Referer[*Referer* header] is absent for the network request when loading {productname} from {cloudname}. {cloudname} verifies the domain {productname} is loading from by checking the domain of the *Referer* header in the network request. - -_Referer_ headers are sometimes removed by browser settings or browser extensions. {cloudname} only needs the domain in the *Referer* header, so for improved performance and privacy {companyname} recommends setting the `+referrerpolicy+` to `+origin+` when requesting {cloudname} resources. +* This notification is shown if the https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Referer[*Referer* header] is absent for the network request when loading {productname} from {cloudname}. {cloudname} verifies the domain {productname} is loading from by checking the domain of the *Referer* header in the network request. +* _Referer_ headers are sometimes removed by browser settings or browser extensions. {cloudname} only needs the domain in the *Referer* header, so for improved performance and privacy {companyname} recommends setting the `+referrerpolicy+` to `+origin+` when requesting {cloudname} resources. ==== Solution @@ -111,10 +113,11 @@ Once you have identified the setting or extension, modify it to allow just the ` ''' -[[the-___-premium-plugin-is-not-enabled-on-your-api-key-upgrade-your-account]] -== "The ___ premium plugin is not enabled on your API key. Upgrade your account." +[[troubleshooting-premium-plugins]] +== Troubleshooting Premium Plugins -=== Scenario +[[the-___-premium-plugin-is-not-enabled-on-your-api-key-upgrade-your-account]] +=== "The ___ premium plugin is not enabled on your API key. Upgrade your account." ==== Cause @@ -126,4 +129,50 @@ You may also be seeing this notification if you are using the wrong API key. Ens Either remove the premium plugin from your {productname} configuration, or upgrade your subscription to provide access to that premium plugin. -NOTE: Visit our xref:invalid-api-key.adoc[Invalid API key] page for more information on how to fix a `invalid API key` with {productname}. \ No newline at end of file +NOTE: Visit our xref:invalid-api-key.adoc[Invalid API key] page for more information on how to fix a `invalid API key` with {productname}. + +''' + +[[read-only-mode-no-api-key]] +== Read-only mode - No API Key + +=== “{productname} is in read-only mode. **Please alert the admin** that an API key is required for continued use. xref:invalid-api-key.adoc[Learn more] + +==== Cause "No API Key (Read only mode)" + +This message is sent when the developer has not supplied an API key, typically because they've copied a getting-started script and have not completed the official https://www.tiny.cloud/auth/signup/[signup] process to get an API key. + +==== Solution + +* **Please alert your Admin** that an API key is required for continued use. xref:invalid-api-key.adoc[Learn more], or +* Sign up for a API key by visiting https://www.tiny.cloud/auth/signup/[www.tiny.cloud/auth/signup], and +* Update your {productname} configuration. + +NOTE: Visit our xref:invalid-api-key.adoc[Invalid API key] page for more information on how to fix a `invalid API key` with {productname}. + +[[read-only-mode-invalid-api-key]] +== Read-only mode - Invalid API Key + +=== “{productname} is in read-only mode. **Please alert the admin** to provide a valid API key to continue use. xref:invalid-api-key.adoc[Learn more] Your {productname} editor state has been set to read-only mode.” + +==== Cause "Invalid API Key (Read only-mode)" + +This message is shown when the API key is not correct, perhaps because of a typo. + +==== Solution + +* Login to your {productname} account and confirm that your API key matches your unique key by visiting https://www.tiny.cloud/auth/login/[www.tiny.cloud/auth/login/]. +* or to sign up for an API key, visit: link:{accountsignup}/[{cloudname}]. + +[[read-only-mode-invalid-origin]] +== Read-only mode - Invalid Origin + +=== “{productname} is in read-only mode. **Please request that the admin** add this domain to the approved domains in the Customer Portal. xref:invalid-api-key.adoc[Learn more]” + +==== Cause "Invalid Origin (Read only mode)" + +This message is shown when {productname} is loaded from a domain that has not been added to the approved domains in our account portal. + +==== Solution + +Please request that your admin add this domain to the approved domains in the Customer Portal xref:invalid-api-key.adoc[Learn more] \ No newline at end of file