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?: { [k: string]: unknown };
      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), attention_seconds (attention time per impression), attention_score (vendor-specific attention score). 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 subscribes), 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').

  • 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?: { [k: string]: unknown }

    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 all optimization goals on this package. 1 = highest priority (primary goal); higher numbers are lower priority (secondary signals). When omitted, sellers may use array position as priority.

• {
      kind: "event";
      event_sources: {
          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?: { post_click: Duration; post_view?: Duration };
      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 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.

  • 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 conversions within budget.

  • Optionalattribution_window?: { post_click: Duration; post_view?: Duration }

    Attribution window for this optimization goal. 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 omitted, the seller uses their default window.

    • post_click: Duration

      Post-click attribution window. Conversions within this duration after a click are attributed to the ad (e.g. {"interval": 7, "unit": "days"}).

    • Optionalpost_view?: Duration

      Post-view attribution window. Conversions within this duration after an ad impression (without click) are attributed to the ad (e.g. {"interval": 1, "unit": "days"}).

  • Optionalpriority?: number

    Relative priority among all optimization goals on this package. 1 = highest priority (primary goal); higher numbers are lower priority (secondary signals). When omitted, sellers may use array position as priority.