Type Alias OptimizationGoal

Type Declaration

• {
      kind: "metric";
      metric:
          | "clicks"
          | "views"
          | "completed_views"
          | "viewed_seconds"
          | "attention_seconds"
          | "attention_score"
          | "engagements"
          | "follows"
          | "saves"
          | "profile_visits"
          | "reach";
      reach_unit?: ReachUnit;
      target_frequency?: {}
      | {};
      view_duration_seconds?: number;
      target?:
          | { kind: "cost_per"; value: number }
          | { kind: "threshold_rate"; value: number };
      priority?: number;
  }

  • kind: "metric"

  • metric:
        | "clicks"
        | "views"
        | "completed_views"
        | "viewed_seconds"
        | "attention_seconds"
        | "attention_score"
        | "engagements"
        | "follows"
        | "saves"
        | "profile_visits"
        | "reach"

    Seller-native metric to optimize for. Delivery metrics: clicks (link clicks, swipe-throughs, CTA taps that navigate away), views (viewable impressions), completed_views (video/audio completions — see view_duration_seconds), reach (unique audience reach — see reach_unit and target_frequency). Duration/score metrics: viewed_seconds (time in view per impression — reported back via delivery-metrics.viewability.viewed_seconds, governed by the viewability standard). Audience action metrics: engagements (any direct interaction with the ad unit beyond viewing — social reactions/comments/shares, story/unit opens, interactive overlay taps, companion banner interactions on audio and CTV), follows (new followers, page likes, artist/podcast/channel follows, or free channel/feed subscribes; paid subscriptions use event_type: subscribe), saves (saves, bookmarks, playlist adds, pins — signals of intent to return), profile_visits (visits to the brand's in-platform page — profile, artist page, channel, or storefront. Does not include external website clicks, which are covered by 'clicks'). DEPRECATED values (slated for removal at next major): attention_seconds and attention_score — these have no industry-graduated definition (DoubleVerify, IAS, Adelaide, TVision, Lumen each define them differently) and cannot be meaningfully optimized for without a vendor binding. Use kind: 'vendor_metric' with an explicit vendor and metric_id instead — that path binds the goal to a specific measurement vendor and reconciles to the same (vendor, metric_id) key in delivery's vendor_metric_values[]. Sellers MAY reject the deprecated values with TERMS_REJECTED and a suggestion to use the vendor_metric kind.

  • Optionalreach_unit?: ReachUnit

    Unit for reach measurement. Required when metric is 'reach'. Must be a value declared in the product's metric_optimization.supported_reach_units.

  • Optionaltarget_frequency?: {} | {}

    Target frequency band for reach optimization. Only applicable when metric is 'reach'. Frames frequency as an optimization signal: the seller should treat impressions toward entities already within the [min, max] band as lower-value, and impressions toward unreached entities as higher-value. This shifts budget toward fresh reach rather than re-reaching known users. When omitted, the seller maximizes unique reach without a frequency constraint. A hard cap can still be layered via targeting_overlay.frequency_cap if a ceiling is needed.

  • Optionalview_duration_seconds?: number

    Minimum video view duration in seconds that qualifies as a completed_view for this goal. Only applicable when metric is 'completed_views'. When omitted, the seller uses their platform default (typically 2–15 seconds). Common values: 2 (Snap/LinkedIn default), 6 (TikTok), 15 (Snap 15-second views, Meta ThruPlay). Sellers declare which durations they support in metric_optimization.supported_view_durations. Sellers must reject goals with unsupported values — silent rounding would create measurement discrepancies.

  • Optionaltarget?: { kind: "cost_per"; value: number } | { kind: "threshold_rate"; value: number }

    Target for this metric. When omitted, the seller optimizes for maximum metric volume within budget.

  • Optionalpriority?: number

    Relative priority among sibling goals. Lower numbers rank first. Goals without priority follow explicitly prioritized goals. Ties use array order, so the earliest goal at the lowest explicit priority is primary; when all priorities are omitted, the first goal is primary.

• {
      kind: "event";
      event_sources: [
          {
              event_source_id: string;
              event_type: EventType;
              custom_event_name?: string;
              value_field?: string;
              value_factor?: number;
          },
          ...{
              event_source_id: string;
              event_type: EventType;
              custom_event_name?: string;
              value_field?: string;
              value_factor?: number;
          }[],
      ];
      target?: | { kind: "cost_per"; value: number }
      | { kind: "per_ad_spend"; value: number }
      | { kind: "maximize_value" };
      attribution_window?: AttributionWindow;
      priority?: number;
  }

  • kind: "event"

  • event_sources: [
        {
            event_source_id: string;
            event_type: EventType;
            custom_event_name?: string;
            value_field?: string;
            value_factor?: number;
        },
        ...{
            event_source_id: string;
            event_type: EventType;
            custom_event_name?: string;
            value_field?: string;
            value_factor?: number;
        }[],
    ]

    Event source and type pairs that feed this goal. Each entry identifies a source and event type to include. When the seller supports multi_source_event_dedup (declared in get_adcp_capabilities), they deduplicate by event_id across all entries — the same business event from multiple sources counts once, using value_field and value_factor from the first matching entry. When multi_source_event_dedup is false or absent, buyers should use a single entry per goal; the seller will use only the first entry. All event sources must be configured via sync_event_sources.

    Min Items

    1

  • Optionaltarget?:
        | { kind: "cost_per"; value: number }
        | { kind: "per_ad_spend"; value: number }
        | { kind: "maximize_value" }

    Target cost or return for this event goal. When omitted, the seller optimizes for maximum conversion count within budget — regardless of whether value_field is present on event sources. The presence of value_field alone does not change the optimization objective; it only makes value available for reporting. An explicit target of maximize_value or per_ad_spend is required to steer toward value.

  • Optionalattribution_window?: AttributionWindow

    Attribution window for this optimization goal — references the canonical attribution-window shape (post_click, post_view, model). Values must match an option declared in the seller's conversion_tracking.attribution_windows capability. Sellers MUST reject windows not in their declared capabilities. When the entire field is omitted, the seller uses their default window.

  • Optionalpriority?: number

    Relative priority among sibling goals. Lower numbers rank first. Goals without priority follow explicitly prioritized goals. Ties use array order, so the earliest goal at the lowest explicit priority is primary; when all priorities are omitted, the first goal is primary.

• {
      kind: "vendor_metric";
      vendor: BrandReference;
      metric_id: VendorMetricID;
      target?:
          | { kind: "cost_per"; value: number }
          | { kind: "threshold_rate"; value: number };
      priority?: number;
  }

  • kind: "vendor_metric"

  • vendor: BrandReference

  • metric_id: VendorMetricID

  • Optionaltarget?: { kind: "cost_per"; value: number } | { kind: "threshold_rate"; value: number }

    Target for this vendor metric. When omitted, the seller optimizes for maximum metric volume / score within budget. cost_per and threshold_rate semantics mirror the same target kinds on the metric kind — units are vendor-defined and depend on the vendor's measurement.metrics[] declaration for this metric_id.

  • Optionalpriority?: number

    Relative priority among sibling goals. Lower numbers rank first. Goals without priority follow explicitly prioritized goals. Ties use array order, so the earliest goal at the lowest explicit priority is primary; when all priorities are omitted, the first goal is primary.