From 9bdd286a44d3b83d538ee85a0aa8678b4e40d735 Mon Sep 17 00:00:00 2001 From: Aaron Greenberg
Date: Thu, 12 Sep 2024 10:37:18 -0700 Subject: [PATCH 01/27] Add v1 docs to the v2 docs site --- docusaurus.config.js | 29 +- .../version-v1/automated-testing.md | 27 ++ versioned_docs/version-v1/browser-support.md | 79 ++++ versioned_docs/version-v1/changelog.md | 197 +++++++++ versioned_docs/version-v1/csp.md | 33 ++ versioned_docs/version-v1/eu-endpoint.md | 79 ++++ versioned_docs/version-v1/flutter.md | 196 +++++++++ versioned_docs/version-v1/installation.md | 143 +++++++ versioned_docs/version-v1/introduction.md | 27 ++ versioned_docs/version-v1/openapi-spec.md | 9 + versioned_docs/version-v1/openapiv3.json | 373 ++++++++++++++++++ versioned_docs/version-v1/swagger.json | 308 +++++++++++++++ versioned_docs/version-v1/theme.md | 33 ++ versioned_docs/version-v1/verification-api.md | 51 +++ versioned_docs/version-v1/widget-api.md | 285 +++++++++++++ versioned_sidebars/version-v1-sidebars.json | 50 +++ versions.json | 3 + 17 files changed, 1908 insertions(+), 14 deletions(-) create mode 100644 versioned_docs/version-v1/automated-testing.md create mode 100644 versioned_docs/version-v1/browser-support.md create mode 100644 versioned_docs/version-v1/changelog.md create mode 100644 versioned_docs/version-v1/csp.md create mode 100644 versioned_docs/version-v1/eu-endpoint.md create mode 100644 versioned_docs/version-v1/flutter.md create mode 100644 versioned_docs/version-v1/installation.md create mode 100644 versioned_docs/version-v1/introduction.md create mode 100644 versioned_docs/version-v1/openapi-spec.md create mode 100644 versioned_docs/version-v1/openapiv3.json create mode 100644 versioned_docs/version-v1/swagger.json create mode 100644 versioned_docs/version-v1/theme.md create mode 100644 versioned_docs/version-v1/verification-api.md create mode 100644 versioned_docs/version-v1/widget-api.md create mode 100644 versioned_sidebars/version-v1-sidebars.json create mode 100644 versions.json diff --git a/docusaurus.config.js b/docusaurus.config.js index ca05c79..9682860 100644 --- a/docusaurus.config.js +++ b/docusaurus.config.js @@ -48,6 +48,13 @@ const config = { // Please change this to your repo. // Remove this to remove the "edit this page" links. editUrl: `https://github.com/${organizationName}/${projectName}/tree/main/`, + lastVersion: 'current', + versions: { + current: { + label: 'v2', + path: 'v2', + }, + }, }, blog: { showReadingTime: true, @@ -98,20 +105,18 @@ const config = { }, items: [ { - type: "doc", - docId: "intro", + type: "docsVersion", position: "left", label: "Docs", }, { - to: "/docs/integrations/", + to: "/docs/v2/integrations/", label: "Integrations", position: "left", }, { to: "/blog", label: "Tech Blog", position: "left" }, { - href: "https://docs.friendlycaptcha.com", - label: "V1 Docs", + type: 'docsVersionDropdown', position: "right", }, { @@ -140,15 +145,15 @@ const config = { items: [ { label: "Getting Started", - to: "/docs/getting-started/introduction", + to: "/docs/v2/getting-started/introduction", }, { label: "Guides", - to: "/docs/guides/", + to: "/docs/v2/guides/", }, { label: "Integrations", - to: "/docs/integrations/", + to: "/docs/v2/integrations/", } ], }, @@ -157,11 +162,11 @@ const config = { items: [ { label: "API Reference", - to: "/docs/api/overview", + to: "/docs/v2/api/overview", }, { label: "SDK Reference", - to: "/docs/sdk/reference/", + to: "/docs/v2/sdk/reference/", }, ], }, @@ -176,10 +181,6 @@ const config = { label: "Status", href: "https://status.friendlycaptcha.com", }, - { - label: "V1 Documentation", - href: "https://docs.friendlycaptcha.com", - }, ], }, { diff --git a/versioned_docs/version-v1/automated-testing.md b/versioned_docs/version-v1/automated-testing.md new file mode 100644 index 0000000..e055cea --- /dev/null +++ b/versioned_docs/version-v1/automated-testing.md @@ -0,0 +1,27 @@ +--- +title: 🤖 Automated Testing +--- + +# Automated Testing + +Testing can be at odds with a captcha you add to your website or app. Perhaps you use automated testing tools like [Cypress](https://www.cypress.io/), [Selenium](https://www.selenium.dev/), or [Puppeteer](https://github.com/puppeteer/puppeteer). On this page you will find some tips and approaches that will help work out a testing story for pages that include a captcha widget. + +## Testing tips + +### Mocking out the API +The easiest and most recommended approach is to mock out the API in the backend. Instead of calling our API and getting the JSON response, you instead always use `{success: true}` when running in test mode. With this approach you can keep all other code in your application the same. + +### IP or password-based gating +If you perform automated end-to-end tests in production you may want to conditionally disable the captcha check for your test-runner. +* If you know the IPs of the machines that run these tests you could whitelist those and skip the captcha check for those (or use the mocking approach above). +* If you do not know the IP beforehand, you could have your test-runner put a secret in the form submission that you check for. In other words, you can specify a password that bypasses the captcha. + +### Dynamic button enabling +Many websites that have a form protected using Friendly Captcha will only enable the submit button after the captcha widget is finished to prevent users from submitting without a valid captcha solution. When you are using a browser automation tool you may want to enable the button despite the captcha not being completed, we advice you achieve this by executing a snippet of Javascript (which is something you can do in all browser testing automation tools). + + +Here's an example such snippet: +```javascript +const button = document.querySelector("#my-button"); +button.disabled = false; +``` diff --git a/versioned_docs/version-v1/browser-support.md b/versioned_docs/version-v1/browser-support.md new file mode 100644 index 0000000..5b95bec --- /dev/null +++ b/versioned_docs/version-v1/browser-support.md @@ -0,0 +1,79 @@ +# Browser Support + +All modern browsers are supported, on both mobile and desktop, all releases up to at least 8 years old. That includes Safari, Edge, Chrome, Firefox, and Opera. Internet Explorer 11 also works, with some sidenotes (see the section below). See the targeted [**browserlist compatible browsers**](https://browserslist.dev/?q=c2luY2UgMjAxMywgbm90IGRlYWQsIG5vdCBpZSA8PTEwLCBub3QgaWVfbW9iIDw9IDEx). + +## Polyfills + +If you want to support browsers over 5 years old, you will need some polyfills (`fetch`, `Promise`, `URL` and `Object.assign`). + +You can use the build that includes the polyfills: + +```html + + +``` + +Or you can include the polyfills manually: + +```html + + + + +``` + +If you find any compatibility issues please create a [**Github issue**](https://github.com/FriendlyCaptcha/friendly-challenge/issues). + +## Compatibility mode for the library + +If you are importing _friendly-challenge_ into your own bundle and want to support old browsers (those that don't support ES2017) you should change your imports to be from `friendly-challenge/compat`. For example: + +``` +import {WidgetInstance} from 'friendly-challenge' +// change to +import {WidgetInstance} from 'friendly-challenge/compat' +``` + +Both imports are ES2017, use a tool like Babel to transpile it to ES5 or lower. The difference between these two imports is the webworker script which is included as a string. In the _compat_ build it is ES5 compatible and includes necessary polyfills (at the cost of slighlty worse performance and an extra 3KB bundle size). + +### Old browser speed + +The Javascript engine in old browsers is generally slower than modern ones, the CAPTCHA may take a minute to solve on very old browsers (>5 years old). + +## NoScript + +Users need to have Javascript enabled to solve the CAPTCHA. We recommend you add a note for users that have Javascript disabled by default: + +```html + +``` + +This will only be visible to users without Javascript enabled. + +## Internet Explorer + +Internet Explorer 11 is supported out of the box, but take note that **the Javascript engine is very slow in Internet Explorer leading to a poor user experience**: the CAPTCHA will likely take more than a minute to solve. + +Consider displaying a message to IE users that they should use a different browser. You can use this Javascript snippet to display a note after the widget in Internet Explorer only: + +```javascript +if (!!document.documentMode) { + // Only true in Internet Explorer + Array.prototype.slice.call(document.querySelectorAll(".frc-captcha")).forEach(function (element) { + var messageElement = document.createElement("p"); + messageElement.innerHTML = + "The anti-robot check works better and faster in modern browsers such as Edge, Firefox, or Chrome. Please consider updating your browser"; + element.parentNode.insertBefore(messageElement, element.nextSibling); + }); +} +``` diff --git a/versioned_docs/version-v1/changelog.md b/versioned_docs/version-v1/changelog.md new file mode 100644 index 0000000..19f7209 --- /dev/null +++ b/versioned_docs/version-v1/changelog.md @@ -0,0 +1,197 @@ +# Changelog + +## 0.9.17 + +- Fixed order of `start` and `ready` events +- Fixed incorrect unit in CSS +- Upgraded NPM dependencies to fix minor security issues + +## 0.9.16 + +- Added Korean (`"kr"`) localization (thank you @dimitriBouteille!). +- Fixed the percentage text for the progress bar. +- Added support for a `styleNonce` parameter when creating widgets programmatically, which is useful for specific CSP setups (thank you @rience!). + +## 0.9.15 + +- Added fallback support for supplying RFC 1766 language codes such as `en-GB` or `fr-FR` (thank you @julianwachholz!). +- Fix for some Node-based server-side rendering setups (where `navigator` is undefined). + +## 0.9.14 + +- Small tweak to the French (`"fr"`) localization. +- Added Hebrew (`"he"`) localization (thank you @tinytim84!). +- Added Thai (`"th"`) localization (thank you @samlaukinoon!). + +## 0.9.13 + +- Improvement to the French (`"fr"`) localization. +- Added feature for not including the hidden form field at all by passing `"-"` as custom field name. + +## 0.9.12 + +- No longer uses the title attribute for debug information during solving. Some screen readers would read this title as it updates. +- Localization fix for Vietnamese (`"vi"`). +- The widget now exposes a `loadLanguage` function that allows you to programmatically change the language of the widget. + +## 0.9.11 + +- Improvements to localizations, fix for Romanian (`"ro"`) localization (thank you @zcserei!). + +## 0.9.10 + +- Fix for false positive headless browser check in rare cases on Windows devices (`"Browser check failed, try a different browser"`). +- Improved French (`"fr"`) localization (thank you @mikejpr!). + +## 0.9.9 + +- Fix for NextJS 13 production builds. +- Added Chinese (Traditional) (`"zh_TW"`) localization (thank you @jhihyulin!). +- Added Vietnamese (`"vi"`) localization (thank you @duy13!). + +## 0.9.8 + +- Fix for false positive headless errors in Chromium browsers when having certain plugins installed (`"Browser check failed, try a different browser"`). + +## 0.9.7 + +- When an error is thrown by fetch (e.g. because of connection errors), the error of the fetch request can now be accessed under `error.rawError` in the object passed in the `onErrorCallback`. + +## 0.9.6 + +- Added Chinese (Simplified) (`"zh"`) localization (thank you @shyn!). +- Added `"nb"` as an alias for Norwegian language (`"no"`). +- Improved accessibility by hiding visual-only SVG icons by adding `aria-hidden="true"`. +- Errors are now logged with `console.error` instead of only appearing in the widget. + +## 0.9.5 + +- Added localizations `"el"`, `"uk"`, `"bg"`, `"cs"`, `"sk"`, `"no"`, `"fi"`, `"lt"`, `"lt"`, `"pl"`, `"et"`, `"hr"`, `"sr"`, `"sl"`, `"hu"`, and `"ro"` (Greek, Ukrainian, Bulgarian, Czech, Slovak, Norwegian, Finnish, Latvian, Lithuanian, Polish, Estonian, Croatian, Serbian, Slovenian, Hungarian, and Romanian), a big thank you to @Tubilopto! +- Added `type: "module"` to `package.json` (see #117) to help fix some issues in Javascript build pipelines. This may require some reconfiguring of your build pipeline. +- Build pipeline updates and upgrades (updated build dependencies, explicitly support IE11 in browser targets). + +## 0.9.4 + +- Fixed the retry button not working after expiration. +- Added `skipStyleInjection` option to the config object. When true is passed the ` + + + + +
+ + + +