Instrukcja wdrożenia dla Merchantów

GA4 · Google Ads · Meta (Facebook) · TikTok · Synerise · Criteo · RTB House

1. Wprowadzenie

Integracja konwersji InPost Pay pozwala na automatyczne przesyłanie danych o zakupach dokonanych przez InPost Pay do wybranych platform marketingowych. Dzięki temu możesz mierzyć skuteczność kampanii reklamowych i optymalizować budżety.

System działa jako Google Cloud Function (Gen2) uruchamiana cyklicznie co 4 godziny przez Cloud Scheduler. Każde uruchomienie pobiera nowe zamówienia z API InPost Pay, przetwarza je i wysyła zdarzenia zakupu (purchase) do włączonych integracji.

Obsługiwane platformy

Platforma	Co jest wysyłane	Tryb

Platforma	Co jest wysyłane	Tryb
Google Analytics 4	Zdarzenie `purchase` (Measurement Protocol)	Opcjonalny
Google Ads	Offline Click Conversions (Enhanced)	BigQuery lub API
Meta (Facebook)	Purchase event (Conversions API)	Opcjonalny
TikTok	Purchase event (Events API v1.3)	Opcjonalny
Synerise	transaction.charge (Batch API v4)	Opcjonalny
Criteo	transactionConfirmation (Marketing Solutions API)	Opcjonalny
RTB House	Purchase event (Events API server-side)	Opcjonalny

Każda integracja jest niezależna — możesz włączyć dowolną kombinację platform. System gwarantuje deduplikację: każde zamówienie jest wysyłane do danej platformy dokładnie raz.

2. Wymagania wstępne

2.1. Projekt Google Cloud (GCP)

Do wdrożenia potrzebny jest projekt GCP z włączonym billingiem. Skrypt deploy.sh automatycznie włączy wymagane API i stworzy zasoby, ale projekt musi już istnieć.

Projekt GCP z aktywnym rozliczeniem (billing)
Zainstalowane narzędzie gcloud CLI (Google Cloud SDK)
Zalogowane konto z uprawnieniami roles/owner lub roles/editor na projekcie

2.2. Dane dostępowe InPost Pay

Dane otrzymujesz od opiekuna InPost Pay:

Parametr	Opis

Parametr	Opis
`client_id`	Identyfikator aplikacji — otrzymujesz od InPost
`client_secret`	Klucz tajny aplikacji — otrzymujesz od InPost
Tryb środowiska	`sandbox` (testowe) lub production (produkcyjne)

2.3. Parametry order_additional_parameters

Kluczowy krok po stronie Merchanta

Aby integracja mogła działać, Twój sklep musi przekazywać identyfikatory marketingowe w polu order_additional_parameters przy tworzeniu zamówienia w InPost Pay.

Bez tych parametrów system nie będzie w stanie powiązać zakupów z kampaniami reklamowymi.

Twoja wtyczka e-commerce / backend musi odczytać odpowiednie cookies/parametry URL i przekazać je w tablicy:

Klucz (key)	Opis	Źródło

Klucz (key)	Opis	Źródło
`client_id`	GA4 Client ID — wymagany dla GA4	Cookie `_ga` (format: GA1.1.XXXXXXX)
`gclid`	Google Click ID — wymagany dla Google Ads	URL param `?gclid=...`
`fbclid`	Facebook Click ID — wymagany dla Meta CAPI	URL param `?fbclid=...`
`ttclid`	TikTok Click ID — wymagany dla TikTok Events API	URL param `?ttclid=...`
`gum_caller_id`	Criteo User ID — opcjonalny dla Criteo	Cookie `cto_bundle` lub Criteo OneTag
`rtb_click_id`	RTB House Click ID — opcjonalny dla RTB House	URL param lub cookie RTB House

Przykład struktury JSON przekazywanej przy tworzeniu zamówienia:

"order_additional_parameters": [
  { "key": "client_id",      "value": "1234567890.9876543210" },
  { "key": "gclid",          "value": "EAIaIQob..." },
  { "key": "fbclid",         "value": "IwAR3x..." },
  { "key": "ttclid",         "value": "E.C.P..." },
  { "key": "gum_caller_id",  "value": "abc123..." },
  { "key": "rtb_click_id",   "value": "xyz789..." }
]

Wartości opcjonalne — jeśli dany parametr jest niedostępny, po prostu pomiń odpowiedni klucz.

Szczegóły implementacji order_additional_parameters dla poszczególnych platform e-commerce znajdziesz w dedykowanych instrukcjach:

Integracja bezpośrednia — InPost Pay - Analityka
Magento — InPost Pay - Analityka - Magento
PrestaShop — InPost Pay - Analityka - PrestaShop
WooCommerce — InPost Pay - Analityka - Woocommerce

3. Konfiguracja poszczególnych integracji

Poniżej znajdziesz instrukcje przygotowania danych potrzebnych dla każdej platformy. Wszystkie dane podasz interaktywnie podczas uruchamiania skryptu wdrożeniowego.

3.1. Google Analytics 4 (Measurement Protocol)

Uwaga — wtyczka Magento z GA4: Jeśli Twój sklep korzysta z wtyczki Magento z wbudowaną integracją GA4, NIE włączaj GA4 w tej integracji — doprowadzi to do duplikacji zdarzeń purchase.

Wymagane dane:

Parametr	Jak pozyskać

Parametr	Jak pozyskać
`Measurement ID`	GA4 → Admin → Data Streams → Web → Measurement ID (format: `G-XXXXXXXXXX`)
`API Secret`	GA4 → Admin → Data Streams → Web → Measurement Protocol API Secrets → Create

Wymagany order_additional_parameters key: client_id

3.2. Google Ads (Offline Conversions)

Dostępne są dwa tryby:

Tryb A: BigQuery (zalecany)

System zapisuje zamówienia do tabeli BigQuery. Następnie w panelu Google Ads konfigurujesz natywny import z BigQuery. Ten tryb jest prostszy i nie wymaga dodatkowych credentiali OAuth.

Podaj nazwę datasetu BigQuery (np. inpost_marketing)
Skrypt automatycznie stworzy tabelę inpost_purchases oraz widok inpost_conversions_view
W panelu Google Ads → Tools → Conversions → Import → Google Cloud / BigQuery
Wskaż widok: {projekt}.{dataset}.inpost_conversions_view

Tryb B: API (bezpośredni upload)

System wysyła konwersje bezpośrednio przez Google Ads API. Wymaga konfiguracji OAuth2 i Developer Tokena.

Parametr	Jak pozyskać

Parametr	Jak pozyskać
`Customer ID`	Google Ads → nagłówek konta (format: 123-456-7890)
`Conversion Action ID`	Tools → Conversions → wybierz akcję typu Upload clicks → ID z URL
`Developer Token`	Google Ads API Center → API Access → Developer Token
`OAuth Client ID`	Google Cloud Console → APIs & Services → Credentials → OAuth 2.0
`OAuth Client Secret`	Jak wyżej — sekcja szczegółów klienta OAuth
`Refresh Token`	Wygeneruj przez OAuth2 Playground lub własny skrypt z scope: `ads`
`Login Customer ID`	Opcjonalny — wymagany tylko przy kontach MCC (format: 123-456-7890)

Wymagany order_additional_parameters key: gclid

3.3. Meta / Facebook (Conversions API)

Parametr	Jak pozyskać

Parametr	Jak pozyskać
`Access Token`	Events Manager → Data Sources → Pixel → Settings → Generate Access Token
`Pixel ID`	Events Manager → Data Sources → Pixel ID (numer w nagłówku)

Wymagany order_additional_parameters key: fbclid (opcjonalnie — system wysyła eventy także bez fbclid, ale matchowanie będzie oparte wyłącznie na danych PII)

Ważność tokena Meta: Token Meta wygasa po ~60 dniach. System zaloguje błąd 401 gdy to nastąpi. Należy wtedy wygenerować nowy token i zaktualizować sekret w Google Cloud Secret Manager.

3.4. TikTok (Events API v1.3)

Parametr	Jak pozyskać

Parametr	Jak pozyskać
`Access Token`	TikTok Business Center → Assets → Events → Settings → Events API → Generate Access Token
`Pixel ID`	TikTok Business Center → Assets → Events → Pixel Code (np. CXXXXXXXXX)

Wymagany order_additional_parameters key: ttclid

3.5. Synerise (transaction.charge)

Parametr	Jak pozyskać

Parametr	Jak pozyskać
`Workspace API Key`	Synerise → Settings → API Keys → klucz z uprawnieniem API_BATCH_TRANSACTION_CREATE
Base URL	Azure EU: `api.synerise.com` \| Azure USA: `api.azu.synerise.com` \| GCP: `api.geb.synerise.com`

Synerise identyfikuje profil klienta po adresie e-mail (nie wymaga dodatkowych click ID). Transakcja zawiera produkty z zamówienia wraz z cenami brutto i netto, a w metadanych przekazywane są gclid, fbclid, ttclid i ga_client_id.

3.6. Criteo Marketing Solutions (Conversions API)

Integracja z Criteo wykorzystuje OAuth2 (client_credentials) do autoryzacji. Token jest automatycznie cache'owany i odświeżany.

Parametr	Jak pozyskać

Parametr	Jak pozyskać
`Client ID`	Criteo Management Center → Settings → API Consumers → utwórz lub wybierz consumer → Client ID
`Client Secret`	Jak wyżej — Secret generowany przy tworzeniu consumera (skopiuj od razu, nie da się go ponownie wyświetlić)
`Account ID`	Criteo Management Center → nagłówek konta → Account ID (numeryczny identyfikator)

Event type wysyłany do Criteo: transactionConfirmation — zawiera produkty z zamówienia, wartość, walutę oraz SHA256(email) jako identity.

Opcjonalny order_additional_parameters key: gum_caller_id — jeśli dostępny, przekazywany jako callerUserId w payloadzie (poprawia matchowanie użytkowników).

Uprawnienia API Consumer: Consumer musi mieć scope events nadany w Criteo Management Center → API Consumers → Edit → Permissions.

3.7. RTB House (Events API — server-side)

RTB House nie wymaga tokena — autoryzacja odbywa się przez taggingHash w payloadzie. Dane dostępowe uzyskujesz wyłącznie od opiekuna konta RTB House (brak publicznej dokumentacji API).

Parametr	Jak pozyskać

Parametr	Jak pozyskać
`Tagging Hash`	Od Account Managera RTB House — unikalny hash autentykacyjny dla Twojego konta
`Partner Key`	Od Account Managera RTB House — identyfikator partnera (accountId)
Region	EMEA: `ams` (domyślnie) \| US: `us` \| Asia: `asia` — determinuje endpoint API

Endpoint zależy od regionu:

Region	Endpoint

Region	Endpoint
EMEA (ams)	`https://creativecdn.com/tags`
US	`https://us-creativecdn.com/tags`
Asia	`https://asia-creativecdn.com/tags`

Event type: purchase — zawiera produkty, wartość zamówienia, SHA256(email) jako userId.

Opcjonalny order_additional_parameters key: rtb_click_id — jeśli dostępny, przekazywany jako clickId w payloadzie (poprawia atrybucję).

Brak publicznej dokumentacji: RTB House nie udostępnia publicznych docs do Events API. Parametry opisane powyżej bazują na dokumentacji connectorów Tealium i MetaRouter oraz informacjach od Account Managerów RTB House.

4. Proces wdrożenia

Cały proces wdrożenia jest zautomatyzowany przez skrypt deploy.sh. Skrypt interaktywnie zapyta o potrzebne dane, stworzy wszystkie zasoby GCP i uruchomi funkcję.

Kliknij poniżej i pobierz cloud-function-ga4.zip

4.1. Przygotowanie plików

Pliki otrzymujesz od zespołu InPost Pay. Umieść je w jednym katalogu:

Plik	Opis

Plik	Opis
`main.py`	Główna logika integracji (Cloud Function)
`deploy.sh`	Skrypt wdrożeniowy (automatyczna konfiguracja GCP)
`requirements.txt`	Zależności Python

4.2. Uruchomienie wdrożenia

Otwórz terminal w katalogu z plikami
Zaloguj się do GCP: gcloud auth login
Uruchom: bash deploy.sh
Skrypt zapyta kolejno o: ID projektu GCP, region, środowisko InPost, a następnie o dane każdej integracji
Poczekaj na zakończenie — skrypt utworzy Service Account, bucket GCS, sekrety, funkcję i harmonogram Cloud Scheduler

4.3. Co skrypt tworzy automatycznie

Zasób	Szczegóły

Zasób	Szczegóły
Service Account	`sa-inpost-ga4@{projekt}.iam.gserviceaccount.com` z minimalnymi uprawnieniami
Bucket GCS	Stan synchronizacji, listy wysłanych ID (auto-kasowanie po 30 dniach)
Secret Manager	Wszystkie tokeny i klucze API (zaszyfrowane at-rest)
Cloud Function	Gen2, 2 GiB RAM, timeout 540s, prywatna (bez publicznego dostępu)
Cloud Scheduler	Co 4h (CRON: `0 /4 * *`), strefa: Europe/Warsaw
BigQuery *	Tylko tryb BQ: dataset, tabela `inpost_purchases`, widok `inpost_conversions_view`

5. Weryfikacja po wdrożeniu

5.1. Wywołanie testowe

Po wdrożeniu wykonaj ręczne wywołanie, aby potwierdzić poprawność działania:

gcloud functions call inpost-ga4-integration \
  --region=europe-central2 \
  --data '{"debug": "true"}'

Parametr debug=true włącza tryb debug dla GA4 (walidacja eventów przez Google) i nie zapisuje wysłanych ID (można uruchamiać wielokrotnie bez duplikacji).

5.2. Sprawdzenie logów

Logi dostępne w Google Cloud Console → Cloud Logging. Filtr:

resource.type="cloud_function" resource.labels.function_name="inpost-ga4-integration"

Poprawne uruchomienie wygląda tak:

Active integrations: GA4=True, GoogleAds=bq, Meta=True, TikTok=False, Synerise=False, Criteo=True, RTB=False
Fetched 47 orders (smart sync from 2026-02-23T12:00:00)
GA4: 42 sent | Meta: 47 sent | BQ: 47 rows saved | Criteo: 47 sent

5.3. Weryfikacja po stronie platform

Platforma	Gdzie sprawdzić

Platforma	Gdzie sprawdzić
GA4	Realtime → Events → purchase \| DebugView (jeśli debug=true)
Google Ads	Tools → Conversions → Status: Recording conversions
Meta	Events Manager → Overview → Purchase → Server events
TikTok	Events Manager → Web Events → Purchase → Server events
Synerise	Data Management → Transactions → filtruj po dacie
Criteo	Criteo Management Center → Events → Event Log → filtruj po `transactionConfirmation`
RTB House	Skontaktuj się z Account Managerem RTB House — brak publicznego dashboardu eventów

6. Utrzymanie i obsługa bieżąca

6.1. Odnawianie tokenów

Platforma	Ważność tokena	Co zrobić

Platforma	Ważność tokena	Co zrobić
Meta	~60 dni	Wygeneruj nowy token w Events Manager i zaktualizuj sekret: `gcloud secrets versions add META_ACCESS_TOKEN --data-file=-`
TikTok	Zależnie od typu	Standardowy token nie wygasa; jeśli używasz krótkoterminowego — odnawiaj przed wygaśnięciem
Google Ads API	Refresh Token: ∞	Refresh Token nie wygasa, ale może zostać unieważniony (zmiana hasła, odwołanie dostępu)
Synerise	Auto-refresh	System automatycznie odnawia JWT co 55 minut — nie wymaga interwencji
GA4	Nie wygasa	API Secret nie ma daty ważności
Criteo	Auto-refresh (~15 min)	System automatycznie odnawia OAuth token — nie wymaga interwencji. W razie zmiany credentiali zaktualizuj sekrety `CRITEO_CLIENT_ID` / `CRITEO_CLIENT_SECRET`.
RTB House	Nie wygasa	`Tagging Hash` i `Partner Key` nie mają daty ważności. W razie rotacji skontaktuj się z Account Managerem.

6.2. Aktualizacja sekretu

Aby zaktualizować token bez ponownego wdrażania funkcji:

# Przykład: aktualizacja tokena Meta
echo "NOWY_TOKEN" | gcloud secrets versions add \
  META_ACCESS_TOKEN --data-file=-

Funkcja automatycznie pobierze nową wersję sekretu przy następnym uruchomieniu (:latest).

InPost Pay - Integracja Konwersji Marketingowych