Wdrożenie samodzielne: Frontend PWA – NPM API

W odpowiedzi na oczekiwania naszych klientów, dostarczamy rozwiązanie umożliwiające samodzielne wdrożenie Systemu Rekomendacji Quarticon w e‑sklepie za pomocą NPM – https://www.npmjs.com/ (Node Package Manager).

Paczka ta napisana w JavaScripcie umożliwia wdrożenie Systemu Rekomendacji Quarticon po frontowej stronie aplikacji w bibliotekach, takich jak React, Vue, Angular poprzez użycie ich bezpośrednio w kodzie aplikacji.

Podobnie, jak wdrożenie po API (https://docs.quarticon.com/storeapi/dokumentacja/#tag-Recommendation) to rozwiązanie w całości odbywa się po stronie klienta. Różnica jest taka, że wdrożenie po API z racji niejawnych kluczy dostępowych musi odbyć się po stronie backendu.

Tak, jak pisaliśmy wyżej, wdrożenie poprzez paczkę NPM odbywa się po stronie frontowej aplikacji, podczas ładowania widoku strony w aplikacjach opartych o frameworki React, Vue, Angular. Oczywiście można jej użyć również w w innych frameworkach, ważne, aby wspierały one NPM.

Dokumentacja techniczna tej wtyczki, znajduje się tutaj:

https://docs.quarticon.com/quarticTs/index.html.

Sama zaś wtyczka znajduje się tutaj:

https://www.npmjs.com/package/qon-connection.

Czego potrzebujesz przed rozpoczęciem wdrożenia

CUSTOMER_SYMBOL oraz HOST_URL otrzymasz od swojego opiekuna w QON. Jeśli nie posiadasz konta w naszym systemie albo po prostu masz pytania, skontaktuj się z naszym działem sprzedaży.

Główne założenia wymagane do prawidłowego działania Systemu Rekomendacji Quarticon

  1. Katalog produktów jest niezbędny do tego, aby wyświetlać rekomendacje. Domyślnie katalog odświeżany jest co 24h (najczęściej wykorzystywanym katalogiem jest ten w formacie XML zgodny z Google Merchant).

  2. Przekazywane do nas ID produktów muszą być zgodne z tymi w katalogu produktów.

  3. Aby system uczył się, potrzebujemy informacji dotyczących wszystkich zachowań użytkownika:

    1. wyświetlenia karty produktu (proces implementacji opisany niżej)

    2. kliknięcia w nasze ramki rekomendacyjne (w przypadku korzystania z naszych linków proces zadzieje się automatycznie)

    3. produkty zakupione przez klienta (proces implementacji opisany niżej)

Przykładowa ścieżka zachowania użytkownika na stronie sklepu

  1. Użytkownik wchodzi na stronę główną

    1. na stronie głównej użytkownik widzi ramkę rekomendacyjną pod tytułem np. Wybrane dla Ciebie

  2. Użytkownik wchodzi na kartę produktu

    1. do systemu QON zostaje wysłana informacja o wyświetleniu produktu

  3. Użytkownik klika w ramkę rekomendacji QON wyświetlającą produkty podobne

    1. do systemu QON zostaje wysłana informacja o kliknięciu w produkt

  4. Użytkownik dodaje do koszyka produkt kliknięty z ramki QON

  5. Użytkownik dokonuje zakupu tego produktu

    1. System QON dostaje informację o dokonanej transakcji

W przypadku, gdy zakup został dokonany po kliknięciu w ramkę rekomendacji, produkt ten zostanie potraktowany jako zakup dzięki QON. Każdy zakup dokonany w ciągu 24h od momentu kliknięcia jest traktowany jako zakup z rekomendacji.

Proces implementacji krok po kroku

A. Przygotuj widgety rekomendacyjne

O tym, jakie rekomendacje sprawdzą się na jakich podstronach, poczytasz w artykule Strategie rekomendacji. Wprowadzenie. Opis poszczególnych strategii znajdziesz z kolei w sekcji Strategie rekomendacji.

Aby dodać nowy widget rekomendacji należy przejść do zakładki Rekomendacje i wybrać przycisk Dodaj widget. Zostaniesz przekierowany do edytora, który składa się z czterech etapów:

  1. Wskazanie miejsca dla rekomendacji w sklepie

  2. Wybranie strategii rekomendacji produktów

  3. Kreator drag&drop

  4. Podsumowanie

1. Wskaż miejsce dla rekomendacji w sklepie

Struktura miejsc dla widgetów jest wstępnie zdefiniowana przez nasz system i wygląda następująco:

Wskaż miejsce dla rekomendacji w sklepie

Powyższy układ został przez nas opracowany na bazie wieloletnich doświadczeń z klientami i sprawdzonych przez nas metod. Miejsca widgetów mogą zostać zmodyfikowane przez użytkownika, jednak zalecamy, aby od początku zarządzania rekomendacjami trzymać się określonej hierarchii wyznaczonych miejsc rekomendacji.

Nazwy stron i miejsc na stronach oznaczają wstępnie zakładaną pozycję, w której zostanie wywołany widget rekomendacji. Przykładowo, jeżeli Twoim celem jest dodanie widgetu na karcie produktu pod krótkim opisem produktu, ale przed sekcją dodatkowych informacji o produkcie, zalecamy wykorzystanie placementu STRONA PRODUKTU -> Middle.

Uwaga!

W ramach jednego placementu możesz zdefiniować wiele widgetów rekomendacji. Spowoduje to losowe wybieranie widgetów przy każdorazowym wywołaniu placementu, do którego są przypięte. W zakładce Wskaż miejsce dla rekomendacji w sklepie należy wybrać miejsce w zdefiniowanej strukturze, w którym dany widget ma się pojawić.

2. Wybór strategii rekomendacji

W kolejnej zakładce Wybierz strategię rekomendacji produktu dostępnych jest 12 predefiniowanych strategii rekomendacji. Po najechaniu kursorem na strategię, pojawi się jej krótki opis. Wybierz jedną z nich i zdecyduj, jakie produkty mają zostać wyświetlone użytkownikowi.
​

Poniżej przedstawiamy nasze best practice strategii rekomendacji:

Best practice dotyczące umieszczania ramek rekomendacji

Pamiętaj!

Opisane praktyki nie muszą sprawdzić się u każdego klienta, ponieważ każda branża rządzi się swoimi prawami i może okazać się, że zoptymalizowanie działania silnika rekomendacji w Twoim sklepie wymaga przetestowania innych ustawień. Powyższy schemat jest jedynie propozycją, jesteśmy otwarci na Twoje sugestie.

3. Kreator drag&drop

W przypadku wdrożenia poprzez NPM, kreator nie będzie wykorzystywany, gdyż to Ty decydujesz o wyglądzie swoich rekomendacji. Nazwij swój widget tak, aby wiedzieć gdzie on się znajduje i przejdź do kolejnego etapu, klikając Dalej.

4. Podsumowanie

Sprawdź podsumowanie i zapisz widget.

Podsumowanie ustawień ramek rekomendacji

Powyższe cztery kroki powtórz dla wszystkich widgetów, które chcesz zamieścić na swojej stronie. Widgety można edytować, przesuwać, deaktywować itp. Więcej szczegółów na temat ich edycji znajdziesz w artykule Kreator widgetów.

B. Zaimplementuj wysyłanie informacji o odwiedzinach karty produktu

Zgodnie z instrukcją paczki (https://www.npmjs.com/package/qon-connection), zaimplementuj kod.

Informacja o odwiedzeniu strony powinna zostać do nas wysłana, gdy użytkownik odwiedzi kartę produktu.

Utwórz instancję paczki, stosując otrzymane od nas CUSTOMER_SYMBOL I HOST_URL:

const CUSTOMER_SYMBOL = 'YOUR_CUSTOMER_SYMBOL'
const HOST_URL = 'YOUR_HOST_URL'

const CUSTOMER_CONFIGURATION = new Config.Config({ customerSymbol: CUSTOMER_SYMBOL, host: HOST_URl})

Przekaż obiekt z id produktu, jak poniżej:

const productTracker = new Track.Tracker(CUSTOMER_CONFIGURATION)
productTracker.sendProductView({ id:'PRODUCT_ID' })

Przykład użycia w kodzie VUE:

export default Vue.extend({
 name: 'demopage1',
 data(): DataParams {
 return {
 hostUrl: 'quartic.test',
 customerSymbol: 'twojcustomerSymbol',',
 customerConfiguration: new Config.Config({ customerSymbol: 'this.customerSymbol', host: 'this.hostUrl' }),
 productViewId: '115310',
 }
 },
 mounted() {
 this.sendProductPageView()
 },
 methods: {
 sendProductPageView() {
 const tracker = new Track.Tracker(this.customerConfiguration)
 tracker.sendProductView({ id: this.productViewId })
 },
 },
})

C. Zaimplementuj wysyłanie informacji o zakupach

Wyślij nam informacje o tym, jakie produkty zakupił użytkownik Twojego sklepu.

Ważne, aby wysyłać do systemu Quarticon wszystkie transakcje. Nasz system na podstawie kliknięć w nasze rekomendacje, sam oznaczy zakupione produkty, jako te z naszych rekomendacji. Transakcję wyślij na stronie tzw. Podsumowania/ Podziękowania za transakcję (Thank You Page).

Tak jak wcześniej, utwórz instancję aplikacji:

const CUSTOMER_SYMBOL = 'YOUR_CUSTOMER_SYMBOL'
const HOST_URL = 'YOUR_HOST_URL'

const CUSTOMER_CONFIGURATION = new Config.Config({ customerSymbol: CUSTOMER_SYMBOL, host: HOST_URl})

Następnie przygotuj informacje o zakupionych produktach (przykład dla 2 produktów):

const transaction = {
 transactionId: 'ID_TRANSAKCJI',
 basket: [{
 productId: 'ID_PRODUKTU_1',
 price: 'CENA_PRODUKTU_1',
 quantity: 'ILOSC_PRODUKTU_1'
 }, {
 productId: 'ID_PRODUKTU_2',
 price: 'CENA_PRODUKTU_2',
 quantity: 'ILOSC_PRODUKTU_2'
 }]
}

Pamiętaj, aby productId przekazywane w transakcji pokrywało się z tym, jakie przekazywane jest w katalogu produktowym.

Wyślij transakcję:

// configure tracker
const transactionTracker = new Tracker(CUSTOMER_CONFIGURATION)
// send transaction
transactionTracker.sendTransaction(transaction)

Przykład użycia VUE:

export default Vue.extend({
 name: 'demopage1',
 data(): DataParams {
 return {
 hostUrl: 'quartic.test',
 customerSymbol: 'twojcustomerSymbol', ',
 customerConfiguration: new Config.Config({ customerSymbol: 'this.customerSymbol', host: 'this.hostUrl' }),
 }
 },
 mounted() {
 this.sendProductPageView()
 },
 methods: {

 sendTransaction() {
 const transactionTracker = new Track.Tracker(this.customerConfiguration)

 const transaction = {
 transactionId: 'ID_TRANSAKCJI',
 basket: [{
 productId: 'ID_PRODUKTU_1',
 price: 'CENA_PRODUKTU_1',
 quantity: 'ILOSC_PRODUKTU_1'
 }, {
 productId: 'ID_PRODUKTU_2',
 price: 'CENA_PRODUKTU_2',
 quantity: 'ILOSC_PRODUKTU_2'
 }]
 }
 transactionTracker.sendTransaction(transaction)
 },
 },
})

D. Zaimplementuj ramki rekomendacji na swojej stronie

Aby rozpocząć proces samej implementacji, musisz wybrać widget do implementacji i posiadać jego placementID.

PlacementId to nasz unikalny identyfikator widgetu. Znajdziesz go przechodząc do zakładki Rekomendacje -> Widgety (https://cp.quarticon.com/upseller/myPlacements).

Proces implementacji opiszemy na przykładzie widgetu Wybrane dla Ciebie na stronie głównej:

widget Wybrane dla Ciebie na stronie głównej

Kolorem zaznaczyliśmy jego placementId – to właśnie jego potrzebujemy do implementacji. Nasz placementId to: _qS_2tj3o.

Widget umieścimy na stronie głównej, zatem nie będziemy używać dostępnych w paczce opcji filtrowania (więcej o dostępnych możliwościach znajdziesz tutaj).

Tak, jak wcześniej, tworzymy instancję aplikacji:

const CUSTOMER_SYMBOL = 'YOUR_CUSTOMER_SYMBOL'
const HOST_URL = 'YOUR_HOST_URL'

const CUSTOMER_CONFIGURATION = new Config.Config({ customerSymbol: CUSTOMER_SYMBOL, host: HOST_URl})

a następnie instancję silnika rekomendacji, przekazując CUSTOMER_CONFIGURATION:

const recommendationEngine = new Recommendation.Recommendation(CUSTOMER_CONFIGURATION )

Teraz przygotujemy konfigurację samego widgetu:

const homePageWidget1= {
 placementId: '_qS_2tj3o',// tu użyliśmy naszego placementId
 filters: []
}

Ponieważ nie filtrujemy ramki, przekazujemy pustą tablicę.

Teraz należy wywołać silnik, który zwróci nam produkty. Należy zwrócić uwagę, że jest to funkcja asynchroniczna, wymagając użycia await. 

const homePageRecomendations = await recommendationEngine.getRecommendation(homePageWidget1)

constole.log (homePageRecomendations)

Użyty tu console.log wyświetli nam produkty rekomendowane dla użytkownika. Teraz wystarczy, że produkty te zostaną opakowane w html i umieszczone na stronie. Nasze API w odpowiedzi zwraca zestaw danych o produkcie:

  • _id – identyfikator produktu

  • _pageUrl – link do produktu z kodem trackującym Quarticon

  • _imageUrl – link do zdjęcia produktu

  • _price – aktualna cena produktu (pobrana z wgranego do Quarticon katalogu produktu)

  • _priceOld – stara cena produktu (pobrana z wgranego do Quarticon katalogu produktu)

  • _title – nazwa produktu

  • _custom.name – nazwa dodatkowego pola produktu

  • _custom.value – wartość dodatkowego pola produktu

Pamiętaj! Tworząc ramkę rekomendacji w oparciu o zwracane dane, koniecznie jako link do danego produktu wstaw _pageUrl znajdujący się w odpowiedzi. Inaczej system rekomendacji nie będzie rejestrował kliknięć w ramkę i – tym samym – raportował ich skuteczności w panelu oraz uczył algorytmów AI, a to ma wpływ na jakość i skuteczność prowadzonych przez Ciebie działań!
Wybrane dla Ciebie, przykład 2

Pamiętaj, że integrując się poprzez paczkę NPM, to, jak będą wyglądały wigdety, zależy od Ciebie. Możesz zdecydować, aby każdy widget wyglądał inaczej lub, odwzorowując swoje widgety na stronie, odwzorować je w taki sposób, że nie będą niczym różniły się od natywnych widgetów znajdujących się na stronie. Tytuły Twoich ramek również zależą od Ciebie, dlatego wdrażając się w ten sposób, masz największą swobodę podczas wdrożenia.

E. Zaimplementuj ramki rekomendacji na pozostałych stronach

Sposób implementacji na innych stronach jest taki sam, jak w powyższym przykładzie.

Różnice są natomiast w użytym filtrowaniu. Rekomendujemy poniższy sposób implementacji:

  • Strona kategorii, podkategorii, marki

    • przekaż do konfiguracji widgetu Filtr kategorii:

      • filters: [Recommendation.FilterApi.category('idkategorii')] – aby zawęzić wyświetlane produkty do jednej kategorii

      • filters: [Recommendation.FilterApi.category('idkategorii1'), Recommendation.FilterApi.category('idkategorii2')] – aby zawęzić wyświetlane produkty do więcej niż jednej kategorii

  • Strona produktu, koszyka

    • przekaż do konfiguracji widgetu ID oglądanego produktu/produktów, które znajdują się w koszyku

      • filters: [Recommendation.FilterApi.product('ID _PRODUKTU_OGLADANEGO')] – przykład dla strony produktu

      • filters: [Recommendation.FilterApi.product('ID _PRODUKTU_W_KOSZYKU1)'), Recommendation.FilterApi.product('ID _PRODUKTU_W_KOSZYKU2')] – przykład dla koszyka i dwóch produktów

  • Opcjonalnie możesz dodać filtr ceny:

    • Recommendation.FilterApi.minPrice('30') – np. jeśli chcesz wyświetlać produkty nie tańsze niż 30

    • Recommendation.FilterApi.maxPrice('70') – np. jeśli chcesz wyświetlić produkty nie droższe niż 70

By rekomendacje