Skip to content

MichelRojo86WPP/copilot-config / skills/dv360-custom-bidding

dv360-custom-bidding

Verified

Custom Bidding de Google Display & Video 360 (DV360): escritura, revisión y depuración de scripts de puja personalizada. Cubre el DSL completo (funciones de agregación max_aggregate/sum_aggregate/first_match_aggregate, casting, log), el catálogo de señales (dimensiones, geo, dispositivo, inventario, viewability, vídeo/audio, Floodlight, GA4), las limitaciones del lenguaje (sin bucles, sin def, sin try, sin slices), y patrones probados en producción: tROAS escalonado, CPA fijo, micro-conversiones de checkout, routing por insertion_order_id, panel de pesos centralizado y bloque fallback. Usar al crear un algoritmo de custom bidding, iterar sobre uno existente, diagnosticar underdelivery o data sparsity, o traducir un objetivo de negocio a una función de scoring.

FileKindSize
SKILL.mdskill md11.5 KB
references/ecosistema-y-recursos.mdmarkdown6.6 KB
references/patterns.mdmarkdown20.5 KB
references/syntax-reference.mdmarkdown18.5 KB
references/video-genre-ids.mdmarkdown7.7 KB

references/patterns.md

View on GitHub
# DV360 Custom Bidding — patrones de código reutilizables

Fragmentos limpios, listos para pegar en DV360. Todos respetan las limitaciones del DSL
(sin bucles, sin `def`, sin `try`, sin `is`). Ver
[`syntax-reference.md`](syntax-reference.md) para el catálogo completo de señales.

---

## P1 · Guardas de `None` y casting seguro

**Cuándo:** siempre, sin excepción, tras cualquier llamada `conversion_*`.
Es la causa número uno de "% de errores de ejecución" en el test del script.

```python
_sales_value = total_conversion_value(_FL_SALES_ID, 0)
if _sales_value == None:
    _sales_value = 0.0
else:
    _sales_value = float(_sales_value)

_item_id = conversion_custom_variable(_FL_SALES_ID, 0, 6)
if _item_id == None:
    _item_id = ""
else:
    _item_id = str(_item_id)
```

No existe `try/except`. No uses `is None`, usa `== None`.

---

## P2 · Panel de control de pesos centralizado

**Cuándo:** en cuanto el script tenga más de un segmento. Separa **qué** se puntúa
(la lógica, estable) de **cuánto** vale (los pesos, lo que se itera semana a semana).

```python
# ==========================================
# --- 1. CONFIGURACIÓN DE IDs ---
# ==========================================
_FL_SALES_ID = 10000001
_FL_CHECKOUT_ID = 10000002

_IOS_PROS = {20000001, 20000002, 20000003}
_IOS_RTG = {30000001, 30000002, 30000003}

_ITEMS_PRIO = {"A101", "A102", "A103"}
_ITEMS_DEST = {"B201", "B202", "B203", "B204", "B205", "B206"}

# ==========================================
# --- PANEL DE CONTROL DE PESOS ---
# ==========================================
_fixed_cpa_prio = 15000      # Puntuación máxima y fija para ventas prioritarias
_weight_pros_other = 1.0    # Peso tROAS para cross-sell en prospecting
_chk_pros_prio = 100         # Valor de checkout en producto prioritario
_chk_pros_dest = 50         # Valor de checkout en producto del destino
_chk_pros_other = 10        # Valor de checkout resto del mundo
_weight_fallback = 0.2      # Paracaídas de seguridad
```

Al iterar solo se tocan los números del panel. El diff entre iteraciones queda legible.

---

## P3 · Extracción de datos en un bloque único

**Cuándo:** siempre. Todas las llamadas a señales arriba, una sola vez, antes del scoring.
No puedes definir funciones, así que centralizar es la única forma de no duplicar.

```python
# ==========================================
# --- 2. EXTRACCIÓN DE DATOS ---
# ==========================================
_sales_count = total_conversion_count(_FL_SALES_ID, 0)
_checkout_count = total_conversion_count(_FL_CHECKOUT_ID, 0)
_sales_value = total_conversion_value(_FL_SALES_ID, 0)

_booked_item_id = conversion_custom_variable(_FL_SALES_ID, 0, 6)
_checkout_item_id = conversion_custom_variable(_FL_CHECKOUT_ID, 0, 6)

if _sales_value == None: _sales_value = 0.0
else: _sales_value = float(_sales_value)

if _booked_item_id == None: _booked_item_id = ""
else: _booked_item_id = str(_booked_item_id)

if _checkout_item_id == None: _checkout_item_id = ""
else: _checkout_item_id = str(_checkout_item_id)

_has_sale = _sales_count > 0
_has_checkout = _checkout_count > 0
```

---

## P4 · tROAS escalonado ("aplanado")

**Cuándo:** el objetivo es revenue pero la distribución tiene cola larga y unas pocas
conversiones caras dominarían el entrenamiento.

En vez de puntuar `_sales_value` en crudo, se aplica un multiplicador por tramos
**acotado**. Multiplicadores agresivos (1.0 → 3.0) hacen explotar el score;
aplanarlos (1.0 → 1.5) estabiliza el modelo.

```python
return max_aggregate([
    ([_has_sale and 0 < _sales_value < 1500],     (1.0 * _sales_value) * _weight),
    ([_has_sale and 1500 <= _sales_value < 3000], (1.2 * _sales_value) * _weight),
    ([_has_sale and 3000 <= _sales_value],        (1.5 * _sales_value) * _weight)
])
```

Alternativa continua, sin tramos, usando la función `log()` del DSL:

```python
if _sales_value > 0:
    _score = log(_sales_value)
else:
    _score = 0.0
```

---

## P5 · CPA fijo (volumen sobre eficiencia)

**Cuándo:** prospecting, o cualquier caso donde importa el **número** de conversiones y no
su importe. Desacopla la puja del precio del producto, lo que da pujas predecibles y
acelera el aprendizaje cuando hay pocas conversiones.

```python
return max_aggregate([
    # Venta en el subconjunto prioritario: score fijo, ignora el precio
    ([_has_sale and _sale_is_priority], _fixed_cpa_prio),

    # Resto de ventas: tROAS aplanado, para no matar la entrega
    ([_has_sale and not _sale_is_priority and 0 < _sales_value < 1500],     (1.0 * _sales_value) * _weight_other),
    ([_has_sale and not _sale_is_priority and 1500 <= _sales_value < 3000], (1.2 * _sales_value) * _weight_other),
    ([_has_sale and not _sale_is_priority and 3000 <= _sales_value],        (1.5 * _sales_value) * _weight_other)
])
```

**Trade-off:** el CPA fijo maximiza volumen y estabiliza el aprendizaje, pero puede pujar
por encima del valor real de conversiones baratas. El tROAS es más eficiente pero fragmenta
los datos por rango de precio y ralentiza el entrenamiento.

---

## P6 · Routing por `insertion_order_id`

**Cuándo:** un mismo algoritmo se comparte entre campañas con objetivos distintos
(prospecting vs. retargeting, mercados distintos). Es la forma de tener un único script
mantenible en lugar de N algoritmos.

```python
if insertion_order_id in _IOS_PROS:
    # Bloque A: prospecting — prioriza volumen
    return max_aggregate([...])

elif insertion_order_id in _IOS_RTG:
    # Bloque B: retargeting — prioriza eficiencia
    return max_aggregate([...])

else:
    # Bloque C: fallback
    return max_aggregate([...])
```

Se puede enrutar igual por `line_item_id`, `advertiser_id` o `country_code`.
Enrutar por IO escala mejor: añadir un LI nuevo dentro de un IO ya cubierto no exige
tocar el script.

---

## P7 · Bloque fallback de seguridad

**Cuándo:** **siempre**. Es la rama `else` final. Sin ella, si alguien asigna el algoritmo
a una campaña no contemplada, el script devuelve un score indefinido o cero y esa campaña
queda ciega.

```python
# ----------------------------------------------------
# BLOQUE C: FALLBACK (seguridad para otras campañas)
# ----------------------------------------------------
else:
    return max_aggregate([
        ([_has_sale and 0 < _sales_value < 1500],     (1.0 * _sales_value) * _weight_fallback),
        ([_has_sale and 1500 <= _sales_value < 3000], (1.2 * _sales_value) * _weight_fallback),
        ([_has_sale and 3000 <= _sales_value],        (1.5 * _sales_value) * _weight_fallback)
    ])
```

El peso del fallback es bajo (p. ej. `0.2`) y **no** puntúa micro-conversiones:
la rama por defecto debe ser conservadora.

Variante aún más estricta, cuando prefieres que una campaña no contemplada quede
completamente fuera del entrenamiento:

```python
else:
    return 0
```

---

## P8 · Segmentación por u-variable (ID de producto)

**Cuándo:** el Floodlight es global y dispara para todo el site, pero solo interesan
las conversiones de un subconjunto de productos. Filtrar por el conteo global de
conversiones puntuaría ventas ajenas a la campaña.

```python
_ITEMS_DEST = {"B201", "B202", "B203", "B204", "B205"}

_booked_item_id = conversion_custom_variable(_FL_SALES_ID, 0, 6)
if _booked_item_id == None: _booked_item_id = ""
else: _booked_item_id = str(_booked_item_id)

_sale_is_dest = _booked_item_id in _ITEMS_DEST
_sale_weight = _weight_rtg_dest if _sale_is_dest else _weight_rtg_other
```

> ⚠️ Los conjuntos son de **strings**: `conversion_custom_variable` devuelve `String`.
> `"A101"` con comillas, nunca `A101` sin ellas ni un entero.

**Punto crítico:** extrae la u-variable **de forma independiente para cada Floodlight**.
El ID de producto de la venta y el del checkout son variables distintas; reutilizar una
para la otra abre el agujero del píxel global (un checkout en cualquier producto del site
acabaría puntuando como si fuera del producto objetivo).

```python
_booked_item_id   = conversion_custom_variable(_FL_SALES_ID, 0, 6)
_checkout_item_id = conversion_custom_variable(_FL_CHECKOUT_ID, 0, 6)
```

---

## P9 · Micro-conversiones de checkout con valor fijo

**Cuándo:** hay *data sparsity* — no llegan suficientes ventas para que el modelo entrene
o para que salga del periodo de aprendizaje.

Se inyecta una señal intermedia (checkout, formulario, add-to-cart) con un valor
**fijo y pequeño**, nunca proporcional al revenue.

```python
if _chk_is_priority:
    _checkout_val = _chk_pros_prio      # 100
elif _chk_is_dest:
    _checkout_val = _chk_pros_dest     # 50
else:
    _checkout_val = _chk_pros_other    # 10

return max_aggregate([
    ([_has_sale and _sale_is_priority], _fixed_cpa_prio),
    ([_has_checkout], _checkout_val)
])
```

Reglas de calibración:

- El valor del checkout debe ser **órdenes de magnitud menor** que el de una venta.
  Si se sobrevalora, el modelo optimiza a micro-conversiones y el ROAS se hunde.
- Punto de partida razonable: ~2% del valor medio de pedido. **Es solo un arranque**:
  en la práctica ese valor suele acabar siendo mucho más bajo tras las primeras semanas.
  Revisa la distribución de scores del test y baja el valor si el checkout compite con la venta.
- Segmenta el valor del checkout igual que la venta, si no el píxel global mete ruido.
- Decide si el peso va **incorporado** en la constante (`_chk_prio = 100`, valores finales) o
  se aplica aparte (`_chk_base * _chk_weight`). Ambas valen, pero mézclalas y acabarás
  aplicando el peso dos veces sin darte cuenta. Elige una y documéntala.
- Requiere que el **Floodlight de checkout esté asignado a los Line Items**; si no,
  `total_conversion_count` devuelve 0 y la señal no existe.
- En ese Floodlight secundario, desmarca **Include in Conversions**: debe alimentar el
  script, no contaminar el reporting de conversiones de negocio.

---

## P10 · Selección de operador ternario para pesos

**Cuándo:** decidir un peso entre dos opciones sin escribir un `if/else` de cuatro líneas.

```python
_sale_weight  = _weight_rtg_dest if _sale_is_dest else _weight_rtg_other
_checkout_val = _chk_rtg_dest    if _chk_is_dest  else _chk_rtg_other
```

---

## P11 · Excluir impresiones del entrenamiento

**Cuándo:** hay un slice contaminado (una fecha con tracking roto, un formato que no
aplica) que no debe entrar en el modelo.

```python
# Excluir una fecha con datos corruptos
if date == 20260711:
    return None

# Entrenar solo con vídeo
if ad_type != 1:
    return None
```

`return None` **excluye**; `return 0` incluye con valor cero. No es lo mismo.

---

## P12 · Señales de calidad de medio

**Cuándo:** el objetivo es branding o no hay volumen de conversión suficiente ni con
micro-conversiones.

```python
return max_aggregate([
    ([active_view_viewed, time_on_screen_seconds >= 10], 3.0),
    ([active_view_viewed, click],                        2.5),
    ([active_view_viewed],                               1.0),
    ([active_view_measurable],                           0.1)
])
```

Para vídeo:

```python
return max_aggregate([
    ([video_completed, audible, viewable_on_complete], 4.0),
    ([video_completed, viewable_on_complete],          3.0),
    ([video_completed],                                2.0),
    ([active_view_viewed],                             1.0)
])
```

---

## P13 · U-variable numérica como score directo

**Cuándo:** la u-variable no es un identificador sino una **magnitud de negocio**
(noches reservadas, unidades, pasajeros, duración del contrato) y esa magnitud *es* el
valor que quieres maximizar.

```python
_uvar = conversion_custom_variable(_FL_ID, 0, _UVAR_IDX)

if _uvar != None and _uvar != "":
    return float(_uvar)
return 0
```

Dos guardas, no una: `conversion_custom_variable` devuelve `None` si no hubo conversión,
pero devuelve **string vacío** si la conversión existe y la variable no venía informada.
`float("")` revienta igual que `float(None)`.

Toda impresión sin conversión —y toda impresión que el modelo de atribución no acredite—
vale 0.

---

## P14 · Ponderar clic frente a post-view

**Cuándo:** una conversión post-clic y una post-view no valen lo mismo, y quieres que el
modelo lo sepa en lugar de tratarlas como el mismo evento.

```python
return sum_aggregate([
    ([click,     total_conversion_count(_FL_ID, 0) > 0], _weight_ct),
    ([not click, total_conversion_count(_FL_ID, 0) > 0], _weight_vt)
])
```

Las dos condiciones son mutuamente excluyentes, así que `sum_aggregate` y `max_aggregate`
dan el mismo resultado. Se usa `sum_aggregate` por convención de la documentación oficial.

Variante para valorar el clic por sí mismo como señal intermedia cuando faltan
conversiones:

```python
return max_aggregate([
    ([click],                                    _weight_click),
    ([total_conversion_count(_FL_ID, 0) > 0],    _weight_conv)
])
```

---

## P15 · Conversiones ponderadas multi-Floodlight

**Cuándo:** hay varias actividades de conversión que valen cosas distintas, y quieres que
el score refleje la **suma** de todo lo que hizo el usuario.

```python
return sum_aggregate([
    ([total_conversion_count(_FL_ID_1, 0) > 0], total_conversion_count(_FL_ID_1, 0) * _w1),
    ([total_conversion_count(_FL_ID_2, 0) > 0], total_conversion_count(_FL_ID_2, 0) * _w2),
    ([total_conversion_count(_FL_ID_3, 0) > 0], total_conversion_count(_FL_ID_3, 0) * _w3)
])
```

Comportamiento de `sum_aggregate` aquí:

- Si una impresión lleva a **conversiones de actividades distintas**, los valores se **suman**.
- Si lleva a **varias conversiones de la misma actividad**, se suma el conteo y luego se
  multiplica por el peso.

Casos de uso típicos:

- Un fabricante de coches con páginas de producto por gama (monovolumen, SUV, berlina),
  cada una con un valor distinto.
- Una ONG cuyo evento de donación es raro: añade actividades de *upper funnel* con pesos
  bajos para generar volumen de señal sin dejar de priorizar la donación.

**Elegir el agregador según la intención:**

| Quieres… | Agregador |
|---|---|
| Acumular todo lo que hizo el usuario | `sum_aggregate` |
| Quedarte con el evento de mayor valor | `max_aggregate` |
| Quedarte con el primero que case, por orden del script | `first_match_aggregate` |

> ⚠️ `sum_aggregate` sobre condiciones **solapables** infla el score y desbalancea el
> modelo. Úsalo solo cuando la acumulación sea intencionada.

---

## P16 · Conversiones ponderadas de GA4

**Cuándo:** el cliente mide en GA4 y no en Floodlight, o quiere usar eventos de embudo
que solo existen en GA4.

Recuerda los prerrequisitos (vinculación GA↔DV360, evento creado, volumen suficiente):
ver `references/syntax-reference.md` § 5.9.

Ponderar tipos de conversión por valor de negocio:

```python
return sum_aggregate([
    ([ga4_conversions_count(123, "one_time_purchase") > 0],  1),
    ([ga4_conversions_count(124, "newsletter_signup")  > 0],  2),
    ([ga4_conversions_count(125, "subscription")       > 0], 10)
])
```

Priorizar la etapa más profunda del embudo alcanzada:

```python
return max_aggregate([
    ([ga4_conversions_count(123, "landing_page")        > 0], 1),
    ([ga4_conversions_count(124, "application_start")   > 0], 5),
    ([ga4_conversions_count(125, "application_summary") > 0], 7),
    ([ga4_conversions_count(126, "application_complete")> 0], 9)
])
```

tROAS directo sobre el valor de transacción de GA4:

```python
return ga4_conversions_total_value(_PROPERTY_ID, "purchase")
```

---

## P17 · Dayparting y formato en campañas de branding

**Cuándo:** campañas de marca, CTV o audio donde no hay conversión que optimizar y la
señal útil es *cuándo* y *cómo* se ve el anuncio.

Por franja horaria (útil en CTV, donde el consumo se concentra en ciertas horas):

```python
return max_aggregate([
    ([0  <= hour_of_day < 7],   _score_a),
    ([7  <= hour_of_day < 9],   _score_b),
    ([9  <= hour_of_day < 18],  _score_c),
    ([18 <= hour_of_day < 22],  _score_b),
    ([22 <= hour_of_day <= 23], _score_a)
])
```

> ⚠️ En **CTV** el scoring basado en `domain` **no está soportado**. Usa `site_id`,
> `app_id` o señales temporales.

Combinando tiempo en pantalla con un formato concreto:

```python
return max_aggregate([
    ([time_on_screen_seconds > 10, creative_width == 300, creative_height == 600], _score_x),
    ([time_on_screen_seconds >= 3, time_on_screen_seconds <= 10,
      creative_width == 300, creative_height == 600],                              _score_y),
    ([time_on_screen_seconds < 3,  creative_width == 300, creative_height == 600], _score_z)
])
```

Audio — maximizar escuchas completas:

```python
return max_aggregate([
    ([audio_completed], _score_a)
])
```

`audio_completed` se registra **una sola vez por impresión**, aunque el usuario reinicie
el clip, y cuenta como completado aunque salte partes, siempre que llegue al final.

---

```python
# [CLIENTE] [MERCADO] - [OBJETIVO] (Iteración N)
# Type: Custom Bidding ([tROAS / CPA / Híbrido])
# Fecha: DD.MM.YYYY

# ==========================================
# --- 1. CONFIGURACIÓN DE IDs ---
# ==========================================
_FL_SALES_ID = 00000000
_FL_CHECKOUT_ID = 00000000

_IOS_PRIMARY = {00000000, 00000000}
_IOS_SECONDARY = {00000000, 00000000}

_ITEMS_PRIORITY = {"0000", "0000"}
_ITEMS_SECONDARY = {"0000", "0000"}

# ==========================================
# --- PANEL DE CONTROL DE PESOS ---
# ==========================================
_weight_priority = 1.5
_weight_other = 0.5
_weight_fallback = 0.2
_checkout_priority = 50
_checkout_other = 15

# ==========================================
# --- 2. EXTRACCIÓN DE DATOS ---
# ==========================================
_sales_count = total_conversion_count(_FL_SALES_ID, 0)
_checkout_count = total_conversion_count(_FL_CHECKOUT_ID, 0)
_sales_value = total_conversion_value(_FL_SALES_ID, 0)

_booked_id = conversion_custom_variable(_FL_SALES_ID, 0, 6)
_checkout_id = conversion_custom_variable(_FL_CHECKOUT_ID, 0, 6)

if _sales_value == None: _sales_value = 0.0
else: _sales_value = float(_sales_value)

if _booked_id == None: _booked_id = ""
else: _booked_id = str(_booked_id)

if _checkout_id == None: _checkout_id = ""
else: _checkout_id = str(_checkout_id)

_has_sale = _sales_count > 0
_has_checkout = _checkout_count > 0

# ==========================================
# --- 3. LÓGICA DE PUNTUACIÓN ---
# ==========================================

# BLOQUE A: funnel primario
if insertion_order_id in _IOS_PRIMARY:
    _sale_is_priority = _booked_id in _ITEMS_PRIORITY
    _chk_is_priority = _checkout_id in _ITEMS_PRIORITY

    _sale_weight = _weight_priority if _sale_is_priority else _weight_other
    _checkout_val = _checkout_priority if _chk_is_priority else _checkout_other

    return max_aggregate([
        ([_has_sale and 0 < _sales_value < 1500],     (1.0 * _sales_value) * _sale_weight),
        ([_has_sale and 1500 <= _sales_value < 3000], (1.2 * _sales_value) * _sale_weight),
        ([_has_sale and 3000 <= _sales_value],        (1.5 * _sales_value) * _sale_weight),
        ([_has_checkout], _checkout_val)
    ])

# BLOQUE B: funnel secundario
elif insertion_order_id in _IOS_SECONDARY:
    _sale_is_secondary = _booked_id in _ITEMS_SECONDARY
    _chk_is_secondary = _checkout_id in _ITEMS_SECONDARY

    _sale_weight = _weight_priority if _sale_is_secondary else _weight_other
    _checkout_val = _checkout_priority if _chk_is_secondary else _checkout_other

    return max_aggregate([
        ([_has_sale and 0 < _sales_value < 1500],     (1.0 * _sales_value) * _sale_weight),
        ([_has_sale and 1500 <= _sales_value < 3000], (1.2 * _sales_value) * _sale_weight),
        ([_has_sale and 3000 <= _sales_value],        (1.5 * _sales_value) * _sale_weight),
        ([_has_checkout], _checkout_val)
    ])

# BLOQUE C: fallback
else:
    return max_aggregate([
        ([_has_sale and 0 < _sales_value < 1500],     (1.0 * _sales_value) * _weight_fallback),
        ([_has_sale and 1500 <= _sales_value < 3000], (1.2 * _sales_value) * _weight_fallback),
        ([_has_sale and 3000 <= _sales_value],        (1.5 * _sales_value) * _weight_fallback)
    ])
```

---

## Checklist antes de guardar

- [ ] Toda llamada `conversion_*` tiene su guarda `== None`.
- [ ] Los conjuntos de u-variables son de **strings**.
- [ ] El ID de producto se extrae **por separado** para cada Floodlight.
- [ ] Existe un bloque `else` de fallback.
- [ ] `max_aggregate` (no `sum_aggregate`) cuando venta y checkout pueden coexistir.
- [ ] El valor del checkout es muy inferior al de la venta.
- [ ] Ningún `for`, `while`, `def`, `try`, `is`, slice ni asignación aumentada.
- [ ] **Check syntax** en verde.
- [ ] **Test your script**: % de errores de ejecución ≈ 0 y % de impresiones con score > 0 razonable.
- [ ] Los Floodlights de ventas **y** de checkout están asignados a los Line Items que usarán el algoritmo.


slack-gif-creatoranthropics/skillsKnowledge and utilities for creating animated GIFs optimized for Slack. Provides constraints, validation tools, and animation concepts. Use when users request animated GIFs for Slack like "make me a GIF of X doing Y for Slack."Stars: 198kUpdated Claude CodeCodexVerifiedInstall
ponytailDietrichGebert/ponytailLazy senior dev mode for any coding task: the smallest change that fully solves it, and a reply a busy human understands in one read.Stars: 194kUpdated Claude CodeCodexVerifiedInstall
ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report.Stars: 194kUpdated Claude CodeCodexVerifiedInstall
ponytail-debtDietrichGebert/ponytailList every `shortcut:` comment (and older `ponytail:` ones) as a debt ledger. One-shot report, changes nothing. Use for "ponytail debt", "what did ponytail defer", "list the shortcuts", /ponytail-debt.Stars: 194kUpdated Claude CodeCodexVerifiedInstall