nopCommerce Dokumentace

Google AI Commerce Search

Google AI Commerce Search je služba Google pro vyhledávání produktů poháněná umělou inteligencí. Rozumí tomu, co nakupující skutečně hledá, a vrací nejrelevantnější produkty z vašeho katalogu, což zlepšuje relevanci vyhledávání a v důsledku toho i konverze a průměrnou hodnotu objednávky.

V nopCommerce je integrace implementována jako plugin Google AI Commerce Search (systémový název AIRecommendation.GoogleAI), který je k dispozici od nopCommerce 5.00. Plugin patří do skupiny Doporučování pomocí AI (AI-powered recommendation).

Jak to funguje

  • Plugin importuje váš katalog produktů do katalogu Google Cloud (projekt → umístění → katalog → větev) prostřednictvím Retail API.
  • Po importu dat Google katalog sestaví a zaindexuje a vyhledávač vrací ID produktů seřazená podle relevance pro zadaná klíčová slova.
  • Změny produktů provedené v nopCommerce se do Google odesílají okamžitě, takže index zůstává aktuální bez nutnosti ručních opakovaných importů.
  • Výsledky vyhledávání vrácené službou Google se mapují zpět na produkty nopCommerce. nopCommerce znovu uplatní svá vlastní omezení (publikované produkty, data dostupnosti, mapování na obchody, seznamy řízení přístupu, cenové rozpětí) a zobrazí produkty v pořadí vráceném službou Google, takže nakupující vidí řazení Google nad standardním vyhledáváním nopCommerce.
  • Kategorie, výrobci, štítky produktů a filtry atributů specifikace vybrané nakupujícím se předávají službě Google jako filtry vyhledávání, takže filtrování provádí přímo vyhledávač.
  • Google používá ID návštěvníka k personalizaci a přeřazení výsledků. Plugin předává jako ID návštěvníka hodnotu cookie _ga (Google Analytics), proto je vyžadován plugin Google Analytics.

Poznámka

Poskytovatel doporučování pomocí AI se používá pouze pro vyhledávání produktů podle klíčových slov, tj. pro rozbalovací seznam automatického doplňování ve vyhledávacím poli a pro stránku výsledků vyhledávání. Ostatní seznamy produktů nejsou ovlivněny.

Předpoklady

Před instalací pluginu připravte integraci na straně Google Cloud:

  1. Povolte pro svůj projekt Google Cloud Retail API.
  2. Vytvořte katalog s výchozí větví (plugin pracuje s jedním katalogem a jednou větví).
  3. Vytvořte servisní účet a udělte mu roli potřebnou pro práci s Retail API (pro úplnou synchronizaci stačí Retail Editor; Retail Viewer lze použít, pokud katalog importuje jiný nástroj, např. BigQuery).
  4. Vytvořte pro servisní účet klíč JSON a stáhněte jej.

Autorizace nopCommerce

Autorizaci zajišťuje Identity and Access Management (IAM) a plugin podporuje Application Default Credentials (ADC), díky čemuž může stejný kód běžet ve vývojovém i produkčním prostředí. Nejspolehlivějším způsobem, jak pro tuto integraci nakonfigurovat ADC, je použít klíč servisního účtu.

Zkopírujte stažený soubor klíče JSON na svůj server (například do adresáře /etc/gcloud/) a nastavte na něj proměnnou prostředí GOOGLE_APPLICATION_CREDENTIALS:

  • Linux (terminál nebo spouštěcí skript .bashrc):

    export GOOGLE_APPLICATION_CREDENTIALS="/etc/gcloud/your-service-account-key.json"
    
  • Windows (PowerShell, rozsah počítače):

    [System.Environment]::SetEnvironmentVariable('GOOGLE_APPLICATION_CREDENTIALS', 'C:\gcloud\your-service-account-key.json', 'Machine')
    
  • Docker (předejte proměnnou a připojte soubor klíče):

    docker run -e GOOGLE_APPLICATION_CREDENTIALS=/app/key.json -v /etc/gcloud/your-service-account-key.json:/app/key.json my-retail-app
    

Poté aplikaci restartujte, aby se nová proměnná prostředí načetla.

Instalace pluginu

  1. Přejděte do Konfigurace → Místní pluginy (Configuration → Local plugins).
  2. V poli Název pluginu (Plugin name) vyhledejte Google AI Commerce Search. Plugin patří do skupiny Doporučování pomocí AI a vyžaduje plugin Google Analytics.
  3. Klikněte na tlačítko Instalovat (Install).
  4. Kliknutím na tlačítko Restartovat aplikaci pro použití změn (Restart application to apply changes) změny použijete.
  5. Na stránce podrobností pluginu zaškrtněte políčko Povoleno (Enabled), aby se plugin stal aktivním poskytovatelem doporučování pomocí AI. Aktivní může být vždy pouze jeden poskytovatel doporučování pomocí AI.

Poznámka

Při instalaci plugin povolí nastavení médií Použít absolutní cestu k obrázkům (Use absolute image path), které je nutné pro předávání absolutních URL obrázků produktů službě Google, a vyplní výchozí hodnoty konfigurace: umístění global, katalog default_catalog a větev default_branch.

Konfigurace pluginu

Chcete-li plugin nakonfigurovat, přejděte do Konfigurace → Místní pluginy a klikněte na Konfigurovat (Configure) vedle Google AI Commerce Search.

Google AI Commerce Search

Konfigurační stránka popisuje, jak funguje autorizace Google Cloud, a poskytuje následující nastavení:

  • Enabled (Povoleno) — zapnutí nebo vypnutí pluginu. Je-li vypnut, plugin nesynchronizuje data se službou Google ani nevrací výsledky vyhledávání.
  • Project ID — ID projektu Google Cloud, kterému katalog patří.
  • Location ID — ID umístění (regionu) katalogu v Google Cloud, například global.
  • Catalog ID — ID katalogu v Google Cloud.
  • Branch ID — ID větve v Google Cloud, do které se odesílají data produktů.
  • Sync Allowed (Synchronizace povolena) — zapnutí nebo vypnutí synchronizace dat produktů se službou Google. Vypněte ji, pokud váš katalog importuje jiný nástroj (například BigQuery) nebo pokud chcete Google používat pouze pro vyhledávání.
  • Search Allowed (Vyhledávání povoleno) — zapnutí nebo vypnutí vyhledávání produktů prostřednictvím Google.
  • Log Requests (Protokolovat požadavky) — zapnutí nebo vypnutí protokolování požadavků odesílaných službě Google. Užitečné pro ladění a testování; požadavky se zapisují do souboru protokolu nopCommerce.

Všechny čtyři identifikátory (projekt, umístění, katalog a větev) jsou povinné a musí odpovídat hodnotám v konzoli Google Cloud.

Kliknutím na Uložit (Save) uložíte změny.

Import katalogu

Chcete-li do Google importovat celý katalog, klikněte na tlačítko Synchronizovat katalog nyní (Sync catalog now). Ke spuštění této akce musíte povolit nastavení Sync Allowed a mít udělené oprávnění Upravovat produkty (Edit products).

Plugin produkty převede a importuje je v dávkách (500 produktů na požadavek), poté zobrazí oznámení s počtem úspěšně importovaných produktů a počtem selhání. Výsledek importu se také zapisuje do protokolu nopCommerce.

Importují se pouze publikované produkty a zohledňuje se mapování na obchody a seznamy řízení přístupu.

Každý produkt se odesílá s následujícími daty:

  • ID — SKU produktu, nebo ID produktu, pokud je SKU prázdné.
  • Type (Typ) — Primary pro běžné produkty a Variant pro kombinace atributů produktu a varianty seskupených produktů.
  • Primary product ID (ID primárního produktu) — SKU (nebo ID) nadřazeného produktu u variant.
  • Name (Název), GTIN, URL, kód jazyka — použije se kód jazyka výchozího jazyka administrace.
  • Title (Titulek) — krátký popis produktu (až 1 000 znaků).
  • Description (Popis) — úplný popis produktu (až 5 000 znaků).
  • Price (Cena) — cena produktu (u varianty přepsaná cena) v primární měně obchodu.
  • Availability (Dostupnost) — IN_STOCK, OUT_OF_STOCK nebo BACKORDER, vypočteno v závislosti na způsobu správy zásob a skladovém množství.
  • Rating (Hodnocení) — průměrné hodnocení a počet schválených recenzí produktu.
  • Categories (Kategorie) — úplná cesta kategorie (např. Sports & Fitness > Athletic Clothing > Shoes). Úplné cesty Google důrazně doporučuje pro lepší kvalitu vyhledávání a doporučení.
  • Brands (Značky) — názvy výrobců.
  • Attributes (Atributy) — atributy specifikace a názvy jejich možností.
  • Tags (Štítky) — štítky produktu.
  • Images (Obrázky) — obrázek produktu; u variant se použije první obrázek kombinace.

Synchronizace změn produktů

Když jsou povolena obě nastavení Enabled i Sync Allowed a plugin je aktivním poskytovatelem doporučování pomocí AI, plugin automaticky udržuje Google aktuální:

  • vytvořený produkt nebo kombinace atributů produktu se odešle do Google;
  • aktualizovaný produkt nebo kombinace atributů produktu se aktualizuje v Google;
  • odstraněný produkt nebo kombinace atributů produktu se z Google odebere.

Pokud jsou tato nastavení vypnuta nebo je aktivní jiný poskytovatel doporučování pomocí AI, neodesílají se žádné požadavky a můžete se místo toho spolehnout na úplný import katalogu.

Vyhledávání ve veřejném obchodě

Když jsou povolena obě nastavení Enabled i Search Allowed, vyhledávání produktů podle klíčových slov ve veřejném obchodě obsluhuje Google:

  • Klíčová slova zadaná nakupujícím se odesílají do umístění default_search nakonfigurovaného katalogu a větve.
  • Filtry kategorií, výrobců, štítků produktů a atributů specifikace se převádějí do syntaxe filtrů Retail API.
  • ID návštěvníka se přebírá z cookie _ga, takže výsledky mohou být personalizovány. Ujistěte se, že plugin Google Analytics je nainstalován a nakonfigurován a že jeho cookie není pro váš obchod blokována.
  • Velikost stránky vyhledávání je omezena na 120 produktů na požadavek (maximum povolené Retail API).
  • Vrácená ID produktů nebo SKU se mapují zpět na produkty nopCommerce; duplicitní položky (například několik variant téhož produktu) se sloučí do jediného produktu.
  • Pokud Google pro zadaná klíčová slova nevrátí žádné produkty nebo požadavek selže, nopCommerce se vrátí ke standardnímu vyhledávání produktů, takže nakupující přesto dostanou výsledky.

Důležité

Google vrací výsledky pouze pro produkty, které již byly importovány do katalogu a zaindexovány. Po úvodní konfiguraci spusťte Synchronizovat katalog nyní a udržujte katalog synchronizovaný, jinak nakupující nemusí dostávat žádné výsledky poháněné AI.

Řešení problémů

  • Žádné výsledky vyhledávání — ujistěte se, že katalog byl importován, nastavení Enabled a Search Allowed jsou povolena a plugin je aktivním poskytovatelem doporučování pomocí AI. Mějte na paměti, že když Google nic nevrátí, nopCommerce se vrátí ke standardnímu vyhledávání.
  • Chyby ověřování — ověřte, že proměnná prostředí GOOGLE_APPLICATION_CREDENTIALS je nastavena pro účet, pod kterým aplikace běží, že soubor klíče je čitelný a že aplikace byla po změně proměnné restartována.
  • Chyby odepření oprávnění — ujistěte se, že servisní účet má požadovanou roli Retail API a že je pro projekt povoleno Retail API.
  • Prázdné nebo nerelevantní výsledky — zlepšete zdrojová data: na řazení mají vliv úplné cesty kategorií, štítky produktů, atributy specifikace, obrázky, ceny i dostupnost.
  • Ladění — povolte nastavení Log Requests a v protokolu nopCommerce zkontrolujte požadavky odeslané službě Google.

Další informace

Přispěvatelé: DmitriyKulagin
Upravit na GitHubu