在 Elasticsearch 中使用用戶行為分析：使用 UBI 和 search-ui 創建一個應用程序

作者：來自 Elastic?Eduard Martin?及?Alexander Dávila

通過一個實際示例學習如何在 Elasticsearch 中使用 UBI。我們將創建一個在搜索和點擊結果時生成 UBI 事件的應用程序。

想要獲得 Elastic 認證嗎？看看下一次 Elasticsearch Engineer 培訓什么時候開始！

Elasticsearch 擁有豐富的新功能，能幫助你為自己的用例構建最佳的搜索解決方案。深入了解我們的示例筆記本，開始免費云試用，或者現在就在本地機器上嘗試 Elastic。

在本文中，我們將創建一個示例應用來收集用戶行為數據，展示如何將 UBI 擴展集成到 search-ui 中。我們還將自定義收集的數據，以展示 UBI 標準的靈活性，以及它如何滿足不同的需求。

這個示例應用是一個簡單的圖書搜索引擎，目標是能夠捕捉用戶的事件，并基于他們的行為（如搜索和點擊）將其索引到 Elasticsearch 中。

需求

這個應用需要在 Elasticsearch 中安裝 UBI 插件。你可以閱讀我們的博客文章獲取更多信息。

加載示例數據

我們需要先在 Elasticsearch 中準備一些數據。在 Kibana DevTools Console 中運行以下命令來加載一組產品列表，以便在我們的 UI 中展示。這將創建一個名為 “books” 的新索引，用于本示例。

POST /_bulk
{ "index" : { "_index" : "books" } }
{"name": "Snow Crash", "author": "Neal Stephenson", "release_date": "1992-06-01", "page_count": 470, "price": 14.99, "url": "https://www.amazon.com/Snow-Crash-Neal-Stephenson/dp/0553380958/", "image_url": "https://m.media-amazon.com/images/I/81p4Y+0HzbL._SY522_.jpg" }
{ "index" : { "_index" : "books" } }
{"name": "Revelation Space", "author": "Alastair Reynolds", "release_date": "2000-03-15", "page_count": 585, "price": 16.99, "url": "https://www.amazon.com/Revelation-Space-Alastair-Reynolds/dp/0441009425/", "image_url": "https://m.media-amazon.com/images/I/61nC2ExeTvL._SY522_.jpg"}
{ "index" : { "_index" : "books" } }
{"name": "1984", "author": "George Orwell", "release_date": "1985-06-01", "page_count": 328, "price": 12.99, "url": "https://www.amazon.com/1984-Signet-Classics-George-Orwell/dp/0451524934/", "image_url": "https://m.media-amazon.com/images/I/71rpa1-kyvL._SY522_.jpg"}
{ "index" : { "_index" : "books" } }
{"name": "Fahrenheit 451", "author": "Ray Bradbury", "release_date": "1953-10-15", "page_count": 227, "price": 11.99, "url": "https://www.amazon.com/Fahrenheit-451-Ray-Bradbury/dp/1451673310/", "image_url": "https://m.media-amazon.com/images/I/61sKsbPb5GL._SY522_.jpg"}
{ "index" : { "_index" : "books" } }
{"name": "Brave New World", "author": "Aldous Huxley", "release_date": "1932-06-01", "page_count": 268, "price": 12.99, "url": "https://www.amazon.com/Brave-New-World-Aldous-Huxley/dp/0060850523/", "image_url": "https://m.media-amazon.com/images/I/71GNqqXuN3L._SY522_.jpg"}
{ "index" : { "_index" : "books" } }
{"name": "The Handmaid's Tale", "author": "Margaret Atwood", "release_date": "1985-06-01", "page_count": 311, "price": 13.99, "url": "https://www.amazon.com/Handmaids-Tale-Margaret-Atwood/dp/038549081X/", "image_url": "https://m.media-amazon.com/images/I/61su39k8NUL._SY522_.jpg"}

創建示例應用程序

我們將使用 search-ui 創建一個 UI 應用程序，將 UBI 事件發送到 Elasticsearch。search-ui 是 Elastic 的 JavaScript 庫，用于使用內置的 React 組件創建 UI。

Search UI 是 Elastic 基于 React 的框架，用于構建搜索應用程序。它為搜索體驗中的所有關鍵部分提供組件 —— 例如搜索欄、分面、分頁和自動建議。自定義其行為（包括添加 UBI）非常簡單。

Elasticsearch 連接器

首先，我們需要安裝 Elasticsearch 連接器，步驟參考連接器教程。

1）從 GitHub 下載 search-ui 啟動應用：

curl https://codeload.github.com/elastic/app-search-reference-ui-react/tar.gz/master | tar -xz

2）進入新目錄 app-search-reference-ui-react-main 并安裝依賴項：

cd app-search-reference-ui-react-main
npm install

3）通過 npm 包管理器安裝 Elasticsearch 連接器：

npm install @elastic/search-ui-elasticsearch-connector

后端服務器

為了遵循最佳實踐并確保對 Elasticsearch 的調用通過中間層服務完成，我們來創建一個后端來調用我們的連接器：

1）我們先創建一個新目錄和一個新的 JavaScript 文件：

mkdir server
touch server/index.js

2）在新的 index.js 文件中，寫入：

import express from "express";
import ElasticsearchAPIConnector from "@elastic/search-ui-elasticsearch-connector";
import { Client } from "@elastic/elasticsearch";
import "dotenv/config";const app = express();
app.use(express.json());const connector = new ElasticsearchAPIConnector({host: process.env.ELASTICSEARCH_HOST,index: process.env.ELASTICSEARCH_INDEX,apiKey: process.env.ELASTICSEARCH_API_KEY
});const esClient = new Client({node: process.env.ELASTICSEARCH_HOST,auth: {apiKey: process.env.ELASTICSEARCH_API_KEY,},
});app.post("/api/search", async (req, res) => {const { state, queryConfig } = req.body;const response = await connector.onSearch(state, queryConfig);res.json(response);
});app.post("/api/autocomplete", async (req, res) => {const { state, queryConfig } = req.body;const response = await connector.onAutocomplete(state, queryConfig);res.json(response);
});app.post("/api/analytics", async (req, res, next) => {try {console.log(`Sending analytics for query_id: ${req.body.query_id}`)req.body.client_id = clientId;await esClient.index({index: "ubi_events",body: req.body,});console.log(req.body);res.status(200).json({ message: "Analytics event saved successfully" });} catch (error) {next(error);}
});app.listen(3001);

通過此更改，我們將默認行為（從瀏覽器調用 Elasticsearch）替換為調用我們的后端。這種方法更適合生產環境。

在文件末尾，將 export default function 替換為以下定義：

export default function App() {return (<SearchProvider config={config}><Layoutheader={<SearchBox autocompleteSuggestions={false} />}bodyContent={<ResultstitleField={"author"}urlField={"url"}thumbnailField={"image_url"}shouldTrackClickThrough={true}/>}/></SearchProvider>);
}

這將允許我們顯示圖書的圖片，并提供可點擊的鏈接。

要查看完整教程，請訪問此文檔。

按照步驟操作后，你將得到一個客戶端的 index.js 文件和一個服務器端的 server/index.js 相關文件。

配置連接器

我們將配置 onSearch 和 onResultClick 處理程序來設置 UBI query_id。然后，在執行搜索和點擊結果時發送 UBI 事件。

配置 onSearch：攔截搜索請求，為每個請求使用 UUID v4 分配一個唯一的 requestId，然后將請求傳遞給處理鏈中的下一個處理程序。我們將使用此 ID 作為 UBI query_id，用于將搜索和點擊分組。

進入 server/index.js 文件，并擴展連接器以配置 onSearch 方法：

const clientId = uuidv4(); // to maintain a constant client id
class UBIConnector extends ElasticsearchAPIConnector {async onSearch(requestState, queryConfig) {const result = await super.onSearch(requestState, queryConfig);result.requestId = uuidv4();result.clientId = clientId;return result;}
}

之后，聲明連接器并自定義搜索請求，通過 ext.ubi 搜索參數將生成的 ID 發送到 UBI 插件。

const connector = new UBIConnector({host: process.env.ELASTICSEARCH_HOST,index: process.env.ELASTICSEARCH_INDEX,apiKey: process.env.ELASTICSEARCH_API_KEY,},(requestBody, requestState, queryConfig) => {requestBody.ext = {ubi: {query_id: requestState.requestId,client_id: requestState.clientId || clientId,user_query: requestState.searchTerm || "",},};if (!requestState.searchTerm) return requestBody;requestBody.query = {multi_match: {query: requestState.searchTerm,fields: Object.keys(queryConfig.search_fields),},};return requestBody;}
);

別忘了添加新的導入。此外，由于我們的前端運行在 localhost:3000，而后端運行在 localhost:3001，它們被視為不同的源。‘源’ 由協議、域名和端口的組合定義，所以即使它們都在同一主機上并使用 HTTP 協議，不同的端口也會使它們成為不同的源，因此我們需要 CORS。要了解更多關于 CORS 的信息，請訪問本指南。

import cors from "cors";
import { v4 as uuidv4 } from "uuid";
...
app.use(cors({origin: "http://localhost:3000", // Your React app URLcredentials: true
}));

進入客戶端的 client/App.js 文件（點擊以打開完整的完成文件）。

在 config 對象聲明中添加 onResultClick 事件處理程序，每當用戶點擊搜索結果時，將分析數據發送到后端，捕獲的信息包括查詢 ID、結果詳情以及用戶交互的具體信息，如點擊的文檔屬性、文檔位置和頁碼。在這里，你還可以添加用戶同意共享的其他信息。確保遵守隱私法律（例如歐洲的 GDPR）。

const config = {apiConnector: connector,
onResultClick: async (r) => {const locationData = await getLocationData();const payload = {application: "search-ui",action_name: "click",query_id: r.requestId || "",client_id: r.clientId || "",timestamp: new Date().toISOString(),message_type: "CLICK_THROUGH",message: `Clicked ${r.result.name.raw}`,user_query: r.query,event_attributes: {object: {device: getDeviceType(),object_id: r.result.id.raw,description: `${r.result.name.raw}(${r.result.release_date.raw}) by ${r.result.author.raw}`,position: {ordinal: r.resultIndexOnPage,page_depth: r.page,},user: {ip: locationData.ip,city: locationData.city,region: locationData.region,country: locationData.country,location: {lat:locationData.latitude,lon:locationData.longitude}}},},};fetch(`http://localhost:3001/api/analytics`, {method: "POST",headers: {"Content-Type": "application/json",},body: JSON.stringify(payload),}).then((r) => console.log(r)).catch((error) => {console.error("Error:", error);});}// other Search UI config options
};

SearchUI 參考中的完整事件鉤子可以在這里找到。

接下來，修改 search_fields 和 result_fields 以與數據集對齊。我們將通過圖書的名稱和作者進行搜索，并返回名稱、作者、image_url、url 和價格。

const config = {
...searchQuery: {search_fields: {name: {},author: {},},result_fields: {name: { raw: {} },author: { raw: {} },image_url: { raw: {} },url: { raw: {} },price: { raw: {} },release_date: { raw: {} }},},
};

最后，我們將添加幾個輔助函數來定義設備類型和用戶數據：

const getDeviceType = () => {const userAgent = navigator.userAgent.toLowerCase();if (/tablet|ipad|playbook|silk/.test(userAgent)) {return 'tablet';}if (/mobile|iphone|ipod|android|blackberry|opera|mini|windows\sce|palm|smartphone|iemobile/.test(userAgent)) {return 'mobile';}return 'desktop';
};const getLocationData = async () => {const response = await fetch('https://ipapi.co/json/');const data = await response.json();return {ip: data.ip,city: data.city,region: data.region,country: data.country_name,latitude: data.latitude,longitude: data.longitude};
};

其余的 config 對象可以保持不變。

我們整理了一個倉庫，你可以在這里找到。它包含了更完整的項目版本。可以通過以下命令克隆：

git clone https://github.com/llermaly/search-ui-ubi.git

如果你使用 GitHub 倉庫，需要為服務器提供以下環境變量：

ELASTICSEARCH_HOST=your_elasticsearch_url
ELASTICSEARCH_API_KEY=your_api_key
ELASTICSEARCH_INDEX=books

運行應用程序

現在你可以啟動服務器：

cd server
npm install && node index.js

如果遇到與該庫相關的錯誤，可能需要單獨安裝 CORS：

npm install cors

在另一個終端中：

cd client
npm install && npm start

然后在瀏覽器中訪問 http://localhost:3000。

最終效果將如下所示：

在 Elasticsearch 端，我們可以為 ubi_events 索引創建一個（相當簡單的）映射，以便將用戶位置作為位置處理：

PUT ubi_events
{"mappings": {"properties": {"event_attributes.object.user.location": {"type": "geo_point"}}}
}

每次搜索時，會生成一個 ubi_queries 事件，而在點擊時，會生成一個類型為 click 的 ubi_events。

這就是一個 ubi_queries 事件的樣子：

{"_index": "ubi_queries","_id": "aCXqW5gB87F1AivbVvHI","_score": null,"_ignored": ["query.keyword"],"_source": {"query_response_id": "a8aca3d9-1cbc-4800-8853-fd1889172b9b","user_query": "snow","query_id": "d198c517-7d3b-49dd-be11-f573728d578e","query_response_object_ids": ["0","6"],"query": """{"from":0,"size":20,"query":{"multi_match":{"query":"snow","fields":["author^1.0","name^1.0"]}},"_source":{"includes":["name","author","image_url","url","price","release_date"],"excludes":[]},"sort":[{"_score":{"order":"desc"}}],"ext":{"query_id":"d198c517-7d3b-49dd-be11-f573728d578e","user_query":"snow","client_id":"8a5de3a1-7a1b-47ed-b64f-5be0537829be","object_id_field":null,"query_attributes":{}}}""","query_attributes": {},"client_id": "8a5de3a1-7a1b-47ed-b64f-5be0537829be","timestamp": 1753888741063},"sort": [1753888741063]}

這是一個示例 ubi_events 文檔：

{"_index": "ubi_events","_id": "fiDqW5gBftHcGY9PXtao","_score": null,"_source": {"application": "search-ui","action_name": "click","query_id": "3850340e-0e72-4f20-a06e-27a52d983b39","client_id": "8a5de3a1-7a1b-47ed-b64f-5be0537829be","timestamp": "2025-07-30T15:19:02.659Z","message_type": "CLICK_THROUGH","message": "Clicked Snow Crash","user_query": "snow","event_attributes": {"object": {"device": "desktop","object_id": "vrFBK5gBZjU2lCOmiNSX","description": "Snow Crash(1992-06-01) by Neal Stephenson","position": {"ordinal": 0,"page_depth": 1},"user": {"ip": "2800:bf0:108:18:d5ca:fa84:416f:99e0","city": "Quito","region": "Pichincha","country": "Ecuador","location": {"lat": -0.2309,"lon": -78.5211}}}}},"sort": [1753888742659]}

從這里，我們已經可以看到有用的信息，比如與特定查詢相關的操作。

結論

將 search-ui 與 UBI 擴展集成是一個可以收集用戶行為的寶貴見解的過程，并可以通過其他元數據擴展，例如用戶位置和設備類型。這些信息會自動索引到兩個獨立的索引中，分別用于查詢和操作，并可以通過唯一 ID 關聯。這些信息使開發者能夠更好地理解用戶如何使用應用，并優先處理可能影響用戶體驗的問題。

原文：Using UBI in Elasticsearch: Creating an app with UBI and search-ui - Elasticsearch Labs