Plans supporting knowledge base widget

Customizing the knowledge base widget

You can customize each knowledge base widget to improve the user experience.

1_Screenshot-Overview_page_of_KNowledge_base_Widget

Log in to the {{glossary.Knowledge base portal}} and select your desired project.
Navigate to Knowledge base widget () in the left navigation bar. A list of widgets created will be displayed.
Hover over the desired widget and click the Edit () icon.
In the Configure & connect tab, expand the Style widget accordion.
The following widget customization options are available:

2_Screenshot-Style_your_widget

Widget color

You can choose a theme color for the widget, which also sets the icon color.

Click Change color to open the color palette.
Select a color using the picker or enter a hex, RGB, or HSL code.

Widget icon

Similarly, under the widget color section, you can replace the icon with an image or an available icon.

Click Change icon.
Choose from the Icon set tab or insert an image under Insert image:
1. From URL: Paste the image link and click Insert.
2. From device: Click Upload an image and select a file.
Click Default to revert to the original icon.

Widget position

Control where the widget appears on your site:

Choose Left or Right.
Set Side spacing and Bottom spacing values to position the widget.

Hide widget

By default, the Hide widget toggle is turned off, so the Knowledge base widget remains visible on the site. To hide the widget, simply enable the Hide widget toggle.

Hide most searched articles

Turn on Hide most searched articles toggle to hide the top search articles section.

NOTE
Enabling the Hide most searched articles toggle will disable URL mapping functionality for the widget.

Once your changes are made, click Save next to the Widget name field.

NOTE
The autosave option is available for navigation between the Knowledge base widget tabs.

Content access for the Knowledge base widget

You may want to show only particular articles or hide some articles in your Knowledge base site. You can do this effectively with the Content access option.

Restricting content access in a Knowledge base widget

To restrict content access in a knowledge base widget:

Navigate to Knowledge base widget () in the left navigation bar.
Hover over a widget and click the Edit () icon.

In the Configuration & connect tab, expand the Content access section.
You have three options:
1. Project
2. Workspace
3. Category

Project

All the articles in the Knowledge base appear in the Widget. By default, Project is selected.

Workspace

Display only specific workspaces or languages:

Select Workspace > Choose workspace
Select the desired workspace(s)/language(s) checkboxes
Click Done
Click Save to apply the changes

For example, you want to select a different workspace with a specific language.

Adding custom links

You can add custom links to the Knowledge base widget. The links will appear in the order they were created. Use this option to direct end users to specific pages or resources.

To add a custom link:

Navigate to Knowledge base widget () in the left navigation bar.
Hover over the desired widget and click the Edit () icon.
In the Configure & connect tab, expand the Add links accordion
In the Section title field, enter the desired title for that section. This will appear in the widget.
Under the Section title, for each link, choose the desired icon, link text (which will appear in the widget), and the destination link.
Example:
- Icon:
- Link text: Contact us
- Link: support@document360.com
NOTE
You can use a mailto: in the link field. For example: mailto:<youremail@somedomain.com>
Click Add and the link will be added. Similarly, you can add multiple links.
To edit, click the Edit () icon. Click to save and to discard.
Click the Delete () icon next to the links to delete the links.
Once done, Click Save to save the changes.

Domain restriction

Document360 lets you restrict the Knowledge base widget to specific domains. Once a domain is added to the widget security list, any project member who wants to install the Knowledge base widget on a different domain must add that domain to the Widget security section.

If no domains are added to the list, the Knowledge base widget can be embedded into any SaaS application or public website without restriction.

Restrict the Knowledge base widget to a specific domain

To restrict your Knowledge base widget to a specific domain,

Navigate to Knowledge base widget () in the left navigation bar.
Hover over the desired widget and click the Edit () icon.
In the Configure & connect tab, expand the Widget security accordion. You can find the list of domains previously added (if added).
Enter the domain where you want the Knowledge base widget to be displayed.
Click Add and click Save.

NOTE
The "www" is not a valid part of your domain. Only add what comes after the www. in your URL.
Example: document360.com

Adding a ticket deflector in Knowledge base widget

You can integrate a Ticket Deflector to help deflect support queries. To add a ticket deflector to your Knowledge base widget, follow the steps below:

Navigate to Knowledge base widget () in the left navigation bar.
The list of widget will be listed.
Hover over the desired widget and click the Edit () icon.
In the Configure & connect tab, expand the Ticket deflector accordion.
Turn on the Show ticket deflector toggle.
Select the desired ticket deflector from the dropdown.
If required, edit the Menu name field.
Click Save.
The Ticket deflector is added to the Knowledge base widget.

3_Screenshot-Ticket_deflector_in_KB_Widget

Securing Knowledge base widget authentication using JWT

You can implement an authentication configuration for the widget using JWT, ensuring a secure environment for private and mixed projects.

Navigate to Knowledge base widget () in the left navigation bar.
The list of widgets will appear.
Hover over the desired widget and click the Edit () icon.
In the Configure & connect tab, navigate to the JWT accordion and turn on the JWT Enable toggle.

Client ID: The client ID will be your project’s ID.
Widget ID: Since multiple widgets may exist, a Widget ID is provided for their unique purposes.
Token endpoint: A token endpoint is an HTTP endpoint that allows you to obtain an access token given an authorization code.
Client secret: Click Regenerate to generate the client secret. You need to save this for future purposes and the same client secret will apply to all widgets in the future.

NOTE
The Client secret will be required for JWT widgets you may create. Note that this information will not be stored in Document360.

e. Authorize URL: Paste the authorized URL from your knowledge base widget webpage.

Click Save.

Securing the Knowledge base widget

Embed the authorized URL within your code and paste it into the script section on your webpage. This will implement a secure, authenticated widget that prevents unauthorized third-party access.

Implementing the auth endpoint

[HttpGet]
[Route("authenticate")]
public async Task<IActionResult> WidgetAuthentication(string id)
{
    if (HttpContext.User.Identity.IsAuthenticated)
    {
        var clientData = new ClientDetails()
        {
            ClientId = "{Client ID}",
            Secret = "{Client secret}",
            TokenEndpoint = "{Token endpoint}",
            WidgetId = "{Widget ID}",
            SecurityGroupIds = "{Comma separated reader group IDs}", // mandatory for configuration to render KB widget
            TokenValidity = 15, // integer representing token validity in minutes
        };

        if (clientData == null)
            return NotFound();

        List<string> readerGroupids = null;
        if (!string.IsNullOrEmpty(clientData.SecurityGroupIds))
            readerGroupids = clientData.SecurityGroupIds.Split(',').Select(c => c.Trim()).ToList();

        var payload = new
        {
            username = "{Username}",
            firstName = "{First name}",
            lastName = "{Last name}",
            emailId = "{Email address}",
            readerGroupIds = readerGroupids,
            tokenValidity = clientData.TokenValidity,
            widgetId = clientData.WidgetId,
            projectId = clientData.ClientId
        };

        var payloadString = JsonConvert.SerializeObject(payload);

        var result = await client.RequestTokenAsync(new TokenRequest
        {
            Address = clientData.TokenEndpoint,
            ClientId = clientData.ClientId,
            ClientSecret = clientData.Secret,
            GrantType = "Widget",
            Parameters =
            {
                {
                    "payload",  payloadString
                },
                {
                    "id", clientData.ClientId
                },
            }
        });

        return Ok(new
        {
            accessToken = result.AccessToken,
            expiresIn = result.ExpiresIn
        });
    }
    else
    {
        return Unauthorized(new { success = false });
    }
}

NOTE
You must include the comma-separated reader group IDs as security group IDs to configure and render the KB widget.

Troubleshooting

This section provides step-by-step guidance to address common challenges that you may encounter while managing or accessing your knowledge base widget.

Widget icon is visible even after mapping to a button

Even after mapping the Knowledge base widget to a custom button, the default widget icon continues to appear on the Knowledge base site. This happens because the widget script includes the default icon display, and it doesn’t automatically get hidden when using a button trigger.

Steps to resolve:

Navigate to Knowledge base widget () in the left navigation bar.
Hover over the desired widget and click the Edit () icon.
In the Configure & connect tab, expand the Style widget accordion.
Locate the Hide widget toggle and ensure it is turned on.
Click Save to apply the changes.
Refresh your Knowledge base site to see the changes.

Once done, the widget icon will no longer be visible on the site, but it will still function as expected when triggered via your custom button.

NOTE
If you're also using URL mappings to control widget visibility, refer to Customizing the Knowledge base widget using Custom CSS/JavaScript for advanced hiding options.

Settings for widget configuration, including options to hide and customize features.

"Most searched articles" section not visible on the Knowledge base site

The Most searched articles section and the mapped list of articles for a specific URL are not appearing in the Knowledge base widget.

This issue typically occurs when the "Hide most searched articles" toggle is enabled in the widget style settings. Enabling this option hides both the Most searched articles section and any mapped article list associated with a specific URL.