Google Ads API — Internal Tool Design

This page documents how Easier Mobile uses the Google Ads API. The tool described here is built and operated by us, for our own Google Ads account and our own app only. It is not a product, is not distributed, and has no users outside Easier Mobile.

1. Company and business model

Easier Mobile is an independent Android application publisher based in Cầu Giấy, Hanoi, Vietnam. We design and publish free-to-download utility applications for users who find standard smartphone interfaces difficult to read or operate — primarily older users and users with reduced vision.

Our published application on Google Play is Big Font — Big Text Size (com.easiermobile.bigfont), a system-wide font scaling utility. Two further applications, Magnifying Glass and AI Cleaner, are in development and are not yet published.

Revenue model. All applications are free to install. Revenue comes from two sources, in order of contribution:

1. In-app advertising via Google AdMob (primary) — interstitial, rewarded, native, banner and app-open formats.
2. In-app purchases via Google Play Billing (secondary) — an optional one-time or subscription "Pro" upgrade that removes advertising and unlocks additional presets.

User acquisition. We buy installs for Big Font through Google Ads App campaigns, funded and operated entirely by Easier Mobile, under the manager account 466-112-2733. We do not manage advertising for any third party, and we do not resell or sublicense any advertising service.

2. Purpose of Google Ads API access

Because our revenue is dominated by advertising impressions rather than in-app purchases, the profitability of a paid user acquisition campaign cannot be judged from Google Ads metrics alone. Cost data lives in Google Ads; the corresponding revenue signal lives in AdMob and in Firebase/Google Analytics 4, delivered per impression through the Google Mobile Ads SDK onAdPaid callback.

We are building an internal tool that joins these two sides into a single view of average revenue per install (ARPI) and return on ad spend (ROAS) broken down by campaign, country and install cohort day, that applies conservative, rule-based budget and bid adjustments based on that view, and that launches new App campaigns reproducibly from reviewed configuration templates.

The tool has three functions:

1. Reporting (read). Retrieve campaign, ad group, geographic and asset performance metrics daily, store them in BigQuery, and join them against ad revenue and retention data from GA4 to produce a per-geography ARPI/ROAS report.
2. Budget and bid automation (write). Apply bounded daily adjustments to campaign budgets and target CPA/target ROAS bids, and pause clearly unprofitable geographic targeting criteria, according to the deterministic rules described in section 8.
3. Templated campaign creation (write). Create App campaigns, their budgets, ad groups, app ads and targeting from a version-controlled configuration template and a fixed library of approved creative assets, so that a geography test can be launched as a set of structurally identical campaigns. Campaigns are always created in a paused state and enabled by a person. This is described in section 8.3.

3. Users and access control

The tool is strictly internal. It is not a product, it is not offered to clients, it has no public sign-up, and it is not distributed to anyone.

4. System architecture

4.1 Implementation stack

5. Daily processing flow

1. Cloud Scheduler triggers the Cloud Run job at 03:00 UTC.
2. The job reads the OAuth refresh token, client secret and developer token from Secret Manager and obtains a short-lived access token.
3. Read. GoogleAdsService.SearchStream is called with GAQL queries (section 7) to fetch yesterday's campaign, ad group, geographic and asset metrics for every account under the manager account.
4. Results are written to partitioned BigQuery tables, keyed by date, customer id, campaign id and country criterion id.
5. Join. A BigQuery query joins Google Ads cost against GA4 ad-revenue events (onAdPaid values from the Google Mobile Ads SDK) and Play Billing purchase events, producing ARPI and ROAS per campaign × country × cohort day.
6. Evaluate. The rule evaluator compares each segment against the thresholds in section 8 and emits a list of proposed changes.
7. Validate. Every proposed change passes the guardrail validator. Proposals exceeding a cap are clamped; proposals outside the allowed class of operations are discarded and logged.
8. Write. Surviving changes are applied through CampaignBudgetService.MutateCampaignBudgets, CampaignService.MutateCampaigns and CampaignCriterionService.MutateCampaignCriteria. In dry-run mode the mutate call is made with validate_only = true and nothing is changed.
9. Record. Each attempted mutation — before value, after value, rule that fired, request id, result — is appended to an immutable BigQuery audit table.
10. A summary email is sent to the marketing team. Any error or clamped proposal is highlighted.

5.1 Campaign launch runs

Campaign creation is not part of the daily automated job. It runs as a separate, manually invoked Cloud Run job that takes a single argument: the path to a campaign template committed to our internal Git repository. A launch run performs the following steps and then exits.

1. Load and schema-validate the template — application id and store, campaign name pattern, bidding goal and target, daily budget, country basket, languages, and the identifiers of the creative assets to use.
2. Verify that every referenced creative asset exists in the approved creative library in Cloud Storage and carries a reviewer signature. A template referencing an unapproved asset is rejected.
3. Query existing campaigns in the target account and abort if a campaign matching the template's name pattern already exists, so that a re-run cannot silently create duplicates.
4. Resolve the country codes in the template to geo target constants.
5. Register the creative assets, then create the campaign budget, the campaign (status PAUSED), the ad group, the app ad and the location and language criteria.
6. Write the full created structure to the audit table and email it to the marketing team for review in the Google Ads user interface.

Every created campaign stays paused until a person enables it in the Google Ads user interface. The tool has no code path that enables a newly created campaign.

6. Google Ads API services and methods used

Expected volume. Under 100 operations per day in normal operation, with an allowance up to roughly 500 on days when historical data is backfilled. This is well inside the 15,000 operations per day of Basic Access. We do not anticipate needing Standard Access.

Services deliberately not used. The tool does not create, link or modify Google Ads accounts, does not manage user access or billing, does not upload click or offline conversions, does not use the App Conversion Tracking and Remarketing API, does not manage audiences or remarketing lists, and does not use keyword planning services. Creative assets are never generated at run time; the tool only registers files that already exist in the approved creative library.

7. Sample queries

7.1 Campaign performance by day

SELECT
  campaign.id,
  campaign.name,
  campaign.advertising_channel_type,
  campaign.status,
  campaign_budget.amount_micros,
  metrics.cost_micros,
  metrics.impressions,
  metrics.clicks,
  metrics.conversions,
  metrics.conversions_value,
  segments.date
FROM campaign
WHERE segments.date DURING YESTERDAY
  AND campaign.advertising_channel_type = 'MULTI_CHANNEL'

7.2 Cost and installs by country — the input to the ARPI join

SELECT
  campaign.id,
  campaign_criterion.location.geo_target_constant,
  metrics.cost_micros,
  metrics.conversions,
  segments.date
FROM location_view
WHERE segments.date DURING LAST_7_DAYS
  AND campaign.status = 'ENABLED'

7.3 Budget mutation with the safety flag set

operation = client.get_type("CampaignBudgetOperation")
budget = operation.update
budget.resource_name = budget_resource_name
budget.amount_micros = clamped_amount_micros      # produced by the guardrail validator
client.copy_from(
    operation.update_mask,
    protobuf_helpers.field_mask(None, budget._pb),
)

response = campaign_budget_service.mutate_campaign_budgets(
    customer_id=customer_id,
    operations=[operation],
    validate_only=DRY_RUN,        # true until a change set is approved
)

7.4 Illustrative output of the joined report

7.5 Creating a paused App campaign from a template

operation = client.get_type("CampaignOperation")
campaign = operation.create
campaign.name = template.campaign_name              # from the version-controlled template
campaign.status = client.enums.CampaignStatusEnum.PAUSED   # always paused on creation
campaign.advertising_channel_type = (
    client.enums.AdvertisingChannelTypeEnum.MULTI_CHANNEL
)
campaign.advertising_channel_sub_type = (
    client.enums.AdvertisingChannelSubTypeEnum.APP_CAMPAIGN
)
campaign.app_campaign_setting.app_id = template.app_id      # e.g. com.easiermobile.bigfont
campaign.app_campaign_setting.app_store = (
    client.enums.AppCampaignAppStoreEnum.GOOGLE_APP_STORE
)
campaign.app_campaign_setting.bidding_strategy_goal_type = (
    client.enums.AppCampaignBiddingStrategyGoalTypeEnum
    .OPTIMIZE_INSTALLS_TARGET_INSTALL_COST
)
campaign.campaign_budget = budget_resource_name             # created at the template minimum
campaign.target_cpa.target_cpa_micros = template.target_cpa_micros

response = campaign_service.mutate_campaigns(
    customer_id=customer_id,
    operations=[operation],
    validate_only=DRY_RUN,          # true unless the launch run is explicitly confirmed
    partial_failure=False,
)

7.6 Duplicate guard run before any creation

SELECT campaign.id, campaign.name, campaign.status
FROM campaign
WHERE campaign.name LIKE 'BigFont-AC-Installs-%'

8. Mutation rules and guardrails

All write operations are generated by deterministic rules, never by discretion at runtime. No machine-learning model or free-form logic issues a mutation.

8.1 Rules

8.2 Guardrails

8.3 Campaign creation rules and guardrails

Campaign creation is template-driven rather than rule-driven: no metric threshold ever causes a campaign to be created. A campaign exists only because a person committed a template and started a launch run.

9. Authentication and security

• OAuth 2.0. Credentials are obtained through the installed-application flow against the OAuth client in Cloud project 135139800127, authorised by the Google account that owns manager account 466-112-2733. The resulting refresh token is exchanged for short-lived access tokens at run time.
• Secret storage. The refresh token, OAuth client secret and developer token are stored in Google Cloud Secret Manager. They are never committed to source control, never written to logs, and never included in error reports. The Cloud Run service account holds secretmanager.versions.access on exactly these secrets and nothing more.
• Scope. Only https://www.googleapis.com/auth/adwords is requested.
• Network exposure. The Cloud Run job has no public ingress. It is invoked only by an authenticated Cloud Scheduler service account. There is no login page, no API endpoint and no user-facing surface that could expose credentials.
• Data handling. Data retrieved from the Google Ads API stays inside Easier Mobile's own Cloud project, is not shared with any third party, is not sold, and is not used for any purpose other than managing our own campaigns. Retention is 24 months, after which BigQuery partitions expire automatically.
• Access review. Because Easier Mobile is operated by one person and access is limited to that person and our own accounts, there is no external permission model to maintain. Access to the Cloud project and the Looker Studio dashboard would be reviewed if that ever changed.

10. Quota, rate limiting and error handling

• Quota headroom. Expected consumption is under 100 operations per day against the 15,000 per day of Basic Access. Reporting uses SearchStream so that a date range is returned in a single streamed request rather than many paged requests.
• Serial execution. The job runs once per day and processes accounts sequentially. There is no parallel fan-out and no possibility of a request storm.
• Retry policy. RESOURCE_EXHAUSTED and transient INTERNAL / UNAVAILABLE errors are retried with exponential backoff and jitter, capped at 5 attempts. Any retry_delay returned by the API is honoured.
• No retry on deterministic failures. Validation errors, authentication errors and policy errors are never retried. They abort the run and raise an alert, so that a broken assumption is corrected rather than repeatedly re-sent.
• Partial failure. Mutate requests are sent with partial_failure = false, so a rejected operation does not leave a change set half applied.
• Idempotency. Each run computes the intended final state rather than a delta, so a re-run after a crash converges to the same values instead of compounding.
• Monitoring. Job failures, quota warnings and any abort raise a Cloud Monitoring alert routed to nguyentran.mobile.dev@gmail.com.

11. Compliance

• The tool is used only with Google Ads accounts owned and funded by Easier Mobile, under manager account 466-112-2733.
• It is not distributed, licensed, resold or made available to any third party, and it contains no third-party Google Ads API tool.
• It does not scrape, cache for redistribution, or expose Google Ads data to anyone else.
• We will comply with the Google Ads API Terms and Conditions and the Required Minimum Functionality policy applicable to our access level, and will submit a new application before materially expanding the tool's scope beyond what is described in this document.
• Our campaign creatives describe the application accurately. Big Font's use of the WRITE_SETTINGS Android permission is disclosed on its Google Play listing and in its privacy policy, and is used solely to apply the system font scale that the user selects.

12. Roadmap