spotter updates

modules/ROOT/pages/common/nav.adoc

@@ -35,6 +35,8 @@
 *** link:{{navprefix}}/full-embed[Embed full application]
 *** link:{{navprefix}}/search-embed[Embed search page]
 *** link:{{navprefix}}/embed-nls[Embed Natural Language Search]
+*** link:{{navprefix}}/embed-spotter[Embed Spotter ^BETA^]
+**** link:{{navprefix}}/spotter-api[Generate Answers from AI APIs ^BETA^]
 *** link:{{navprefix}}/embed-searchbar[Embed search bar]
 *** link:{{navprefix}}/react-app-embed[Embed with React components]
 

modules/ROOT/pages/embed-spotter.adoc

@@ -0,0 +1,221 @@
+= Embed Spotter[beta betaBackground]^Beta^
+:toc: true
+:toclevels: 3
+
+:page-title: Embed Spotter
+:page-pageid: embed-spotter
+:page-description: You can use the ConversationEmbed SDK library to embed Conversational analytics experience in your application.
+
+ThoughtSpot Spotter enables users to find insights from their data through a conversational interface powered by Generative AI. Spotter functions as your Analyst, with whom your application users can start a conversation, ask follow-up questions on the results generated by ThoughtSpot, and get the data they need.
+
+[NOTE]
+====
+The Spotter feature is in beta and disabled by default on ThoughtSpot Embedded instances. To enable this feature on your instance, contact ThoughtSpot Support.
+====
+
+== Conversational analytics with Spotter
+
+ThoughtSpot supports Natural Language Search queries and AI-generated Answers. With Spotter, this experience is further enhanced to a full conversational interface that users can use to start a conversation with Spotter, ask follow-up questions, and get insights.
+
+Embedding applications can avail the benefits Spotter by using any of the following methods:
+
+* xref:embed-spotter.adoc#_embed_spotter_using_visual_embed_sdk[Embed Spotter conversation capabilities via Visual Embed SDK] +
+
+////
+To embed Spotter components on Homepage and Liveboards, use the `AppEmbed` package.
+////
+
+* Use xref:spotter-apis.adoc[REST APIs to create a conversation session, ask follow-up questions, and generate Answers]
+* Integrate xref:spotter-in-custom-chatbot.adoc[Spotter capabilities into your chatbot].
+
+== Embed Spotter using Visual Embed SDK
+
+Visual Embed SDK offers several options to seamlessly embed conversational analytics within your applications and customize the interface and experience as per your organization's branding guidelines.
+If you want to embed only the conversation interface, you can use the `ConversationEmbed` package and add it to your application.
+
+=== Spotter components
+
+The Spotter embedding adds the following components to your embedding application:
+
+* *Datasource selector* that allows users to select a data source for conversation with Spotter.
+* *Preview data* link that allows users to preview the contents of the data source used for the conversation.
+* Input box to ask a question to Spotter
+* *Reset* button to reset the chat conversation
+* Charts and tables generated by Spotter in response to a query
+* Menu actions such as *Pin*, *Save*, and *Download*, and a toggle switch to switch between chart and tabular format
+
+Developers can use the customization features in the SDK to customize the look and feel of the interface, and include or exclude menu elements on the conversation interface.
+
+== Get started with embedding Spotter
+
+Before you begin, check the following:
+
+* Spotter is enabled on your ThoughtSpot instance
+* Your environment has Visual Embed SDK v1.33.1 or later version
+
+=== Import the SDK package
+
+Import the `ConversationEmbed` SDK library to your application environment:
+
+**npm**
+[source,JavaScript]
+----
+import {
+    ConversationEmbed,
+    AuthType,
+    init,
+    prefetch,
+}
+from '@thoughtspot/visual-embed-sdk';
+----
+
+**ES6**
+[source,JavaScript]
+----
+<script type = 'module'>
+    import {
+        ConversationEmbed,
+        AuthType,
+        init,
+        prefetch,
+    }
+from 'https://cdn.jsdelivr.net/npm/@thoughtspot/visual-embed-sdk/dist/index.js';
+----
+
+=== Initialize the SDK
+
+To initialize the SDK, the following information is required:
+
+* `thoughtSpotHost` +
+The hostname of your ThoughtSpot application instance. See xref:faqs.adoc#tsHostName[FAQs] to know how to find the hostname of your application instance.
+* `authType` +
+Authentication type. ThoughtSpot supports a variety of Authentication types. For testing purposes, you can use `AuthType.None`. For other authentication options, see xref:embed-authentication.adoc[Authentication].
+
+[source,JavaScript]
+----
+init({
+    thoughtSpotHost: '<%=tshost%>',
+    authType: AuthType.None,
+});
+----
+
+=== Create an instance of ConversationEmbed object
+
+Create an instance of the `ConversationEmbed` object and specify the data source ID. Optionally, you can specify the search query string to generate a chart or table at load time.
+
+[source,JavaScript]
+----
+const conversation = new ConversationEmbed(document.getElementById('ts-embed'), {
+    frameParams: {
+        width: '100%',
+        height: '100%',
+    },
+    worksheetId: '<%=datasourceGUID%>',
+    searchOptions: {
+        searchQuery: 'sales by region',
+    },
+});
+----
+
+[source,JavaScript]
+----
+const conversation = new ConversationEmbed(document.getElementById('ts-embed'), {
+    frameParams: {
+        width: '100%',
+        height: '100%',
+    },
+    worksheetId: '<%=datasourceGUID%>',
+    searchOptions: {
+        searchQuery: 'sales by region',
+    },
+});
+----
+
+=== Customize your embed (Optional)
+
+To customize the Spotter page contents, use the customization attributes in the SDK.
+
+==== Customize style, icons, and text
+To customize the look and feel of the Spotter page, you can use the `customizations` settings in the SDK. The `customizations` object allows you to add xref:customize-css-styles.adoc[custom CSS definitions], xref:customize-text-strings.adoc[text strings], and xref:customize-icons.adoc[icons].
+
+For example, if you want to use your own icon sprites and the SVG for the icons is  hosted on a Web server, you can replace the default icons on the spotter page as shown in this example.
+
+[source,JavaScript]
+----
+ init({
+     //...
+     customizations: {
+         iconSpriteUrl: "https://cdn.jsdelivr.net/gh/thoughtspot/custom-css-demo/alternate-spotter-icon.svg"
+     }
+ });
+----
+
+[NOTE]
+====
+When customizing icons, ensure that the hosting server is added to to the *CSP connect-src domains* list on the *Develop* > *Security Settings* page. For more information, see xref:security-settings.adoc#csp-connect-src[Security Settings].
+====
+
+==== Customize menu elements
+
+You can show or hide menu elements such as the *Pin*, *Save* buttons on the Spotter page using xref:embed-actions.adoc[`disabledActions`, `visibleActions`, or `hiddenActions`] array as shown in this example:
+
+[source,JavaScript]
+----
+ //...
+ disabledActions: [Action.Pin,Action.Save]
+----
+
+[NOTE]
+====
+In ThoughtSpot 10.4.0.cl release, you can hide or disable only *Pin* and *Save* menu actions on the Spotter page.
+====
+
+=== Register, handle, and trigger events
+
+Register event listeners.
+
+[source,JavaScript]
+----
+ conversation.on(EmbedEvent.Init, showLoader)
+ conversation.on(EmbedEvent.Load, hideLoader)
+----
+For more information about event types, see the following pages:
+
+* xref:HostEvent.adoc[HostEvent]
+* xref:EmbedEvent.adoc[EmbedEvent]
+
+=== Render the embedded object
+
+[source,JavaScript]
+----
+conversation.render();
+----
+
+== Test your embedding
+
+Load the embedded object in your app. If the embedding is successful, you will see the following page:
+
+=== Spotter page
+
+[.widthAuto]
+[.bordered]
+image::./images/converseEmbed_default.png[Conversation embed]
+
+=== Spotter page with the preloaded query and search result
+
+[.widthAuto]
+[.bordered]
+image::./images/converseEmbed-with-query.png[Conversation embed]
+
+=== Spotter page with custom icon and text
+
+The following figures show the Spotter page with custom icon sprite and text:
+
+[.widthAuto]
+[.bordered]
+image::./images/spotter-customization.png[Spotter customization]
+
+
+[.widthAuto]
+[.bordered]
+image::./images/spotter-customization2.png[Spotter customization]