Skip to content

t1k:marketing:ua:mintegral-campaign-optimization

FieldValue
Moduleua
Version1.13.11
Efforthigh
Tools—
/t1k:marketing:ua:mintegral-campaign-optimization

Buy-side operator playbook for Mintegral UA. Each play is a self-contained loop: a trigger, a read-only diagnostic, a decision gate, an action with an explicit autonomy boundary, and a verification step.

Scope. Advertiser / AppGrowth side only — offers, bids, budgets, geos, creatives. Publisher-side optimization (eCPM floors, placements, units, fill rate) is not here; see the sibling table.

Activate on: “optimize mintegral”, “mintegral CPI too high”, “which mintegral offer should I pause”, “raise the bid on this offer”, “reallocate mintegral budget”, “this offer isn’t spending”, “mintegral geo breakdown”, “scale the winning mintegral campaign”, “mintegral creative fatigue”.

Sibling skills own the adjacent surfaces (Mintegral auth and report endpoints, MCP playbooks, report artifacts, cross-network structure, creatives, attribution, spend-vs-revenue merge). Table and routing: references/sibling-skills.md. Cross-link, don’t duplicate.


The account model — what is tunable, and where

Section titled “The account model — what is tunable, and where”

Offer is the optimization unit. Knobs map to mintegral_update_bid, mintegral_update_budget, mintegral_set_offer_status and mintegral_update_offer; the tree and the knob-to-tool constraints (bid floors, daily_cap minimum, per-geo reset, maintain_by gate, CPE settlement event) live in references/account-model.md.


Every play below inherits rules/ad-network-mcp-write-safety.md. Restated because this is live spend:

  1. Read before you write. No bid, budget, or pause recommendation without this period’s report behind it. A number you cannot source is a guess with a credit card attached.
  2. Preview first. Call the write tool with confirm:false (or omitted), show the operator offer · field · old → new · expected spend impact, get explicit go-ahead, then re-call with confirm:true. Writes also require MINTEGRAL_ALLOW_WRITES=1 on the MCP server.
  3. Confirm the account. Credentials live in ~/.config/t1k/ads.env, and there is more than one Mintegral advertiser account (MINTEGRAL_* and MINTEGRAL_2_*). State which account a write targets before sending it.
  4. One change per offer per cycle. Bid and budget moved together makes the result uninterpretable, and doubles the blast radius of a mistake.
  5. Never blind-retry a failed write. A timeout may have partially applied — re-read state first.

Step 0 — Ground the decision (mandatory)

Section titled “Step 0 — Ground the decision (mandatory)”
mintegral_get_campaign_report
window: a CLOSED, ≤7-day range (see the caps below)
dimension: Offer → then Location, then Creative, then Sub as the funnel narrows

Four data-hygiene checks (closed days, ≤7-day spans, sum-then-divide, zero-guard), the metric definitions (CPI, CVR, IPM) and the Currency rule: references/grounding-metrics.md. Hard rules repeat the enforcement points.


Deriving the target — from the account, not from a benchmark

Section titled “Deriving the target — from the account, not from a benchmark”

Derive the target from the app’s own economics, never an industry benchmark: target_CPI = ARPU(payback_window) × (1 / target_payback_ROAS). Revenue sources and worked example: references/target-derivation.md.

Confidence gate — act only on a real sample. Before any bid, pause, or scale decision an offer (or geo, or creative) must clear both:

  • ≥ 50 conversions in the window, or spend ≥ 3 × target_CPI × 50, and
  • ≥ 3 complete days of delivery.

Below that, the CPI swing is noise. State “insufficient sample — N conversions over D days” and either widen the window or wait. This gate is what stops a $12 sample from triggering a live bid cut.


Trigger. Effective CPI is off target, or a healthy offer is budget-capped and starved of volume.

offer clears the confidence gate?
├─ NO → widen the window / wait. No write.
└─ YES → CPI vs target?
├─ CPI > target, material spend → lower bid
├─ CPI ≤ target AND budget-capped → raise bid (scale — see Play 5)
├─ CPI ≤ target AND NOT capped → hold; the constraint is delivery, not price (Play 6)
└─ CPI ≈ target → hold

Action. mintegral_update_bid, one step at a time: ±10–20% of the current bid. A bid is a price in an auction, not a dial — a 50% cut usually buys silence rather than efficiency, and a 50% raise buys the worst inventory at the top of the curve. Respect the floors (0.01 / 0.001 CPC).

Verify. Re-read with mintegral_list_offers, then wait a full 3-day learning window before judging the move. Re-bidding daily is the most common self-inflicted failure: references/play-details.md § Play 1.

Autonomy boundary. Every bid write is preview-then-confirm. No exceptions, including decreases.


Trigger. Blended CPI is off target but the offer looks healthy in aggregate — the average is hiding a split.

Diagnostic. mintegral_get_campaign_report with dimension:"location", CPI per country, confidence gate applied per country: references/play-details.md § Play 2.

Decision gate.

Country patternAction
High spend, CPI above targetLower that country’s bid via bid_rate_by_location
Low spend, CPI well under targetRaise that country’s bid — usually an under-bid T2/T3 geo
Sustained spend, CPI ≥ 2× target, cleared the gatePropose removing the geo from target_geo
Below the confidence gateLeave alone. Report as “insufficient sample”, don’t tune

Action. mintegral_update_bid with bid_rate_by_location:[{country_code,bid_rate}], upper-case country codes. Send the complete intended set of overrides in one call — and never send [] unless the intent really is to wipe every per-geo override and fall back to the flat bid.

Autonomy boundary. Preview each geo’s old → new as a table before confirming.


Trigger. An offer hits its daily cap early (capped-and-efficient), or spends its full cap at a CPI above target (spending-and-inefficient).

Diagnostic. Report grouped by geo, plus current budgets from mintegral_list_offers. Classify:

capped early + CPI ≤ target → raise daily_cap (+20–30%)
not capped → budget is not the constraint; do not touch it (go to Play 6)
full spend + CPI > target → lower daily_cap, or fix price first via Play 1

Action. mintegral_update_budget with budget:[{country_code, daily_cap_type:"BUDGET", daily_cap, total_budget}]. Constraints (daily_cap floor 50, full per-area budget[], OPEN = uncapped): references/play-details.md § Play 3.

Autonomy boundary. Preview with the daily spend delta spelled out in dollars, then confirm.


Trigger. An offer is spending materially at a CPI that will not pay back.

Decision gate. Pause only when all hold: confidence gate cleared · CPI ≥ ~1.5× target · a bid reduction has already been tried and given a full learning window · spend is material enough that the waste is worth a pause.

Action. mintegral_set_offer_status {offer_id, status:"STOPPED"} — individually, one preview per offer. Never batch-blind-pause a list; a pause list is where one bad filter silently kills a whole account’s delivery. Resume with status:"RUNNING".

Autonomy boundary. Always preview-then-confirm; pausing discards delivery learning even though it is reversible: references/play-details.md § Play 4.


Trigger. An offer is at or under target CPI and is capped (by budget or by bid competitiveness).

The order matters. Raise the budget first, then the bid:

Steps 1–4 (budget before bid, one step per learning window, widen before over-bidding): references/play-details.md § Play 5.

Autonomy boundary. Each step is a separate preview-and-confirm. Do not chain steps 1 and 2 in one cycle — you lose the ability to tell which one bought the volume.


Play 6 — Under-delivery diagnosis (“the offer isn’t spending”)

Section titled “Play 6 — Under-delivery diagnosis (“the offer isn’t spending”)”

Trigger. An offer is RUNNING but spend is zero or far below cap. Work the checks in order and stop at the first hit — do not raise the bid before reaching step 6.

Six checks, in order: references/play-details.md § Play 6.

Report the cause, not just the fix. “Bid raised” without “because the offer was losing the auction in its two highest-inventory geos” is not a diagnosis.


Trigger. CTR / CVR / IPM decaying over consecutive days at a stable bid and spend.

Diagnostic. Creative (+Endcard) report over ≥2 weeks as ≤7-day slices, summed; CTR and IPM per creative over time: references/play-details.md § Play 7.

Decision gate. Sustained decay across days at a constant bid, cleared confidence gate → rotate. Single low days are noise; a drop that coincides with a bid or budget change is that change’s effect, not fatigue: references/play-details.md § Play 7.

Action. Supply fresh creatives via mintegral_update_offer (blocked when maintain_by != "ADV"). Creative concepting, hook-rate work, and testing frameworks live in t1k:marketing:ua:creatives.


Daily, every 3–4 days, weekly and monthly rhythm: references/operating-cadence.md.

Log every write — offer, field, old → new, timestamp, and the report window that justified it. When a campaign turns two weeks later, that log is the only way to tell which change did it.


  • The 7-day cap fails silently on the advertiser surface. A wider window returns empty / $0 with HTTP success. Every “spend collapsed” alarm gets this check first.
  • Never average per-slice ratios when stitching chunks. Sum the numerators and denominators, then divide once.
  • bid_rate_by_location:[] wipes every per-geo override. It is a reset, not a no-op.
  • A partial budget[] array can zero the geos you omitted. Always build the full array from current state when managing by area.
  • daily_cap cannot go below 50. To throttle harder, pause the offer.
  • maintain_by != "ADV" blocks every offer write. Account-managed offers change via the AM.
  • Two advertiser accounts exist (MINTEGRAL_*, MINTEGRAL_2_*). Confirm which one a write hits.
  • Currency is per-row, USD or CNY. Convert before summing or comparing.
  • Conversion is the settled event, not necessarily an install — CPE offers settle on settlement_event, so “CPI” on a CPE offer is a cost-per-settled-event.
  • Re-bidding daily restarts learning. The most common self-inflicted Mintegral failure.
  • Sub-publisher blocking has no MCP tool. Read the evidence, recommend, hand to the AM.
  • Data is ~1.5h delayed and advertiser report files are retained ~1 month. Archive anything you need for a longer look-back.