Develop custom search agents

Search agents enable you to search and then interact with your own content within the Here™ enterprise browser. They are external logical components that respond to search queries and actions from the enterprise browser.

• You type your search string in the enterprise browser.

• The search agent returns the appropriate search results to the enterprise browser.

• You can then interact with actions (call, chat, email) listed on your individual search results.

For custom search agents, we provide the API and GitHub example so you can build your own custom search agent and integrate it with the Here™ enterprise browser. You then configure the agent in the UI in order to use it.

Basic code sample

// Handles an incoming action and returns a response that 
// includes the URL to navigate to
const onAction: Search.OnActionListener = (action, result) => 
    {
    const { name } = action;
    const { data, key } = result;
    const { owner, searchResultHostUrl } = data as 
        { 
        owner: { id: string, name: string }, 
        searchResultHostUrl: string 
        };
    const { id: ownerId }  = owner;
    console.log(`action "${name}" triggered on search result
                 with ${key}`);
    switch (name) 
        {
        case "view-owner": 
            return 
                { url: `${searchResultHostUrl}/people/${ownerId}` };
        case "view-result":
            return 
                { url: `${searchResultHostUrl}/people/${key}` };
        default:
            console.warn(`unknown action: ${name}`);
        }
    };

// Handles an incoming search request and returns the relevant 
// search results
const onSearch: Search.onSearchListener = 
    ({ content, query, signal }) => {
        const { pageNumber, pageSize } = context;

        try {
            let results: Search.SearchResult[] = [];
            const urlRoot = `https://my-web-app.com/search?`;
            const url = `${urlRoot}q=${query}$page=${pageNumber}&limit=${pageSize}`;

            const response = await fetch(url, { signal });
            if (!response.ok) {
                throw new Error(`Request failed: ${response.status}`);
            }
            const { searchResults } = await response.json();

            results = searchResults.map((result) => {
                const { iconUrl, id: key, owner, subTitle, title } = 
                    result;
                const { name: ownerName } = owner as 
                    { id: string, name: string };

                return {
                    actions: [
                        {
                            name: `view result`,
                            description: `Go to ${title} in My Web App`,
                        },
                        {
                            name: `view result`,
                            description: `Go to ${ownerName} in My Web App`,
                            title: `View Owner`
                        }
                    ],
                    data: {
                        owner,
                        searchResultHostUrl: `https://my-web-app.com`
                    },
                    icon: iconUrl,
                    key,
                    label: subTitle,
                    title
                };
            });
            console.log(`Returning results:`, results);
            return { results };

        } catch (err) {
            if ((err as Error).name === `Abort Error`) {
                //Ignore error for cancelled results
                return { results: [] };
            }
            throw err;
        }
    };

// Registers the search agent
const searchAgent = await Search.register({ onAction, onSearch });

// Sets the search agent as ready to receive search requests
await searchAgent.isReady();