HOSTED SPACES

App documentation widget

9min

Contextual documentation is embedded within your product where the user needs it most. The contextual docs widget helps users read the documentation without the need to browse the user guide portal in another window.

You can load specific articles or the entire user guide portal, which is a must-have for companies who want to increase product adoption and retention.

All you need to do is embed the HTML code generated under Space settings -> Widget integration.

How the widget works

Check out the video below showing the widget in action:



How to implement the widget

To integrate the widget, follow these steps:

1

Select your Space inside the editor.

2

Click on the gear icon (⚙️) to get into Settings.

3

Go to Widget integration.

4

Click on the copy button, and paste the code into your index.html file, or in your application code.

Copy app widget code
Copy app widget code


Now, the widget will handle everything behind the scenes. Don't worry, everything is bundled and minified. It's a mere 56Kb download and it loads asynchronously, so your users won't feel a difference.

Init event

In the init event, for the spaceId value, you can use the spaceId or the PUBLISHED-{spaceId}. This way you can use Spaces without publishing them, straight in your app.

Use PREVIEW-{spaceId} when you only want to publish a space to Preview and not on your domain.

Property

Type

Description

Required

spaceId

string

Pass the desired id to load your docs.

required

jwt

string

Pass the jwt token in order to see jwt protected docs.

optional

shareableToken

string

Pass the shareableToken from your private links to protect your docs.

optional

widgetType

'docs' | 'search'

Default value is docs. This opens the widget with the desired behaviour. docs type will open the widget with the default behaviour, search will open a search widget bar that shows a search bar with AI support (if included in your subscription).



loadingStrategy

lazy | eager

The default value is lazy. While lazy loading delays the initialization of a resource, eager loading initializes or loads the widget as soon as the code is executed.

optional

bubble

invisible | ask

The default value is invisible. If set to ask it will display a bubble in the bottom-right of your screen. Whenever someone clicks on it, the search widget will open.

optional

bubblePlaceholder

string

The placeholder that will be displayed in the bubble section. If not passed, a default value of Ask a question will be displayed.

optional

anchor

string

You can provide your class, id or path to a DOM element where you would like the widget to anchor and instantiate. It will anchor to the first element found in the DOM, if multiple elements with the same path are present. The container provided should have position: relative as the widget will be displayed based on the first relative parent found. e.g.,: anchor: "#my-container" / anchor: ".container-class"

optional

If you want a simple search bubble to always be present in your app, use the bubble: "ask" prop.

Document image


Show widget event

show-widget event triggers the action to display the widget. It also has an optional property that you can pass to open a specific document from your initialized Spaces.

Property

Description

Required

docId

Set the doc id value to open a specific document. If docId is passed, widgetType is ignored, it will open in docs mode regardless of the prop passed.

Note: You must add the word PUBLISHED in front of the docId as PUBLISHED-docId or PREVIEW-spaceId; otherwise, the widget will open the document from edit mode that might have unpublished changes.

optional

blockId

Set a certain block id, in order to scroll to the desired section in that document.

optional

Supported events

Here is a brief description of our Widget event API:

Event name

Description

Required

init

This event helps Archbee widget boostrap required files into your app.

required

show-widget

This event displays the widget on demand.

required

hide-widget

This event hides the widget if built-in mechanics are not enough.

optional

Code samples

Add a function wherever you want to display the widget on your site, like this:

JS


This will load the widget, with the desired Space docs and users will be able to see everything straight from your app.

If you want to load a specific doc only, just pass docId: `${docId}` to our initial object as in the example above.

You don't need the closeWidget function, since the widget will automatically close if you press Esc or click outside of it.

However, if you want to close the widget programatically and not rely on the built-in close mechanics, you can use hide-widget event type this way:

JS




🤔
Have a question?
Our super-smart AI, knowledgeable support team and an awesome community will get you an answer in a flash.
To ask a question or participate in discussions, you'll need to authenticate first.