Szablony niestandardowe w GTM: kiedy zastąpić nimi Custom HTML i jak je pisać

Czym szablon niestandardowy różni się od tagu Custom HTML

Tag „Niestandardowy HTML” wykonuje dowolny kod z pełnym dostępem do strony, a szablon wykonuje kod w izolowanym środowisku, które udostępnia tylko wybrane funkcje. Różnica dotyczy bezpieczeństwa, wygody obsługi i kontroli nad wydajnością.

W praktyce najważniejsza jest druga i czwarta pozycja. Kod w niestandardowym HTML może bez ostrzeżenia odczytać dane z formularzy, przekierować użytkownika albo załadować skrypt z dowolnej domeny. Szablon tego nie zrobi, jeśli nie ma odpowiedniego uprawnienia, a lista uprawnień jest widoczna przy każdym imporcie i aktualizacji.

Kiedy zastąpić Custom HTML szablonem, a kiedy zostać przy HTML

Zamiana opłaca się dla tagów, które żyją długo i dotyka ich wiele osób. Do jednorazowych testów i nietypowych skryptów niestandardowy HTML nadal bywa rozsądnym wyborem.

Szablon wybierz, gdy:

• ten sam piksel występuje w kontenerze kilkanaście razy z różnymi zdarzeniami i parametrami,
• tag obsługują specjaliści od kampanii, którzy nie powinni edytować kodu,
• skrypt pochodzi od zewnętrznego dostawcy i chcesz ograniczyć, skąd może ładować kolejne pliki,
• pracujesz w kontenerze kilku klientów i chcesz używać tej samej, przetestowanej logiki.

Przy HTML zostań, gdy kod jest tymczasowy, wymaga bezpośredniej manipulacji stroną, której API piaskownicy nie obsługuje, albo dostawca dostarcza wyłącznie fragment do wklejenia i nie da się go sensownie przepisać.

Pamiętaj, że od 9 lipca 2026 roku kontener ładowany z identyfikatorem G- lub AW- uruchamia wyłącznie tagi i zmienne dostarczone przez Google – ani szablony społeczności, ani niestandardowy HTML w nim nie zadziałają. Szczegóły opisujemy w omówieniu zmian w GTM w 2026 roku.

Galeria szablonów społeczności: jak ocenić gotowy szablon

Zanim napiszesz własny szablon, sprawdź galerię szablonów społeczności. Wielu dostawców, w tym platformy reklamowe, publikuje w niej oficjalne szablony swoich pikseli, a szablony pochodzą z publicznych repozytoriów GitHub.

Przy ocenie zwróć uwagę na cztery rzeczy. Po pierwsze, autor: oficjalny szablon dostawcy lub znanego twórcy jest bezpieczniejszy niż anonimowy. Po drugie, uprawnienia: szablon piksela potrzebuje wstrzykiwania skryptu z domeny dostawcy i dostępu do jednej lub dwóch zmiennych globalnych, ale nie odczytu wszystkich ciasteczek. Po trzecie, data ostatniej aktualizacji. Po czwarte, kod – po imporcie możesz go otworzyć w edytorze i przeczytać. Gdy autor opublikuje nową wersję, GTM pokaże powiadomienie i porównanie zmian, więc aktualizację również przeglądasz przed akceptacją. Przykład wdrożenia piksela z oficjalnego szablonu znajdziesz w artykule o TikTok Pixel i Events API.

Jak napisać szablon niestandardowy GTM krok po kroku

Szablon tworzysz w sekcji Szablony, w części dotyczącej szablonów tagów lub zmiennych. Edytor ma kilka kart: informacje, pola, kod, uprawnienia, testy i notatki.

1. Utwórz szablon. W GTM przejdź do sekcji Szablony i w części szablonów tagów kliknij „Nowy”.
2. Uzupełnij informacje. Nadaj nazwę, opis i ikonę. Nazwa pojawi się na liście typów tagów, więc niech wskazuje dostawcę.
3. Zdefiniuj pola. Dodaj pole tekstowe na identyfikator piksela z regułą walidacji, listę rozwijaną z typem zdarzenia i prostą tabelę na parametry. Każde pole ma nazwę, przez którą kod odczyta wartość z obiektu data.
4. Napisz kod. Pobierz potrzebne API funkcją require() i zakończ działanie wywołaniem data.gtmOnSuccess() lub data.gtmOnFailure().
5. Skonfiguruj uprawnienia. GTM sam wykrywa użyte API i dodaje odpowiadające im uprawnienia. Ty określasz ich zakres, np. dozwolone adresy skryptów i nazwy zmiennych globalnych.
6. Dodaj testy. Opisujemy je w dalszej części tekstu.
7. Zapisz i użyj. Utwórz tag na podstawie szablonu i sprawdź go w trybie podglądu.
8. Wyeksportuj. Szablon możesz wyeksportować do pliku i zaimportować w innych kontenerach.

Poniżej kod szablonu dla hipotetycznego dostawcy, którego piksel korzysta z globalnej kolejki exq i ładuje bibliotekę z domeny cdn.example.com.

const injectScript = require('injectScript');
const createArgumentsQueue = require('createArgumentsQueue');
const makeTableMap = require('makeTableMap');
const logToConsole = require('logToConsole');

const exq = createArgumentsQueue('exq', 'exq.queue');
exq('init', data.pixelId);

const params = data.params ? makeTableMap(data.params, 'key', 'value') : {};
exq('track', data.eventName, params);

injectScript('https://cdn.example.com/pixel.js', function () {
  logToConsole('ExampleAds: biblioteka załadowana');
  data.gtmOnSuccess();
}, function () {
  logToConsole('ExampleAds: błąd ładowania biblioteki');
  data.gtmOnFailure();
}, 'exampleads');

Ten kod potrzebuje trzech uprawnień: wstrzykiwania skryptów z wzorcem https://cdn.example.com/*, dostępu do zmiennych globalnych exq (odczyt, zapis, wykonanie) i exq.queue (odczyt, zapis) oraz rejestrowania w konsoli. Ostatnie z nich domyślnie działa tylko w trybie podglądu i debugowania, więc komunikaty nie zaśmiecają konsoli użytkowników. Ostatni argument injectScript to klucz pamięci podręcznej – dzięki niemu biblioteka ładuje się raz, nawet jeśli tag uruchomi się kilka razy na stronie.

Uprawnienia i bezpieczeństwo: co daje piaskownica

Piaskownica sprawia, że szablon nie ma bezpośredniego dostępu do obiektu window ani do struktury strony. Wszystko, co robi, przechodzi przez API z określonym zakresem.

Najczęściej używane uprawnienia to wstrzykiwanie skryptów z listy wzorców adresów, dostęp do wskazanych zmiennych globalnych, wysyłanie pikseli na określone domeny, odczyt i zapis ciasteczek o podanych nazwach, odczyt adresu strony i warstwy danych oraz dostęp do stanu zgód. To ostatnie pozwala szablonowi samodzielnie respektować Consent Mode: API isConsentGranted sprawdza, czy dany typ zgody został przyznany, a addConsentListener reaguje na jego zmianę. Jak upewnić się, że tagi faktycznie przestrzegają wyborów użytkownika, pokazujemy w tekście o testowaniu Consent Mode przez parametry gcs i gcd.

Jeśli chcesz wymusić korzystanie z szablonów, możesz zablokować w kontenerze niestandardowe skrypty. Służy do tego lista zablokowanych typów tagów ustawiana w kodzie strony przed fragmentem GTM. Wartość customScripts blokuje niestandardowe tagi HTML i niestandardowe zmienne JavaScript.

<script>
  window.dataLayer = window.dataLayer || [];
  window.dataLayer.push({ 'gtm.blocklist': ['customScripts'] });
</script>
<!-- poniżej standardowy fragment Google Tag Manager -->

Bardziej zaawansowaną opcją są zasady szablonów definiowane w kodzie strony, które pozwalają np. zezwolić na wstrzykiwanie skryptów tylko z wybranych domen niezależnie od tego, co zadeklarował szablon. Uprawnienia ułatwiają też dokumentowanie, jakie dane i do kogo wysyłasz, co przydaje się przy rozliczalności wymaganej przez RODO – więcej o podstawach prawnych w reklamie piszemy w artykule o RODO w reklamie online. W konkretnych sprawach warto skonsultować się z prawnikiem.

Testy jednostkowe w edytorze szablonów

Karta testów pozwala uruchomić kod szablonu z przykładowymi danymi i podmienionymi API. Dzięki temu sprawdzisz logikę bez publikowania czegokolwiek na stronie.

const mockData = { pixelId: '123456', eventName: 'Purchase', params: [] };

mock('injectScript', function (url, onSuccess, onFailure) {
  onSuccess();
});

runCode(mockData);

assertApi('injectScript').wasCalled();
assertApi('gtmOnSuccess').wasCalled();

Dopisz co najmniej trzy przypadki: poprawne ładowanie skryptu, błąd ładowania (w atrapie wywołaj onFailure i sprawdź, czy wywołano gtmOnFailure) oraz brak wymaganego pola. Testy zapisują się razem z szablonem, więc kolejna osoba, która go zmieni, od razu zobaczy, czy czegoś nie zepsuła.

Szablony w kontenerze serwerowym

W kontenerze serwerowym nie ma niestandardowego HTML, więc każdy tag, klient i zmienna spoza wbudowanych typów to szablon. Piaskownica działa tak samo, ale udostępnia inne API: odczyt danych zdarzenia, wysyłanie żądań HTTP, odczyt nagłówków, ustawianie ciasteczek w odpowiedzi czy zapytania do baz danych Google Cloud.

Na szablonie opiera się np. tag Conversions API Meta, który konfigurujemy w poradniku o Meta Conversions API przez server-side GTM. Własne szablony zmiennych przydają się do dopisywania marży lub statusu klienta z bazy danych – przykład takiej zmiennej znajdziesz w tekście o wzbogacaniu zdarzeń po stronie serwera. Przenoszenie logiki na serwer to też sposób na lepszą kontrolę nad danymi first-party, bo decydujesz, które pola trafią do dostawców.

Jak przeprowadzić migrację istniejącego kontenera

Migracja nie musi odbyć się naraz. Najrozsądniej zacząć od tagów, które mają gotowe odpowiedniki w galerii, a własne szablony pisać dla skryptów powtarzających się w wielu miejscach.

1. Spisz tagi HTML. Wyeksportuj kontener do pliku JSON i wyszukaj tagi typu html oraz niestandardowe zmienne JavaScript.
2. Pogrupuj je. Podziel na piksele dostawców, własne skrypty, jednorazowe testy i tagi nieużywane. Te ostatnie od razu usuń.
3. Zastąp piksele szablonami z galerii. W trybie podglądu porównaj żądania wysyłane przez stary i nowy tag – powinny zawierać te same parametry.
4. Napisz własne szablony dla skryptów powtarzających się w kontenerze lub u wielu klientów.
5. Opisz pozostały HTML. Dla każdego tagu, który zostaje, dodaj notatkę z uzasadnieniem i właścicielem.

Mniej niestandardowego kodu to zwykle także szybsza strona; jak zmierzyć ten efekt, pokazujemy w artykule o tagach a Core Web Vitals. Jeśli dopiero porządkujesz kontener, zacznij od podstaw opisanych w tekście Google Tag Manager od podstaw, a kolejne poradniki znajdziesz w podtemacie Google Tag Manager.