Type Alias CanonicalFormatHTML5Banner

Type Declaration

• Optionalexperimental?: boolean

  When true, this canonical or seller narrowing may not work as declared. Adopters SHOULD preflight it with validate_input or in a sandbox and SHOULD NOT route production budget without testing; experimental status never makes the deprecated v1 path preferable. Drivers include unsettled spec shape, an adopter runtime gap, and custom shapes awaiting promotion. This replaces the earlier status plus runtime_status axes. Sellers SHOULD set experimental whenever a canonical or declaration is not production-ready.

• Optionaldeprecated?: boolean

  When true, this canonical (or a seller's specific narrowing of it) is going away. Existing adopters are supported through the deprecation cycle; new adoption is discouraged. Pair with migration_target_version to indicate when the canonical is expected to be removed. Distinct from experimental: an experimental canonical may stabilize and stop being experimental; a deprecated canonical is on a sunset path.

• Optionalv1_translatable?: boolean

  Whether this canonical has any v1 named-format equivalent. true (default) — the canonical is structurally expressible as one or more v1 named formats (IAB display sizes, VAST tags, DAAST tags, etc.); v1→v2 projection via v1-canonical-mapping.json is meaningful. false — the canonical is inherently new in v2 and has no v1 form; v1's list_creative_formats couldn't express it because the underlying concept (algorithmic surface composition, AI-surface mentions, retail-media catalog placements, multi-card carousels) didn't exist as a v1 named-format archetype.

  Lets SDKs distinguish two failure modes that today look identical: (a) the registry hasn't covered this canonical yet (correctable — seller adds explicit canonical field or files a registry entry) vs (b) no v1 path is possible (informational — buyer needs v2-aware consumption, or seller declares canonical_formats_only: true on the product declaration). SDKs encountering v1_translatable: false on a canonical SHOULD NOT emit FORMAT_PROJECTION_FAILED (which signals registry-coverage gap) — instead surface the inherent v1-unreachability as a different diagnostic or skip silently. The 4 inherently-v2 canonicals at 3.1 GA: image_carousel, sponsored_placement, responsive_creative, agent_placement.

• Optionalsince_version?: string

  AdCP MAJOR.MINOR version that introduced this canonical (e.g., '3.1', '3.2'). Lets adopters reason about minimum protocol version requirements when consuming a format declaration. Patch precision is intentionally rejected — canonicals are introduced at minor-version boundaries.

• Optionalmigration_target_version?: string

  AdCP MAJOR.MINOR version by which the working group expects this canonical to stabilize, surface a breaking revision, or (when deprecated: true) be removed. Patch precision is intentionally rejected — canonicals shift at minor-version boundaries. Absence signals 'no specific target' (omit the field rather than use a placeholder like 'unknown').

• Optionalcomposition_model?: "deterministic" | "algorithmic"

  Whether the surface composes deterministically (buyer can predict per-slot rendering — sponsored_placement, image, video) or algorithmically (surface chooses combinations or phrasing — responsive_creative, agent_placement).

• Optionalprovenance_required?: boolean

  When true, the product rejects unsigned synthesized assets. Builders calling build_creative MUST attach a C2PA-compatible provenance manifest attributing synthesis to the creative agent.

• Optionalplatform_extensions?: PlatformExtensionReference[]

  Platform-specific extensions narrowing the canonical (pixel ID shapes, conversion event taxonomies, platform-specific CTAs/destinations). Each extension is a URI+digest reference resolved against the bundled extensions map in get_products responses or fetched directly.

  Collision precedence (normative). When two or more platform_extensions[] entries on the same declaration extend the same target (e.g., both extend tracking) with overlapping field names, array order is authoritative — later entries override earlier ones on a per-field basis (last-in-array-wins). SDKs MUST surface the overlap via the errors[] array on the get_products response with a structured code (FORMAT_DECLARATION_DIVERGENT is appropriate when the overlap appears across dual-emitted shapes; a producer-self-emitted overlap on a single declaration SHOULD use the same code with error.details: { collision_kind: "platform_extension_field", target, overlapping_fields, winning_extension_uri }). Producers SHOULD avoid the collision by emitting one extension per target or by partitioning fields across extensions; the deterministic precedence is for last-resort consistency across SDK implementations, not a sanctioned merging strategy.

• Optionalsynthesis_nondeterministic?: boolean

  When true, the format's production pipeline is genuinely nondeterministic — the platform cannot guarantee that synthesis from a given input set produces in-spec output. Veo / Sora / Runway-class generative video, and other AI-synthesis flows where output dimensions, duration, or quality vary per run. Implies a different validation contract: predictive validate_input is impossible; the platform's own post-synthesis QA loop applies; if the QA loop exhausts without producing a valid artifact, build_creative returns task_failed with a synthesis_failed reason. Distinct from composition_model (which describes how the surface composes per-slot rendering, not whether synthesis is deterministic). When false or absent, the format's production is predictable enough that validate_input can predict output properties from input properties.

  Compatibility with asset_source / item_production_model: synthesis_nondeterministic: true MAY pair with any of seller_pre_rendered_from_brief, seller_human_designed, or agent_synthesized (the QA loop is concept-level, not source-specific — 'seller renders from brief but each retry differs' is just as nondeterministic as Veo). It MUST NOT pair with buyer_uploaded (the buyer ships pre-rendered bytes; there's no synthesis step to be nondeterministic about). It MUST NOT pair with publisher_host_recorded (the publisher's host produces a deterministic-from-script output even if the human voice varies). When synthesis_nondeterministic: true is set with an incompatible source, validators SHOULD reject with a structured error.

• Optionalslots?: {
      asset_group_id: string;
      asset_type:
          | "image"
          | "video"
          | "audio"
          | "text"
          | "markdown"
          | "url"
          | "html"
          | "css"
          | "javascript"
          | "vast"
          | "daast"
          | "webhook"
          | "brief"
          | "catalog"
          | "published_post"
          | "zip"
          | "card"
          | "object"
          | "pixel_tracker"
          | "vast_tracker"
          | "daast_tracker";
      required?: boolean;
      min?: number;
      max?: number;
      max_chars?: number;
      max_size_kb?: number;
      pixel_ratios?: number[];
      required_pixel_ratios?: number[];
      logo_slots?: LogoSlot[];
      required_logo_slots?: LogoSlot[];
      description?: string;
      consumed_for_production?: boolean;
  }[]

  Default slots for html5 canonical. Buyer ships a zip bundle plus optional backup image (required when backup_image_required: true) and clickthrough URL. The zip's entry point is typically index.html; click handling uses the clickTag (or clickTAG) macro substituted by the seller at serve time.

• Optionalrequired_connections?: DownstreamConnectionRequirement[]

  Downstream platform connections or grants required to use this format declaration. These are in addition to the single AdCP caller credential. Use this when a platform product requires multiple downstream grants, such as an advertiser account connection plus a publisher identity or post authorization for published-post references.

• Optionalreference_mutability?: "immutable_snapshot" | "mutable_requires_reapproval" | "mutable_auto_recheck"

  Policy for formats whose slots accept a published_post reference. immutable_snapshot: seller snapshots the referenced post at approval and later source changes do not change the served creative. mutable_requires_reapproval: the source post may change and material changes require review before continued serving. mutable_auto_recheck: the source post may change and the seller continuously or periodically rechecks authorization/policy without requiring buyer resubmission. Omit when the format has no published_post slot.

• Optionalproduction_window_business_days?: number

  Typical production turnaround in business days when the format requires seller-side production (e.g., host-recording from a buyer-supplied script). 0 for synchronous (e.g., generative AI); >0 for human-produced (e.g., podcast host-read). Absent when no production is required (buyer uploads complete creative).

• Optionalwidth?: number

  Required banner width in pixels — use for fixed-size slots. For multi-size flexible slots use sizes[]; for responsive use min_width/max_width/min_height/max_height. Exactly one of (width, height), sizes[], or min/max_width + min/max_height ranges MUST be set.

  Minimum

  1

• Optionalheight?: number

  Required banner height in pixels. See width for size-mode mutual exclusion.

  Minimum

  1

• Optionalsizes?: { width: number; height: number }[]

  List of accepted (width, height) pairs for a multi-size flexible slot (publisher banner that accepts 300×250 OR 728×90 OR 970×250). Mirrors OpenRTB banner.format[]. Mutually exclusive with (width, height) and with responsive ranges.

• Optionalmin_width?: number

  Minimum accepted width for responsive HTML5 banners that adapt within a range. Pair with max_width. Mutually exclusive with (width, height) and sizes[].

  Minimum

  1

• Optionalmax_width?: number

  Maximum accepted width for responsive HTML5 banners. Pair with min_width.

  Minimum

  1

• Optionalmin_height?: number

  Minimum accepted height for responsive HTML5 banners. Pair with max_height.

  Minimum

  1

• Optionalmax_height?: number

  Maximum accepted height for responsive HTML5 banners. Pair with min_height.

  Minimum

  1

• Optionalmax_initial_load_kb?: number

  Maximum initial-load file size (zip + above-the-fold assets) in kilobytes. IAB display standards: 200 KB for fixed sizes, 100 KB for mobile.

  Minimum

  1

• Optionalmax_polite_load_kb?: number

  Maximum polite-load file size after host-initiated subload, in kilobytes. IAB display standards: 500 KB for fixed sizes.

  Minimum

  1

• Optionalhost_initiated_subload?: boolean

  Whether the host page must initiate the polite-load phase. IAB-compliant banners require true.

• Optionalmax_animation_duration_ms?: number

  Maximum total animation duration in milliseconds. IAB standard: 30000 (30 seconds).

  Minimum

  0

• Optionalmax_cpu_load_percent?: number

  Maximum CPU load percentage during render.

  Minimum

  1

  Maximum

  100

• Optionalmraid_required?: boolean

  Whether MRAID compatibility is required (mobile in-app).

• Optionalmraid_version?: "2.0" | "3.0"

  Required MRAID version when mraid_required is true.

• Optionalom_sdk_required?: boolean

  Whether IAB Open Measurement SDK integration is required.

• Optionalclicktag_macro?: "clickTag" | "clickTAG"

  Name of the click-tag macro the bundle must use.

• Optionalbackup_image_required?: boolean

  Whether a backup image must accompany the zip for non-HTML5 environments.

• Optionalbackup_image_max_size_kb?: number

  Maximum backup image file size in kilobytes.

  Minimum

  1

• Optionalssl_required?: boolean