@alphasense/embedded-widgets

v2.1.5

Published

a month ago

The AlphaSense Widget SDK allows you to easily integrate AlphaSense widgets into your web applications.

Downloads

130

0High
0Medium
0Low

lappi_lynx

dtuan

algun

AlphaSense Widget SDK

The AlphaSense Widget SDK allows you to easily integrate AlphaSense widgets into your web applications.

Installation

You can install the AlphaSense Widget SDK using npm:

npm install @alphasense/embedded-widgets

Alternatively, you can use the SDK via a CDN:

<script src="https://unpkg.com/@alphasense/embedded-widgets@latest/dist/index.min.js"></script>

Quick Start

Install the SDK using one of the methods above.
Import and initialize the SDK in your project:

import { AlphaSenseWidget } from '@alphasense/embedded-widgets';

const widget = new AlphaSenseWidget({
  // Configuration options
});

Example:

<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <title>AlphaSense Widget SDK</title>
  </head>
  <body>
    <div class="container">
      <div id="widget"></div>
    </div>
    <script src="https://unpkg.com/@alphasense/embedded-widgets@latest/dist/index.min.js"></script>
    <script>
      new AlphaSenseWidget({
        target: '#widget',
        widgetType: 'companySummary',
        companyParams: {
          tickerCode: 'AAPL'
        },
        width: '300px',
        height: '500px',
      }).init();
    </script>
  </body>
</html>

Configuration

When initializing the AlphaSenseWidget, you can pass the following options:

| Option | Type | Required | Description | | ------------------- | --------------------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------- | | target | string | HTMLElement | No | The target element to render the widget into. Can be a CSS selector string or an HTMLElement. If not provided, a default container will be created. | | widgetType | WidgetType | Yes | The type of widget to render. Available values: 'companySummary', 'companyTopics', 'documentList', 'smartSummary', 'documentViewer', 'generativeSearch' | | companyParams | object | No | Parameters specific to the target company identification. See below for details. | | documentSearchParams | object | No | Parameters for filtering and sorting documents in the Document List widget. See "Document List Parameters" section below for details. | | generativeSearchParams | object | No | Parameters specific to the Generative Search widget. See below for details. | | documentViewerParams | object | No | Parameters specific to the Document Viewer widget. Required when widgetType is 'documentViewer'. See below for details. | | onDocumentClick | function | No | Callback that is called when a document is clicked (e.g., an item in DocumentList, a citation in GenerativeSearch, or a citation in CompanyTopics). Receives the document ID as a parameter. When provided, automatically sets documentClickMode to 'docviewer'. | | documentClickMode | string | No | Navigation mode for document click handling. Possible values: 'platform' (default), 'docviewer', 'popup'. | | height | string | No | The height of the widget. Defaults to '100%'. | | width | string | No | The width of the widget. Defaults to '100%'. |

companyParams

For now it is optional, since tickerCode has a default value but in the future companyParams might be required (for example if we decide not to use the fallback tickerCode value or another params will be added). The companyParams object can include the following properties:

| Parameter | Type | Description | | ------------ | ------ | ----------------------------------------------- | | tickerCode | string | The ticker code for the company (e.g., 'AAPL', 'NVDA', 'TSLA'). |

documentViewerParams

The documentViewerParams object is required when using the Document Viewer widget. It includes the following properties:

| Parameter | Type | Required | Description | | --------- | ------ | -------- | ---------------------------------------------- | | docId | string | Yes | The document ID to display in the viewer (e.g., 'doc-12345'). |

generativeSearchParams

The generativeSearchParams object is optional when using the Generative Search widget. It includes the following properties:

| Parameter | Type | Required | Description | | --------- | ------ | -------- | ---------------------------------------------- | | conversationId | string | No | The conversation ID to continue an existing conversation (e.g., '1234567890__987654321'). | | initialPrompt | string | No | The initial prompt to start a new conversation with (e.g., 'What are the latest Intel results?'). Note: This parameter is ignored when conversationId is provided, as it only works with new conversations. |

Examples

Starting a new conversation with an initial prompt:

new AlphaSenseWidget({
  target: '#generative-search',
  widgetType: 'generativeSearch',
  generativeSearchParams: {
    initialPrompt: 'What are the latest Intel results?'
  },
  width: '100%',
  height: '600px',
}).init();

Continuing an existing conversation:

new AlphaSenseWidget({
  target: '#generative-search',
  widgetType: 'generativeSearch',
  generativeSearchParams: {
    conversationId: '1234567890__987654321'
  },
  width: '100%',
  height: '600px',
}).init();

Document List Parameters

When using the Document List widget, you can provide document search parameters to filter and sort documents. These parameters can be passed through the SDK configuration.

Document Search Parameters

The SDK supports the following document search parameters through the documentSearchParams configuration object:

| Parameter | Type | Description | Example | |-----------|------|-------------|---------| | keyword | string | Text search keyword to filter documents | keyword: 'semiconductor' | | documentTypes | string[] | Array of document type IDs for filtering | documentTypes: ['1', '2', '3'] | | savedSearchId | string | Saved search ID to load predefined search criteria | savedSearchId: '123' | | watchlistIds | string[] | Array of watchlist IDs to filter documents by watchlists | watchlistIds: ['1367044'] | | contentSetIds | string[] | Array of content set IDs to filter by document sources | contentSetIds: ['12001', '77'] | | tickers | string[] | Array of ticker codes to filter documents by multiple companies | tickers: ['MSFT', 'AAPL', 'GOOGL'] | | sorting | object | Sort configuration with field and direction | sorting: {field: 'DATE', direction: 'DESC'} | | primaryOnly | boolean | If true, only show documents where the company is the primary subject. If false or undefined, show all company mentions (both primary and secondary). | primaryOnly: true |

Sorting Options

The sorting parameter accepts an object with the following properties:

| Property | Type | Valid Values | Description | |----------|------|--------------|-------------| | field | string | 'DATE', 'RELEVANCE', 'SENTIMENT', 'PAGES' | The field to sort by | | direction | string | 'ASC', 'DESC' | Sort direction (ascending or descending) |

Usage Examples

Basic company document search with keyword:

new AlphaSenseWidget({
  target: '#document-list',
  widgetType: 'documentList',
  companyParams: {
    tickerCode: 'AAPL'
  },
  documentSearchParams: {
    keyword: 'earnings',
    documentTypes: ['1', '2'],
    sorting: {
      field: 'DATE',
      direction: 'DESC'
    }
  },
  width: '100%',
  height: '600px',
}).init();

Watchlist-based document filtering:

new AlphaSenseWidget({
  target: '#document-list',
  widgetType: 'documentList',
  documentSearchParams: {
    watchlistIds: ['1367044'],
    keyword: 'earnings',
    sorting: {
      field: 'DATE',
      direction: 'DESC'
    }
  },
  width: '100%',
  height: '600px',
}).init();

Multi-company document search:

new AlphaSenseWidget({
  target: '#document-list',
  widgetType: 'documentList',
  documentSearchParams: {
    tickers: ['MSFT', 'AAPL', 'GOOGL'],
    keyword: 'revenue',
    contentSetIds: ['12001', '77'],
    sorting: {
      field: 'RELEVANCE',
      direction: 'DESC'
    }
  },
  width: '100%',
  height: '600px',
}).init();

Content set filtering:

new AlphaSenseWidget({
  target: '#document-list',
  widgetType: 'documentList',
  companyParams: {
    tickerCode: 'NVDA'
  },
  documentSearchParams: {
    contentSetIds: ['12001', '77'],
    keyword: 'AI chips',
    sorting: {
      field: 'DATE',
      direction: 'DESC'
    }
  },
  width: '100%',
  height: '600px',
}).init();

Primary company mentions only:

new AlphaSenseWidget({
  target: '#document-list',
  widgetType: 'documentList',
  companyParams: {
    tickerCode: 'AAPL'
  },
  documentSearchParams: {
    keyword: 'iPhone',
    primaryOnly: true, // Only show documents specifically about Apple
    sorting: {
      field: 'RELEVANCE',
      direction: 'DESC'
    }
  },
  width: '100%',
  height: '600px',
}).init();

Parameter Combinations

Single company: Use companyParams.tickerCode for a single company
Multiple companies: Use documentSearchParams.tickers array for multiple companies
Watchlist mode: Use documentSearchParams.watchlistIds (no ticker needed)
Combined filters: You can combine keyword, contentSetIds, sorting, and company/watchlist filters

Notes

When using watchlistIds, you don't need to specify a tickerCode
The tickers parameter is useful when searching across multiple companies simultaneously
Content set IDs filter documents by their source (e.g., broker research, earnings calls, news)
All parameters are optional and can be combined to create complex search queries

Document Click Handling

When using the Document List widget, you can provide an onDocumentClick callback function to handle document clicks:

new AlphaSenseWidget({
  target: '#document-list',
  widgetType: 'documentList',
  companyParams: {
    tickerCode: 'AAPL'
  },
  onDocumentClick: (docId) => {
    console.log('Document clicked:', docId);
    // Custom handling of document click
  // For example, update a document viewer on the same page
    console.log(`Document clicked: ${docId} for ticker: AAPL`);
    updateDocumentViewer(docId); // this is a placeholder for your custom handling function of the document click
  },
  width: '300px',
  height: '500px',
}).init();

Important: When you provide an onDocumentClick callback, the documentClickMode is automatically set to 'docviewer'. This prevents the default behavior of opening a new tab when a document is clicked, allowing your callback to handle the document click instead.

Document Viewer Widget

The Document Viewer widget displays a specific document by its ID. It works with any widget that supports the onDocumentClick callback and returns a document ID.

Basic Usage

import { AlphaSenseWidget } from '@alphasense/embedded-widgets';

const documentViewer = new AlphaSenseWidget({
  target: '#document-viewer',
  widgetType: 'documentViewer',
  documentViewerParams: {
    docId: 'your-document-id'
  },
  width: '100%',
  height: '600px',
}).init();

Required Parameters

| Parameter | Type | Required | Description | |-----------|------|----------|-------------| | target | string | HTMLElement | Yes | Container element selector or HTMLElement | | widgetType | string | Yes | Must be 'documentViewer' | | documentViewerParams.docId | string | Yes | The document ID to display |

CDN Usage

<div id="document-viewer" style="width: 100%; height: 600px;"></div>
<script src="https://unpkg.com/@alphasense/embedded-widgets@latest/dist/index.min.js"></script>
<script>
  new AlphaSenseWidget({
    target: '#document-viewer',
    widgetType: 'documentViewer',
    documentViewerParams: {
      docId: 'your-document-id'
    }
  }).init();
</script>

Integration with Other Widgets

The Document Viewer works seamlessly with any widget that provides document IDs through the onDocumentClick callback. Here's an example of using it with both GenerativeSearch and DocumentList widgets:

let documentViewer = new AlphaSenseWidget({
  target: '#document-viewer',
  widgetType: 'documentViewer',
  documentViewerParams: { docId: 'initial-doc-id' }
}).init();

function updateDocumentViewer(docId) {
  documentViewer.destroy();
  documentViewer = new AlphaSenseWidget({
    target: '#document-viewer',
    widgetType: 'documentViewer',
    documentViewerParams: { docId }
  }).init();
}

// Generative Search with a callback to update the viewer
const generativeSearch = new AlphaSenseWidget({
  target: '#generative-search',
  widgetType: 'generativeSearch',
  onDocumentClick: (docId) => {
    console.log(`Citation clicked in Generative Search: ${docId}`);
    updateDocumentViewer(docId);
  }
}).init();

// Document List with a callback to update the viewer
const documentList = new AlphaSenseWidget({
  target: '#document-list',
  widgetType: 'documentList',
  companyParams: { tickerCode: 'AAPL' },
  onDocumentClick: (docId) => {
    console.log(`Document clicked in Document List: ${docId}`);
    updateDocumentViewer(docId);
  }
}).init();

// Company Topics with a callback to update the viewer
const companyTopics = new AlphaSenseWidget({
  target: '#company-topics',
  widgetType: 'companyTopics',
  companyParams: { tickerCode: 'AAPL' },
  onDocumentClick: (docId) => {
    console.log(`Citation clicked in Company Topics: ${docId}`);
    updateDocumentViewer(docId);
  }
}).init();

Compatible Widgets

Any widget supporting onDocumentClick callback and provides the docId can be used with the Document Viewer. For example:

✅ Generative Search - Available for citations source documents.
✅ Document List - Available for document browsing.
✅ Company Topics - Available for topic summary citations.
⚠️ Smart Summary - Planned to provide needed callback.

Error Handling

try {
  const viewer = new AlphaSenseWidget({
    target: '#document-viewer',
    widgetType: 'documentViewer',
    documentViewerParams: { docId: 'your-document-id' }
  }).init();
} catch (error) {
  console.error('Failed to initialize document viewer:', error.message);
}