Przejdź do treści

Integracja wyszukiwarki z silnikiem rekomendacji

Wyszukiwarka produktowa oparta jest na silniku rekomendacji Recombee, który zasila ECDP. Silnik jest na bieżąco zasilany zdarzeniami behawioralnymi użytkowników przez skrypt śledzący ECDP (web tracking), dzięki czemu wyniki wyszukiwania są personalizowane w oparciu o rzeczywiste interakcje z produktami.

Celem integracji jest:

  • poprawne raportowanie requestów o rekomendacje w ECDP,
  • powiązanie kliknięć i sprzedaży z konkretnym ID rekomendacji (recommId),
  • obsługa przypadku braku wyników.

Dane dostępowe (po stronie ExpertSender)#

Po potwierdzeniu wdrożenia dostarczymy dane niezbędne do połączenia z bazą Recombee oraz konfiguracji ECDP:

  • Database ID, Public Token, Region – do inicjalizacji klienta Recombee
  • Scenario ID – identyfikator scenariusza wyszukiwania
  • Banner ID – identyfikator przypisany do danego rynku / języka (używany w metodach ECDP)
  • Engine ID, Logic ID – stałe wartości do budowania parametru ecdp_recom w URL

Implementacja widgetu#

Widget implementowany jest przy użyciu SDK Recombee: Quick Search Widget (JS) – dokumentacja

npm install @recombee/quick-search-widget-js@0.2.4 recombee-js-api-client

Inicjalizacja klienta#

import { ApiClient } from "recombee-js-api-client";

const apiClient = new ApiClient(DATABASE_ID, PUBLIC_TOKEN, {
  region: REGION,
});

Pobieranie userId#

Do identyfikacji użytkownika w requestach do Recombee należy użyć Visitor ID z ECDP. Dostępne są dwie metody – można użyć jednej z nich lub obudować obie w callback z fallbackiem.

Metoda 1 – przez JS:

$ecdp.helpers.getVisitorId()
// zwraca np. 'b39431c7-23e1-47b1-873c-a5e2629c3f6c'

Metoda 2 – przez cookie vId:

const match = document.cookie
  .split("; ")
  .find(row => row.startsWith("vId="));

const parsed = JSON.parse(decodeURIComponent(match.split("=")[1]));
const userId = parsed?.vId;
// zwraca np. 'b39431c7-23e1-47b1-873c-a5e2629c3f6c'

Obie metody zwracają ten sam Visitor ID. Można je połączyć w jedną funkcję z fallbackiem – najpierw próba przez getVisitorId(), a w razie niedostępności (np. race condition przy ładowaniu skryptu ECDP) odczyt z cookie.

Funkcja createRequest#

Zapytanie do Recombee należy opakować w Batch i użyć dostarczonego SCENARIO_ID. Każdy użytkownik musi być identyfikowany przez userId – dla zalogowanych użytkowników należy użyć ich ID, dla anonimowych wygenerować i utrwalić losowe ID (np. przez PersistentUserID z SDK):

import { Batch, SearchItems } from "recombee-js-api-client";

const createRequest = ({ searchQuery }) => {
  return new Batch([
    new SearchItems(userId, searchQuery, 6, {
      scenario: SCENARIO_ID,
      cascadeCreate: true,
      returnProperties: true,
    }),
  ]);
};

Tracking ECDP – kluczowe wymagania#

Metoda 1 – rejestrowanie requestu rekomendacji#

$ecdp.helpers.registerIncreaseBannerRecommendationAndView(bannerId, count)

Należy ją wywołać po każdym zapytaniu do Recombee – zarówno przy wyszukiwaniu, jak i przy pobieraniu bestsellerów. Rejestruje wykonanie requestu oraz wyświetlenie bannera.

  • bannerId – dostarczony przez ExpertSender
  • count – liczba produktów, o którą odpytano Recombee (np. 6); nie jest to liczba faktycznie zwróconych produktów

⚠️ Wywołanie tej metody jest krytyczne dla poprawnego raportowania w ECDP. Powinna być wywoływana raz na request, nawet jeśli wyniki są cachowane.

Metoda 2 – rejestrowanie samego wyświetlenia#

// Jeden banner
$ecdp.helpers.registerIncreaseBannerView(83)

// Wiele bannerów
$ecdp.helpers.registerIncreaseBannerView([83, 84])

Służy wyłącznie do rejestracji wyświetleń (view) bez requestu rekomendacyjnego.

Pobranie recommId i modyfikacja linków produktowych#

onRecommResponse: (response) => {
  const recommId = response.recommId;
}

recommId jest unikalne dla każdego requestu i musi zostać użyte do zbudowania linków do produktów. Każdy link produktowy w wynikach wyszukiwania musi zawierać dwa parametry:

https://example.com/product
  ?ecdp_recom={engineId}-{logicId}-{recommId}
  &ecdp_banner_click={bannerId}

⚠️ Jeśli recommId zwrócony przez Recombee zawiera suffix po znaku |, należy go usunąć przed użyciem:

1-1-xxxxxx|734  ❌
1-1-xxxxxx      ✅

Obsługa stanów specjalnych#

Otwarcie wyszukiwarki (puste pole) – opcjonalnie#

Istnieje możliwość wyświetlania bestsellerów od razu po kliknięciu w pole wyszukiwania, zanim użytkownik wpisze zapytanie. Jest to opcja dodatkowa – decyzja o jej wdrożeniu leży po stronie klienta. Jeśli ta funkcjonalność zostanie zaimplementowana, request o bestsellery należy zarejestrować w ECDP metodą 1.

Brak wyników#

Gdy props.state.items(0).length === 0:

  1. Wyświetl komunikat o braku wyników dla danego zapytania.
  2. Wykonaj dodatkowy request do Recombee o bestsellery.
  3. Wywołaj registerIncreaseBannerRecommendationAndView dla tego requestu.
  4. Wyświetl alternatywne produkty.

Każdy request (również fallback na bestsellery) musi być osobno zarejestrowany w ECDP.

Checklist wdrożeniowy#

  • Każdy request do Recombee wywołuje registerIncreaseBannerRecommendationAndView
  • Każdy link produktowy zawiera parametry ecdp_recom i ecdp_banner_click
  • recommId w URL nie zawiera suffixu po |
  • Brak wyników generuje osobny request o bestsellery z trackingiem ECDP
  • Otwarcie wyszukiwarki (puste zapytanie) generuje request o bestsellery z trackingiem ECDP (opcjonalnie)
  • Bestsellery mogą być cachowane po stronie frontendu (opcjonalnie)

Model rozliczeniowy#

Wyszukiwarka rozliczana jest wspólnie z rekomendacjami produktowymi w ramach wspólnej puli requestów. Każde wywołanie wyszukiwania generuje 1 request. Wolumen wyszukiwań został uwzględniony w przedstawionej ofercie.

Polityka prywatności