If you are using a KnowledgeOwl subdomain (such as my-amazing-kb.knowledgeowl.com), you don't need to configure your own reCAPTCHA.
However, if you have customized your knowledge base to use your own private domain, such as www.mykb.mycompany.com, you'll need to add your own reCAPTCHA to your site if you have any of these options enabled:
- Settings > Comments: The "Only allow logged in readers and users to leave comments" box is unchecked (e.g. you allow unrestricted commenters)
- Settings > Subscriptions: The "Enable public subscriptions" box is checked (e.g. you allow public subscriptions)
- Knowledge Base > Contact Form: The "Require ReCaptcha "I'm not a robot" validation to submit a ticket" box is checked
- If you are using this setting and also using Contextual Help Widget (2.0), you'll also need to add a V3 reCAPTCHA to add reCAPTCHA to the Contact tab on the Widget.
- If you are using this setting and don't have reCAPTCHA enabled, your contact form will display an invalid domain error to your end-users.
What is reCAPTCHA?
reCAPTCHA is a free service from Google designed to verify that someone signing up for a subscription is a real person and not a bot. A "CAPTCHA" is a simple test--usually a task that is very easy for a human to perform, but hard for bots and other malicious software to figure out. There are two versions of reCAPTCHA:
- v2: Verify requests with a challenge. Example: checking a box next to "I am not a robot."
- v3: Verify requests with a score. Example: click on all the images that have cars in them.
KnowledgeOwl currently supports specific versions in specific places:
- v2: Supported in the full knowledge base; not supported in Contextual Help Widget (2.0). For these reCAPTCHAs, configurations with "I am not a robot" reCAPTCHAs, and you can see one in action if you try to subscribe to a category in this knowledge base.
- v3: Supported in Contextual Help Widget (2.0); not supported in the full knowledge base.
Only v2 reCAPTCHAs will work properly in KnowledgeOwl. We've tested our configurations with "I am not a robot" reCAPTCHAs, and you can see one in action if you try to subscribe to a category in this knowledge base!
Creating a new reCAPTCHA
To create a new reCAPTCHA, you'll need a Google account.
- Go to https://www.google.com/recaptcha/admin
- If you've never generated a reCAPTCHA before, this should take you directly into the page to create one. If you've generated a reCAPTCHA before, you'll need to click the + in the upper right to Create a new reCAPTCHA.
- Pick a label for your reCAPTCHA. You might use the name of your knowledge base or the URL for it.
- Select the reCAPTCHA type:
- For domain, use the URL of your KnowledgeOwl knowledge base.
- Your Gmail account will automatically be added as an Owner. You can add additional email addresses. If you'd like us to be able to help troubleshoot issues with your reCAPTCHA, add firstname.lastname@example.org as an owner.
- You'll need to check the box next to Accept the reCAPTCHA Terms of Service.
- You can choose to receive or opt out of alerts to owners. These alerts will notify you if Google detects problems with your site, such as misconfigurations affecting the reCAPTCHA or increases in suspicious traffic. We recommended receiving the alerts.
So a completed v2 reCAPTCHA might look something like this:
- Once you've entered all your selections, click Submit.
- This will take you to a confirmation screen that will provide you with the Site Key and the Secret Key for your reCAPTCHA. You'll need these to add them to your knowledge base!
Add your reCAPTCHA to your knowledge base
With your reCAPTCHA generated, you can add the site key and secret key to your knowledge base. To do so:
- Go to Settings > Basic.
- In Domain Settings, copy and paste your reCAPTCHA site key and secret key from Google into the appropriate fields here. Note the different sections for reCAPTCHA Key V2 and reCAPTCHA Key V3. Be sure you're using the right ones!
- When you're done making changes, click Save.