📗 This content is the Smart Bidding Ninja Script user manual, the same one the script writes in the «Manual» tab of its spreadsheet. Here you can search it, listen to it, highlight it and save it to favourites.
All the script's configuration is centralised in the "Config" tab. The layout is organised in thematic blocks and the editable values are grouped by concept. Here is the detail of each block:
Block 1 — Base configuration (affects both modes)
These fields define the script's operating context. You fill them in once at install time and rarely touch them afterwards.
| Concept | Description |
|---|---|
| ID of the account to manage | Format with or without dashes: 123-456-7890. In an MCC installation this is the client account (mandatory); in an individual account it can be left empty (the account itself is used). |
| Script label | Normally ".SBNS". Only campaigns with this label will be managed. |
| Email for notifications | Address that receives the automatic reports. If empty, no email is sent. |
| TEST mode | "ON" simulates without applying real changes. "OFF" acts for real. |
| Date range | LAST_7_DAYS / LAST_14_DAYS / LAST_30_DAYS / THIS_MONTH / etc. |
| 7-day cost threshold | A fraction. E.g. 0.5 = requires having spent at least 50% of the expected weekly budget before allowing increases. |
Block 2 — Operating mode
| Concept | Values |
|---|---|
| Mode | "Manual" (or empty) → traditional behaviour with scenarios and percentages. "Smart" → automatic mode driven by targets. |
Block 3 — MANUAL mode (scenarios and percentages)
Sets up the classic behaviour: scenarios with their thresholds and adjustment percentages. Only used if the Mode is "Manual" or empty.
| Concept | Description |
|---|---|
| Default scenario | Applied to .SBNS campaigns with no specific scenario label. E.g. ".neutro". It sits in the Targets section because Smart also uses it as a fallback. |
Scenario table: five rows, one per scenario, in this order: .lanzamiento, .conservador, .neutro, .ninja1, .ninja2. Each row has three configurable values.
| Value | Meaning | Format |
|---|---|---|
| Smart Bidding deviation threshold | Decimal. E.g. -0.10 = -10%, 0.20 = +20%. | |
| Budget increase (target met) | Decimal. E.g. 0.05 = 5%. | |
| Budget decrease (target missed) | Decimal. E.g. 0.03 = 3%. |
Block 4 — SMART mode (targets and policy)
Smart mode leaves the scenario and adjustment-percentage decisions to the algorithm. You only define TARGETS (CPA, ROAS, volume) and the script decides how to get there. Only used if the Mode is "Smart".
| Concept | Valid values / description |
|---|---|
| Smart policy | "Smart" (maximum automation) / "Conservative" (leans towards ninja1/ninja2/neutro, prioritises profitability) / "Explorer" (leans towards lanzamiento/conservador/neutro, looks to scale). |
| Account CPA target | A number in euros. Decimals with a dot are accepted (e.g. 29.50). Applied to campaigns with no .cpa label of their own. |
| Account ROAS target | A number as a percentage (e.g. 200 = ROAS 2x). Applied to campaigns with no .roas label of their own. |
| Conversion scope | "Primary" counts every conversion marked as primary in Google Ads. "Custom" counts only the ones you list in the next row. |
| Custom conversions | Only if the scope is "Custom". Conversion action names separated by commas. E.g. "Qualified lead, Sale, Demo booked". |
| Volume mode | "OFF" (off, explicitly) / "Minimo" (at least N conv/month) / "Maximo" (no more than N conv/month) / "Aproximado" (around N). No accents. Empty is the same as OFF (backwards compatibility). Optional. |
| Conversion target | A whole number. Read together with the Volume mode. If either of the two is empty, the other is ignored. |
| Priority between targets | "CPA or ROAS" (default) → the metric targets outrank volume. "Volume" → volume outranks the metrics. "Volume w/o+budget" → chases volume but respects the strict monthly budget. |
Campaign-level labels (Smart mode)
Campaign labels always take precedence over the account settings:
- .cpa[number] — Sets a specific CPA target for that campaign. E.g. .cpa45.50 for a €45.50 target CPA.
- .roas[number] — Sets a specific ROAS target (as a percentage). E.g. .roas300 for a 3x target ROAS.
- .smart / .conservador / .investigador — Sets the specific policy for that campaign, overriding the account policy.
- If they collide (.cpa and .roas on the same campaign), the script uses the one that matches the real bidding mode: TARGET_CPA or MAXIMIZE_CONVERSIONS → .cpa; TARGET_ROAS or MAXIMIZE_CONVERSION_VALUE → .roas. The other one is ignored with an informative log entry.
Validation of the Smart configuration
When you switch Smart mode on but the configuration is incomplete or inconsistent, the script:
- Keeps working in traditional Manual mode (with the usual scenarios and percentages) — so you lose no service.
- Sends a daily email reminding you what is missing or wrong. Only once a day.
- Counts the consecutive days with an incomplete configuration. If they reach 7, the email changes tone and flags the account as "Emergency Manual mode".
- As soon as you fix the configuration, the email stops and the script goes into Smart on the next run.
Block 5 — Monthly budget and dynamic adjustments
Controls the account's monthly budget and how sensitive the dynamic adjustments are.
| Concept | Description |
|---|---|
| Monthly budget | "Yes" blocks increases if the pro-rated pace is exceeded. Empty or "No" → informative only. |
| Monthly budget amount | Total amount (€). Spanish formatting is accepted: 1.500 or 1500. |
| Current pro-rated (auto) | Auto-calculated by the script. % spent vs expected as of today. Do not edit. |
| Budget adjustments | "Yes" → the script may adjust budgets in MANUAL. "No" → blocks ALL budget adjustments in Manual. NO EFFECT in Smart (the Smart engine decides on its own). |
| Dynamic adjustments | "Yes" / "Positive only" / "Negative only" / empty. MANUAL ONLY. If active, the fixed percentages of the scenario table are ignored. |
| Maximum increase limit | Whole number 0-50 (%). MANUAL ONLY. |
| Maximum decrease limit | Whole number 0-50 (%). MANUAL ONLY. |
⚠️ If you switch Dynamic adjustments on, the fixed increase/decrease percentages of the scenario table are ignored. Only the maximum limits are used.
Block 6 — Auto-managed cells (do not touch)
At the end of the Config tab there is a grey band with cells that the script manages automatically. Do NOT edit them by hand: changing them can cause duplicate emails, missed runs or a desynchronised Smart learning period.
| Concept | What the script uses it for |
|---|---|
| Last email sent | Prevents duplicate emails on the same day. |
| Last nightly run | Decides whether a nightly or an intra-day cycle is due. |
| Last Smart configuration warning | Date of the last email about an incomplete Smart configuration. |
| Days counter, incomplete Smart config | Counts consecutive days with an invalid configuration; on reaching 7 it changes the tone of the warning. |
| Last Smart learning date | Start date of the learning period (14 days). |
| Learning start email sent | A marker so the Smart learning start email is not sent twice. |
| Learning exit email sent | A marker so the learning exit email is not sent twice. |
| Last Smart runtime error warning | Date of the last Smart runtime error email. |
| Consecutive days with a runtime error | Counts consecutive days with an active runtime error. |
| Percentages hash (signature) | Signature of the scenario table. Detects whether you change the percentages and re-applies them. |
| Volume: date of first nightly run with drift | If volume is active, marks when drift was first detected. After 5 days the system moves from Layer 1 (budget only) to Layer 2 (scenario too). |
| Volume: last spend warning step | Only applies when the priority is Volume and no budget is defined. Marks the last +20% overspend step already warned about this month. Reset when the month changes. |
| Volume: last low-remainder warning (.vol) | Month (yyyy-MM) in which the last "the remainder of the global figure is low or negative" warning was sent after subtracting .vol labels. Warned only once a month. |
| Smart notif 1: warnings for campaigns off target | JSON with the date of the last warning per campaign. Anti-spam: 1 email per campaign every 14 days. |
| Smart notif 2: low overall convergence | Date of the last warning about convergence <40% sustained for 4 weeks. Anti-spam: once a month at most. |
| Smart notif 3: policy out of step | Date of the last warning suggesting a change of Smart policy. Anti-spam: once a month at most. |
| Smart notif 4: serious loops per campaign | JSON with the date of the last warning about a loop of ≥10 cycles. Anti-spam: 1 email per campaign every 14 days. |
| Smart notif 2: convergence time series | JSON with the last 8 weeks of the % of campaigns on target (±5%). Updated once a week in the nightly cycle. |
| Suggestions cross-checked with targets (Manual) | JSON with the date of the last scenario suggestion cross-checked against the CPA/ROAS target. Anti-spam: 14 days per campaign. |
| Ignored suggestions with a period | JSON with the campaigns the user has marked as "Ignore for X days" in Suggestions, with the exclusion end date. |
What Smart already does (Phase 2 + Phase 3 active)
Phase 2 switches on target reading and deviation tracking. Phase 3 switches on the Smart ENGINE: the scenario is decided dynamically on each cycle according to each campaign's context, replacing the traditional .ninja1/.ninja2/etc. labels.
- A new Day-Stats column, "Smart deviation": shows the deviation of the current metric from the target (red = worse, green = better, empty = no target).
- If the conversion scope is "Custom", the script filters only the listed conversions. A single GAQL query at the start of the cycle.
- In Smart mode, the traditional scenario labels (.ninja1, .ninja2, .conservador, .neutro, .lanzamiento) ARE MUTED. The applied scenario is calculated dynamically.
- The "Reason" column in Day-Stats states the decision: e.g. "Smart (Conservative): average CPA €32 vs target €30 (+6.7%) → .ninja1".
How Smart decides which scenario to apply
On each nightly cycle, for each campaign in Smart mode, the script:
- Calculates the AVERAGE of the period set as the date range (not an instant value, so it does not react to spikes).
- Compares that average with the resolved Smart target (a .cpa/.roas label or the account-level target).
- Identifies the policy (a .smart/.conservador/.investigador label or the account policy).
- Applies the decision table to pick one of the 5 canonical scenarios.
| Situation | Conservative | Smart (balanced) | Explorer |
|---|---|---|---|
| On target or better (±5%) | .ninja1 (consolidates) | .neutro (balance) | .conservador (explores with restraint) |
| Worse than target (>+5%) | .ninja2 (maximum pressure) | .ninja1 (tightens) | .neutro (slows exploration) |
🚀 If a campaign is in its LAUNCH phase (<30 cumulative conversions OR <3 days with activity in the last 14), the scenario is always .lanzamiento, ignoring the policy and the deviation. This covers brand new campaigns and campaigns reactivated after a long pause.
Learning period (first 14 days)
When you switch Smart on for the first time (or if History is deleted), the script enters a learning period in which:
- Every campaign uses the .neutro scenario uniformly, ignoring the dynamic decision and the configured policy.
- Adjustments are small and cautious (the ones .neutro uses).
- The hard labels .min, .max, .p, .presupuesto off are ALWAYS respected.
- The script counts days with REAL DATA in History (not calendar days). If the script was down for several days, those do not count.
- When you switch Smart on you get an email explaining this; when the 14 days are complete you get another email confirming the move to full Smart.
- Every weekly email during the learning period includes the progress (day X of 14).
Loop detector
If a campaign in Smart has had 5 or more consecutive cycles with adjustments in the same direction (all increases or all decreases), it is treated as a possible structural problem and included in the WEEKLY email with the corresponding alert.
Typical causes to investigate if a loop appears: a target too demanding for the current volume, a change in the competition, landing page or creative problems, undetected seasonality. The detector takes no action on its own — it is a nudge for you to look into it.
About the auto-managed cells
In the grey band at the end of Config, the script keeps several internal markers: date of the last incomplete-configuration email, counter of consecutive days with an incomplete Smart configuration, markers for the learning emails, runtime error counter, etc. There is no need to touch them.