Feedy produktowe

Feed produktowy, który potrzebny jest do działania systemu, jest zgodny ze standardowym feedem dla Google Shopping. Wystarczy podać adres url, pod którym znajduje się feed, aby rozpoczęła się synchronizacja danych. Akceptujemy zarówno zwykłe pliki XML, jak i skompresowane gzip - należy wtedy podać URL kończący się na .gz.

Poniżej listujemy opcjonalne oraz wymagane atrybuty dla feedu produktowego. Dodatkowo załączamy przykładowy feed zawierający jeden produkt — stanowi dobry punkt wyjścia przy tworzeniu docelowego feedu.

Atrybuty wymagane i opcjonalne dla produktów

Zakładamy, że namespace XML dla Google jest nazwany g (dodane xmlns:g="http://base.google.com/ns/1.0" na górze pliku), a dla AdsHero ah (dodane xmlns:ah="http://adshero.io/ns/1.0" na górze pliku).

Lista atrybutów:

Nazwa pola	Opis	Format	Wymagane	Wskazówki
`g:id`	Unikalny kod produktu lub oferty	Maksymalnie 50 znaków	Tak	Kod SKU powinien być unikalny dla każdego produktu. Jeśli ten sam produkt jest sprzedawany przez wielu sprzedawców (`g:external_seller_id`), to `g:id` jest unikalnym identyfikatorem oferty, a do identyfikacji produktu wykorzystaj `ah:product_id`. Utrzymuj ten sam kod podczas aktualizacji danych.
`ah:product_id`	Unikalny kod produktu	Maksymalnie 128 znaków	Nie	Identyfikator produktu, jeśli `g:id` jest wykorzystywane jako identyfikator oferty (w przypadku gdy ten sam produkt może być sprzedawany przez wielu sprzedawców). Utrzymuj ten sam kod podczas aktualizacji danych.
`g:title`	Nazwa produktu	Maksymalnie 300 znaków	Tak	Dokładnie opisuje Twój produkt i pasuje do tytułu w Twoim sklepie. Nie umieszczaj w tytule informacji promocyjnych ani o wysyłce.
`g:description`	Opis produktu	Maksymalnie 5000 znaków	Nie	Wymień cechy produktu, specyfikacje techniczne i atrybuty wizualne. Szczegółowy opis pomoże nam pokazać Twój produkt odpowiednim klientom.
`g:link`	Link do produktu w sklepie	URL	Tak	Użyj linku ze swojej domeny. Zacznij od `http://` bądź `https://`.
`g:image_link`	URL do głównego obrazka produktu	URL	Tak	Do linku obrazka: Linkuj do głównego zdjęcia produktu. Zacznij od `http://` bądź `https://`. Do obrazka: Pokaż dokładnie produkt, który sprzedajesz. Użyj jednego z formatów: JPEG (.jpg/.jpeg), WebP (.webp), PNG (.png), GIF bez animacji (.gif), BMP (.bmp), and TIFF (.tif/.tiff)
`g:availability`	Dostępność produktu	Enum: `in stock` `out of stock`	Tak	Podaj dostępność swojego produktu zgodną z dostępnością produktu w Twoim sklepie.
`g:price`	Cena produktu.	Wartość pieniężna: Numeryczna, z kropką jako separator dziesiętny. Waluta zgodna z ISO-4217	Tak	Dokładnie podaj cenę i walutę produktu zgodną z ceną w Twoim sklepie. Upewnij się, że cena produktu jest w walucie zgodną z krajem docelowym.
`g:sale_price`	Cena promocyjna produktu.	Wartość pieniężna: Numeryczna, z kropką jako separator dziesiętny. Waluta zgodna z ISO-4217	Nie	Dokładnie podaj cenę promocyjną i walutę produktu zgodną z ceną w sklepie.
`g:google_product_category`	Zdefiniowana przez Google kategoria Twojego produktu.	Wartość z taksonomii produktów Google: Numeryczny identyfikator kategorii (ID) lub Pełna ścieżka kategorii	Nie	Uwzględnij tylko jedną kategorię. Uwzględnij najbardziej odpowiednią kategorię. Uwzględnij albo pełną ścieżkę kategorii albo ID kategorii - nie używaj obydwu wartości jednocześnie.
`g:product_type`	Kategoria produktu, którą definiujesz dla swojego produktu.	Maksymalnie 750 znaków alfanumerycznych.	Nie	Uwzględnij pełną kategorię produktu, czyli aż do najniższego rzędu. Kategorie powinny być rozdzielone znakiem: >, np. `Zdrowie > Witaminy > Witamina C`
`g:brand`	Nazwa marki Twojego produktu.	Maksymalnie 70 znaków.	Nie	Podaj markę produktu, którą powszechnie znają konsumenci. Podanie właściwej marki wpływa pozytywnie na doświadczenia zakupowe konsumentów i zapewnia lepsza wyniki. Jeśli sprzedajesz produkty marki własnej uzupełnij to pole wpisując nazwę swojej marki. Jeśli produkt nie ma marki, pozostaw to pole puste.
`g:gtin`	Globalny Numer Jednostki Handlowej (GTIN) Twojego produktu.	W Europie będzie to EAN (GTIN-13): 13-cyfrowy numer	Nie	Wyklucz myślniki i spacje. Przesyłaj tylko ważne i poprawne numery GTIN. Jeśli produkt nie ma numeru GTIN nie zgaduj i nie twórz go samodzielnie.
`g:MPN`	Unikalny numer identyfikujący produkt.	Maksymalnie 70 znaków alfanumerycznych.	Nie	Uwzględnij tylko numery MPN określone przez producenta. Użyj najbardziej szczegółowego numeru MPN dla produktu (różny kolor, różny MPN). Podanie prawidłowego numeru MPN sprawia, że reklama będzie lepiej dopasowana do konsumenta. Jeśli nie znasz numeru MPN, nie podawaj go i zostaw to pole puste.
`g:shipping`	Koszt i czas dostawy produktów oraz kraje, do których wysyłasz produkty.	Dodatkowo możesz ustawić atrybuty podrzędne, czyli: `country` `region` `price` `min_handling_time` `max_handling_time` `min_transit_time` `max_transit_time`	Nie
`g:unit_pricing_measure`	Miara ceny jednostkowej	Przykład `2.5 kg` Obsługiwane jednostki: Waga: `oz`, `lb`, `mg`, `g`, `kg` Objętość (miary amerykańskie/imperialne): `floz`, `pt`, `qt`, `gal` Objętość (miary metryczne): `ml`, `cl`, `l`, `cbm` Długość: `in`, `ft`, `yd`, `cm`, `m` Powierzchnia: `sqft`, `sqm` Za jednostkę: `ilość`	Nie	Atrybut określa miarę i rozmiar produktu bez opakowania wysyłkowego.
`g:adult`	Atrybut określa, czy produkt jest przeznaczony dla osób dorosłych..	Przykład: `yes` Obsługiwane wartości: `yes` `no`	Nie	Użyj atrybutu yes dla produktów, które są przeznaczone tylko dla dorosłych, np. nagość, treści erotyczne.
`g:energy_efficiency_class`	Klasa efektywności energetycznej	Przykład `A+++` Maksymalnie 10 znaków.	Nie	Dołącz prawnie wymaganą etykietę energetyczną.
`g:age_group`	Grupa wiekowa określająca grupę demograficzną, dla której jest produkt.	Przykład `kids` Maksymalnie 100 znaków.	Nie	Uwzględnij tylko jedną wartość na produkt.
`g:color`	Kolor Twojego produktu.	Przykład `White` Maksymalnie 100 znaków alfanumerycznych (40 znaków na jeden kolor).	Nie
`g:gender`	Płeć, dla której jest przeznaczony produkt.	Przykład `Unisex` Maksymalnie 10 znaków.	Nie
`g:material`	Materiał z jakiego jest wykonany produkt.	Przykład `Leather` Maksymalnie 200 znaków opisujących materiał.	Nie	Dodaj informację z jakiego materiału/materiałów wykonany jest Twój produkt. Jeśli wskazujesz więcej niż jeden materiał zapisz to w taki sposób: `”cotton/polyester/elastane”`
`g:pattern`	Wzór lub nadruk graficzny produktu.	Przykład `striped` `paisley` Maksymalnie 100 znaków.	Nie
`g:size`	Rozmiar produktu.	Przykład `XS` Maksymalnie 100 znaków.	Nie
`g:product_detail`	Dane techniczne lub dodatkowe szczegóły produktu.	Posiada pola: `attribute_name`: Nazwa atrybutu, wymagane, do 140 znaków, np. `Rozdzielczość` `attribute_value`: Wartość atrybutu, wymagane, do 1000 znaków, np. `432 x 240` `section_name`: Kategoria do której należy atrybut, opcjonalne, do 140 znaków, np. `Wyświetlacz` Pole można podać wielokrotnie z różnymi wartościami, maksymalnie 50 razy.	Nie	Nie umieszczaj tutaj informacji, które zawarte są w innych atrybutach.
`g:item_group_id`	Atrybut służy do grupowanie unikalnych produktów.	Pole tekstowe	Nie	Dla pojedynczego zapytania o reklamę nie zostanie zwrócona więcej niż jedna reklama z tej samej grupy.
`g:external_seller_id`	Zewnętrzne ID sprzedawcy.	Pole tekstowe	Nie	Jeśli to pole jest uzupełnione, wymagane jest uzupełnienie pola `external_seller_name`.
`ah:external_seller_name`	Zewnętrzna nazwa sprzedawcy.	Pole tekstowe	Nie	Jeśli to pole jest uzupełnione, wymagane jest uzupełnienie pola `external_seller_id`.
`g:deep_link`	Link do produktu w aplikacji mobilnej.	URI	Nie	Zacznij od `http://`, `https://` bądź `myapp://`.
`g:certification`	Certyfikaty produktu, zgodność z przepisami lub standardy branżowe.	Posiada pola: `certification_authority`: Nazwa organu wydającego certyfikat `certification_name`: Nazwa certyfikatu `certification_code`: Unikalny kod lub identyfikator certyfikatu `certification_value`: Wartość lub poziom certyfikatu	Nie	Użyj tego atrybutu, aby wskazać certyfikaty lub informacje o zgodności produktu z normami.
`ah:adshero_label`	Niestandardowe etykiety, które można wykorzystać do własnego grupowania produktów lub zarządzania kampaniami.	Przykład: `onsite` Pole można podać wielokrotnie z różnymi wartościami.	Nie	Te etykiety mogą być używane do niestandardowego filtrowania.

“Produkt” vs “oferta”

Domyślnie feed zawiera produkty. W przypadku sklepów multi-merchant (na platformie sprzedaje wielu sprzedawców i różni sprzedawcy mogą sprzedawać ten sam produkt pod postacią różnych ofert) każdy item w feedzie traktujemy jako pojedynczą ofertę. Efektywnie feed zawiera “oferty”, gdy wypełnione jest pole g:external_seller_id mówiące, do którego sprzedawcy należy oferta.

W przypadku feedu z ofertami g:id musi być unikalne dla każdej oferty. Jeśli wielu sprzedawców sprzedaje ten sam “produkt” (taki sam przedmiot, ale np. w innej cenie), to wypełnić należy opcjonalne pole ah:product_id, które jest identyfikatorem produktu (wiele ofert może mieć taki sam ah:product_id - daje to informacje dla systemu, że kilka ofert reprezentuje taki sam produkt).

Przykładowe feedy

Poniżej znajdują się przykładowe feedy.

Minimalny Feed XML

Zawiera 6 wymaganych pól dla dwóch produktów. Służy do najszybszej weryfikacji połączenia i wdrożenia.

<?xml version="1.0" encoding="utf-8" ?>
<rss version="2.0" xmlns:g="http://base.google.com/ns/1.0" xmlns:ah="http://adshero.io/ns/1.0">
  <channel>
    <g:title>Minimalny Feed Produktowy AdsHero (PrzykladowySklep)</g:title>
    <g:link>https://www.przykladowysklep.pl/</g:link>
    <g:description>Feed z minimalną ilością danych wymaganych do synchronizacji.</g:description>

    <item>
      <g:id><![CDATA[KWA-ZIAR-EKO-1KG]]></g:id>
      <g:title><![CDATA[Kawa ziarnista Arabica Bio, 1 kg]]></g:title>
      <g:link><![CDATA[https://www.przykladowysklep.pl/kawa-arabica-bio-1kg]]></g:link>
      <g:image_link><![CDATA[https://www.przykladowysklep.pl/img/kawa-bio-main.jpg]]></g:image_link>
      <g:availability><![CDATA[in stock]]></g:availability>
      <g:price>79.99 PLN</g:price>
    </item>

    <item>
      <g:id><![CDATA[EXP-AUTO-SILVER]]></g:id>
      <g:title><![CDATA[Automatyczny Ekspres do Kawy Barista Pro X10]]></g:title>
      <g:link><![CDATA[https://www.przykladowysklep.pl/ekspres-barista-x10]]></g:link>
      <g:image_link><![CDATA[https://www.przykladowysklep.pl/img/ekspres-x10-main.jpg]]></g:image_link>
      <g:availability><![CDATA[in stock]]></g:availability>
      <g:price>2499.00 PLN</g:price>
    </item>

  </channel>
</rss>

Maksymalny Feed XML

Zawiera wszystkie możliwe pola dla dwóch produktów.

<?xml version="1.0" encoding="utf-8" ?>
<rss version="2.0" xmlns:g="http://base.google.com/ns/1.0" xmlns:ah="http://adshero.io/ns/1.0">
  <channel>
    <metadata>
      <ref_application_id>101010101010101</ref_application_id>
      <ref_asset_id>PrzykladowySklep.pl-FULL-MAX</ref_asset_id>
    </metadata>
    <g:title>Perfekcyjnie Maksymalny Feed Produktowy PrzykladowySklep</g:title>
    <g:link>https://www.przykladowysklep.pl/</g:link>
    <g:description>Feed wypełniony każdym atrybutem, bez pustych wartości, dla maksymalnej monetyzacji.</g:description>

    <item>
      <g:id><![CDATA[KWA-ZIAR-EKO-1KG-SPRZ1]]></g:id>
      <g:title><![CDATA[Kawa ziarnista Arabica Bio, 1 kg, palona średnio]]></g:title>
      <g:link><![CDATA[https://www.przykladowysklep.pl/kawa-arabica-bio-1kg]]></g:link>
      <g:image_link><![CDATA[https://www.przykladowysklep.pl/img/kawa-bio-main.jpg]]></g:image_link>
      <g:availability><![CDATA[in stock]]></g:availability>
      <g:price>79.99 PLN</g:price>

      <ah:product_id><![CDATA[KWA-ZIAR-EKO-1KG]]></ah:product_id>
      <g:external_seller_id><![CDATA[SPRZEDAWCA-001]]></g:external_seller_id>
      <ah:external_seller_name><![CDATA[Palarnia Kawy Świata]]></ah:external_seller_name>

      <g:description><![CDATA[100% Arabica z etiopskich upraw ekologicznych. Średnio palona, nuty czekolady i orzechów. Idealna do espresso.]]></g:description>
      <g:sale_price>69.99 PLN</g:sale_price>
      <g:google_product_category>129</g:google_product_category>
      <g:product_type><![CDATA[Żywność > Kawa i herbata > Kawa ziarnista]]></g:product_type>
      <g:brand>EcoCoffee</g:brand>
      <g:gtin><![CDATA[7777777777777]]></g:gtin>
      <g:mpn><![CDATA[EC-KZ-AB-1K]]></g:mpn>
      <g:item_group_id><![CDATA[KAWA-ZIARNISTA-SERIES]]></g:item_group_id>
      <g:condition>new</g:condition>
      <g:adult>no</g:adult>

      <g:age_group>adult</g:age_group>
      <g:gender>Unisex</g:gender>
      <g:material>Ziarna Arabica</g:material>
      <g:color>Ciemnobrązowy</g:color>
      <g:pattern>Gładki</g:pattern>
      <g:size>1 kg (opakowanie)</g:size>

      <g:unit_pricing_measure>1 kg</g:unit_pricing_measure>
      <g:energy_efficiency_class>A</g:energy_efficiency_class>
      <g:product_detail>
        <g:section_name>Profil Smakowy</g:section_name>
        <g:attribute_name>Kwasowość</g:attribute_name>
        <g:attribute_value>Niska</g:attribute_value>
      </g:product_detail>
      <g:certification>
        <g:certification_authority>UE</g:certification_authority>
        <g:certification_name>Eko Certyfikat</g:certification_name>
        <g:certification_code>PL-EKO-05-001</g:certification_code>
        <g:certification_value>PL-EKO-05</g:certification_value>
      </g:certification>

      <g:shipping>
        <g:country>PL</g:country>
        <g:region>Mazowieckie</g:region>
        <g:price>11.00 PLN</g:price>
        <g:min_handling_time>1 day</g:min_handling_time>
        <g:max_handling_time>2 days</g:max_handling_time>
        <g:min_transit_time>2 days</g:min_transit_time>
        <g:max_transit_time>4 days</g:max_transit_time>
      </g:shipping>
      <g:deep_link><![CDATA[app://przykladowysklep/product/KWA-ZIAR-EKO-1KG-SPRZ1]]></g:deep_link>
      <ah:adshero_label><![CDATA[premium-eko]]></ah:adshero_label>
      <ah:adshero_label><![CDATA[w-promocji]]></ah:adshero_label>
    </item>

    <item>
      <g:id><![CDATA[EXP-AUTO-SILVER-SPRZ3]]></g:id>
      <g:title><![CDATA[Automatyczny Ekspres do Kawy Barista Pro X10]]></g:title>
      <g:link><![CDATA[https://www.przykladowysklep.pl/ekspres-barista-x10]]></g:link>
      <g:image_link><![CDATA[https://www.przykladowysklep.pl/img/ekspres-x10-main.jpg]]></g:image_link>
      <g:availability><![CDATA[in stock]]></g:availability>
      <g:price>2499.00 PLN</g:price>

      <ah:product_id><![CDATA[EXP-AUTO-BPX10]]></ah:product_id>
      <g:external_seller_id><![CDATA[SPRZEDAWCA-003]]></g:external_seller_id>
      <ah:external_seller_name><![CDATA[AGD Ekspert]]></ah:external_seller_name>

      <g:description><![CDATA[Ekspres ciśnieniowy z wbudowanym młynkiem, 15 barów, system spieniania mleka. Czyszczenie automatyczne.]]></g:description>
      <g:sale_price>2299.00 PLN</g:sale_price>
      <g:google_product_category>502</g:google_product_category>
      <g:product_type><![CDATA[Elektronika > Sprzęt AGD > Ekspresy automatyczne]]></g:product_type>
      <g:brand>BaristaPro</g:brand>
      <g:gtin><![CDATA[1234567890123]]></g:gtin>
      <g:mpn><![CDATA[BPX10-SILVER-EU]]></mpn>
      <g:item_group_id><![CDATA[BARISTAPRO-X10-SERIES]]></g:item_group_id>
      <g:condition>new</g:condition>
      <g:adult>no</g:adult>

      <g:age_group>adult</g:age_group>
      <g:gender>Unisex</g:gender>
      <g:material>Stal nierdzewna / Tworzywo sztuczne</g:material>
      <g:color>Srebrny</g:color>
      <g:pattern>Gładki</g:pattern>
      <g:size>Kompaktowy</g:size>

      <g:unit_pricing_measure>1 szt.</g:unit_pricing_measure>
      <g:energy_efficiency_class>A+++</g:energy_efficiency_class>
      <g:product_detail>
        <g:section_name>Parametry Techniczne</g:section_name>
        <g:attribute_name>Ciśnienie</g:attribute_name>
        <g:attribute_value>15 barów</g:attribute_value>
      </g:product_detail>
      <g:certification>
        <g:certification_authority>TÜV</g:certification_authority>
        <g:certification_name>Bezpieczeństwo Elektryczne</g:certification_name>
        <g:certification_code>TUV-EXP-2024</g:certification_code>
        <g:certification_value>Zgodny z normą IEC</g:certification_value>
      </g:certification>

      <g:shipping>
        <g:country>PL</g:country>
        <g:region>Łódzkie</g:region>
        <g:price>0.00 PLN</g:price>
        <g:min_handling_time>1 day</g:min_handling_time>
        <g:max_handling_time>1 day</g:max_handling_time>
        <g:min_transit_time>1 day</g:min_transit_time>
        <g:max_transit_time>2 days</g:max_transit_time>
      </g:shipping>
      <g:deep_link><![CDATA[app://przykladowysklep/product/EXP-AUTO-SILVER-SPRZ3]]></g:deep_link>
      <ah:adshero_label><![CDATA[premium-agd]]></ah:adshero_label>
      <ah:adshero_label><![CDATA[darmowa-dostawa]]></ah:adshero_label>
    </item>

  </channel>
</rss>

Dodatkowy feed

Podczas konfiguracji feeda produktowego można podać URL do dodatkowego feeda. Dodatkowy feed zawiera dokładnie te same dane co podstawowy, ale nie posiada g:id - zamiast tego jest tylko ah:product_id. Można go wykorzystać, gdy główny feed ma bardzo duży rozmiar i dane między ofertami (np. g:description) często się powtarzają.

Gdy dodatkowy feed jest skonfigurowany, to Adshero będzie go pobierać razem z głównym feedem i uzupełni dane o ofertach/produktach z głównego feedu na podstawie danych z feedu dodatkowego (dopasowanie jest po ah:product_id).

Oprócz redukcji rozmiaru feed-a pozwala to także generować te pliki w różnym tempie (np. dane o cenie i stocku co godzinę, a opis produktu, tytuł, raz dziennie).

Tworzenie feedów produktowych za pomocą API

🛡

To API jest zabezpieczone — w requestach w nagłówku Authorization należy przekazać token dostępowy.

Domyślną ścieżką wgrywania feedów do AdsHero jest ich utworzenie w panelu. Poza szczególnymi przypadkami nie musisz używać tego API.

POST https://api.adshero.io/v1/feed/ HTTP/2
Authorization: Bearer {access_token}
Content-Type: application/json

{
  "name": "string",
  "url": "string",
  "shopId": "string",
  "currency": "string",
  "lang": "string"
}

curl --location --request POST 'https://api.adshero.io/v1/feed/' \
    --header 'Authorization: Bearer {access_token}' \
    --header 'Content-Type: application/json' \
    --data '{ 
      "name": "string", 
      "url": "string", 
      "shopId": "string", 
      "currency": "string", 
      "lang": "string"
    }'

Znaczenie parametrów:

name: Nazwa feedu widoczna w panelu.
url: URL do feedu — pod tym adresem oczekujemy pliku XML z feedem.
shopId: Identyfikator sklepu. Dostępny jest w panelu wydawcy (sklepu) w ustawieniach konta.
currency: Waluta feedu zgodna z ISO-4217.
lang: Język feedu zgodny z ISO-639-1 (dwuliterowe kody języków).