Apple Search Ads × Antigravity Agent: Autonomous Keyword Bid Tuning Notes from an Indie iOS Studio

JWT auth and a short-lived token cache

ASA Campaign Management API uses a JWT signed with an Apple-issued ES256 key as a client_assertion, then exchanges it for an access token via OAuth Client Credentials. I tried this with curl first and ended up wrangling header escaping; eventually it collapsed into a small Node module.

// asa_token.mjs — invoked as a child process by the Antigravity sub-agent
import { SignJWT, importPKCS8 } from 'jose';
 
const CLIENT_ID = process.env.ASA_CLIENT_ID;
const TEAM_ID = process.env.ASA_TEAM_ID;
const KEY_ID = process.env.ASA_KEY_ID;
const PRIVATE_KEY = await importPKCS8(
  process.env.ASA_PRIVATE_KEY,
  'ES256'
);
 
async function getAccessToken() {
  const now = Math.floor(Date.now() / 1000);
  const assertion = await new SignJWT({})
    .setProtectedHeader({ alg: 'ES256', kid: KEY_ID })
    .setIssuer(TEAM_ID)
    .setSubject(CLIENT_ID)
    .setAudience('https://appleid.apple.com')
    .setIssuedAt(now)
    .setExpirationTime(now + 86400 * 180) // up to 180 days
    .sign(PRIVATE_KEY);
 
  const res = await fetch('https://appleid.apple.com/auth/oauth2/token', {
    method: 'POST',
    headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
    body: new URLSearchParams({
      client_id: CLIENT_ID,
      client_secret: assertion,
      grant_type: 'client_credentials',
      scope: 'searchadsorg',
    }),
  });
  if (!res.ok) throw new Error(`ASA token failed: ${res.status}`);
  return res.json(); // { access_token, expires_in: 3600, token_type: "Bearer" }
}
 
export { getAccessToken };

In the first version I was minting a fresh token on every call — roughly 300 redundant auth requests per day. I asked the Antigravity Agent View to redesign the caching, and it suggested an in-memory cache keyed on expires_in - 60 seconds. Adopting that cleared up an intermittent 401 I had been seeing once or twice a week.

Three small landmines that cost me half a day each, written out so you don't repeat them:

• Forgetting scope: 'searchadsorg' — Apple's docs mention it almost in passing. Without it, token minting succeeds, but downstream API calls return 401 with no useful message.
• Forgetting the X-AP-Context: orgId=... header — If your Apple ID manages multiple organizations, the API returns 200 with an empty result set when this header is missing. From the agent's perspective every keyword looks like zero impact, which can trigger sweeping pauses.
• Trusting expires_in: 3600 literally — Empirically I see 401s starting around the 50-minute mark. Refresh on expires_in - 300 seconds and the morning runs stay clean.

I leave these as comments at the top of asa_token.mjs so that when Antigravity edits the file later, the agent reads them and respects the constraints.

Pulling the keyword report into the agent's workspace

GET /api/v5/reports/campaigns returns flexible JSON aggregations. My sub-agent fetches the last seven days of keyword-level data each morning at 06:00 JST, drops the result into the agent workspace, then runs the decision logic on top.

// asa_keyword_report.ts
import { getAccessToken } from './asa_token.mjs';
 
type KeywordRow = {
  keywordId: number;
  keyword: string;
  matchType: 'EXACT' | 'BROAD';
  impressions: number;
  taps: number;
  installs: number;
  newDownloads: number;
  reDownloads: number;
  localSpend: { amount: number; currency: string };
  averageCpa: { amount: number };
  averageCpt: { amount: number };
  ttr: number;
  conversionRate: number;
};
 
export async function fetchKeywordReport(campaignId: number, days = 7) {
  const { access_token } = await getAccessToken();
  const endDate = new Date();
  const startDate = new Date(Date.now() - days * 86400_000);
  const body = {
    startTime: startDate.toISOString().slice(0, 10),
    endTime: endDate.toISOString().slice(0, 10),
    selector: {
      orderBy: [{ field: 'localSpend', sortOrder: 'DESCENDING' }],
      pagination: { offset: 0, limit: 1000 },
    },
    groupBy: ['keywordId'],
    timeZone: 'ORTZ',
    returnRecordsWithNoMetrics: false,
  };
  const res = await fetch(
    `https://api.searchads.apple.com/api/v5/reports/campaigns/${campaignId}/keywords`,
    {
      method: 'POST',
      headers: {
        'Authorization': `Bearer ${access_token}`,
        'X-AP-Context': `orgId=${process.env.ASA_ORG_ID}`,
        'Content-Type': 'application/json',
      },
      body: JSON.stringify(body),
    }
  );
  if (!res.ok) throw new Error(`ASA report ${campaignId} failed: ${res.status}`);
  const json = await res.json();
  return json.data.reportingDataResponse.row as Array<{
    metadata: KeywordRow;
    other: { granularity?: unknown[] };
  }>;
}

One small operational rule I converged on: never hand the raw JSON to the agent. I narrow it to the top 50 high-spend keywords and the bottom 20 low-spend keywords, and I pre-compute per-row metrics (CPI for the last 7 days, estimated ROAS, week-over-week install growth). Constraining the information surface keeps the agent's recommendations reproducible.

A deterministic policy for moving bids

This is the part where I tried to be clever and got burned. My first version asked an LLM to decide bids in natural language. On day three, the agent recommended a bidAmount.amount: 999.99 jump on a single keyword because it was reading a stale prompt that still assumed JPY when I had already migrated reports to USD. From then on, the rule became: decisions are deterministic code; the agent only handles anomaly detection and natural-language summarization.

# bid_policy.py — deterministic bid decisions
from dataclasses import dataclass
 
@dataclass
class BidDecision:
    keyword_id: int
    action: str  # "pause" | "decrease" | "increase" | "hold"
    new_bid_amount: float | None
    reason: str
 
def decide_bid(row, target_cpi: float, target_roas: float) -> BidDecision:
    cpi = row['averageCpa']['amount']
    spend = row['localSpend']['amount']
    installs = row['installs']
    estimated_roas = row.get('estimated_roas', 0.0)
    current_bid = row['bidAmount']['amount']
 
    # Safety: melted >= JPY 3000 with 0 installs over 7 days -> pause
    if spend >= 3000 and installs == 0:
        return BidDecision(row['keywordId'], 'pause', None,
                           '7-day spend>=¥3000 / installs=0')
 
    # ROAS below 50% of target -> decrease
    if installs >= 5 and estimated_roas < target_roas * 0.5:
        return BidDecision(row['keywordId'], 'decrease',
                           round(current_bid * 0.7, 2),
                           f'ROAS {estimated_roas:.2f} < target {target_roas:.2f}*0.5')
 
    # CPI above 1.3x target -> decrease
    if installs >= 10 and cpi > target_cpi * 1.3:
        return BidDecision(row['keywordId'], 'decrease',
                           round(current_bid * 0.85, 2),
                           f'CPI {cpi:.0f} > target {target_cpi:.0f}*1.3')
 
    # All clean and ROAS above target by 10% -> nudge up (capped)
    if installs >= 10 and estimated_roas >= target_roas * 1.1:
        next_bid = min(round(current_bid * 1.15, 2), current_bid + 50)
        return BidDecision(row['keywordId'], 'increase', next_bid,
                           f'ROAS {estimated_roas:.2f} >= target*1.1')
 
    return BidDecision(row['keywordId'], 'hold', None, 'within tolerance')

The rule sheet has to fit on a single page. The minute a solo developer accumulates three nested black boxes, debugging becomes prohibitive. After the policy runs, my agent's only remaining job is to translate the BidDecision list into a Slack message I can scan in 30 seconds.

When to promote Broad into Exact Match

Search Match in ASA lets Apple choose matching queries automatically. It is convenient, but running it alongside Exact campaigns can starve your branded Exact campaigns of budget. My sub-agent pulls a separate Search Term report and looks for queries like:

{
  "search_term": "calm wallpaper minimal",
  "match_type_used": "BROAD",
  "impressions": 4521,
  "taps": 132,
  "installs": 18,
  "cpi": 285
}

When a Broad-matched query consistently converts, it gets promoted to an Exact Match keyword in a dedicated campaign. Conversely, when Search Match catches a branded query that already lives in another campaign, it is added as a negative keyword on the Search Match side to stop the cannibalization.

Most of that runs automatically, but once a month I ask Antigravity to summarize the trailing 30 days of Search Term performance and propose promotion and exclusion candidates. I approve everything by hand for that monthly pass — five minutes over coffee.

The Crashlytics safety valve

This is the most important section if you take only one thing away. When ad spend rises but the latest build is crashing, every incremental user accelerates the rating decay. I lived this with one wallpaper app: the 1-star rate spiked and the average rating dropped from 4.6 to 4.1 inside two weeks. The recovery took months.

So the ASA agent never increases bids without checking Firebase Crashlytics' crash_free_users_percentage.

# crashlytics_gate.py
CRASH_FREE_FLOOR = 99.4  # 0.2pt below the trailing 6-month median
 
def is_safe_to_bid_up(crash_free_pct: float, daily_active_users: int) -> bool:
    if daily_active_users < 500:
        # DAU is too small for a meaningful crash signal — be conservative
        return False
    return crash_free_pct >= CRASH_FREE_FLOOR

If is_safe_to_bid_up returns False, every "increase" decision in that morning's batch is downgraded to "hold". Since this gate went live, I have not had a single incident where a worsening crash rate and a bid increase compounded.

A guiding principle that emerged from this work: in indie operations, make the "back off" decision smarter than the "lean in" decision. The hardest part of running solo is recognizing when to slow down, and the agent is best used to enforce that discipline.

A case of forgetting to kill a low-LTV keyword

Worth a confession. In week two, a derivative of the calming wallpaper cluster started picking up — CPI around JPY 180, 30 installs a day, very tidy on the surface. The agent dutifully nudged the bid to JPY 210.

Three days in, Firebase Analytics showed a Day7 retention of 4.8%. The median for my wallpaper apps sits around 21% on Day7, so this was less than a quarter of normal. AdMob revenue lagged accordingly and the estimated ROAS came out at 0.12. I was quietly burning about JPY 6,000 a day.

The root cause was embarrassing: my ROAS calculation was dividing by 24-hour install revenue instead of 7-day cumulative revenue. New users hit very few ads on day one, so the denominator was a fraction of what it should be. I fixed the windowing and the agent paused the cluster within a single morning run; daily spend dropped from JPY 6,000 to JPY 800 by the third day.

The recommendation I took from that experience: make sure the numerator and denominator of any ROAS calculation share the same time window, and enforce that in code rather than in the prompt. Any time the windows drift apart, force the agent to hold rather than increase. Data-layer defence beats agent-layer defence.

A complementary trick: any keyword with three consecutive days of 0% purchase-rate among first-24-hour users gets auto-paused, regardless of CPI. This catches low-LTV traffic before Day7 data even arrives. The first time I switched it on, four keywords paused themselves overnight and I recovered about JPY 18,000 of monthly spend.

Tying ASA, AdMob, StoreKit 2, and Crashlytics into one weekly view

I prefer to look at bidding alongside AdMob eCPM and StoreKit 2 subscription health on the same screen. What Antigravity does well here is letting the Background Agent View aggregate output from multiple sub-agents into a single artifact.

Concretely, AdMob comes through the Reporting API, StoreKit 2 through the App Store Server API, and Crashlytics through a thin Firebase Cloud Function proxy. Each client implements the same interface so the agent can call fetchWeeklyMetrics(source) four times.

// metrics_aggregator.ts
type Source = 'asa' | 'admob' | 'storekit2' | 'crashlytics';
const SOURCES: Source[] = ['asa', 'admob', 'storekit2', 'crashlytics'];
 
async function fetchAll(): Promise<Record<Source, unknown>> {
  const entries = await Promise.all(
    SOURCES.map(async (s) => [s, await fetchWeeklyMetrics(s)] as const)
  );
  return Object.fromEntries(entries) as Record<Source, unknown>;
}

Promise.all keeps the whole pull under four seconds. The sub-agent only sees the consolidated JSON and only writes the narrative summary on top. Keeping data acquisition in deterministic code is what keeps the AI surface area small.

[Week Report 2026-05 W3]
- ASA: spend ¥84,200 / installs 412 / blended_cpi ¥204
- AdMob: ARPDAU $0.18 / eCPM $9.40 / daily_revenue avg ¥9,300
- StoreKit2: new_subs 38 / churn 6 / MRR delta +¥4,800
- Crashlytics: crash_free 99.62% (prev week 99.49%)
- Suggestions: promote 'simple wallpaper' to Exact / hold 'asmr calm' on Search Match

Handling currencies and regional differences

My apps install across Japan, the US, Taiwan, Korea, and Brazil. ASA returns spend in local currency unless told otherwise, so I normalize everything to JPY before the agent touches it.

# fx_normalize.py
RATES = {
    'JPY': 1.0,
    'USD': 158.4,
    'TWD': 4.9,
    'KRW': 0.115,
    'BRL': 28.5,
}
 
def to_jpy(amount: float, currency: str) -> float:
    rate = RATES.get(currency)
    if rate is None:
        raise ValueError(f'unknown currency: {currency}')
    return round(amount * rate, 2)

A separate Background Agent refreshes RATES every Monday morning from an FX provider; if that step fails, Slack gets a "FX update failed" alert because stale rates are worse than no rates when bids are at stake.

One more regional nuance: US CPI tends to be 2–3x Japan CPI in JPY terms, but ARPU is also significantly higher. Comparing US CPI to a single global target will quietly suffocate your best-performing US keywords. I keep target_cpi per region and pass region into every report row given to the agent. That single change reduced false pauses by roughly five per month in my running operation.

Heuristics I'd give myself on day one

Three weeks of operating this loop produced a handful of principles I'd send back to my past self.

• Design the "stop" before the "go". Pausing rules deserve more thought than bid-up rules in indie operations.
• Trim the information you hand the agent. Raw API responses produce sprawling recommendations; pre-computed top-N tables produce repeatable ones.
• Whatever can be code, write as code. Reserve the LLM for anomaly detection and narrative summarization.
• Keep a human checkpoint each morning. A Slack message with three buttons — approve, reject, defer — closes the loop in under three minutes a day.
• Write the failures down. My _runbooks/asa.md has a paragraph titled "week 2 incident: calming wallpaper cluster" that has prevented me from repeating the same mistake twice.

A sustainable daily cadence for solo operations

The cadence I'm settling on after three weeks of refinement:

1. 06:00 JST — Background Agent fetches the trailing 7-day ASA report and runs decide_bid for every keyword.
2. 06:15 JST — Crashlytics is queried; is_safe_to_bid_up decides whether to downgrade "increase" actions to "hold".
3. 06:30 JST — Slack receives the proposed actions with an agent-generated explanation per row.
4. 07:00 JST — I review and tap approve / reject / defer; the entire review fits within three minutes.
5. Approved decisions only flow into a second sub-agent that calls Campaign Management API endpoints to apply changes.
6. First Monday of the month, 10:00 JST — Search Term promotion / negative-keyword candidates are proposed in one Slack message.
7. Anytime — A single button in Antigravity Agent View halts every sub-agent at once.

What I like about this cadence is that the morning shrinks to three minutes, but the human still keeps the right to stop. AdMob revenue moves up and down with seasonality, but the ASA bidding rhythm now feels calm — which is the result I was actually after.

Thank you for reading this far. I've written more about pairing Antigravity with Crashlytics in a separate piece if that part is interesting to you. If ASA is new to your stack, the gentlest place to start is one Exact Match campaign read daily by an Antigravity Background Agent. That is exactly where I began.