schakl.
All integrations

Marketing & analytics Available

Google Ads

Ads shares the per-client link and the Google consent with Analytics and Search Console, but needs two things more: a developer token from your agency and, with a manager account, the knowledge of which account each client account must be reached through. And unlike the other sources, here you can change things too.

What you need

  • The Marketing module is enabled and licensed for this workspace (Instellingen → Modules)
  • The Google Ads API is switched on in your OAuth client's Google Cloud project
  • A developer token from the <strong>API Center</strong> of your Google Ads manager account. Apply early: Google reviews the request itself, and a freshly issued token does not yet read your live accounts.
  • A Google account with access to the Ads account, or to the manager account above it, connected under Instellingen → Mijn account
  • The marketing.link.manage permission, which gates both the token and the linking
  • For the working screen and the changes: the Google Ads integration switched on under Instellingen → Integraties, with a licence covering it

How to connect it

  1. 1 Request a developer token in your Google Ads manager account under API Center. This is one token for the whole agency, not one per client.
  2. 2 Switch on the Google Ads API in the Google Cloud project your OAuth client belongs to.
  3. 3 Put the token into Instellingen → Google Ads (Settings → Google Ads). It is stored encrypted and never handed back; the screen only reports that a token is present, and leaving the field empty keeps the stored one. An install that still has SCHAKL_GOOGLE_ADS_DEVELOPER_TOKEN in its environment keeps working, but the screen is where it belongs.
  4. 4 Connect your Google account under Instellingen → Mijn account (Settings → My account) if you haven't. That single consent covers Analytics, Search Console and Ads together.
  5. 5 Link the account to the client: pick it under Instellingen → Google Ads and attach the client, or open Klanten → de klant (Clients → the client), click edit on the Marketing panel and pick it under Ads-account. It is one link: what you make in one place shows in the other. If the account sits under a manager account, that is shown as a hint beside its name.
  6. 6 The link backfills roughly 13 months and is then updated nightly, re-pulling the last 30 days on every run.

Manager accounts are the normal shape, not an edge case

An agency is granted access to the manager account, not to each client account separately. Google's answer to "which accounts may you see" covers direct grants only, so that list is exactly one MCC id and none of the clients you actually run. So schakl. expands each manager account into its whole hierarchy in one query, and remembers per client account which manager it has to be reached through. That last part is the load-bearing half: without it every later call is made by someone with no grant on that account.

  • A nested MCC needs no separate walk: the whole tree arrives in one call
  • Sub-managers are dropped and their client accounts kept
  • Manager accounts cannot be linked themselves — Google refuses metric queries at that level
  • Past 500 client accounts per manager the list is capped and that is logged, never silently dropped

The API version is a setting, because it expires

Google Ads is the one Google API here whose URL carries a version, and Google sunsets a version roughly a year after it ships. From that day every path under it answers 404. That is not a token, permission or account problem, so none of the usual failure messages fits it and the module simply looks broken. schakl. therefore recognises a 404 from Ads specifically and says what is going on. The release pins a current version and <code>SCHAKL_GOOGLE_ADS_API_VERSION</code> overrides it, so an install that outlives its release can be bumped from the compose file instead of waiting for an upgrade.

Without a token, the rest keeps working

With no developer token, Ads is not broken but off: the picker and the sync fall back to a labelled state saying Ads still needs configuring. Analytics and Search Console keep running in the meantime. That is deliberate, because an agency that only wants the first two sources should not have to apply for a developer token to get them.

A conversion only counts once Google has finished counting

Google credits a conversion to the day of the click, up to the end of the conversion window, 30 days by default. A nightly run that re-pulls only the last week freezes every day before Google is done, while the same period last year was settled long ago. You then compare an unfinished year with a finished one, and every month looks worse than it was. So the sync re-pulls the last 30 days for Ads; the other sources keep to a week. The comparison defaults to the same period last year, and a tile says so in words, with the figure it was measured against.

Read and change, with a policy as a guard rail

The working screen under Marketing → Google Ads reads campaigns, ad groups, ads, keywords, search terms, negatives, devices, locations, recommendations, the change history and conversion health. Changing is split into four permissions, so you can mint a key that may tidy search terms overnight and never touch a budget. Per advertiser account, with your agency's as the house default, you set a policy: protected terms that may never be excluded, banned phrases in ads, a daily budget ceiling, a maximum cost per click and a budget that at most doubles in one change. Everything created here arrives paused. Because every route is also an MCP tool, an assistant works inside exactly the same limits.

Permissions

Grant these to the role that manages this integration (Settings → Roles). Admin-only by default, and never to the client role.

  • marketing.metrics.read Read a client's marketing figures, spend included. Granted by default to admin, member and the client portal; an agency that treats ad spend as sensitive narrows this to admins.
  • marketing.link.manage Link Ads accounts to a client from the Marketing panel and open the account picker. Admin only by default.
  • marketing.overview.read The cross-client grid under Overzicht → Marketing, which is where the spend column comes from. Admin only by default.
  • google_ads.settings.manage The developer token, linking and verifying accounts. Admin only by default.
  • google_ads.account.read Everything the working screen reads. Admin and member by default, never the client role.
  • google_ads.policy.manage The per-client policy, the house policy and the decision log. Admin only by default.
  • google_ads.query.run The pass-through for your own queries, read-only and bounded. Admin only by default.
  • google_ads.campaign.write Change campaigns, ad groups and ads. Admin only by default.
  • google_ads.budget.write Change budgets, separate because this is the money. Admin only by default.
  • google_ads.keyword.write Change keywords. Admin only by default.
  • google_ads.negative.write Change negatives and shared lists, and record which search terms you deliberately keep. Admin only by default.

What it deliberately does not do

  • Changes are only possible through the working screen and the API, within the four permissions and the client's policy. The marketing figures themselves only read.
  • Manager accounts cannot be linked; you link the client accounts beneath them.
  • The campaign drill-down on the dashboard shows ten campaigns sorted on spend. Ad groups, keywords and individual ads live on the working screen.
  • Amounts arrive in the Ads account's own currency and are never converted.
  • At most 500 client accounts per manager account are offered in the picker.
  • A link made before manager-account expansion shipped does not carry the manager it is reached through. Unlink it and pick the account again — the picker hides accounts already linked to the client, so the unlink is what puts it back in the list.

Where to find it Instellingen → Google Ads (Settings → Google Ads) for the developer token and the accounts, Marketing → Google Ads for the working screen, and Klanten → de klant → paneel Marketing (Clients → the client → Marketing panel) for the figures.

Read the guide

More in this category

Google Analytics 4 Google Search Console SE Ranking Google Tag Manager

Other integrations

Mollie Stripe Adyen Exact Online SnelStart Timeon