Class: WhopSDK::Resources::AdGroups

Inherits:
Object
  • Object
show all
Defined in:
lib/whop_sdk/resources/ad_groups.rb,
sig/whop_sdk/resources/ad_groups.rbs

Overview

An Ad Group sits inside an ad campaign and controls delivery for ads. It sets the audience, placements, schedule, budget, and optimization goal for its ads.

Use the Ad Groups API to create ad groups in campaigns, list or retrieve targeting and delivery settings, update budgets or targeting, delete groups that should stop running, and pause or resume delivery.

Instance Method Summary collapse

Constructor Details

#initialize(client:) ⇒ AdGroups

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Returns a new instance of AdGroups.

Parameters:



293
294
295
 
# File 'lib/whop_sdk/resources/ad_groups.rb', line 293

def initialize(client:)
  @client = client
end

Instance Method Details

#create(ad_campaign_id:, audiences: nil, bid_type: nil, budget_amount: nil, budget_type: nil, conversion_event: nil, conversion_location: nil, demographics: nil, desired_cost_per_result: nil, devices: nil, dynamic_creative: nil, ends_at: nil, frequency_cap: nil, languages: nil, message_apps: nil, minimum_daily_spend: nil, optimization_goal: nil, placements: nil, regions: nil, starts_at: nil, status: nil, title: nil, request_options: {}) ⇒ WhopSDK::Models::AdGroup

Some parameter documentations has been truncated, see Models::AdGroupCreateParams for more details.

Creates an ad group (ad set) in a campaign.

Parameters:

  • ad_campaign_id (String) —

    The ad campaign to create the ad group in.

  • audiences (Object) —

    Saved-audience targeting: { include, exclude } arrays of audience IDs. Incompati

  • bid_type (Symbol, WhopSDK::Models::AdGroupCreateParams::BidType) —

    Bid strategy.

  • budget_amount (Float) —

    Ad-set budget in dollars (ABO only; omit under CBO).

  • budget_type (Symbol, WhopSDK::Models::AdGroupCreateParams::BudgetType) —

    Whether the budget is daily or lifetime.

  • conversion_event (Symbol, String, WhopSDK::Models::AdGroupCreateParams::ConversionEvent, nil) —

    The pixel event optimized for. A standard event, or any custom pixel event name.

  • conversion_location (Symbol, WhopSDK::Models::AdGroupCreateParams::ConversionLocation) —

    Where results happen: website (conversions), profile (IG/FB engagement), messagi

  • demographics (Object) —

    Demographic targeting: { automatic, minimum_age, maximum_age, gender }.

  • desired_cost_per_result (Float) —

    Target/cap cost for average_target / maximum_target.

  • devices (Object) —

    Device targeting: { platforms, operating_systems: [{ os, minimum_version }] }.

  • dynamic_creative (Boolean) —

    Run Meta dynamic (Advantage+) creative for this ad set. Set at creation; immutab

  • ends_at (String) —

    Schedule end, ISO 8601.

  • frequency_cap (Object) —

    { maximum_impressions, per_days } — only valid for reach optimization.

  • languages (Array<String>) —

    Languages to target as ISO 639 codes (e.g. en, es). Empty/omitted = all language

  • message_apps (Array<Symbol, WhopSDK::Models::AdGroupCreateParams::MessageApp>) —

    Required when conversion_location is messaging: which apps to message on. Combin

  • minimum_daily_spend (Float) —

    Daily spend floor within the budget.

  • optimization_goal (String) —

    What the ad group optimizes for (e.g. conversions, link_clicks, reach).

  • placements (Object) —

    'automatic' (Advantage+) or a list of { platform, positions }. Omit positions to

  • regions (Object) —

    Geo targeting: { include / exclude: { countries (ISO 3166-1), regions (states/pr

  • starts_at (String) —

    Schedule start, ISO 8601.

  • status (Symbol, WhopSDK::Models::AdGroupCreateParams::Status) —

    Initial status (default: active).

  • title (String) —

    The display name of the ad group.

  • request_options (WhopSDK::RequestOptions, Hash{Symbol=>Object}, nil)

Returns:

See Also:



70
71
72
73
74
75
76
77
78
79
 
# File 'lib/whop_sdk/resources/ad_groups.rb', line 70

def create(params)
  parsed, options = WhopSDK::AdGroupCreateParams.dump_request(params)
  @client.request(
    method: :post,
    path: "ad_groups",
    body: parsed,
    model: WhopSDK::AdGroup,
    options: options
  )
end

#delete(id, request_options: {}) ⇒ Boolean

Deletes an ad group. Returns true on success.

Parameters:

  • id (String) —

    The ad group ID.

  • request_options (WhopSDK::RequestOptions, Hash{Symbol=>Object}, nil)
  • request_options: (WhopSDK::request_opts)

Returns:

  • (Boolean)

See Also:



241
242
243
244
245
246
247
248
 
# File 'lib/whop_sdk/resources/ad_groups.rb', line 241

def delete(id, params = {})
  @client.request(
    method: :delete,
    path: ["ad_groups/%1$s", id],
    model: WhopSDK::Internal::Type::Boolean,
    options: params[:request_options]
  )
end

#list(account_id: nil, ad_campaign_id: nil, after: nil, before: nil, created_after: nil, created_before: nil, direction: nil, first: nil, last: nil, order: nil, query: nil, stats_from: nil, stats_to: nil, status: nil, time_zone: nil, request_options: {}) ⇒ WhopSDK::Internal::CursorPage<WhopSDK::Models::AdGroup>

Some parameter documentations has been truncated, see Models::AdGroupListParams for more details.

Lists ad groups for the account, newest first.

Parameters:

  • account_id (String) —

    Account whose ad groups to list. Defaults to the authenticated account.

  • ad_campaign_id (String) —

    Filter to ad groups in this campaign.

  • after (String) —

    Cursor to fetch the page after (from page_info.end_cursor).

  • before (String) —

    Cursor to fetch the page before (from page_info.start_cursor).

  • created_after (String) —

    Only return ad groups created after this timestamp.

  • created_before (String) —

    Only return ad groups created before this timestamp.

  • direction (Symbol, WhopSDK::Models::AdGroupListParams::Direction) —

    The sort direction. Defaults to desc.

  • first (Integer) —

    The number of ad groups to return.

  • last (Integer) —

    The number of ad groups to return from the end of the range.

  • order (Symbol, WhopSDK::Models::AdGroupListParams::Order) —

    The field to sort by. Defaults to created_at. Stat columns (spend, impressions,

  • query (String) —

    Filter ad groups by a title or ID substring.

  • stats_from (String) —

    Start of the stats window. Defaults to all-time.

  • stats_to (String) —

    End of the stats window. Defaults to now.

  • status (String) —

    Filter to a status (active, paused, in_review, rejected).

  • time_zone (String) —

    IANA timezone (e.g. America/New_York) the stats window is interpreted in. Bare s

  • request_options (WhopSDK::RequestOptions, Hash{Symbol=>Object}, nil)

Returns:

See Also:



217
218
219
220
221
222
223
224
225
226
227
228
 
# File 'lib/whop_sdk/resources/ad_groups.rb', line 217

def list(params = {})
  parsed, options = WhopSDK::AdGroupListParams.dump_request(params)
  query = WhopSDK::Internal::Util.encode_query_params(parsed)
  @client.request(
    method: :get,
    path: "ad_groups",
    query: query,
    page: WhopSDK::Internal::CursorPage,
    model: WhopSDK::AdGroup,
    options: options
  )
end

#pause(id, request_options: {}) ⇒ WhopSDK::Models::AdGroup

Pauses delivery of an ad group.

Parameters:

Returns:

See Also:



261
262
263
264
265
266
267
268
 
# File 'lib/whop_sdk/resources/ad_groups.rb', line 261

def pause(id, params = {})
  @client.request(
    method: :post,
    path: ["ad_groups/%1$s/pause", id],
    model: WhopSDK::AdGroup,
    options: params[:request_options]
  )
end

#retrieve(id, stats_from: nil, stats_to: nil, time_zone: nil, request_options: {}) ⇒ WhopSDK::Models::AdGroup

Retrieves a single ad group.

Parameters:

  • id (String) —

    The ad group ID.

  • stats_from (String) —

    Start of the stats window.

  • stats_to (String) —

    End of the stats window.

  • time_zone (String) —

    IANA timezone the stats window is interpreted in. Defaults to UTC.

  • request_options (WhopSDK::RequestOptions, Hash{Symbol=>Object}, nil)

Returns:

See Also:



98
99
100
101
102
103
104
105
106
107
108
 
# File 'lib/whop_sdk/resources/ad_groups.rb', line 98

def retrieve(id, params = {})
  parsed, options = WhopSDK::AdGroupRetrieveParams.dump_request(params)
  query = WhopSDK::Internal::Util.encode_query_params(parsed)
  @client.request(
    method: :get,
    path: ["ad_groups/%1$s", id],
    query: query,
    model: WhopSDK::AdGroup,
    options: options
  )
end

#unpause(id, request_options: {}) ⇒ WhopSDK::Models::AdGroup

Resumes delivery of a paused ad group.

Parameters:

Returns:

See Also:



281
282
283
284
285
286
287
288
 
# File 'lib/whop_sdk/resources/ad_groups.rb', line 281

def unpause(id, params = {})
  @client.request(
    method: :post,
    path: ["ad_groups/%1$s/unpause", id],
    model: WhopSDK::AdGroup,
    options: params[:request_options]
  )
end

#update(id, audiences: nil, bid_type: nil, budget_amount: nil, budget_type: nil, conversion_event: nil, conversion_location: nil, demographics: nil, desired_cost_per_result: nil, devices: nil, ends_at: nil, frequency_cap: nil, languages: nil, message_apps: nil, minimum_daily_spend: nil, optimization_goal: nil, placements: nil, regions: nil, starts_at: nil, status: nil, title: nil, request_options: {}) ⇒ WhopSDK::Models::AdGroup

Some parameter documentations has been truncated, see Models::AdGroupUpdateParams for more details.

Updates an ad group's editable fields. Only the keys you send are changed.

Parameters:

  • id (String) —

    The ad group ID.

  • audiences (Object) —

    Saved-audience targeting: { include, exclude } arrays of audience IDs. Incompati

  • bid_type (Symbol, WhopSDK::Models::AdGroupUpdateParams::BidType) —

    Bid strategy.

  • budget_amount (Float) —

    Ad-set budget in dollars (ABO only; omit under CBO).

  • budget_type (Symbol, WhopSDK::Models::AdGroupUpdateParams::BudgetType) —

    Whether the budget is daily or lifetime.

  • conversion_event (Symbol, String, WhopSDK::Models::AdGroupUpdateParams::ConversionEvent, nil) —

    The pixel event optimized for. A standard event, or any custom pixel event name.

  • conversion_location (Symbol, WhopSDK::Models::AdGroupUpdateParams::ConversionLocation) —

    Where results happen: website (conversions), profile (IG/FB engagement), messagi

  • demographics (Object) —

    Demographic targeting: { automatic, minimum_age, maximum_age, gender }.

  • desired_cost_per_result (Float) —

    Target/cap cost for average_target / maximum_target.

  • devices (Object) —

    Device targeting: { platforms, operating_systems: [{ os, minimum_version }] }.

  • ends_at (String) —

    Schedule end, ISO 8601.

  • frequency_cap (Object) —

    { maximum_impressions, per_days } — only valid for reach optimization.

  • languages (Array<String>) —

    Languages to target as ISO 639 codes (e.g. en, es). Empty/omitted = all language

  • message_apps (Array<Symbol, WhopSDK::Models::AdGroupUpdateParams::MessageApp>) —

    Required when conversion_location is messaging: which apps to message on. Combin

  • minimum_daily_spend (Float) —

    Daily spend floor within the budget.

  • optimization_goal (String) —

    What the ad group optimizes for (e.g. conversions, link_clicks, reach).

  • placements (Object) —

    'automatic' (Advantage+) or a list of { platform, positions }. Omit positions to

  • regions (Object) —

    Geo targeting: { include / exclude: { countries (ISO 3166-1), regions (states/pr

  • starts_at (String) —

    Schedule start, ISO 8601.

  • status (Symbol, WhopSDK::Models::AdGroupUpdateParams::Status) —

    Initial status (default: active).

  • title (String) —

    The display name of the ad group.

  • request_options (WhopSDK::RequestOptions, Hash{Symbol=>Object}, nil)

Returns:

See Also:



164
165
166
167
168
169
170
171
172
173
 
# File 'lib/whop_sdk/resources/ad_groups.rb', line 164

def update(id, params = {})
  parsed, options = WhopSDK::AdGroupUpdateParams.dump_request(params)
  @client.request(
    method: :patch,
    path: ["ad_groups/%1$s", id],
    body: parsed,
    model: WhopSDK::AdGroup,
    options: options
  )
end