Repository navigation
Description
Problem
A buyer can't schedule when an assignment change takes effect. Every sync_creatives assignment_operations assign or replace applies as soon as the creative is approved for the package. So:
- Timed launches need someone watching the clock. A sale that starts at midnight, a product reveal, an embargo lift, or a game-day creative means a buyer agent has to be running at exactly that moment and send a
replaceto every package on every buy. - There's no "approved but not yet live" state. A buyer that wants creatives reviewed days ahead can't stage them on a package without them serving as soon as they're approved. The only workaround is a weight-0 assignment ("assigned but paused"). That works only under
weightedrotation, and nothing requires sellers to review weight-0 assignments. - Swaps across buys drift. Swapping the same creative across several buys and sellers at one moment depends on the buyer sending many requests at the same time.
Live creative updates (#8488) and replace transferring settings (#8688) cover changing what serves. This covers when it starts.
Proposal: one optional activate_at
Add an optional activate_at (RFC 3339 date-time with an offset) to the assign and replace assignment operations. It is gated on a new capability, creative.supports_scheduled_activation. A seller that doesn't declare it rejects the field with UNSUPPORTED_FEATURE, and buyers MUST NOT send it.
assignwith a futureactivate_at: the seller records the assignment and reviews the creative for that package, but the creative isn't eligible to serve untilactivate_at. That's the held assignment, with no separate flag.replacewith a futureactivate_at: the replaced creative keeps serving. Atactivate_at, the seller performs the replace atomically, transferring the replaced assignment's settings as in fix(creative): replace transfers the replaced assignment's settings #8688.- Omitted, or in the past: applies immediately. That's today's behavior, so nothing changes for buyers who don't send it.
- Rescheduling and cancelling:
- Re-sending the same operation with a different
activate_atreplaces the schedule. - Re-sending it without
activate_atactivates it now. unassignof the scheduled creative cancels it.
- Re-sending the same operation with a different
- Readback:
get_media_buyscreative_approvals[]andlist_creativesassigned_packages[]show a pending activation'sactivate_at, and the actualactivated_atonce it has happened. A scheduledreplacealso shows the creative that keeps serving until then. - Activation is a seller-side change: it advances the media buy's
revisionand firescreative.assignment_changedlike any assignment change. Delivery reporting splits at the actual activation time. - Bounds:
activate_atmust fall inside the package's flight; otherwise the request fails withVALIDATION_ERROR. A paused package still activates on schedule and serves when it resumes.
Decisions for the working group
-
Approval misses the time. What happens if the creative isn't approved for the package by
activate_at?- (a) Wait: activate as soon as it's approved, late.
- (b) Lapse: cancel the activation and notify the buyer.
- (c) Buyer chooses per operation, for example
if_not_approved: "wait" | "lapse".
Late activation is harmless for an evergreen refresh but wrong for a time-boxed promotion, which argues for (c) with
waitas the default. -
Precision. Should sellers declare a maximum activation skew (for example
scheduled_activation.max_skew_seconds), so buyers know how close toactivate_atthe change lands across ad servers and caches? -
Atomicity across packages. Are activations scheduled for the same time on several packages or buys independent, each landing within the skew? Or does the spec promise anything stronger? Independent is the realistic answer across sellers.
-
Surfaces. Should
activate_atalso go oncreate_media_buyandupdate_media_buycreative_assignmentsrows, or only onsync_creativesassignment_operationsto start? -
A matching
deactivate_at. Should an assignment also be able to stop at a time, for a promo that ends at midnight? Or is that covered by package flight dates and a scheduledreplaceorunassign? -
Staged live updates. Should a staged update (feat(creative): live creative updates with staged activation (experimental) #8488) be able to promote at a scheduled time after approval, rather than immediately? Or is that out of scope for the first version?
Testability
A storyboard can drive this if comply_test_controller can trigger due activations without waiting on the clock, for example a force_scheduled_activation scenario or an advanced virtual time. The training agent's assignment_operations support (#8695) is the natural place for the reference implementation.
Background
This replaces #6780. That issue's core, staged activation under the same creative_id, shipped in #8488. Of its remaining items, held assignments are covered here by a future activate_at, and per-product overrides of creative.live_updates are dropped: a dry run answers for one specific change, and no implementer has asked for overrides.
Metadata
Metadata
Assignees
Labels
Type
Projects
- StatusShow more project fieldsNo status
Activity