Wprowadzenie

Cel Integracji

Celem integracji z platformą OnetAds jest umożliwienie sklepom internetowym efektywnego wykorzystania różnych rodzajów reklam, takich jak Promo Bannery czy Sponsored Products. Integracja ta pozwala na dostosowanie i wyświetlanie reklam w odpowiednich miejscach na stronie sklepu, zwiększając zasięg i angażowanie klientów. Dodatkowo, zapewnia sklepom dodatkowy kanał przychodowy.

🚧
Ważne
Wszystkie pokazywane reklamy na sklepie przekierowują wyłącznie w ramach domeny sklepu.

Ogólny Przegląd Integracji

Integracja z platformą OnetAds jest procesem, który składa się z kilku kluczowych etapów:

Weryfikacja Sklepu: Upewnienie się, że sklep spełnia wszystkie techniczne i biznesowe wymagania. Witryna sklepu powinna być utworzona w panelu OnetAds
Konfiguracja Skryptu Ad & Pixel: Ustawienie odpowiednich skryptów i parametrów, aby umożliwić wyświetlanie reklam, dodatkowo ten sam skrypt odpowiedzialny jest za zbieranie informacji o konwersjach.
Aktywny Feed produktowy: Witryna musi posiadać feed produktowy z całym udostępnionym asortymentem sklepu. Więcej na temat feedu produktowego możesz przeczytać Specyfikacja plików XML
Umieszczanie Reklam: Wybór typów reklam i umieszczenie ich w odpowiednich miejscach na stronie.
Testowanie i Walidacja: Sprawdzenie, czy reklamy wyświetlają się prawidłowo i osiągają zamierzone cele.
Monitorowanie i Optymalizacja: Analiza wyników i dostosowanie strategii reklamowej w razie potrzeby.

Typy Reklam i Ich Zastosowanie

Platforma OnetAds oferuje różne typy reklam, które można wykorzystać w ramach integracji

Promo Banner

Banery reklamowe, które mogą być umieszczone na wszystkich stronach sklepu. Przykładowy banner wertykalny <https://www.skapiec.pl/budowa-i-remont.html#adbeta=l495447!slot.right>

Przykładowy podgląd na stronie skapiec.pl dla rozmiaru 300x600

Poniższa tabela zawiera podglądy Promo Banner bezpośrednio na witrynie skapiec.pl. Linki mają charakter poglądowy, docelowo Promo Banner dostosowuje się do wielkości miejsca udostępnionego przez witrynę sklepu.

Rozmiar [px]	Podgląd na stronie skapiec.pl
300x250	`<https://www.skapiec.pl/sub/125-akcesoria-do-biegania.html#adbeta=l495451!slot.right>`
750x200	`<https://www.skapiec.pl/sub/125-akcesoria-do-biegania.html#adbeta=l495448!slot.top>`
950x300	`<https://www.skapiec.pl/sub/125-akcesoria-do-biegania.html#adbeta=l495449!slot.top>`
1260x350	`<https://www.skapiec.pl/sub/125-akcesoria-do-biegania.html#adbeta=l495450!slot.top>`
300x600	`<https://www.skapiec.pl/sub/125-akcesoria-do-biegania.html#adbeta=l495447!slot.right>`

Sponsored Product

Reklamy produktów sponsorowanych, które mogą być wyświetlane w wynikach wyszukiwania lub na stronach kategorii, na stronie detalu produktu. Pozwalają na wyróżnienie konkretnych produktów i zwiększenie ich widoczności.

Każdy z tych typów reklam może być dostosowany do indywidualnych potrzeb sklepu, umożliwiając tworzenie spersonalizowanych i skutecznych kampanii reklamowych.

Typy podstron sklepu

Strona główna: main
Strona kategorii: listing
Strona wyników wyszukiwania: search
Strona detalu produktowego: product_card
Inne typy stron: other

Rozpoczęcie Pracy

Konfiguracja Skryptu Ad & Pixel

Na każdej stronie sklepu w nagłówku (tzn. przed zamknięciem znacznika </head>) osadź następujący kod:

<script type="text/javascript">
  dlApi = {
    cmd: [], // Tablica działająca jako kolejka asynchronicznych zadań, pozwalająca na wywoływanie funkcji SDK przed załadowaniem skryptu minit.boot.min.js

    autoslot: 1 // Skanuje dokument DOM i automatycznie inicjalizuje zapytania o reklamy posiadające atrybut data-slot="rmn-promo-banner"
  };
</script>
<script src="https://lib.onet.pl/s.csr/build/dlApi/minit.boot.min.js" async></script>

Więcej o samym skrypcie możesz przeczytać w sekcji Ad & Pixel.

🚧
Ważne
Jeżeli na stronie Twojego sklepu już wcześniej był osadzony skrypt Ad & Pixel albo Pixel only, najpierw go usuń, a dopiero potem dodaj powyższy kod.

Krok po Kroku: Integracja Reklam

Promo Banner

Opcja 1 – integracja automatyczna

Sprawdź, czy nie masz na swoim sklepie osadzonego skryptu Pixel only. Jeśli go znajdziesz, najpierw go w całości usuń (wraz z jego konfiguracją).
Jeśli nie masz jeszcze na swoim sklepie skryptu Ad & Pixel, osadź go zgodnie z uproszczoną instrukcją integracji. Nie potrzebujesz do tego programisty, a sama integracja zajmie Ci najwyżej tyle, co przerwa na kawę. Jeżeli chcesz, możemy nawet ten krok wykonać za Ciebie.
Skontaktuj się z opiekunem z Ringier Axel Springer Polska mailowo albo na czacie.
W odpowiedzi prześlemy Ci specjalne linki z proponowanym podglądem umiejscowienia reklam bezpośrednio na Twoim sklepie. Podgląd testowych reklam będzie widoczny wyłącznie dla Ciebie i ewentualnie dla innych osób, którym udostępnisz wygenerowane przez nas linki. Nie uruchomimy na Twoim sklepie żadnych reklam bez Twojej wyraźnej zgody.
Przejrzyj propozycje osadzenia reklam klikając w przesłane przez nas linki. Sprawdź zarówno wersję desktop jak i mobilną. Poinformuj nas tą samą drogą, czy je akceptujesz albo ewentualnie zgłoś swoje uwagi.
Po uzyskaniu od Ciebie akceptacji, reklamy zostaną przez nas aktywowane na Twoim sklepie. Nic więcej nie musisz już robić.

Opcja 2 – osadzenie poprzez HTML

Skonfiguruj i osadź na stronie skrypt Ad & Pixel.
W miejscu na stronie, w którym ma się wyświetlać Promo Banner, wstaw następujący kod:

<div data-slot="rmn-promo-banner" data-collapse="1"></div>

Opcja 3 – osadzenie przez JS

Alternatywnym sposobem osadzenia Promo Bannera jest użycie DL API SDK z poziomu JS. Dzięki temu można obsługiwać bardziej złożone przypadki. Jednym z głównych potrzeb użycia API jest sytuacja w której w przypadku braku reklamy chcemy dane miejsce zastąpić czyś innym. Poniżej przykład:

dlApi.cmd.push(function() {
  var slot = dlApi.defineSlot('rmn-promo-banner', 'id-dom-element-id');
  slot.on('empty', function() {
     console.log('brak banneru dla tego slotu'); 
  });
  dlApi.fetch();
});

Gdzie:

rmn-promo-banner to stała nazwa slotu do wyświetlania promo bannerów,
id-dom-element-id to identyfikator elementu DOM ID w którym wyświetlona zostanie reklama

Pamiętaj, że najpierw na stronie musisz osadzić i skonfigurować skrypt Ad & Pixel.

Przykład pełnego kodu

🦉 Promo Banner – integracja

Testowanie integracji

Aby upewnić się, że proces integracji został zakończony pomyślnie, należy odwiedzić stronę, na której został osadzony slot do wyświetlania Promo Banner. Aby przeprowadzić test, dodaj do adresu strony znak hasztagu #adbeta=l510825!slot.rmn-promo-banner. Dzięki temu na ekranie pojawi się specjalnie przygotowany baner reklamowy z ofertami, które sklep dostarczył w swoim feedzie.

Ten krok jest istotny, aby zweryfikować, czy dane z feedu są poprawnie przesyłane do systemu reklamowego i czy baner jest w stanie poprawnie wykorzystać te informacje do wyświetlenia odpowiednich ofert. Testowa reklama pozwoli na szybkie sprawdzenie, czy cały proces integracji przebiegł zgodnie z oczekiwaniami.

Sponsored Product

Sponsored product example

📘
WooCommerce
Poniższa instrukcja dotyczy witryn działających w oparciu o własną technologię. Jeśli Twój sklep jest oparty o platformę WordPress z zastosowaniem rozwiązania WooCommerce, sprawdź informacje, jak zainstalować naszą wtyczkę do WooCommerce: Integracja Sponsored Product z WooCommerce.

Opcja 1 – integracja przez dlApi SDK (front)

Integracja przez dlApi SDK (client side) jest najprostszym sposobem na wyświetlenie Sponsored Product. Sprowadza się do wywołania funkcji dlApi.fetchNativeAd, która zwraca Promise. W parametrach funkcji należy podać listę ofert, do których będzie dobrana najlepsza reklama do wyświetlenia.

Wymagania

Do integracji przez dlApi SDK potrzebne jest poprawne skonfigurowanie skryptu Ad & Pixel.

Diagram integracji

sequenceDiagram
    participant U as 👤 Użytkownik sklepu
    participant S as 💻 Strona sklepu
    participant API as ☁ API sklepu
    participant SDK as 🟡 Onet Ads SDK
    U->>S: Żądanie strony
    S->>API: Pobierz listę standardowych produktów
    API-->>S: Zwraca listę produktów
    S-->>U: Wyświetl standardowe produkty
    S->>SDK: Pobierz oferty sponsorowane
    SDK-->>S: Zwraca oferty sponsorowane
    S->>API: Sprawdź dostępność produktów sponsorowanych
    API-->>S: Zwraca dostępne produkty sponsorowane
    S-)SDK: Zlicz wyświetlenie reklamy
    S-->>U: Wyświetl produkt sponsorowany

Przykład kodu

// Skrypt Ad & Pixel musi być wcześniej zainicjowany, więc obiekt dlApi już istnieje
dlApi.cmd.push(dlApi => {
    // Krok 1: Pobierz oferty sponsorowane przy pomocy dlApi SDK
    dlApi.fetchNativeAd({
        slot: 'rmn-sponsored-product',  // stała wartość dla Sponsored Product
        opts: {
            offer_ids: [10, 20, 1234]  // identyfikatory ofert obecnych na bieżącej stronie
        },
        tplCode: '1746213/Sponsored-Product',  // stała wartość – dla Sponsored Product
        asyncRender: true  // samodzielnie zlicz wyświetlenie reklamy, jeśli chcesz pokazywać tylko aktywne oferty
    }).then(ad => {
        if (ad && ad.fields.feed.offers && ad.fields.feed.offers.length) {  // weryfikacja, że mamy zwróconą reklamę z ofertami
            const offers = ad.fields.feed.offers;
            const offerIds = offers.map(offer => offer.id);

            // Krok 2: Sprawdź dostępność produktów sponsorowanych w bazie danych sklepu
            fetch(`/api/products?active=1&id=${encodeURIComponent(offerIds)}`).then(response => {
                if (!response.ok) {
                    throw new Error(`status ${response.status}`);
                }

                response.json().then(data => {
                    const offer = offers.find(offer => data[offer.id]);

                    if (offer) {
                        // Krok 3: Zlicz wyświetlenie reklamy
                        ad.render();

                        // Użyj produktu z bazy danych sklepu, ponieważ może być bardziej aktualny (np. cena)
                        const sponsoredProduct = data[offer.id];
                        
                        // Krok 4: Aby poprawnie zliczać kliknięcia w reklamę, użyj linku oferty zwróconego z dlApi SDK
                        // (ten link zawsze będzie prowadził do karty wybranego produktu w Twoim sklepie)
                        sponsoredProduct.url = offer.offer_url;

                        // Krok 5: Wyświetl produkt sponsorowany
                        console.info(sponsoredProduct);
                    } else {
                        console.info('No active offers for rmn-sponsored-product');
                    }
                }).catch(err => {
                    console.error('Invalid local API response for rmn-sponsored-product:', err);
                });
            }).catch(err => {
                console.error('Local API for rmn-sponsored-product could not be loaded:', err);
            });
        } else {
            console.info('No offers for rmn-sponsored-product');
        }
    }).catch(err => {
        console.error('Ad for rmn-sponsored-product could not be loaded:', err);
    });
});

📘
Ważne informacje przy zapytaniu
Przy każdym zapytaniu należy podać parametry slot: 'rmn-sponsored-product' oraz tplCode: '1746213/Sponsored-Product'.
Jeśli w konfiguracji Skryptu Ad & Pixel nie został podany keyvalue offer_ids, należy go podać w parametrze opts jak w przykładzie. Jeśli offer_ids będzie podany zarówno w konfiguracji jak i w wywołaniu funkcji fetchNativeAd, pod uwagę będzie brana wartość z wywołania funkcji.
Jeśli nie potrzebujesz weryfikować, czy pobrane oferty sponsorowane nadal są aktywne i aktualne (np. cena), usuń parametr asyncRender: true z zapytania.

Obsługa odpowiedzi

Jak zostało wspomniane wcześniej, funkcja fetchNativeAd zwraca Promise, który w resolve otrzymuje reklamę (lub wartość null, jeśli nie udało się dopasować żadnej reklamy). Na podstawie odpowiedzi należy wyrenderować w odpowiednim miejscu na stronie zwróconą ofertę produktu.

Struktura listy ofert dla reklamy (ad.fields.feed.offers) jest zgodna ze specyfikacją API.

🚧
Wymogi prawne
Każda reklama Sponsored Product powinna być odpowiednio oznaczona - np. etykietką "Sponsorowane". Ponadto jeżeli Twój sklep spełnia definicję platformy w rozumieniu DSA (Digital Services Act), po tekście etykiety powinna się znaleźć ikonka informująca o reklamie - zobacz: Kompletny przykład integracji RMN w JavaScript.
Każda reklama produktu będącego lekiem powinna być dodatkowo opatrzona ostrzeżeniem, którego treść jest zdefiniowana prawnie, oraz skróconą informacją o leku (SIL). Informacje te są umieszczane zgodnie ze specyfikacją API przy właściwych ofertach w polach pharma_legal oraz pharma_sil.

W odpowiedzi z funkcji fetchNativeAd w tablicy ad.fields.feed.offers może zostać zwrócona więcej niż jedna oferta. Należy wyświetlić tylko jedną ofertę sponsorowaną z tej listy - pierwszą, która jest w danej chwili aktywna w bazie danych sklepu. Aby wyświetlić na stronie więcej niż jeden produkt sponsorowany, zamiast tego należy wywołać funkcję wiele razy. Na przykład (zwróć uwagę na parametry opts.pos):

dlApi.cmd.push((dlApi) => {
    dlApi.fetchNativeAd({
        slot: 'rmn-sponsored-product',
        opts: {
            offer_ids: [1, 2, 3],
            pos: 1  // numer porządkowy
        },
        tplCode: '1746213/Sponsored-Product'
    }).then((ad) => {
        console.log('Pierwsza reklama:', ad);
    });

    dlApi.fetchNativeAd({
        slot: 'rmn-sponsored-product',
        opts: {
            offer_ids: [1, 2, 3],
            pos: 2  // kolejny numer porządkowy
        },
        tplCode: '1746213/Sponsored-Product'
    }).then((ad) => {
        console.log('Druga reklama:', ad);
    });
});

Opcja 2 – integracja przy pomocy API (server to server / backend)

Korzystając z API możesz zintegrować swój sklep po stronie backendu (server side).

Pełna specyfikacja API dostępna jest tutaj: Sponsored Product API spec

Diagram integracji

sequenceDiagram
    participant U as 👤 Użytkownik sklepu
    participant S as ☁ Serwer sklepu
    participant DB as 🗄️ Baza danych sklepu
    participant API as 🟡 Onet Ads API
    U->>S: Żądanie strony
    S->>DB: Pobierz listę standardowych produktów
    DB-->>S: Zwraca listę produktów
    S->>API: Pobierz oferty sponsorowane
    API-->>S: Zwraca oferty sponsorowane
    S->>DB: Sprawdź dostępność produktów sponsorowanych
    DB-->>S: Zwraca dostępne produkty sponsorowane
    S-->>U: Wyświetl produkt sponsorowany
    U-)API: Zlicz wyświetlenie reklamy
    S-->>U: Wyświetl pozostałe produkty

Przykład kodu

Przed rozpoczęciem integracji backendowej upewnij się, że masz dostęp do identyfikatora witryny: <<website_id>> sklepu. Jeśli jesteś zalogowany, możesz zobaczyć identyfikatory Twojej witryny sklepu Jeśli masz więcej niż 1 stronę, kliknij na domenę, aby wybrać witrynę.

📘
Twoja witryna: <<website_name>>
Website: <<website_name>> - Website ID: <<website_id>>
Website URL: <<website_url>>

Jeżeli nie posiadasz konta, bądź dostępu do panelu OnetAds poproś swojego opiekuna o identyfikator witryny bądź

Zadaj pytanie na czacie
Napisz email na adres: bok@onetads.pl

// Dane konfiguracyjne Onet Ads
$onetAdsWebsiteId = <<website_id>>;
$onetAdsSite = preg_replace(array('/^www\./i', '/[^\w-]+/'), array('', '_'), $_SERVER['SERVER_NAME']);
$onetAdsArea = 'listing';

// Krok 1: Pobierz listę standardowych produktów z bazy danych
// (poniżej zakładamy, że masz połączenie z bazą danych już ustanowione przy pomocy biblioteki PDO)
$productsResult = $pdo->query("SELECT * FROM products WHERE active = 1 LIMIT 10");
$products = $productsResult->fetchAll(PDO::FETCH_ASSOC);

// Krok 2: Pobierz oferty sponsorowane z REST API
$apiUrl = "https://csr.onet.pl/1746213/csr-006/csr.json?site=$onetAdsSite&area=$onetAdsArea&kvwebsite_id=$onetAdsWebsiteId&slot0=rmn-sponsored-product&ems_url=1";
// Dodaj identyfikatory produktów do zapytania, aby dobrać ofertę sponsorowaną pasującą do pozostałych
$apiUrl .= "&kvoffer_ids=" . urlencode(implode(',', array_column($products, 'id')));
// Jeśli Twój sklep spełnia definicję platformy w rozumieniu DSA (Digital Services Act), dodaj poniższy parametr
$apiUrl .= "&dsainfo=1";
// Dodaj do zapytania parametry pomocne przy testowaniu integracji
if (isset($_GET['adbeta'])) {
    $apiUrl .= "&adbeta=" . urlencode($_GET['adbeta']);
}
if (isset($_GET['test_kwrd'])) {
    $apiUrl .= "&kwrd=" . urlencode($_GET['test_kwrd']);
    echo "<!-- Onet Ads request: $apiUrl -->";
}
$response = json_decode(file_get_contents($apiUrl), true);

// Krok 3: Sprawdź dostępność produktów sponsorowanych w bazie danych sklepu
$activeSponsoredProduct = null;
$sponsoredProducts = & $response['ads'][0]['data']['fields']['feed']['offers'];
if ($sponsoredProducts) {
    $checkActiveStatement = $pdo->prepare("SELECT * FROM products WHERE id = :id AND active = 1");
    foreach ($sponsoredProducts as $sponsoredProduct) {
        $sponsoredProductId = $sponsoredProduct['id'];
        $checkActiveStatement->bindParam(':id', $sponsoredProductId);
        $checkActiveStatement->execute();
        if ($row = $checkActiveStatement->fetch(PDO::FETCH_ASSOC)) {
            $activeSponsoredProduct = $row;
            break;
        }
    }
}

// Krok 4: Wyświetl produkt sponsorowany
if ($activeSponsoredProduct) {
    echo '<div class="product sponsored">';
        // Krok 5: Zlicz wyświetlenie reklamy
        echo '<img src="' . htmlspecialchars($response['ads'][0]['ems_link']) . '" alt="" width="0" height="0">';

        // Oznacz ofertę sponsorowanę zgodnie z wymogami prawnymi
        echo '<p>Sponsorowane' . (empty($response['ads'][0]['data']['meta']['dsaurl']) ? '' : ' <a href="' . htmlspecialchars($response['ads'][0]['data']['meta']['dsaurl']) . '" target="_blank">&#x24D8;</a>') . '</p>';

        // Krok 6: Aby poprawnie zliczać kliknięcia w reklamę, użyj linku oferty zwróconego z REST API
        // (ten link zawsze będzie prowadził do karty wybranego produktu w Twoim sklepie)
        echo '<a href="' . htmlspecialchars($sponsoredProduct['offer_url']) . '">';
            echo '<img src="' . htmlspecialchars($activeSponsoredProduct['image_url']) . '" alt="' . htmlspecialchars($activeSponsoredProduct['name']) . '">';
            echo '<p>' . htmlspecialchars($activeSponsoredProduct['name']) . '</p>';
        echo '</a>';
        echo '<p>Cena ' . $activeSponsoredProduct['price'] . ' zł</p>';
    echo '</div>';
}

// Krok 7: Wyświetl pozostałe produkty
foreach ($products as $product) {
    // Krok 8: Usuń wybraną ofertę sponsorowaną z listy pozostałych produktów na stronie, aby się nie powtarzała
    if ($activeSponsoredProduct && $product['id'] == $activeSponsoredProduct['id']) {
        continue;
    }

    echo '<div class="product">';
        echo '<a href="?id=' . htmlspecialchars($product['id']) . '">';
            echo '<img src="' . htmlspecialchars($product['image_url']) . '" alt="' . htmlspecialchars($product['name']) . '">';
            echo '<p>' . htmlspecialchars($product['name']) . '</p>';
        echo '</a>';
        echo '<p>' . $product['price'] . ' zł</p>';
    echo '</div>';
}

📘
Ważne informacje przy zapytaniu
Ważne jest poprawne podanie parametru kvoffer_ids, który powinien zawierać listę identyfikatorów ofert na wyświetlanej stronie, aby dobrać ofertę pasującą do pozostałych. Nie jest istotne czy to oferty na stronie kategorii, czy np. w wynikach wyszukiwania. Tak jak opisano w API, to powinna być lista identyfikatorów ofert oddzielonych przecinkami.
Ponadto, aby ograniczyć oferty tylko do Twojego sklepu, musisz poprawnie ustawić parametr kvwebsite_id
Dodatkowo należy zgodnie ze specyfikacją API ustawić parametr area odpowiadający właściwemu typowi podstrony sklepu.

Do poprawnego wyświetlenia oferty na liście, potrzebujesz następujących pól z odpowiedzi:

id – identyfikator oferty
offer_url – link do oferty, z przeklikiem przez mechanizm zliczający

Pozostałe niezbędne informacje o ofercie, powinny być dociągnięte bezpośrednio z bazy/API sklepu.

Obsługa odpowiedzi

Jeśli została zwrócona reklama, musisz osadzić na stronie piksel 1x1, aby wyświetlenie reklamy u użytkownika zostało zliczone: <img src="{$response['ads'][0]['ems_link']}">
Możesz użyć id zwróconej oferty, aby pobrać najbardziej aktualne dane o ofercie z własnej bazy. Nie zapomnij, żeby jednak użyć offer_url z odpowiedzi, aby poprawnie zliczyć kliknięcie użytkownika w ofertę.
Jeśli zwrócona oferta znajduje się na liście ofert wyświetlanych (czyli na liście kvoffer_ids w zapytaniu), należy usunąć wspomnianą ofertę z listy, a wyświetlić na początku listy ofertę zwróconą w reklamie, odpowiednio ją oznaczając.

W odpowiedzi z API w tablicy $response['ads'][0]['data']['fields']['feed']['offers'] może zostać zwrócona więcej niż jedna oferta. Należy wyświetlić tylko jedną ofertę sponsorowaną z tej listy - pierwszą, która jest w danej chwili aktywna w bazie danych sklepu. Aby wyświetlić na stronie więcej niż jeden produkt sponsorowany, zamiast tego należy wykonać rozszerzone zapytanie do API. Na przykład (zwróć uwagę na parametry id0, slot0, pos0 oraz id1, slot1, pos1):

curl --request GET \
     --url 'https://csr.onet.pl/1746213/csr-006/csr.json?site=example_com&area=other&kvwebsite_id=<<website_id>>&id0=p1&slot0=rmn-sponsored-product&pos0=1&id1=p2&slot1=rmn-sponsored-product&pos1=2&ems_url=1&kvoffer_ids=1%2C2%2C3' \
     --header 'accept: application/json'

W odpowiedzi na powyższe zapytanie mogą zostać zwrócone dwie osobne reklamy - każda ze swoimi ofertami wewnątrz:$response['ads'][0]['data']['fields']['feed']['offers'] oraz $response['ads'][1]['data']['fields']['feed']['offers']. Z każdej z nich należy wyświetlić po jednej ofercie sponsorowanej.

Obsługa cache

Mechanizm cache polega na zapisywaniu strony w specjalnej pamięci podręcznej serwera lub/i przeglądarki. Dzięki temu przy kolejnym wejściu może się ona wyświetlić znacznie szybciej.

Z technicznego punktu widzenia produkty sponsorowane mogą być cache'owane zarówno na serwerze, na którym działa Twój sklep, jak i w pamięci podręcznej przeglądarek Twoich użytkowników. Nie zalecamy jednak tego robić, ponieważ może to obniżyć Twoje przychody:

O możliwość wyświetlenia produktu sponsorowanego w Twoim sklepie rywalizuje jednocześnie wielu reklamodawców. Jeśli użyjesz cache, to wtedy nawet jeśli nagle pojawi się ktoś chcący zapłacić więcej za emisję reklamy, do momentu odświeżenia pamięci podręcznej na Twoje konto wciąż będą wpływać przychody z wyświetleń za niższą stawkę.
Każda kampania reklamowa w Onet Ads ma ustawiony limit budżetu. Po jego osiągnięciu system natychmiast wstrzymuje emisję. Jeśli użyjesz cache, nie będzie to możliwe, a na Twoje konto nie wpłyną żadne przychody z tytułu nadprogramowych emisji reklamy po przekroczeniu budżetu reklamodawcy.

🚧
Ważne
W żadnym razie nie można cache'ować piksela 1x1 służącego do zliczania liczby wyświetleń reklamy, ponieważ drastycznie obniżyłoby to Twoje przychody.

Wyświetlanie ofert sponsorowanych zgodnych z filtrami użytkownika

W przypadku integracji typu Sponsored Product, funkcja dlApi.fetchNativeAd (lub odpowiednie zapytanie do API) zwraca listę ofert sponsorowanych, które pochodzą z feeda produktowego sklepu. Zazwyczaj jest ich więcej niż jedna, a ich podstawowe dopasowanie do kontekstu strony odbywa się w systemie Onet Ads.

Aby zapewnić spójność z doświadczeniem użytkownika, sklep może dodatkowo przefiltrować otrzymane oferty zgodnie z aktualnie wybranymi filtrami (np. marka, cena, kolor, dostępność). Dzięki temu reklama nie będzie wprowadzać użytkownika w błąd, prezentując produkt, który nie spełnia jego oczekiwań.

Przykład działania:

Użytkownik wybiera filtr: „Cena do 200 zł”.
Sklep otrzymuje z SDK lub z API listę np. 5 ofert sponsorowanych wraz z ich identyfikatorami przekazanymi wcześniej w feedzie produktowym.
Na podstawie zwróconych identyfikatorów skrypt sklepu sprawdza w swojej bazie danych, które z tych ofert spełniają filtr ceny.
Jeśli znajdzie pasującą ofertę, wyświetla ją.
Jeśli żadna oferta nie spełnia filtrów, nie wyświetla reklamy i nie zlicza jej wyświetlenia.

🚧
Nie zliczaj wyświetlenia, jeśli żadna oferta nie została wyświetlona
Jeśli żadna oferta sponsorowana nie spełnia kryteriów wybranych przez użytkownika:

W przypadku integracji za pomocą SDK nie wywołuj funkcji ad.render() (jeśli chcesz filtrować oferty, pamiętaj również, aby najpierw przekazać do funkcji dlApi.fetchNativeAd parametr asyncRender: true).

W przypadku integracji za pomocą API nie osadzaj piksela 1x1 służącego do zliczania liczby wyświetleń reklamy.

Kompletny przykład integracji RMN w JavaScript

Otwórz poniższy przykład, aby zobaczyć krok po kroku jak skonfigurować kompletną integrację skryptu Ad & Pixel, osadzić Promo Banner oraz pobrać i wyświetlić Sponsored Product.

📘
Informacja
Poniższy przykład uwzględnia przypadek, kiedy nie potrzebujesz weryfikować, czy pobrana oferta sponsorowana nadal jest aktualna (np. cena) oraz wciąż dostępna w sklepie. Jeżeli nie chcesz wyświetlać takich produktów, zapoznaj się z przykładami integracji Sponsored Product opisanymi wcześniej.

Testowanie integracji

W celu dokładnego sprawdzenia, czy proces integracji przebiegł pomyślnie, konieczne jest przeprowadzenie testu na stronie, na której został umieszczony slot przeznaczony dla Sponsored Product. Aby to zrobić, należy do adresu strony dodać specjalny fragment ?adbeta=l510824!slot.rmn-sponsored-product albo &adbeta=l510824!slot.rmn-sponsored-product - jeśli znak pytajnika już znajduje się w adresie strony. W wyniku tego prostego zabiegu zostanie wyświetlona testowa reklama, prezentująca oferty pochodzące bezpośrednio z katalogu sklepu dostarczanego w formie feedu.

Przeprowadzenie tego testu pozwoli na bieżąco monitorować, czy cały proces integracji został zakończony poprawnie oraz czy dane ofert z feedu są prawidłowo wykorzystywane do wyświetlenia sponsorowanych produktów. Jest to kluczowy etap w zapewnieniu efektywnego działania systemu reklamowego.

Wytyczne dot. UX/UI

Miejsca na stronie sklepu powinny być maksymalnie wyeksponowane w viewporcie użytkownika.

Komfort użytkownika w korzystaniu z serwisu jest najważniejszy. Pamiętaj aby dbać o wartość metryki CLS (Cumulative Layout Shift) w ramach Core Web Vitals. Oznacza to, że miejsce na reklamy powinno zawsze posiadać dedykowaną zarezerwowaną minimalną przestrzeń do wypełnienia. Reklama może nie być zwrócona z różnych powodów, np. być zablokowana przez adblockery, w tym celu najlepiej użyć placeholdera o rozmiarach przewidzianych na reklamę i który wyświetla się w momencie kiedy nie jest zwrócona żadna reklama.

🚧
Nie blokuj możliwości rozszerzania wysokości placeholdera (użyj stylu min-height zamiast height). Reklamy są dopasowane wizualnie do wyglądu serwisu, dlatego może się zdarzyć, że nie zmieszczą się w założonym rozmiarze.

Prosty placeholder

Poniższy kod rezerwuje wysokość co najmniej 400 pikseli na reklamę. Jeśli reklama nie zostanie wyświetlona, na ekranie pozostanie pusta przestrzeń. Dzięki temu nie będzie to miało negatywnego wpływu na metrykę CLS w ramach Core Web Vitals.

<div data-slot="rmn-promo-banner" style="min-height: 400px"></div>

Zaawansowany placeholder

Poniższy kod rezerwuje wysokość co najmniej 400 pikseli na reklamę. Zanim reklama zostanie wyświetlona, w jej miejscu pojawi się szary prostokąt z napisem "REKLAMA" w centrum.

<style>
[data-slot="rmn-promo-banner"] {
    min-height: 400px;
    margin: 1em 0;
    display: flex;
    justify-content: center;
    align-items: center;
}
[data-slot="rmn-promo-banner"]:empty {
    background-color: #eee;
}
[data-slot="rmn-promo-banner"]:empty::before {
    content: "REKLAMA";
    color: #666;
    font-size: 10px;
}
</style>
<div data-slot="rmn-promo-banner"></div>

RODO i Polityka prywatności

Wszystkie dane jakie są wykorzystywanie do targetowania reklamy nie przechowują i nie przetwarzają danych użytkownika by default. Jeżeli na stronie sklepu zaimplementwana jest plansza do zbierania zgód TCF skrypty automatycznie sprawdzą zgodę udzieloną przez użytkownika w ramach platformy Onet Ads.

Wsparcie

Kontakty do Wsparcia Technicznego

Kontakt do wsparcia technicznego możliwy jest przez opcję czatu na stronie, bądź mailowo

Dokumentacja API

Integracja S2S dla Sponsored Product API spec