App Widget
Contextual documentation is served in your product where the user needs it. Using the contextual docs widget helps users read the product documentation without requiring them 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 to increase product adoption and retention.
All you need to do is embed the HTML code generated under Space Settings -> Widget integration.
Here are the steps to integrate the widget:
- First you have to select a Space
- Click on the gear icon ⚙️ for Settings
- Go to Widget Integration
- Click on the copy button and paste the code into your index.html file, or in your application code
Now our widget will handle everything behind the scenes. Don't worry, everything is bundled and minified. Just a 56Kb download and it loads asynchronously, so your users won't feel a difference.
On 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 the space is only published 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 |
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 |
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 |
Read more about the JWT token here: Public Access Controls .
Use bubble: "ask" prop when you want to have an easy to use search bubble present into your app all the time.
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 in order to open a specific document. Note: you have to 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 |
Here is a brief description of our Widget Event API:
Event name | Description | Required |
init | This event help archbee widget boostrap required files into your app. | required |
show-widget | This event will display the widget on demand. | required |
hide-widget | This event will hide the widget if built in mechanics are not enough. | optional |
Attach a function, wherever you want to display the widget like so:
This will load the widget, with the desired Space docs and the user will be able to see everything straight from your app.
If you want to load only a specific doc, just pass docId: `${docId}` to our initial object as in example above.
We don't need a closeWidget function, since the widget will automatically close if you press Esc or click outside of it.
If you want to close the widget programatically, and do not rely on the built in close mechanics, you can use hide-widget event type like so: