@adcp/sdk API Reference - v10.0.1
    Preparing search index...

    Type Alias Placement

    Placement: { [k: string]: unknown } & {
        kind: "publisher_ref" | "seller_inline";
        placement_id: string;
        publisher_domain?: string;
        name?: string;
        description?: string;
        mode: "targetable" | "included";
        tags?: string[];
        format_ids?: FormatReferenceStructuredObject[];
        format_options?: ProductFormatDeclaration[];
        video_placement_types?: VideoPlacementType[];
        audio_distribution_types?: AudioDistributionType[];
        sponsored_placement_types?: SponsoredPlacementType[];
        social_placement_surfaces?: SocialPlacementSurface[];
    }

    Represents a specific public ad placement within a product's inventory. Placement IDs are scoped by publisher domain, matching placement definitions in that publisher's adagents.json. kind is the structural discriminator: publisher_ref means this product placement is a reference to {publisher_domain, placement_id}; seller_inline means the seller is defining public buyer-facing placement metadata inline. The schema accepts either name or publisher_domain because publisher-referenced placements can omit name only when the publisher declaration supplies it; seller-inline placements carry name directly. Whether a reference was resolved from publisher-hosted adagents.json or a community-maintained fallback is resolver metadata, not placement structure. Buyers reference placements in creative assignments with structured PlacementRef objects (publisher_domain + placement_id) when a product spans multiple publishers or the namespace is otherwise ambiguous. Reusing a registered placement preserves the registry's semantic identity; product-level placement objects may narrow format_ids/format_options or add operational detail, but SHOULD NOT redefine the placement's meaning incompatibly.

    Type Declaration

    • [k: string]: unknown
    • kind: "publisher_ref" | "seller_inline"

      Placement structure discriminator. publisher_ref identifies a placement by {publisher_domain, placement_id} and resolves public metadata from the named publisher's adagents.json placement declarations; seller_inline identifies buyer-facing placement metadata defined inline by the sales agent (still in the named publisher namespace when publisher_domain is present, or the seller's own namespace in legacy single-publisher contexts).

    • placement_id: string

      Placement identifier in the publisher namespace. When publisher_domain is present, this matches a placement ID in that publisher's adagents.json catalog or a seller-defined inline placement in that publisher namespace. Buyers use this with publisher_domain in creative_assignments[].placement_refs; legacy creative_assignments[].placement_ids strings are only unambiguous in single-publisher contexts.

    • Optionalpublisher_domain?: string

      Publisher domain whose adagents.json placement declarations define this placement. Required for kind: "publisher_ref". Omitted only for kind: "seller_inline" in legacy single-publisher seller contexts where the seller agent's own publisher domain is the namespace.

      ^a-z0-9?(.a-z0-9?)*$

    • Optionalname?: string

      Human-readable name for the placement (e.g., 'Homepage Banner', 'Article Sidebar'). Required for kind: "seller_inline". May be omitted for publisher-referenced placements because buyers resolve the name from the publisher declaration identified by {publisher_domain, placement_id}.

    • Optionaldescription?: string

      Detailed description of where and how the placement appears

    • mode: "targetable" | "included"

      Required product-level relationship to this placement. targetable means the buyer may reference this placement_id when assigning creatives or otherwise selecting placements within the product. included means the placement is part of the product's public delivery composition but the buyer cannot cherry-pick it by placement_id. During the migration window ending 2026-11-25, buyers MAY tolerate legacy products that omit mode and treat them as targetable; after that date buyers SHOULD fail closed. Seller-private delivery objects MUST NOT be exposed here; keep those mappings in seller-internal systems.

    • Optionaltags?: string[]

      Optional tags for grouping placements within a product (e.g., 'homepage', 'native', 'premium'). When the placement_id comes from the publisher registry, these should align with the registry tags unless the product is narrowing scope.

    • Optionalformat_ids?: FormatReferenceStructuredObject[]

      Format IDs supported by this specific placement. Can include: (1) concrete format_ids (fixed dimensions), (2) template format_ids without parameters (accepts any dimensions/duration), or (3) parameterized format_ids (specific dimension/duration constraints). When present on a product placement, this field narrows the product-level format_ids contract for this placement and MUST NOT introduce formats the product does not accept.

    • Optionalformat_options?: ProductFormatDeclaration[]

      3.1+ canonical format-option declarations supported by this specific product placement. When present, this field narrows the product-level format_options contract for this placement and MUST NOT introduce formats the product does not accept. Buyers compute the effective accepted formats for a placement as the intersection of product-level and placement-level declarations; placements without a format declaration inherit the product-level formats.

    • Optionalvideo_placement_types?: VideoPlacementType[]

      Declared video placement types for this product placement, using IAB Tech Lab/OpenRTB 2.6 video.plcmt definitions with AdCP-native names. Most concrete placements SHOULD declare a single value; aggregate placements MAY declare multiple values. This is seller-declared discovery metadata, not independent verification of inventory quality or delivery context.

    • Optionalaudio_distribution_types?: AudioDistributionType[]

      Declared audio distribution types for this product placement, using IAB Tech Lab/OpenRTB 2.6 audio.feed definitions with AdCP-native names. Most concrete placements SHOULD declare a single value; aggregate placements MAY declare multiple values. This is seller-declared discovery metadata, not independent verification of inventory quality or delivery context.

    • Optionalsponsored_placement_types?: SponsoredPlacementType[]

      Declared sponsored-placement types for this product placement, distinguishing where the catalog-driven retail-media placement renders on the retailer surface. Most concrete placements SHOULD declare a single value; aggregate placements MAY declare multiple values. This is seller-declared discovery metadata, not independent verification of inventory quality or delivery context.

    • Optionalsocial_placement_surfaces?: SocialPlacementSurface[]

      Declared social-placement surfaces for this product placement, distinguishing the in-app surface where the social placement renders. Most concrete placements SHOULD declare a single value; aggregate placements MAY declare multiple values. This is seller-declared discovery metadata, not independent verification of inventory quality or delivery context.

    Settings

    Member Visibility