Contract v1.0.0

← Integrations

Google Ads

Coming soon (platform verification) Ads

Reads campaign structure, daily spend and conversions so ad spend, pacing and CAC are tracked per campaign.

What we pull

  • customer (currency, time zone)
  • campaigns and budgets
  • ad groups and ads
  • daily metrics (cost, impressions, clicks, conversions, value)

Every record lands as a financial event with source_type, external_id (deduplicated on re-sync) and provenance. Mode: mock.

Signals and sync

  • Webhooks deliver changes in real time; a scheduled sync fills gaps.
  • Sync interval: daily after 04:00 in the account time zone.
  • Health signals: auth_expired, silent (no sync for over twice the interval), error. Each becomes an in-app notification for the owner and shows in Integrations.

Permissions and secrets

  • Google Cloud OAuth client (Web application)
  • Google Ads developer token (Basic Access)
  • Google Ads user with Read only role
  • Customer ID (and manager account ID)

Secrets are encrypted at rest (AES-256-GCM, per-owner) and never returned by the API; the panel shows only the last 4 characters and the date. Read-only keys wherever the provider offers them.

Availability

Coming soon: the provider is verifying our app. Agents can already plan budgets and reserve capital; live data arrives once the review is done. Use “Notify me” in the panel.

Setup steps

From the Integrator’s owner checklist (Polish; the panel walks you through the same steps).

C1. Projekt Google Cloud (5 min)

  1. https://console.cloud.google.com → menu projektów (góra) → New project → nazwa Operlance → Create → wybierz projekt.
  2. APIs & Services → Library → wyszukaj Google Ads API → Enable.

C2. OAuth consent screen (10 min; weryfikacja Google tylko przy publikacji)

  1. APIs & Services → OAuth consent screen (nowy widok: Google Auth Platform → Branding).
  2. User type: External → Create. App name Operlance, support e-mail = Twój, developer contact = Twój.
  3. Scopes → Add or remove scopes → wpisz ręcznie https://www.googleapis.com/auth/adwords → Update → Save and continue.
  4. Test users → + Add users → Twój adres Google, którym logujesz się do Google Ads → Save.
  5. Zostaw Publishing status: Testing. W tym trybie refresh token wygasa po 7 dniach: na start wystarczy; przed produkcją klikniesz Publish app (bez weryfikacji Google działa, bo scope adwords nie jest „sensitive” w rozumieniu przeglądu: ekran ostrzeżenia „unverified app” widzisz tylko Ty).

C3. OAuth client (3 min)

  1. APIs & Services → Credentials → + Create credentials → OAuth client ID.
  2. Application type: Web application, nazwa Operlance api.
  3. Authorized redirect URIs → + Add URI: https://api-production-3516.up.railway.app/v1/integrations/google_ads/callback oraz (na czas generowania tokena narzędziem) http://localhost:8080.
  4. Create → skopiuj Client ID → Railway GOOGLE_ADS_CLIENT_ID, Client secret → Railway GOOGLE_ADS_CLIENT_SECRET.

C4. Developer token Google Ads (5 min + weryfikacja)

  1. https://ads.google.com → zaloguj się na konto menedżerskie (MCC). Nie masz? Create a manager account na https://ads.google.com/home/tools/manager-accounts/ (bezpłatne), potem z MCC Link existing account → THARAN.
  2. W MCC: Admin (ikona koła zębatego) → API Center (jeśli nie widzisz, MCC musi być w pełni utworzone i zaakceptować warunki).
  3. Wypełnij formularz (nazwa firmy, URL, e-mail, zgoda na warunki) → pojawi się Developer token → Railway GOOGLE_ADS_DEVELOPER_TOKEN.
  4. Token startuje z poziomem Test Account access: działa tylko na kontach testowych. Na tej samej stronie Apply for Basic Access: opis „Wewnętrzne narzędzie finansowe Operlance: odczyt wydatków i metryk kampanii własnych kont, bez zmian kampanii”; link do https://operlance.app; kontakt. Czas weryfikacji: zwykle 1 do 3 dni robocze, bywa do 2 tygodni. Do tego czasu robimy sync na koncie testowym.
  5. Zapisz do Railway: GOOGLE_ADS_CUSTOMER_ID = 10 cyfr konta THARAN (z prawego górnego rogu Google Ads, bez myślników lub z: obojętne), GOOGLE_ADS_LOGIN_CUSTOMER_ID = 10 cyfr MCC.

C5. Refresh token (5 min; jednorazowo, na Twoim komputerze) Skrypt jest w repo: packages/integrations/scripts/google-refresh-token.mjs (Node 22, bez zależności, nic nie zapisuje na dysk).

  1. W C3 dodaj redirect URI http://127.0.0.1:8085/callback (dokładnie tak, z portem).
  2. W terminalu, w katalogu repo: node packages/integrations/scripts/google-refresh-token.mjs. Skrypt zapyta o Client ID i Client secret z C3 (secret wpisujesz na ślepo), otworzy przeglądarkę: zaloguj się kontem z C2 pkt 4 i zatwierdź dostęp.
  3. Skrypt wypisze GOOGLE_ADS_REFRESH_TOKEN=... z instrukcją. Wklej wartość do Railway, potem wyczyść terminal (clear). Nie wysyłaj tokena nam. Jeśli skrypt zgłosi brak refresh tokena: cofnij dostęp na https://myaccount.google.com/permissions i uruchom ponownie.

Alternatywa bez skryptu: narzędzie Google OAuth 2.0 Playground (https://developers.google.com/oauthplayground → ⚙ „Use your own OAuth credentials” → wpisz Client ID/Secret z C3 → scope https://www.googleapis.com/auth/adwords → Authorize → Exchange → skopiuj Refresh token); wtedy w C3 dodaj redirect URI https://developers.google.com/oauthplayground.

C6. Relay webhooków (opcjonalnie, później): Railway GOOGLE_ADS_RELAY_SECRET = losowy ciąg (≥ 32 znaki): wygeneruj np. w 1Password. Google Ads nie ma webhooków; bez relaya wszystko działa przez codzienny sync.