Skip to content

Scheduled creative activation: activate_at on assign and replace #8746

Open

Description

@bokelley

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 replace to 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 weighted rotation, 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.

  • assign with a future activate_at: the seller records the assignment and reviews the creative for that package, but the creative isn't eligible to serve until activate_at. That's the held assignment, with no separate flag.
  • replace with a future activate_at: the replaced creative keeps serving. At activate_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_at replaces the schedule.
    • Re-sending it without activate_at activates it now.
    • unassign of the scheduled creative cancels it.
  • Readback: get_media_buys creative_approvals[] and list_creatives assigned_packages[] show a pending activation's activate_at, and the actual activated_at once it has happened. A scheduled replace also shows the creative that keeps serving until then.
  • Activation is a seller-side change: it advances the media buy's revision and fires creative.assignment_changed like any assignment change. Delivery reporting splits at the actual activation time.
  • Bounds: activate_at must fall inside the package's flight; otherwise the request fails with VALIDATION_ERROR. A paused package still activates on schedule and serves when it resumes.

Decisions for the working group

  1. 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 wait as the default.

  2. Precision. Should sellers declare a maximum activation skew (for example scheduled_activation.max_skew_seconds), so buyers know how close to activate_at the change lands across ad servers and caches?

  3. 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.

  4. Surfaces. Should activate_at also go on create_media_buy and update_media_buy creative_assignments rows, or only on sync_creatives assignment_operations to start?

  5. 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 scheduled replace or unassign?

  6. 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.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    creativeneeds-wg-reviewBlocked on a working-group decision — surface in WG meeting agendasrfcProtocol change — auto-adds to roadmap boardspec / protocol

    Type

    No type

    Projects

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions