Google Ads as code: from clicking to reviewing a diff

Google Search is still an important source of leads for a software company like ours. Someone searching for 'custom software development' often has a concrete problem to solve. We want them to find us. Even as we spend more of our own working day talking to an LLMGlossary · In briefLLMLLM stands for large language model: an AI model trained on large amounts of text. It can process language and generate text, including answers, summaries and code.Read more⁠.

But ask a room of developers who would like to spend an afternoon clicking through the Google Ads console, and it goes noticeably quiet. It certainly does here. Campaigns, ad groups, keywords, exclusions, bidding strategies. We know how to build software. We know considerably less about advertising.

Our usual response to this sort of situation is fairly predictable: can we do it as code?

Our Google Ads campaigns now live in 42KBGlossary · In brief42KB42KB is the central repository of 10KB for code, company knowledge, documentation and internal tools. It is where we put our company as code approach into practice.Read more⁠, the repository where we manage a growing part of our company. We manage them with readable files, validation, a plan before anything changes and a state file on S3. This fits company as codeGlossary · In briefcompany as codeCompany as code is an approach to recording company knowledge, processes and settings in text files and code. This lets you manage them with version control, checks and automation.Read more⁠, our idea of organising the work around our business with the same tools we use for software development.

First the website, then the ads

We write our entire website in MDXGlossary · In briefMDXMDX is a file format that lets you combine Markdown with JSX, JavaScript expressions, and import and export statements.Read more⁠, which combines MarkdownGlossary · In briefMarkdownMarkdown is a way to add structure to plain text using simple characters, for example for headings, lists, emphasis, and links.Read more⁠ with componentsGlossary · In briefcomponentA component is a distinct part of software with its own task and a clear way of interacting with other parts.Read more⁠. Copy, metadata and layout instructions live in files. Qwik and our plugins turn them into pages. We can search, compare and review changes in the same editor we use to develop software. We explain how that works in the case study about our own website.

We wanted the same for our ads. We find the Google Ads interface hard to navigate. You click from a campaign to an ad group, then look for a setting somewhere else. You cannot simply grepGlossary · In briefgrepTo grep means to search text for a word or pattern, usually across several files or in a program's output. The term comes from the Unix program grep.Read more⁠ across all your ads to find a phrase. Nor can you do a global find and replace as you would in an editor. Text files let us do both and then review the changes side by side.

Keeping the files in version controlGlossary · In briefversion controlVersion control records changes to code, including who changed what and when. It lets developers collaborate, compare changes and return to an earlier version.Read more⁠ also gives us an automatic audit logGlossary · In briefaudit trailAn audit trail is a chronological record of actions and changes in a system. It shows who or what performed an action, when it happened and what changed.Read more⁠: who changed what, and when? If a change does not work out, a rollbackGlossary · In briefrollbackA rollback reverses a change so software, configuration or data returns to an earlier state. Teams use it when a change causes errors or other unwanted effects.Read more⁠ is straightforward: restore the earlier configuration and generate a new plan. After approval, the tool reapplies those settings in Google.

So each landing page got a campaign file beside it. The page and ad address the same search intent and service. Keeping them together makes it easier to update them together:

apps/website/
├── ads.yaml
└── pages/landingspagina's/software-op-maat/
    ├── nl.mdx
    ├── en.mdx
    └── campaign.mdx

MDX is a slightly unusual choice for advertising configuration. It did fit the rest of our website, though. Settings go at the top in YAML, with the ad copy underneath as Markdown. We can use the same file structure for pages and ads.

Here, ads.yaml contains shared settings such as the target country and language. nl.mdx and en.mdx are the two versions of the landing page. campaign.mdx contains the campaign and is read only by our Ads tooling. It extracts the settings and copy without executing MDX code.

Our own Terraform for Google Ads

For the website, we can regenerate and upload all the HTML each time. Doing that with ads would cause problems. A campaign in Google has its own ID, settings and history. Creating a new campaign for every change would lose the connection to what is already running. We would also have two campaigns spending money.

We wanted to manage Google Ads in exactly the same way as our infrastructure through Terraform. The logical answer was, of course, to implement our own Terraform for Google Ads.

With Terraform, you describe your desired infrastructure in files. That might include which servers should exist and how they should be configured. This is called working declarativelyGlossary · In briefdeclarativeDeclarative means describing the desired outcome without specifying every step the software must take to achieve it.Read more⁠. The tool compares that description with what already exists and produces a plan of the required changes. After approval, apply executes the plan. The next run performs the same comparison again.

Our ads follow the same process. Take an example with fictional amounts: we reduce the monthly budget for custom software in ads.yaml from €900 to €600. For simplicity, we use a 30-day month here. The tool finds the existing shared budget in Google and proposes reducing it from €30 to €20 per day. That amount covers all campaigns in the group together. After approval, the tool makes the change. The next comparison has nothing left to do: the file and Google now describe the same budget.

We built a tool in TypeScript to compare desired and existing settings and execute changes. Most requests go through Zernio's Google Ads API. Zernio provides the connection our program uses to manage campaigns, groups and ads. We also use a direct Google Ads client for features including network settings and images.

By 'our own Terraform', we mean that workflow of configuration, plan and apply. Our tool is a standalone program that manages the Google Search campaigns it creates. Existing campaigns created manually stay outside its scope.

A campaign fits in a text file

A Google Ads campaign has settings including a budget and a schedule. Within the campaign are ad groups, which bring keywords and their corresponding ads together. Our file follows the same structure.

Here is an abbreviated version of our custom software campaign. At the top is the frontmatterGlossary · In brieffrontmatterFrontmatter is a block of metadata at the beginning of a content file, usually read by the tool that processes the file.Read more⁠, the settings block between the two lines of dashes:

---
id: software-op-maat
name: Software op maat
deploy: true
status: active
budgetGroup: maatwerk-nieuwbouw
schedule: weekdays
adGroups:
  maatwerk:
    keywords:
      - text: software op maat
        matchType: exact
---

The main settings are:

• deploy: true include this campaign in the comparison.
• status: active the desired status when we roll out the campaign with activation.
• budgetGroup use the shared budget and CPC limit from ads.yaml. In our fictional example, the entire group gets €600 per month, or €20 per day, with a limit of €15 per click.
• schedule: weekdays allow ads to run on weekdays.
• adGroups group keywords and ads. Here, the maatwerk group contains one keyword.

The ad copy follows below. The heading ad-group: maatwerk connects it to the group above. Within that group, we name the ad technisch-maatwerk. We have kept the original Dutch copy because this campaign targets Dutch searches:

## ad-group: maatwerk
### ad: technisch-maatwerk
#### headlines
- Software op maat
- Bedrijfskritische software
- Direct contact met developers
#### descriptions
- 10+ jaar maatwerkervaring. Bouw je bedrijfssoftware samen met onze developers.
- Kies de techniek samen met de developers die je software bouwen en onderhouden.

Our parser reads those fixed headings and lists. It checks that the groups exist, that there are enough headlines and descriptions and that they meet the length limits. The destination URL comes from the Dutch landing page in the same directory. The tooling adds UTM tagsGlossary · In briefUTM tagsUTM tags are URL parameters that identify a link's source, channel and campaign. Web analytics software can use them to attribute visits to that campaign.Read more⁠ so that our web analytics can show which campaign brought a visitor to the site.

We supply several headlines and descriptions. With a responsive search ad, Google selects a combination when serving it. One campaign file can produce different versions of an ad.

For this article, we had our ad rendered on a phone and laptop as an example.

From configuration to a plan

The campaign file describes what we want. To work out what needs to happen, the tool also needs to know which campaign it refers to and how that campaign is currently configured in Google. It therefore uses three sources:

• desired is the configuration we want, read from our campaign files.
• state is our record of previously created campaigns, groups and ads. It contains their Google IDs.
• live contains the current settings the tool has retrieved from Google using those IDs.

These three inputs go into the function that calculates the differences, commonly called a diffGlossary · In briefdiffA diff is an overview of the differences between two versions of a file or two states. It shows what has been added, removed or changed.Read more⁠. Current shared budgets and bidding strategies are read separately and passed in as budget. The function receives its inputs as named fields in a single object:

const operations = diff({ desired, state, live, budget });

operations is the list of actions needed to get from the existing setup to the desired one. These might include creating a campaign, updating a budget or pausing an ad. This list forms the plan we review before anything is executed.

Reading Google each time also reveals changes made outside the repository. Suppose the monthly allocation in ads.yaml translates to a shared daily budget of €20, but someone has changed that budget to €40 in the console. The tool proposes bringing it back to €20. The repository is authoritative for the fields we manage. An external difference like this is called driftGlossary · In briefdriftDrift is a difference caused by a managed environment changing outside its recorded configuration. The actual settings no longer match what the files describe.Read more⁠.

We run the tool through a CLIGlossary · In briefCLICLI stands for command-line interface: a way to control a program using text commands, usually from a terminal.Read more⁠, a program started from the terminal. It checks the files, retrieves the current settings and shows the plan. We review the proposed changes before the tool executes them. Activating campaigns is a deliberate choice; by default, the tool prepares them in a paused state. An empty diff means everything is already as intended.

A plan can become outdated too. While we are reviewing the changes, a colleague might update a budget. Just before apply, the tool therefore reads the configuration, state and live settings again. If anything has changed, execution stops and we need to review a new plan. Our approval stays tied to the changes we saw.

S3 remembers which campaign is which

Our file uses the local ID software-op-maat for the campaign. Google knows that same campaign by a numeric ID. The tool needs to remember this connection so it can find the correct campaign on the next run. We keep that connection in a state file, just as Terraform does.

We store this record as JSONGlossary · In briefJSONJSON stands for JavaScript Object Notation. It is a text format that software uses to exchange and store structured data.Read more⁠ in Amazon S3, AWS's file storage service. Every run then uses the same state, even when we work from a different laptop. Here is an excerpt, using fictional Google IDs:

{
  "campaigns": {
    "software-op-maat": {
      "googleId": "12345678901",
      "adGroups": {
        "maatwerk": {
          "googleId": "23456789012"
        }
      }
    }
  }
}

On the next run, the tool knows that changes to software-op-maat belong to campaign 12345678901. The local ID stays the same if we move the file to another directory. It remains the same campaign in Google.

The complete state also contains the ads, managed images, account and a revision number that increases with each write. If we remove a campaign file, the tool proposes pausing the corresponding campaign. It does so after approval. The IDs stay in the state and the campaign history remains available in Google. The same applies to removed groups and ads.

The S3 bucket holds state.json, saved plans and our approvals or rejections. It is private and encrypted. S3 also keeps earlier versions of the files. Plans and decisions are created once so we can later see what was proposed and approved.

await client.send(new PutObjectCommand({
  Bucket: bucket,
  Key: 'state.json',
  Body: JSON.stringify(nextState),
  ...(stateEtag
    ? { IfMatch: stateEtag }
    : { IfNoneMatch: '*' }),
}));

New campaigns are created in a paused state. The tool populates the settings and ads, then retrieves them from Google again. Activation follows only if we have chosen it and those checks pass. After apply, we compare everything with the desired configuration one more time. An empty diff means the managed settings match and execution succeeded.

state.pending = {
  journalVersion: 1,
  calls: [],
  credentialFingerprint: api.credentialFingerprint,
  planId: plan.id,
  operation: op,
  idempotencyKey: randomUUID(),
  startedAt: new Date().toISOString(),
};
await store.saveState(state);
await journalMutation(api, state, desired, () => store.saveState(state));
delete state.pending;
await store.saveState(state);

What the LLM era changes

LLMs read text and produce text. That makes this way of working well suited to AI. Our company knowledge, keyword research, landing pages and campaigns all live in text files. An agentGlossary · In briefagentAn AI agent is software that uses a language model and tools to carry out a task. It chooses its next steps based on the goal and the results of earlier steps.Read more⁠ can read them as context and return its work as changes to those same files. The tooling then turns those changes into a website or a campaign in Google Ads.

That lets an LLM do the work of a marketer. We explain which services we want to sell, who we want to reach and how much we want to spend. The agent can research keywords, organise campaigns, write landing pages and create matching ads. Reading the page and campaign together lets it align the ad's promise with what a visitor finds after clicking.

The results come back as text too. pnpm ads report produces Markdown, JSON and a CSV of search terms. The agent can read these to analyse spending and results, identify irrelevant search terms and propose changes. It then updates the campaign files and requests a new plan. We can use the same workflow to set up campaigns and maintain them.

Making both the inputs and results available as text lets an LLM do this work from start to finish: read the context, update files and propose improvements based on reports. We set the direction and review the changes. The tooling turns the approved files into an actual website or campaign.