What is the Zive Widget?
The Zive Widget is a component that allows embedding the Zive platform into third party platforms via a JavaScript code snippet. The goal of the embed is to present the user with all Zive capabilities wherever they are working. Consider using the company's intranet and quickly needing to search or asking the Assistant about a Sales deal that was posted in the News just now.
Note: Zive Widget is available to all customers in Business and Enterprise plan.
Zive’s widget is designed to have the smallest footprint possible:
Limited bundle size (~4kb) for the embed code
iFrame for the Zive Platform to sandbox Zive’s Frontend code for Security purposes
Integrateable with other buttons than the default (bottom right) chat bubble.
Technical Integration
The following illustration shows provides an overview how the widget integrates from a technical perspective.
1. Request signing certificate
To start the embedding process into your third party application, an Admin needs to request a new signing certificate via our Support. Zive’s support staff will issue a new certificate for you and securely transfer the signing certificate to you. When requesting the certificate please provide the following information:
Use-Case (where do you want to embed Zive Widget)
Zive URL (your Zive platform URL)
URL (exact base URL of the hosting platform)
Unique identifier of your application inside your ecosystem (e.g. sharepoint-online-production)
2. Load frontend embeddable
In your own application insert the following JavaScript code to be able to initialize the Zive Widget.
<script type="module" src="https://YOUR_ZIVE_URL/embeddable.js"></script>
3. Request and sign JWT token from backend
To be able to correctly initialize the Zive Widget you need to issue a new JWT token with the signing certificate that you obtained from Zive. The following claims are expected:
iat – Issue date of the token as UTC timestamp in seconds.
exp – Expiry date of the token as UTC timestamp in seconds.
sub – The email address of the user trying to use the Zive widget.
source – The unique platform identifier you specified.
The token must be signed with RSA SHA 256 (RS256).
4. Initialize Zive Widget
After you successfully obtained a token for the user, initialize the Zive Widget in your code as shown in the example below.
<script>
(function () {
const interval = setInterval(() => {
if (!ziveWidget) return;
ziveWidget.init({
token: "<YOUR TOKEN>",
email: "<UNIQUE USER EMAIL>",
source: "<YOUR UNIQUE PLATFORM IDENTIFIER>",
baseUrl: "https://<YOUR ZIVE PLATFORM URL>"
});
clearInterval(interval);
}, 500);
})();
</script>
After correctly initializing the Zive widget, the default button will be rendered on your platform and after clicking it the full Zive interface should be presented.
Configuration options
1. Disabling features
ziveWidget.init({
...,
disabledFeatures: ["home", "search", "knowledge"],
});You may choose to disable certain features of the Zive Platform for this Widget. Selected features will only be visually hidden for that instance of the Widget and are still accessible to users when visiting the Zive platform. Following features can be disabled:
Home – Disable use of the home dashboard
Search – Users will not be able to search in this widget
Assistant – Users will not be able to use the Zive assistant in this Widget
Knowledge – Users can’t browse Knowledge collections and other KM feat
2. Guest users
When issuing the JWT token you may choose to add an additional claim.
guest – Boolean to make the current user a guest
When setting this to true the current user becomes a Guest user. Guest users are only able to browse the platform in the scope of knowledge collections they have been added to. Moderators of the Zive platform may choose to publish their collections to guests. When working with the Search or the Assistant, Zive will only pull the contents and people that are linked in those collections to answer the Guest users questions.
When working with Guests please keep in mind that:
When making an existing internal user a guest via the Widget they will be converted into a guest, only reversible by an admin.
Guest accounts will be deprovisioned after 30 days of inactivity.
Guest accounts can only access public content (content that has permissions set in the source can not be read, e.g. private Sharepoint Groups).
Guest accounts count towards your user license.
3. Customizing the Trigger
ziveWidget.init({
...,
trigger: {
position: "bottom-left",
left: 20,
}
});By default the button is rendered in the bottom-left corner. You can override this setting by specifying the position attribute, valid values are:
bottom-left
bottom-right
top-left
top-right
You may choose to add distance properties to the relevant edges of the screen in px.
4. Custom Trigger
ziveWidget.init({
...,
trigger: {
selector: "#my-custom-trigger"
}
});You can use an existing button in your platform to trigger the Zive Widget popup. Please specify a unique css selector for this. Zive will register a click listener to this HTML element and center the PopUp below this button on click. Providing a custom trigger disables the default button and its position attribute.
5. Fixed user language
ziveWidget.init({
...,
language: "de"
});Zive widget will by default use the browser language of the user. You may choose to pass a language property to override this behavior. The following language codes are supported:
de – Informal German
en – American English
6. Future options
Note: These options are not yet available but will come soon.
Font customization: Customize the font that the Zive platform is using inside the iFrame
Route interception: Listen on navigation events inside the iFrame to intercept clicks on e.g. SharePoint files to open them directly in the hosting application