Class: WhopSDK::Resources::Ads

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

Overview

An Ad is the individual creative unit delivered by an ad group. It holds the copy, creative assets, and destination URL for one ad.

Use the Ads API to list ads for an account, create ads inside ad groups, retrieve or update creative details, delete ads that should stop running, and pause or resume delivery.

Instance Method Summary collapse

Constructor Details

#initialize(client:) ⇒ Ads

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 Ads.

Parameters:



268
269
270
 
# File 'lib/whop_sdk/resources/ads.rb', line 268

def initialize(client:)
  @client = client
end

Instance Method Details

#create(ad_group: nil, ad_group_id: nil, call_to_action: nil, creatives: nil, descriptions: nil, headlines: nil, lead_form: nil, lead_form_id: nil, messaging_config: nil, multi_advertiser_ads: nil, post_id: nil, post_source: nil, primary_texts: nil, social_accounts: nil, title: nil, url: nil, url_parameters: nil, request_options: {}) ⇒ WhopSDK::Models::Ad

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

Creates an ad in an ad group.

Parameters:

  • ad_group (Object) —

    An inline ad group to create (same shape as POST /ad_groups, including ad_campai

  • ad_group_id (String) —

    The existing ad group to create the ad in. Provide this OR ad_group, not both.

  • call_to_action (Symbol, WhopSDK::Models::AdCreateParams::CallToAction) —

    The call-to-action button shown on the ad.

  • creatives (Array<WhopSDK::Models::AdCreateParams::Creative>) —

    The ad's creative assets. Each entry is an uploaded file id with an optional for

  • descriptions (Array<String>) —

    The description variants shown on the ad.

  • headlines (Array<String>) —

    The headline variants shown on the ad.

  • lead_form (WhopSDK::Models::AdCreateParams::LeadForm) —

    Instant lead form for the ad. Only allowed when the ad group's conversion_locati

  • lead_form_id (String) —

    Use an existing Meta instant form instead of creating one — the form's Meta id,

  • messaging_config (WhopSDK::Models::AdCreateParams::MessagingConfig) —

    Click-to-message welcome copy: the greeting (message) and the ice-breaker prompt

  • multi_advertiser_ads (Boolean) —

    Whether the ad can appear alongside other advertisers' ads in the same unit. Def

  • post_id (String) —

    Promote an existing post instead of uploading creatives — a Facebook post or Ins

  • post_source (Symbol, WhopSDK::Models::AdCreateParams::PostSource) —

    Which network post_id refers to — facebook (a page post) or instagram (a media i

  • primary_texts (Array<String>) —

    The primary text variants shown in the ad body.

  • social_accounts (Array<WhopSDK::Models::AdCreateParams::SocialAccount>) —

    The social accounts (Facebook page, Instagram profile) the ad runs under.

  • title (String) —

    The display name of the ad.

  • url (String) —

    The URL the ad links to.

  • url_parameters (Object) —

    Query parameters appended to the destination URL, as a string-to-string map.

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

Returns:

See Also:



59
60
61
62
 
# File 'lib/whop_sdk/resources/ads.rb', line 59

def create(params = {})
  parsed, options = WhopSDK::AdCreateParams.dump_request(params)
  @client.request(method: :post, path: "ads", body: parsed, model: WhopSDK::Ad, options: options)
end

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

Deletes an ad. Returns true on success.

Parameters:

  • id (String) —

    The ad ID.

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

Returns:

  • (Boolean)

See Also:



216
217
218
219
220
221
222
223
 
# File 'lib/whop_sdk/resources/ads.rb', line 216

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

#list(account_id: nil, ad_campaign_id: nil, ad_group_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::Ad>

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

Lists the ads for an account, with stats over the requested window.

Parameters:

  • account_id (String) —

    The account the ads belong to. Defaults to the account-scoped key's own account.

  • ad_campaign_id (String) —

    Only return ads in this ad campaign.

  • ad_group_id (String) —

    Only return ads in this ad group.

  • 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 ads created after this timestamp.

  • created_before (String) —

    Only return ads created before this timestamp.

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

    The sort direction. Defaults to desc.

  • first (Integer) —

    The number of ads to return.

  • last (Integer) —

    The number of ads to return from the end of the range.

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

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

  • query (String) —

    Filter ads 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 (Symbol, WhopSDK::Models::AdListParams::Status) —

    Only return ads with this status.

  • 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:



192
193
194
195
196
197
198
199
200
201
202
203
 
# File 'lib/whop_sdk/resources/ads.rb', line 192

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

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

Pauses an active ad.

Parameters:

Returns:

See Also:



236
237
238
239
240
241
242
243
 
# File 'lib/whop_sdk/resources/ads.rb', line 236

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

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

Retrieves a single ad with stats over the requested window.

Parameters:

  • id (String) —

    The ad 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:



81
82
83
84
85
86
87
88
89
90
91
 
# File 'lib/whop_sdk/resources/ads.rb', line 81

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

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

Resumes a paused ad.

Parameters:

Returns:

See Also:



256
257
258
259
260
261
262
263
 
# File 'lib/whop_sdk/resources/ads.rb', line 256

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

#update(id, call_to_action: nil, creatives: nil, descriptions: nil, headlines: nil, lead_form: nil, lead_form_id: nil, messaging_config: nil, multi_advertiser_ads: nil, post_id: nil, post_source: nil, primary_texts: nil, social_accounts: nil, title: nil, url: nil, url_parameters: nil, request_options: {}) ⇒ WhopSDK::Models::Ad

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

Updates an ad's editable fields.

Parameters:

  • id (String) —

    The ad ID.

  • call_to_action (Symbol, WhopSDK::Models::AdUpdateParams::CallToAction) —

    The call-to-action button shown on the ad.

  • creatives (Array<WhopSDK::Models::AdUpdateParams::Creative>) —

    The ad's creative assets. Each entry is an uploaded file id with an optional for

  • descriptions (Array<String>) —

    The description variants shown on the ad.

  • headlines (Array<String>) —

    The headline variants shown on the ad.

  • lead_form (WhopSDK::Models::AdUpdateParams::LeadForm) —

    Instant lead form for the ad. Only allowed when the ad group's conversion_locati

  • lead_form_id (String) —

    Use an existing Meta instant form instead of creating one — the form's Meta id,

  • messaging_config (WhopSDK::Models::AdUpdateParams::MessagingConfig) —

    Click-to-message welcome copy: the greeting (message) and the ice-breaker prompt

  • multi_advertiser_ads (Boolean) —

    Whether the ad can appear alongside other advertisers' ads in the same unit. Def

  • post_id (String) —

    Promote an existing post instead of uploading creatives — a Facebook post or Ins

  • post_source (Symbol, WhopSDK::Models::AdUpdateParams::PostSource) —

    Which network post_id refers to — facebook (a page post) or instagram (a media i

  • primary_texts (Array<String>) —

    The primary text variants shown in the ad body.

  • social_accounts (Array<WhopSDK::Models::AdUpdateParams::SocialAccount>) —

    The social accounts the ad runs under.

  • title (String) —

    The display name of the ad.

  • url (String) —

    The URL the ad links to.

  • url_parameters (Object) —

    Query parameters appended to the destination URL, as a string-to-string map.

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

Returns:

See Also:



137
138
139
140
141
142
143
144
145
146
 
# File 'lib/whop_sdk/resources/ads.rb', line 137

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