omnisocials 0.14.0 → 0.16.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- checksums.yaml +4 -4
- data/README.md +176 -9
- data/lib/omnisocials/client.rb +17 -6
- data/lib/omnisocials/internal.rb +7 -0
- data/lib/omnisocials/resources/ads.rb +1817 -0
- data/lib/omnisocials/resources/automations.rb +27 -9
- data/lib/omnisocials/resources/feature_requests.rb +61 -0
- data/lib/omnisocials/resources/inbox.rb +3 -2
- data/lib/omnisocials/resources/limits.rb +36 -0
- data/lib/omnisocials/resources/media.rb +3 -1
- data/lib/omnisocials/resources/posts.rb +64 -15
- data/lib/omnisocials/resources/webhooks.rb +46 -8
- data/lib/omnisocials/version.rb +1 -1
- data/lib/omnisocials/webhooks.rb +9 -1
- data/lib/omnisocials.rb +3 -0
- metadata +5 -2
|
@@ -0,0 +1,1817 @@
|
|
|
1
|
+
# frozen_string_literal: true
|
|
2
|
+
|
|
3
|
+
module OmniSocials
|
|
4
|
+
module Resources
|
|
5
|
+
# Ads resource: boosts, campaigns and "Create an ad" drafts on Meta,
|
|
6
|
+
# Pinterest, TikTok, LinkedIn, X and Google.
|
|
7
|
+
#
|
|
8
|
+
# Ads spend real money once a campaign starts. Boosts and drafts are
|
|
9
|
+
# created as drafts (no spend). Starting or raising spend needs a key with
|
|
10
|
+
# the opt-in ads:spend scope ("Start ads", a second switch under "Ads";
|
|
11
|
+
# its creator needs manage_ads): activate, activate_multi, resume, the
|
|
12
|
+
# draft launch (drafts.launch), a budget raise or any change of a campaign
|
|
13
|
+
# that reached the network through update, and the parity calls that
|
|
14
|
+
# switch something on or raise a budget. Each repeats the amount. Without
|
|
15
|
+
# ads:spend these calls answer 403 start_in_app with the page in the app
|
|
16
|
+
# where a person does it; on Google (api_draft_only) they always do, also
|
|
17
|
+
# with ads:spend. Pause and delete stay open, except on the networks in
|
|
18
|
+
# api_stop_in_app (Google). The calls that start or raise spend are never
|
|
19
|
+
# retried after a 5xx, a timeout or a lost connection (only a 429),
|
|
20
|
+
# because the first attempt may have started the ad. Budgets are in major
|
|
21
|
+
# currency units (10 = 10 EUR) in the ad account's currency. An Ads error
|
|
22
|
+
# may carry "param" (the field at fault) in its body. Ad accounts are
|
|
23
|
+
# connected and picked in the OmniSocials dashboard. The scopes ads:read
|
|
24
|
+
# and ads:write are opt-in on the API key (the Ads switch).
|
|
25
|
+
#
|
|
26
|
+
# The Ads API parity sub-resources (objects, campaign_ads, comments,
|
|
27
|
+
# targeting, audiences, lead_forms, leads, conversions, insights, reports,
|
|
28
|
+
# rules, results, media, previews, partnership, accounts, reach_frequency,
|
|
29
|
+
# studies, budget_schedules, google) are a thin passthrough. Every call
|
|
30
|
+
# there that switches something on or can raise spend (objects.update,
|
|
31
|
+
# objects.set_status, objects.duplicate, bulk_status, campaign_ads.add,
|
|
32
|
+
# campaign_ads.set_status, rules.create, rules.update, rules.undo,
|
|
33
|
+
# accounts.update_settings, reach_frequency.reserve, studies.create,
|
|
34
|
+
# budget_schedules.create) needs a key with ads:spend (rules: else 403
|
|
35
|
+
# rule_raises_spend), takes the person's own amount where it raises spend
|
|
36
|
+
# (confirm_budget_amount, rules confirm_max_daily_budget) and follows the
|
|
37
|
+
# same no-retry rule. Pausing, deleting and archiving stay open, except on
|
|
38
|
+
# Google.
|
|
39
|
+
class Ads
|
|
40
|
+
# "Create an ad" drafts (an OmniSocials::Resources::AdDrafts).
|
|
41
|
+
attr_reader :drafts
|
|
42
|
+
# The Ads API parity sub-resource for campaigns, ad sets and ads of an ad account, also the ones made outside OmniSocials, and their import (an
|
|
43
|
+
# OmniSocials::Resources::AdObjects).
|
|
44
|
+
attr_reader :objects
|
|
45
|
+
# The Ads API parity sub-resource for the ads of an OmniSocials campaign (an
|
|
46
|
+
# OmniSocials::Resources::AdCampaignAds).
|
|
47
|
+
attr_reader :campaign_ads
|
|
48
|
+
# The Ads API parity sub-resource for comments on ads (an
|
|
49
|
+
# OmniSocials::Resources::AdComments).
|
|
50
|
+
attr_reader :comments
|
|
51
|
+
# The Ads API parity sub-resource for targeting search, browse, reach estimate and bid suggestions (an
|
|
52
|
+
# OmniSocials::Resources::AdTargeting).
|
|
53
|
+
attr_reader :targeting
|
|
54
|
+
# The Ads API parity sub-resource for custom audiences (an
|
|
55
|
+
# OmniSocials::Resources::AdAudiences).
|
|
56
|
+
attr_reader :audiences
|
|
57
|
+
# The Ads API parity sub-resource for lead forms (an
|
|
58
|
+
# OmniSocials::Resources::AdLeadForms).
|
|
59
|
+
attr_reader :lead_forms
|
|
60
|
+
# The Ads API parity sub-resource for leads copied from the lead forms (an
|
|
61
|
+
# OmniSocials::Resources::AdLeads).
|
|
62
|
+
attr_reader :leads
|
|
63
|
+
# The Ads API parity sub-resource for pixels, conversion goals, custom conversions, server-side events (an
|
|
64
|
+
# OmniSocials::Resources::AdConversions).
|
|
65
|
+
attr_reader :conversions
|
|
66
|
+
# The Ads API parity sub-resource for live numbers, analytics, timeline, ranking, alerts (an
|
|
67
|
+
# OmniSocials::Resources::AdInsights).
|
|
68
|
+
attr_reader :insights
|
|
69
|
+
# The Ads API parity sub-resource for background reports (an
|
|
70
|
+
# OmniSocials::Resources::AdReports).
|
|
71
|
+
attr_reader :reports
|
|
72
|
+
# The Ads API parity sub-resource for automated rules (an
|
|
73
|
+
# OmniSocials::Resources::AdRules).
|
|
74
|
+
attr_reader :rules
|
|
75
|
+
# The Ads API parity sub-resource for your own numbers per campaign and day (an
|
|
76
|
+
# OmniSocials::Resources::AdResults).
|
|
77
|
+
attr_reader :results
|
|
78
|
+
# The Ads API parity sub-resource for the network's own image and video library (an
|
|
79
|
+
# OmniSocials::Resources::AdMedia).
|
|
80
|
+
attr_reader :media
|
|
81
|
+
# The Ads API parity sub-resource for previews drawn by the network (an
|
|
82
|
+
# OmniSocials::Resources::AdPreviews).
|
|
83
|
+
attr_reader :previews
|
|
84
|
+
# The Ads API parity sub-resource for partnership ads (Meta) (an
|
|
85
|
+
# OmniSocials::Resources::AdPartnership).
|
|
86
|
+
attr_reader :partnership
|
|
87
|
+
# The Ads API parity sub-resource for ad account admin (health, finance, settings, people, change log) (an
|
|
88
|
+
# OmniSocials::Resources::AdAccountsAdmin).
|
|
89
|
+
attr_reader :accounts
|
|
90
|
+
# The Ads API parity sub-resource for Meta reach and frequency (an
|
|
91
|
+
# OmniSocials::Resources::AdReachFrequency).
|
|
92
|
+
attr_reader :reach_frequency
|
|
93
|
+
# The Ads API parity sub-resource for A/B tests and lift studies (Meta) (an
|
|
94
|
+
# OmniSocials::Resources::AdStudies).
|
|
95
|
+
attr_reader :studies
|
|
96
|
+
# The Ads API parity sub-resource for planned budget increases (Meta) (an
|
|
97
|
+
# OmniSocials::Resources::AdBudgetSchedules).
|
|
98
|
+
attr_reader :budget_schedules
|
|
99
|
+
# The Ads API parity sub-resource for Google reports (an
|
|
100
|
+
# OmniSocials::Resources::AdGoogle).
|
|
101
|
+
attr_reader :google
|
|
102
|
+
|
|
103
|
+
def initialize(client)
|
|
104
|
+
@client = client
|
|
105
|
+
@drafts = AdDrafts.new(client)
|
|
106
|
+
@objects = AdObjects.new(client)
|
|
107
|
+
@campaign_ads = AdCampaignAds.new(client)
|
|
108
|
+
@comments = AdComments.new(client)
|
|
109
|
+
@targeting = AdTargeting.new(client)
|
|
110
|
+
@audiences = AdAudiences.new(client)
|
|
111
|
+
@lead_forms = AdLeadForms.new(client)
|
|
112
|
+
@leads = AdLeads.new(client)
|
|
113
|
+
@conversions = AdConversions.new(client)
|
|
114
|
+
@insights = AdInsights.new(client)
|
|
115
|
+
@reports = AdReports.new(client)
|
|
116
|
+
@rules = AdRules.new(client)
|
|
117
|
+
@results = AdResults.new(client)
|
|
118
|
+
@media = AdMedia.new(client)
|
|
119
|
+
@previews = AdPreviews.new(client)
|
|
120
|
+
@partnership = AdPartnership.new(client)
|
|
121
|
+
@accounts = AdAccountsAdmin.new(client)
|
|
122
|
+
@reach_frequency = AdReachFrequency.new(client)
|
|
123
|
+
@studies = AdStudies.new(client)
|
|
124
|
+
@budget_schedules = AdBudgetSchedules.new(client)
|
|
125
|
+
@google = AdGoogle.new(client)
|
|
126
|
+
end
|
|
127
|
+
|
|
128
|
+
# GET /ads/accounts - the connected ad accounts, as { "data" => [...],
|
|
129
|
+
# "platforms_available" => [...] }. Accounts are connected and picked in
|
|
130
|
+
# the dashboard; only is_selected accounts can run campaigns. Requires
|
|
131
|
+
# ads:read (opt-in on the API key).
|
|
132
|
+
def list_accounts
|
|
133
|
+
@client.request("GET", "/ads/accounts")
|
|
134
|
+
end
|
|
135
|
+
|
|
136
|
+
# GET /ads/capabilities - what each network accepts for a new ad (goals,
|
|
137
|
+
# media, text limits, buttons, minimum daily budget), create_networks
|
|
138
|
+
# and network_states ("live", "preview" or "coming_soon"), and per
|
|
139
|
+
# network the "features" its API offers, "targeting_types",
|
|
140
|
+
# "bid_strategies", "settings" and "ad_fields", plus "api_goals",
|
|
141
|
+
# "api_draft_only" (networks where every API caller stops at the draft,
|
|
142
|
+
# also a key with ads:spend: Google) and "api_stop_in_app" (networks
|
|
143
|
+
# where the API may not even pause or delete a campaign that reached the
|
|
144
|
+
# network: Google). Requires ads:read.
|
|
145
|
+
def capabilities
|
|
146
|
+
@client.request("GET", "/ads/capabilities")
|
|
147
|
+
end
|
|
148
|
+
|
|
149
|
+
# GET /ads/campaigns - list campaigns and boosts, optionally by status,
|
|
150
|
+
# platform or campaign_type ("campaign" or "boost"); limit is 1..100
|
|
151
|
+
# (default 25). Requires ads:read.
|
|
152
|
+
def list(status: nil, platform: nil, campaign_type: nil, limit: nil, offset: nil)
|
|
153
|
+
@client.request(
|
|
154
|
+
"GET", "/ads/campaigns",
|
|
155
|
+
query: {
|
|
156
|
+
"status" => status, "platform" => platform, "campaign_type" => campaign_type,
|
|
157
|
+
"limit" => limit, "offset" => offset
|
|
158
|
+
}
|
|
159
|
+
)
|
|
160
|
+
end
|
|
161
|
+
|
|
162
|
+
# GET /ads/campaigns/{id} - one campaign with its latest numbers.
|
|
163
|
+
# Requires ads:read.
|
|
164
|
+
def get(campaign_id)
|
|
165
|
+
@client.request("GET", "/ads/campaigns/#{Internal.path_segment(campaign_id)}")
|
|
166
|
+
end
|
|
167
|
+
|
|
168
|
+
# POST /ads/boost - boost a published post. Creates a DRAFT boost that
|
|
169
|
+
# spends nothing; the person starts it in the app. budget is
|
|
170
|
+
# { "type" => "daily", "amount" => 5, "currency" => "EUR" } in the ad
|
|
171
|
+
# account's currency. TikTok needs creative "spark_auth_code", Google
|
|
172
|
+
# needs "headlines", "descriptions" and "logo_url". Requires ads:write.
|
|
173
|
+
def boost(post_id:, ad_account_id:, budget:, objective: nil, targeting: nil,
|
|
174
|
+
schedule: nil, creative: nil, name: nil)
|
|
175
|
+
body = Internal.drop_nil(
|
|
176
|
+
{
|
|
177
|
+
"post_id" => post_id, "ad_account_id" => ad_account_id, "budget" => budget,
|
|
178
|
+
"objective" => objective, "targeting" => targeting, "schedule" => schedule,
|
|
179
|
+
"creative" => creative, "name" => name
|
|
180
|
+
}
|
|
181
|
+
)
|
|
182
|
+
@client.request("POST", "/ads/boost", json: body)
|
|
183
|
+
end
|
|
184
|
+
|
|
185
|
+
# POST /ads/boost-multi - one DRAFT boost per ad account (up to 10),
|
|
186
|
+
# each with the same budget, so the total is amount x accounts. Answers
|
|
187
|
+
# { "results" => [...] }; one failed account never stops the others.
|
|
188
|
+
# Requires ads:write.
|
|
189
|
+
def boost_multi(post_id:, ad_account_ids:, budget:, objective: nil, targeting: nil,
|
|
190
|
+
schedule: nil, creative: nil, name: nil)
|
|
191
|
+
body = Internal.drop_nil(
|
|
192
|
+
{
|
|
193
|
+
"post_id" => post_id, "ad_account_ids" => ad_account_ids.to_a, "budget" => budget,
|
|
194
|
+
"objective" => objective, "targeting" => targeting, "schedule" => schedule,
|
|
195
|
+
"creative" => creative, "name" => name
|
|
196
|
+
}
|
|
197
|
+
)
|
|
198
|
+
@client.request("POST", "/ads/boost-multi", json: body)
|
|
199
|
+
end
|
|
200
|
+
|
|
201
|
+
# PATCH /ads/campaigns/{id} - change the name, budget, targeting or
|
|
202
|
+
# schedule of a draft; objective and settings only while the campaign is
|
|
203
|
+
# a draft (400 settings_locked after the start: duplicate it).
|
|
204
|
+
#
|
|
205
|
+
# A campaign that reached the network changes only with a key that has
|
|
206
|
+
# ads:spend; without it, and on Google always, the call answers 403
|
|
207
|
+
# start_in_app and a person changes it in the app. A higher budget on a
|
|
208
|
+
# running campaign RAISES REAL AD SPEND: show the person the new amount
|
|
209
|
+
# and get their yes first, then pass it again as confirm_budget_amount.
|
|
210
|
+
# Not retried after a 5xx, a timeout or a lost connection: read the
|
|
211
|
+
# campaign with get to see what happened. Requires ads:write.
|
|
212
|
+
def update(campaign_id, name: nil, budget: nil, confirm_budget_amount: nil,
|
|
213
|
+
targeting: nil, schedule: nil, objective: nil, settings: nil)
|
|
214
|
+
body = Internal.drop_nil(
|
|
215
|
+
{
|
|
216
|
+
"name" => name,
|
|
217
|
+
"budget" => budget,
|
|
218
|
+
"confirm_budget_amount" => confirm_budget_amount,
|
|
219
|
+
"targeting" => targeting,
|
|
220
|
+
"schedule" => schedule,
|
|
221
|
+
"objective" => objective,
|
|
222
|
+
"settings" => settings
|
|
223
|
+
}
|
|
224
|
+
)
|
|
225
|
+
@client.request(
|
|
226
|
+
"PATCH", "/ads/campaigns/#{Internal.path_segment(campaign_id)}",
|
|
227
|
+
json: body, retry_on: :rate_limit
|
|
228
|
+
)
|
|
229
|
+
end
|
|
230
|
+
|
|
231
|
+
# POST /ads/campaigns/{id}/activate - START REAL AD SPEND.
|
|
232
|
+
#
|
|
233
|
+
# Needs a key with the opt-in ads:spend scope ("Start ads"); without it,
|
|
234
|
+
# and on Google (api_draft_only) always, the call answers 403
|
|
235
|
+
# start_in_app with the page where a person does it in the app. Show the
|
|
236
|
+
# person the budget (amount, currency, daily or lifetime) and get their
|
|
237
|
+
# yes first; confirm_budget_amount must equal the campaign's budget
|
|
238
|
+
# amount. A campaign of a draft group answers 409 use_draft_launch: use
|
|
239
|
+
# ads.drafts.launch. Not retried after a 5xx, a timeout or a lost
|
|
240
|
+
# connection: read the campaign with get to see what happened. Requires
|
|
241
|
+
# ads:write.
|
|
242
|
+
def activate(campaign_id, confirm_budget_amount)
|
|
243
|
+
@client.request(
|
|
244
|
+
"POST", "/ads/campaigns/#{Internal.path_segment(campaign_id)}/activate",
|
|
245
|
+
json: { "confirm_budget_amount" => confirm_budget_amount }, retry_on: :rate_limit
|
|
246
|
+
)
|
|
247
|
+
end
|
|
248
|
+
|
|
249
|
+
# POST /ads/campaigns/activate-multi - START REAL AD SPEND on up to 10
|
|
250
|
+
# campaigns.
|
|
251
|
+
#
|
|
252
|
+
# Needs a key with ads:spend: without it, and on Google always, a result
|
|
253
|
+
# answers "ok" => false with code start_in_app and the page where a
|
|
254
|
+
# person starts it. Every campaign's budget must equal
|
|
255
|
+
# confirm_budget_amount; show the person the total (amount x campaigns)
|
|
256
|
+
# and get their yes first. Answers { "results" => [...] }. Not retried
|
|
257
|
+
# after a 5xx, a timeout or a lost connection: read the campaigns with
|
|
258
|
+
# get to see what happened. Requires ads:write.
|
|
259
|
+
def activate_multi(campaign_ids, confirm_budget_amount)
|
|
260
|
+
@client.request(
|
|
261
|
+
"POST", "/ads/campaigns/activate-multi",
|
|
262
|
+
json: {
|
|
263
|
+
"campaign_ids" => campaign_ids.to_a,
|
|
264
|
+
"confirm_budget_amount" => confirm_budget_amount
|
|
265
|
+
},
|
|
266
|
+
retry_on: :rate_limit
|
|
267
|
+
)
|
|
268
|
+
end
|
|
269
|
+
|
|
270
|
+
# POST /ads/campaigns/{id}/pause - pause a campaign (also while in
|
|
271
|
+
# review). Open with ads:write, except on the networks in
|
|
272
|
+
# api_stop_in_app (Google): there a campaign that reached the network
|
|
273
|
+
# answers 403 start_in_app. Requires ads:write.
|
|
274
|
+
def pause(campaign_id)
|
|
275
|
+
@client.request("POST", "/ads/campaigns/#{Internal.path_segment(campaign_id)}/pause")
|
|
276
|
+
end
|
|
277
|
+
|
|
278
|
+
# POST /ads/campaigns/{id}/resume - resume a paused campaign: it STARTS
|
|
279
|
+
# REAL AD SPEND again. Needs a key with the opt-in ads:spend scope
|
|
280
|
+
# ("Start ads"); without it, and on Google (api_draft_only) always, the
|
|
281
|
+
# call answers 403 start_in_app with the page where a person does it in
|
|
282
|
+
# the app. Only a paused campaign resumes (409 not_paused). Show the
|
|
283
|
+
# person the budget and get their yes first. Not retried after a 5xx, a
|
|
284
|
+
# timeout or a lost connection: read the campaign with get to see what
|
|
285
|
+
# happened. Requires ads:write.
|
|
286
|
+
def resume(campaign_id)
|
|
287
|
+
@client.request(
|
|
288
|
+
"POST", "/ads/campaigns/#{Internal.path_segment(campaign_id)}/resume",
|
|
289
|
+
retry_on: :rate_limit
|
|
290
|
+
)
|
|
291
|
+
end
|
|
292
|
+
|
|
293
|
+
# POST /ads/campaigns/bulk-status - pause or resume up to 50 campaigns
|
|
294
|
+
# (status "paused" or "active").
|
|
295
|
+
#
|
|
296
|
+
# Resuming RESTARTS REAL AD SPEND: every campaign's budget must equal
|
|
297
|
+
# confirm_budget_amount (one amount for all), checked before any change;
|
|
298
|
+
# show the person the total and get their yes first. Resuming needs a
|
|
299
|
+
# key with ads:spend: without it, and on Google always, a result answers
|
|
300
|
+
# start_in_app. Pausing stays open (Google: start_in_app). Answers
|
|
301
|
+
# { "data" => { "results" => [...] } }. Not retried after a 5xx, a
|
|
302
|
+
# timeout or a lost connection. Requires ads:write.
|
|
303
|
+
def bulk_status(campaign_ids:, status:, confirm_budget_amount: nil)
|
|
304
|
+
@client.request(
|
|
305
|
+
"POST", "/ads/campaigns/bulk-status",
|
|
306
|
+
json: Internal.drop_nil(
|
|
307
|
+
{
|
|
308
|
+
"campaign_ids" => campaign_ids.to_a, "status" => status,
|
|
309
|
+
"confirm_budget_amount" => confirm_budget_amount
|
|
310
|
+
}
|
|
311
|
+
),
|
|
312
|
+
retry_on: :rate_limit
|
|
313
|
+
)
|
|
314
|
+
end
|
|
315
|
+
|
|
316
|
+
# POST /ads/campaigns/{id}/duplicate - copy a campaign as a new draft
|
|
317
|
+
# (same ad account, goal, budget, targeting, settings and ads). A draft
|
|
318
|
+
# never spends. Requires ads:write.
|
|
319
|
+
def duplicate(campaign_id, name: nil)
|
|
320
|
+
@client.request(
|
|
321
|
+
"POST", "/ads/campaigns/#{Internal.path_segment(campaign_id)}/duplicate",
|
|
322
|
+
json: Internal.drop_nil({ "name" => name })
|
|
323
|
+
)
|
|
324
|
+
end
|
|
325
|
+
|
|
326
|
+
# DELETE /ads/campaigns/{id} - delete a campaign on the network too. A
|
|
327
|
+
# campaign that spent is archived: its spend stays in the totals. Open
|
|
328
|
+
# with ads:write, except on the networks in api_stop_in_app (Google):
|
|
329
|
+
# there a campaign that reached the network answers 403 start_in_app.
|
|
330
|
+
# Requires ads:write.
|
|
331
|
+
def delete(campaign_id)
|
|
332
|
+
@client.request("DELETE", "/ads/campaigns/#{Internal.path_segment(campaign_id)}")
|
|
333
|
+
end
|
|
334
|
+
|
|
335
|
+
# GET /ads/overview - accounts, campaigns per status and the totals.
|
|
336
|
+
# totals["spend"] is nil when the campaigns use more than one currency
|
|
337
|
+
# (totals["currency"] names the one currency): read totals_by_currency
|
|
338
|
+
# then, one row per currency with "currency", "spend", "impressions" and
|
|
339
|
+
# "clicks" (spend is never added across currencies). Requires ads:read.
|
|
340
|
+
def overview
|
|
341
|
+
@client.request("GET", "/ads/overview")
|
|
342
|
+
end
|
|
343
|
+
|
|
344
|
+
# GET /ads/suggestions - organic posts that do better than the
|
|
345
|
+
# workspace median: boost candidates. Read-only. Requires ads:read.
|
|
346
|
+
def suggestions
|
|
347
|
+
@client.request("GET", "/ads/suggestions")
|
|
348
|
+
end
|
|
349
|
+
|
|
350
|
+
# POST /ads/research/keywords - keyword ideas from seed keywords (up to
|
|
351
|
+
# 20), a url or both, through the connected Google Ads account. country
|
|
352
|
+
# defaults to "US", language to "en", limit is 1..500 (default 100);
|
|
353
|
+
# ad_account_id only when the workspace has more than one Google Ads
|
|
354
|
+
# account. Read-only and free. Requires ads:read.
|
|
355
|
+
def research_keywords(keywords: nil, url: nil, country: nil, language: nil, limit: nil,
|
|
356
|
+
ad_account_id: nil)
|
|
357
|
+
body = Internal.drop_nil(
|
|
358
|
+
{
|
|
359
|
+
"keywords" => keywords&.to_a,
|
|
360
|
+
"url" => url,
|
|
361
|
+
"country" => country,
|
|
362
|
+
"language" => language,
|
|
363
|
+
"limit" => limit,
|
|
364
|
+
"ad_account_id" => ad_account_id
|
|
365
|
+
}
|
|
366
|
+
)
|
|
367
|
+
@client.request("POST", "/ads/research/keywords", json: body)
|
|
368
|
+
end
|
|
369
|
+
|
|
370
|
+
# POST /ads/research/keywords/metrics - search numbers for an exact
|
|
371
|
+
# keyword list. Read-only. Requires ads:read.
|
|
372
|
+
def keyword_metrics(keywords:, country: nil, language: nil, ad_account_id: nil)
|
|
373
|
+
body = Internal.drop_nil(
|
|
374
|
+
{
|
|
375
|
+
"keywords" => keywords.to_a,
|
|
376
|
+
"country" => country,
|
|
377
|
+
"language" => language,
|
|
378
|
+
"ad_account_id" => ad_account_id
|
|
379
|
+
}
|
|
380
|
+
)
|
|
381
|
+
@client.request("POST", "/ads/research/keywords/metrics", json: body)
|
|
382
|
+
end
|
|
383
|
+
end
|
|
384
|
+
|
|
385
|
+
# "Create an ad" drafts: one campaign per network in platforms, each with
|
|
386
|
+
# the same ads. A draft never spends; launch starts it (a key with
|
|
387
|
+
# ads:spend), or a person does in the app from its review_url.
|
|
388
|
+
class AdDrafts
|
|
389
|
+
def initialize(client)
|
|
390
|
+
@client = client
|
|
391
|
+
end
|
|
392
|
+
|
|
393
|
+
# GET /ads/drafts/defaults - suggested countries (where the Instagram
|
|
394
|
+
# followers are), the currency and the workspace's ad account per
|
|
395
|
+
# network. Requires ads:read.
|
|
396
|
+
def defaults
|
|
397
|
+
@client.request("GET", "/ads/drafts/defaults")
|
|
398
|
+
end
|
|
399
|
+
|
|
400
|
+
# POST /ads/drafts - save a new ad as a draft group. It needs no ad
|
|
401
|
+
# account and spends nothing.
|
|
402
|
+
#
|
|
403
|
+
# objective is "traffic", "engagement", "awareness" or "video_views";
|
|
404
|
+
# through the API also "lead_generation", "conversions", "messages" or
|
|
405
|
+
# "calls" (each network's goal in ads.capabilities says what it
|
|
406
|
+
# "needs"). platforms lists network keys ("meta", "pinterest",
|
|
407
|
+
# "tiktok", "linkedin", "x", "google") or { "platform" => ...,
|
|
408
|
+
# "budget_amount" => ..., "ad_account_id" => ..., "settings" => {...} }
|
|
409
|
+
# per network (settings: bidding, conversion goal, lead form,
|
|
410
|
+
# messaging). budget is the daily amount
|
|
411
|
+
# per network, { "amount" => 10, "currency" => "EUR" }. schedule is
|
|
412
|
+
# { "duration_days" => 7 } (nil runs until it is stopped). targeting
|
|
413
|
+
# needs "countries"; "automatic_audience" => true lets the network find
|
|
414
|
+
# the audience; "networks" => { "meta" => { "include" => {...},
|
|
415
|
+
# "exclude" => {...}, "audiences" => {...} } } adds each network's own
|
|
416
|
+
# targeting (ids from ads.targeting.search). Each of ads has "media",
|
|
417
|
+
# "primary_text", "link" and optionally "headline", "description",
|
|
418
|
+
# "cta", "primary_text_b" (an A/B test), "network" (per network extras
|
|
419
|
+
# such as "lead_form_id", "media_ref", "spark_auth_code" or Google's
|
|
420
|
+
# "responsive_search_ad") and, on Meta, "placement_media" => { "stories_reels" => {...} }
|
|
421
|
+
# (an upright 9:16 file for Stories and Reels).
|
|
422
|
+
#
|
|
423
|
+
# Read ads.capabilities first for what each network accepts. The answer
|
|
424
|
+
# carries review_url (the builder in the dashboard, where the person
|
|
425
|
+
# checks and starts the ad: hand it over) and per network readiness. A
|
|
426
|
+
# budget["currency"] other than the attached ad account's currency
|
|
427
|
+
# answers 400 currency_mismatch with param "budget.currency". Requires
|
|
428
|
+
# ads:write.
|
|
429
|
+
def create(objective:, platforms:, budget:, targeting:, ads:, name: nil, schedule: nil)
|
|
430
|
+
body = draft_body(
|
|
431
|
+
objective: objective, platforms: platforms, budget: budget,
|
|
432
|
+
targeting: targeting, ads: ads, name: name, schedule: schedule
|
|
433
|
+
)
|
|
434
|
+
@client.request("POST", "/ads/drafts", json: body)
|
|
435
|
+
end
|
|
436
|
+
|
|
437
|
+
# GET /ads/drafts/{group_id} - one draft group. Requires ads:read.
|
|
438
|
+
def get(group_id)
|
|
439
|
+
@client.request("GET", "/ads/drafts/#{Internal.path_segment(group_id)}")
|
|
440
|
+
end
|
|
441
|
+
|
|
442
|
+
# PUT /ads/drafts/{group_id} - replace the draft with the full body (the
|
|
443
|
+
# same fields as create). Networks that already started are left alone
|
|
444
|
+
# (campaigns[].editable). A budget["currency"] other than the attached
|
|
445
|
+
# ad account's currency answers 400 currency_mismatch with param
|
|
446
|
+
# "budget.currency". Requires ads:write.
|
|
447
|
+
def update(group_id, objective:, platforms:, budget:, targeting:, ads:, name: nil,
|
|
448
|
+
schedule: nil)
|
|
449
|
+
body = draft_body(
|
|
450
|
+
objective: objective, platforms: platforms, budget: budget,
|
|
451
|
+
targeting: targeting, ads: ads, name: name, schedule: schedule
|
|
452
|
+
)
|
|
453
|
+
@client.request("PUT", "/ads/drafts/#{Internal.path_segment(group_id)}", json: body)
|
|
454
|
+
end
|
|
455
|
+
|
|
456
|
+
# DELETE /ads/drafts/{group_id} - delete a draft group that never
|
|
457
|
+
# started. Requires ads:write.
|
|
458
|
+
def delete(group_id)
|
|
459
|
+
@client.request("DELETE", "/ads/drafts/#{Internal.path_segment(group_id)}")
|
|
460
|
+
end
|
|
461
|
+
|
|
462
|
+
# POST /ads/drafts/{group_id}/account - set the ad account of one
|
|
463
|
+
# network in the draft (from ads.list_accounts, same network). Requires
|
|
464
|
+
# ads:write.
|
|
465
|
+
def attach_account(group_id, platform:, ad_account_id:)
|
|
466
|
+
@client.request(
|
|
467
|
+
"POST", "/ads/drafts/#{Internal.path_segment(group_id)}/account",
|
|
468
|
+
json: { "platform" => platform, "ad_account_id" => ad_account_id }
|
|
469
|
+
)
|
|
470
|
+
end
|
|
471
|
+
|
|
472
|
+
# POST /ads/drafts/{group_id}/launch - START REAL AD SPEND for every
|
|
473
|
+
# network of the draft that never started.
|
|
474
|
+
#
|
|
475
|
+
# Needs a key with the opt-in ads:spend scope ("Start ads"): without it
|
|
476
|
+
# the call answers 403 start_in_app with the draft's page (its
|
|
477
|
+
# review_url), and a network in api_draft_only (Google) is always
|
|
478
|
+
# skipped with code start_in_app. Show the person the daily amount per
|
|
479
|
+
# network and get their yes first, then pass it as confirm_budget_amount
|
|
480
|
+
# (or per campaign id as confirm_budget_amounts). A wrong or missing
|
|
481
|
+
# amount answers 400 budget_confirmation_required and writes nothing.
|
|
482
|
+
# The answer is { "data" => { "group" => ..., "results" => [...] } }
|
|
483
|
+
# with a result per network ("campaign_id" is a string); one failed
|
|
484
|
+
# network never stops the others. Not retried after a 5xx, a timeout or
|
|
485
|
+
# a lost connection: read the draft with get to see what started.
|
|
486
|
+
# Requires ads:write.
|
|
487
|
+
def launch(group_id, confirm_budget_amount: nil, confirm_budget_amounts: nil)
|
|
488
|
+
body = Internal.drop_nil(
|
|
489
|
+
{
|
|
490
|
+
"confirm_budget_amount" => confirm_budget_amount,
|
|
491
|
+
"confirm_budget_amounts" => confirm_budget_amounts
|
|
492
|
+
}
|
|
493
|
+
)
|
|
494
|
+
@client.request(
|
|
495
|
+
"POST", "/ads/drafts/#{Internal.path_segment(group_id)}/launch",
|
|
496
|
+
json: body, retry_on: :rate_limit
|
|
497
|
+
)
|
|
498
|
+
end
|
|
499
|
+
|
|
500
|
+
private
|
|
501
|
+
|
|
502
|
+
def draft_body(objective:, platforms:, budget:, targeting:, ads:, name:, schedule:)
|
|
503
|
+
Internal.drop_nil(
|
|
504
|
+
{
|
|
505
|
+
"name" => name,
|
|
506
|
+
"objective" => objective,
|
|
507
|
+
"platforms" => platforms.to_a,
|
|
508
|
+
"budget" => budget,
|
|
509
|
+
"schedule" => schedule,
|
|
510
|
+
"targeting" => targeting,
|
|
511
|
+
"ads" => ads.to_a
|
|
512
|
+
}
|
|
513
|
+
)
|
|
514
|
+
end
|
|
515
|
+
end
|
|
516
|
+
|
|
517
|
+
# -------------------------------------------------------------------------
|
|
518
|
+
# Ads API parity (2026-11-05). Thin passthrough: the API checks every
|
|
519
|
+
# field. A network without the feature answers 400
|
|
520
|
+
# not_supported_on_network (ads.capabilities lists "features" per
|
|
521
|
+
# network); a missing permission on the network side answers 403
|
|
522
|
+
# network_permission_missing. Every call that switches something on or can
|
|
523
|
+
# raise spend needs a key with ads:spend (without it, and on Google
|
|
524
|
+
# always, 403 start_in_app; rules: 403 rule_raises_spend), takes the
|
|
525
|
+
# person's own amount and is sent with retry_on: :rate_limit (never again
|
|
526
|
+
# after a 5xx, a timeout or a lost connection). Pausing, deleting and
|
|
527
|
+
# archiving stay open, except on Google.
|
|
528
|
+
# -------------------------------------------------------------------------
|
|
529
|
+
|
|
530
|
+
# Shared path helpers of the ads sub-resources.
|
|
531
|
+
module AdPaths
|
|
532
|
+
private
|
|
533
|
+
|
|
534
|
+
def seg(value)
|
|
535
|
+
Internal.path_segment(value)
|
|
536
|
+
end
|
|
537
|
+
|
|
538
|
+
def object_path(account_id, level, external_id)
|
|
539
|
+
"/ads/accounts/#{seg(account_id)}/objects/#{seg(level)}/#{seg(external_id)}"
|
|
540
|
+
end
|
|
541
|
+
|
|
542
|
+
def ad_path(campaign_id, ad_id)
|
|
543
|
+
"/ads/campaigns/#{seg(campaign_id)}/ads/#{seg(ad_id)}"
|
|
544
|
+
end
|
|
545
|
+
|
|
546
|
+
def account_path(account_id, rest)
|
|
547
|
+
"/ads/accounts/#{seg(account_id)}/#{rest}"
|
|
548
|
+
end
|
|
549
|
+
|
|
550
|
+
def list_param(value)
|
|
551
|
+
Internal.join_list(value)
|
|
552
|
+
end
|
|
553
|
+
end
|
|
554
|
+
|
|
555
|
+
# Campaigns, ad sets and ads of an ad account as the network has them,
|
|
556
|
+
# also the ones made outside OmniSocials, and the import of those
|
|
557
|
+
# campaigns. level is "campaign", "ad_set" or "ad". Objects of OmniSocials
|
|
558
|
+
# campaigns answer 409 use_campaign_routes: change those with the
|
|
559
|
+
# campaign methods.
|
|
560
|
+
class AdObjects
|
|
561
|
+
include AdPaths
|
|
562
|
+
|
|
563
|
+
def initialize(client)
|
|
564
|
+
@client = client
|
|
565
|
+
end
|
|
566
|
+
|
|
567
|
+
# GET /ads/accounts/{accountId}/tree - campaigns, ad sets and ads with
|
|
568
|
+
# the numbers of the date range (from / to, ISO dates; at most 90 days,
|
|
569
|
+
# default the last 30). Each campaign says "source" ("omnisocials" or
|
|
570
|
+
# "external"). status is an Array or a comma list. Requires ads:read.
|
|
571
|
+
def tree(account_id, from: nil, to: nil, status: nil, limit: nil, cursor: nil)
|
|
572
|
+
@client.request(
|
|
573
|
+
"GET", account_path(account_id, "tree"),
|
|
574
|
+
query: {
|
|
575
|
+
"from" => from, "to" => to, "status" => list_param(status),
|
|
576
|
+
"limit" => limit, "cursor" => cursor
|
|
577
|
+
}
|
|
578
|
+
)
|
|
579
|
+
end
|
|
580
|
+
|
|
581
|
+
# GET /ads/accounts/{accountId}/objects/{level}/{externalId} - live
|
|
582
|
+
# details of one object. Requires ads:read.
|
|
583
|
+
def get(account_id, level, external_id)
|
|
584
|
+
@client.request("GET", object_path(account_id, level, external_id))
|
|
585
|
+
end
|
|
586
|
+
|
|
587
|
+
# PATCH /ads/accounts/{accountId}/objects/{level}/{externalId} - change
|
|
588
|
+
# the name, budget or end date (end_at: nil removes it) of a campaign
|
|
589
|
+
# or ad set made outside OmniSocials.
|
|
590
|
+
#
|
|
591
|
+
# A higher budget RAISES REAL AD SPEND: show the person the new amount
|
|
592
|
+
# and get their yes first, then pass it as confirm_budget_amount. It
|
|
593
|
+
# changes the campaign on the network: needs a key with the opt-in
|
|
594
|
+
# ads:spend scope ("Start ads"); without it, and on Google
|
|
595
|
+
# (api_draft_only) always, the call answers 403 start_in_app with the
|
|
596
|
+
# page where a person does it in the app. Not retried after a 5xx, a
|
|
597
|
+
# timeout or a lost connection: read the object with get. Requires
|
|
598
|
+
# ads:write.
|
|
599
|
+
def update(account_id, level, external_id, name: nil, budget: nil, end_at: OmniSocials::NOT_GIVEN,
|
|
600
|
+
confirm_budget_amount: nil)
|
|
601
|
+
body = Internal.drop_nil(
|
|
602
|
+
{ "name" => name, "budget" => budget, "confirm_budget_amount" => confirm_budget_amount }
|
|
603
|
+
)
|
|
604
|
+
body["end_at"] = end_at unless end_at.is_a?(NotGiven)
|
|
605
|
+
@client.request(
|
|
606
|
+
"PATCH", object_path(account_id, level, external_id),
|
|
607
|
+
json: body, retry_on: :rate_limit
|
|
608
|
+
)
|
|
609
|
+
end
|
|
610
|
+
|
|
611
|
+
# PUT /ads/accounts/{accountId}/objects/{level}/{externalId}/status -
|
|
612
|
+
# status is "paused" or "active".
|
|
613
|
+
#
|
|
614
|
+
# Switching on STARTS REAL AD SPEND: pass the budget that pays (the
|
|
615
|
+
# object's own or its parent's) as confirm_budget_amount after the
|
|
616
|
+
# person agreed. Switching on: needs a key with the opt-in ads:spend
|
|
617
|
+
# scope ("Start ads"); without it, and on Google (api_draft_only)
|
|
618
|
+
# always, the call answers 403 start_in_app with the page where a person
|
|
619
|
+
# does it in the app. Pausing needs nothing and stays open (Google:
|
|
620
|
+
# start_in_app). Not retried after a 5xx, a timeout or a lost
|
|
621
|
+
# connection. Requires ads:write.
|
|
622
|
+
def set_status(account_id, level, external_id, status:, confirm_budget_amount: nil)
|
|
623
|
+
@client.request(
|
|
624
|
+
"PUT", "#{object_path(account_id, level, external_id)}/status",
|
|
625
|
+
json: Internal.drop_nil(
|
|
626
|
+
{ "status" => status, "confirm_budget_amount" => confirm_budget_amount }
|
|
627
|
+
),
|
|
628
|
+
retry_on: :rate_limit
|
|
629
|
+
)
|
|
630
|
+
end
|
|
631
|
+
|
|
632
|
+
# POST /ads/accounts/{accountId}/objects/{level}/{externalId}/duplicate -
|
|
633
|
+
# copy an object made outside OmniSocials; the copy is paused (Meta
|
|
634
|
+
# today). It changes the ad account on the network: needs a key with the
|
|
635
|
+
# opt-in ads:spend scope ("Start ads"); without it, and on Google
|
|
636
|
+
# (api_draft_only) always, the call answers 403 start_in_app with the
|
|
637
|
+
# page where a person does it in the app. Requires ads:write.
|
|
638
|
+
def duplicate(account_id, level, external_id, deep: nil, rename: nil)
|
|
639
|
+
@client.request(
|
|
640
|
+
"POST", "#{object_path(account_id, level, external_id)}/duplicate",
|
|
641
|
+
json: Internal.drop_nil({ "deep" => deep, "rename" => rename })
|
|
642
|
+
)
|
|
643
|
+
end
|
|
644
|
+
|
|
645
|
+
# GET /ads/accounts/{accountId}/import - the import state of the
|
|
646
|
+
# campaigns made outside OmniSocials. Requires ads:read.
|
|
647
|
+
def import_status(account_id)
|
|
648
|
+
@client.request("GET", account_path(account_id, "import"))
|
|
649
|
+
end
|
|
650
|
+
|
|
651
|
+
# POST /ads/accounts/{accountId}/import - read the ad account again at
|
|
652
|
+
# the next sync (within 15 minutes). The first import reads 90 days;
|
|
653
|
+
# webhook ads.initial_sync_completed when it is done. Requires
|
|
654
|
+
# ads:write.
|
|
655
|
+
def start_import(account_id)
|
|
656
|
+
@client.request("POST", account_path(account_id, "import"))
|
|
657
|
+
end
|
|
658
|
+
|
|
659
|
+
# GET /ads/external-campaigns - the imported campaigns (limit at most
|
|
660
|
+
# 200). Requires ads:read.
|
|
661
|
+
def list_external(ad_account_id: nil, platform: nil, status: nil, limit: nil, offset: nil)
|
|
662
|
+
@client.request(
|
|
663
|
+
"GET", "/ads/external-campaigns",
|
|
664
|
+
query: {
|
|
665
|
+
"ad_account_id" => ad_account_id, "platform" => platform, "status" => status,
|
|
666
|
+
"limit" => limit, "offset" => offset
|
|
667
|
+
}
|
|
668
|
+
)
|
|
669
|
+
end
|
|
670
|
+
|
|
671
|
+
# GET /ads/external-campaigns/{id} - one imported campaign with its
|
|
672
|
+
# daily numbers. Requires ads:read.
|
|
673
|
+
def get_external(campaign_id, from: nil, to: nil)
|
|
674
|
+
@client.request(
|
|
675
|
+
"GET", "/ads/external-campaigns/#{seg(campaign_id)}",
|
|
676
|
+
query: { "from" => from, "to" => to }
|
|
677
|
+
)
|
|
678
|
+
end
|
|
679
|
+
end
|
|
680
|
+
|
|
681
|
+
# The ads of an OmniSocials campaign.
|
|
682
|
+
class AdCampaignAds
|
|
683
|
+
include AdPaths
|
|
684
|
+
|
|
685
|
+
def initialize(client)
|
|
686
|
+
@client = client
|
|
687
|
+
end
|
|
688
|
+
|
|
689
|
+
# GET /ads/campaigns/{id}/ads - the ads with their status, review and
|
|
690
|
+
# latest numbers. Requires ads:read.
|
|
691
|
+
def list(campaign_id)
|
|
692
|
+
@client.request("GET", "/ads/campaigns/#{seg(campaign_id)}/ads")
|
|
693
|
+
end
|
|
694
|
+
|
|
695
|
+
# POST /ads/campaigns/{id}/ads - add up to 6 ads (the shape of a draft
|
|
696
|
+
# ad) to a campaign that runs. They are created PAUSED on the network;
|
|
697
|
+
# switch each one on with set_status. Needs a key with the opt-in
|
|
698
|
+
# ads:spend scope ("Start ads"); without it, and on Google
|
|
699
|
+
# (api_draft_only) always, the call answers 403 start_in_app with the
|
|
700
|
+
# page where a person does it in the app. Webhook ad.created. Requires
|
|
701
|
+
# ads:write.
|
|
702
|
+
def add(campaign_id, ads)
|
|
703
|
+
@client.request("POST", "/ads/campaigns/#{seg(campaign_id)}/ads", json: { "ads" => ads.to_a })
|
|
704
|
+
end
|
|
705
|
+
|
|
706
|
+
# GET /ads/campaigns/{id}/ads/{adId} - one ad. Requires ads:read.
|
|
707
|
+
def get(campaign_id, ad_id)
|
|
708
|
+
@client.request("GET", ad_path(campaign_id, ad_id))
|
|
709
|
+
end
|
|
710
|
+
|
|
711
|
+
# PUT /ads/campaigns/{id}/ads/{adId}/status - "paused" or "active".
|
|
712
|
+
#
|
|
713
|
+
# Switching on STARTS REAL AD SPEND: pass the campaign budget as
|
|
714
|
+
# confirm_budget_amount after the person agreed. Switching on: needs a
|
|
715
|
+
# key with the opt-in ads:spend scope ("Start ads"); without it, and on
|
|
716
|
+
# Google (api_draft_only) always, the call answers 403 start_in_app with
|
|
717
|
+
# the page where a person does it in the app. Pausing stays open
|
|
718
|
+
# (Google: start_in_app). Not retried after a 5xx, a timeout or a lost
|
|
719
|
+
# connection. Webhook ad.updated. Requires ads:write.
|
|
720
|
+
def set_status(campaign_id, ad_id, status:, confirm_budget_amount: nil)
|
|
721
|
+
@client.request(
|
|
722
|
+
"PUT", "#{ad_path(campaign_id, ad_id)}/status",
|
|
723
|
+
json: Internal.drop_nil(
|
|
724
|
+
{ "status" => status, "confirm_budget_amount" => confirm_budget_amount }
|
|
725
|
+
),
|
|
726
|
+
retry_on: :rate_limit
|
|
727
|
+
)
|
|
728
|
+
end
|
|
729
|
+
|
|
730
|
+
# GET /ads/campaigns/{id}/ads/{adId}/review - the network's review
|
|
731
|
+
# verdict ("in_review", "approved" or "rejected" with reasons).
|
|
732
|
+
# Requires ads:read.
|
|
733
|
+
def review(campaign_id, ad_id)
|
|
734
|
+
@client.request("GET", "#{ad_path(campaign_id, ad_id)}/review")
|
|
735
|
+
end
|
|
736
|
+
end
|
|
737
|
+
|
|
738
|
+
# Comments on an ad of an OmniSocials campaign.
|
|
739
|
+
class AdComments
|
|
740
|
+
include AdPaths
|
|
741
|
+
|
|
742
|
+
def initialize(client)
|
|
743
|
+
@client = client
|
|
744
|
+
end
|
|
745
|
+
|
|
746
|
+
# GET /ads/campaigns/{id}/ads/{adId}/comments. Requires ads:read.
|
|
747
|
+
def list(campaign_id, ad_id, cursor: nil)
|
|
748
|
+
@client.request("GET", "#{ad_path(campaign_id, ad_id)}/comments", query: { "cursor" => cursor })
|
|
749
|
+
end
|
|
750
|
+
|
|
751
|
+
# POST /ads/campaigns/{id}/ads/{adId}/comments/{commentId}/reply -
|
|
752
|
+
# answer a comment. Requires ads:write.
|
|
753
|
+
def reply(campaign_id, ad_id, comment_id, text)
|
|
754
|
+
@client.request(
|
|
755
|
+
"POST", "#{ad_path(campaign_id, ad_id)}/comments/#{seg(comment_id)}/reply",
|
|
756
|
+
json: { "text" => text }
|
|
757
|
+
)
|
|
758
|
+
end
|
|
759
|
+
|
|
760
|
+
# POST /ads/campaigns/{id}/ads/{adId}/comments/{commentId}/hide - hide
|
|
761
|
+
# (default) or show a comment. Requires ads:write.
|
|
762
|
+
def hide(campaign_id, ad_id, comment_id, hidden: true)
|
|
763
|
+
@client.request(
|
|
764
|
+
"POST", "#{ad_path(campaign_id, ad_id)}/comments/#{seg(comment_id)}/hide",
|
|
765
|
+
json: { "hidden" => hidden }
|
|
766
|
+
)
|
|
767
|
+
end
|
|
768
|
+
|
|
769
|
+
# DELETE /ads/campaigns/{id}/ads/{adId}/comments/{commentId}. Requires
|
|
770
|
+
# ads:write.
|
|
771
|
+
def delete(campaign_id, ad_id, comment_id)
|
|
772
|
+
@client.request("DELETE", "#{ad_path(campaign_id, ad_id)}/comments/#{seg(comment_id)}")
|
|
773
|
+
end
|
|
774
|
+
end
|
|
775
|
+
|
|
776
|
+
# Targeting options of a network. The ids go in
|
|
777
|
+
# targeting["networks"][<network>]["include"] of a draft (or
|
|
778
|
+
# targeting["network"] of a campaign); the types per network are
|
|
779
|
+
# ads.capabilities "targeting_types".
|
|
780
|
+
class AdTargeting
|
|
781
|
+
def initialize(client)
|
|
782
|
+
@client = client
|
|
783
|
+
end
|
|
784
|
+
|
|
785
|
+
# GET /ads/targeting/search - interests, places, languages, job titles
|
|
786
|
+
# ... (limit at most 100). Requires ads:read.
|
|
787
|
+
def search(ad_account_id:, type:, q:, limit: nil, country: nil)
|
|
788
|
+
@client.request(
|
|
789
|
+
"GET", "/ads/targeting/search",
|
|
790
|
+
query: {
|
|
791
|
+
"ad_account_id" => ad_account_id, "type" => type, "q" => q,
|
|
792
|
+
"limit" => limit, "country" => country
|
|
793
|
+
}
|
|
794
|
+
)
|
|
795
|
+
end
|
|
796
|
+
|
|
797
|
+
# GET /ads/targeting/browse - the categories as a tree. Requires
|
|
798
|
+
# ads:read.
|
|
799
|
+
def browse(ad_account_id:, type:)
|
|
800
|
+
@client.request(
|
|
801
|
+
"GET", "/ads/targeting/browse", query: { "ad_account_id" => ad_account_id, "type" => type }
|
|
802
|
+
)
|
|
803
|
+
end
|
|
804
|
+
|
|
805
|
+
# POST /ads/targeting/reach-estimate - the audience size of a targeting
|
|
806
|
+
# ("countries", "age_min", "age_max", "genders", "network"). Read-only.
|
|
807
|
+
# Requires ads:read.
|
|
808
|
+
def reach_estimate(ad_account_id:, targeting:, objective: nil)
|
|
809
|
+
@client.request(
|
|
810
|
+
"POST", "/ads/targeting/reach-estimate",
|
|
811
|
+
json: Internal.drop_nil(
|
|
812
|
+
{ "ad_account_id" => ad_account_id, "objective" => objective, "targeting" => targeting }
|
|
813
|
+
)
|
|
814
|
+
)
|
|
815
|
+
end
|
|
816
|
+
|
|
817
|
+
# POST /ads/targeting/bid-suggestions - a suggested bid and daily
|
|
818
|
+
# budget. Read-only. Requires ads:read.
|
|
819
|
+
def bid_suggestions(ad_account_id:, targeting:, objective: nil, budget: nil)
|
|
820
|
+
@client.request(
|
|
821
|
+
"POST", "/ads/targeting/bid-suggestions",
|
|
822
|
+
json: Internal.drop_nil(
|
|
823
|
+
{
|
|
824
|
+
"ad_account_id" => ad_account_id, "objective" => objective,
|
|
825
|
+
"targeting" => targeting, "budget" => budget
|
|
826
|
+
}
|
|
827
|
+
)
|
|
828
|
+
)
|
|
829
|
+
end
|
|
830
|
+
end
|
|
831
|
+
|
|
832
|
+
# Custom audiences of an ad account: customer lists, lookalikes and
|
|
833
|
+
# company lists. audience_id is the network's audience id.
|
|
834
|
+
class AdAudiences
|
|
835
|
+
include AdPaths
|
|
836
|
+
|
|
837
|
+
def initialize(client)
|
|
838
|
+
@client = client
|
|
839
|
+
end
|
|
840
|
+
|
|
841
|
+
# GET /ads/audiences. Requires ads:read.
|
|
842
|
+
def list(ad_account_id:, cursor: nil)
|
|
843
|
+
@client.request(
|
|
844
|
+
"GET", "/ads/audiences", query: { "ad_account_id" => ad_account_id, "cursor" => cursor }
|
|
845
|
+
)
|
|
846
|
+
end
|
|
847
|
+
|
|
848
|
+
# POST /ads/audiences - kind is "customer_list", "lookalike" (lookalike:
|
|
849
|
+
# { "source_audience_id", "country", "ratio" }, ratio 0.01 to 0.2) or
|
|
850
|
+
# "company_list". customer_file_source (Meta: "user_provided",
|
|
851
|
+
# "partner_provided" or "both") is what the person says. schema + rows
|
|
852
|
+
# are optional first members of a customer list (Pinterest needs
|
|
853
|
+
# them); raw values are hashed with SHA-256 before they leave.
|
|
854
|
+
# Requires ads:write.
|
|
855
|
+
def create(ad_account_id:, name:, description: nil, kind: nil, lookalike: nil,
|
|
856
|
+
customer_file_source: nil, schema: nil, rows: nil)
|
|
857
|
+
@client.request(
|
|
858
|
+
"POST", "/ads/audiences",
|
|
859
|
+
json: Internal.drop_nil(
|
|
860
|
+
{
|
|
861
|
+
"ad_account_id" => ad_account_id, "name" => name, "description" => description,
|
|
862
|
+
"kind" => kind, "lookalike" => lookalike,
|
|
863
|
+
"customer_file_source" => customer_file_source,
|
|
864
|
+
"schema" => schema&.to_a, "rows" => rows&.to_a
|
|
865
|
+
}
|
|
866
|
+
)
|
|
867
|
+
)
|
|
868
|
+
end
|
|
869
|
+
|
|
870
|
+
# GET /ads/audiences/{audienceId}. Requires ads:read.
|
|
871
|
+
def get(audience_id, ad_account_id:)
|
|
872
|
+
@client.request(
|
|
873
|
+
"GET", "/ads/audiences/#{seg(audience_id)}", query: { "ad_account_id" => ad_account_id }
|
|
874
|
+
)
|
|
875
|
+
end
|
|
876
|
+
|
|
877
|
+
# PATCH /ads/audiences/{audienceId} - rename. Requires ads:write.
|
|
878
|
+
def update(audience_id, ad_account_id:, name: nil, description: nil)
|
|
879
|
+
@client.request(
|
|
880
|
+
"PATCH", "/ads/audiences/#{seg(audience_id)}",
|
|
881
|
+
json: Internal.drop_nil(
|
|
882
|
+
{ "ad_account_id" => ad_account_id, "name" => name, "description" => description }
|
|
883
|
+
)
|
|
884
|
+
)
|
|
885
|
+
end
|
|
886
|
+
|
|
887
|
+
# DELETE /ads/audiences/{audienceId}. Requires ads:write.
|
|
888
|
+
def delete(audience_id, ad_account_id:)
|
|
889
|
+
@client.request(
|
|
890
|
+
"DELETE", "/ads/audiences/#{seg(audience_id)}", query: { "ad_account_id" => ad_account_id }
|
|
891
|
+
)
|
|
892
|
+
end
|
|
893
|
+
|
|
894
|
+
# POST /ads/audiences/{audienceId}/members - add people to a customer
|
|
895
|
+
# list. Send the raw values: OmniSocials normalizes them and hashes
|
|
896
|
+
# them with SHA-256 before they leave and stores nothing. At most
|
|
897
|
+
# 10,000 rows. schema keys: email, phone, first_name, last_name, city,
|
|
898
|
+
# state, zip, country, external_id, dob_year, gender, maid. Requires
|
|
899
|
+
# ads:write.
|
|
900
|
+
def add_members(audience_id, ad_account_id:, schema:, rows:)
|
|
901
|
+
@client.request(
|
|
902
|
+
"POST", "/ads/audiences/#{seg(audience_id)}/members",
|
|
903
|
+
json: { "ad_account_id" => ad_account_id, "schema" => schema.to_a, "rows" => rows.to_a }
|
|
904
|
+
)
|
|
905
|
+
end
|
|
906
|
+
|
|
907
|
+
# DELETE /ads/audiences/{audienceId}/members - remove people (the same
|
|
908
|
+
# body as add_members). Requires ads:write.
|
|
909
|
+
def remove_members(audience_id, ad_account_id:, schema:, rows:)
|
|
910
|
+
@client.request(
|
|
911
|
+
"DELETE", "/ads/audiences/#{seg(audience_id)}/members",
|
|
912
|
+
json: { "ad_account_id" => ad_account_id, "schema" => schema.to_a, "rows" => rows.to_a }
|
|
913
|
+
)
|
|
914
|
+
end
|
|
915
|
+
|
|
916
|
+
# POST /ads/audiences/{audienceId}/companies - add companies ("name",
|
|
917
|
+
# "domain", "linkedin_url") to a company list (LinkedIn). Requires
|
|
918
|
+
# ads:write.
|
|
919
|
+
def add_companies(audience_id, ad_account_id:, companies:)
|
|
920
|
+
@client.request(
|
|
921
|
+
"POST", "/ads/audiences/#{seg(audience_id)}/companies",
|
|
922
|
+
json: { "ad_account_id" => ad_account_id, "companies" => companies.to_a }
|
|
923
|
+
)
|
|
924
|
+
end
|
|
925
|
+
end
|
|
926
|
+
|
|
927
|
+
# Lead forms (Meta: the workspace's Page). form_id is the OmniSocials
|
|
928
|
+
# form id; a form's "external_id" goes in settings "lead_form_id".
|
|
929
|
+
class AdLeadForms
|
|
930
|
+
include AdPaths
|
|
931
|
+
|
|
932
|
+
def initialize(client)
|
|
933
|
+
@client = client
|
|
934
|
+
end
|
|
935
|
+
|
|
936
|
+
# GET /ads/lead-forms. Requires ads:read.
|
|
937
|
+
def list(ad_account_id:)
|
|
938
|
+
@client.request("GET", "/ads/lead-forms", query: { "ad_account_id" => ad_account_id })
|
|
939
|
+
end
|
|
940
|
+
|
|
941
|
+
# POST /ads/lead-forms. accept_terms: true says the person accepts the
|
|
942
|
+
# network's lead ad terms (Pinterest refuses a form without it): only
|
|
943
|
+
# send it after the person said yes. Requires ads:write.
|
|
944
|
+
def create(ad_account_id:, name:, privacy_policy_url:, questions:, thank_you:, locale: nil,
|
|
945
|
+
headline: nil, description: nil, accept_terms: nil)
|
|
946
|
+
@client.request(
|
|
947
|
+
"POST", "/ads/lead-forms",
|
|
948
|
+
json: Internal.drop_nil(
|
|
949
|
+
{
|
|
950
|
+
"ad_account_id" => ad_account_id, "name" => name,
|
|
951
|
+
"privacy_policy_url" => privacy_policy_url, "locale" => locale,
|
|
952
|
+
"headline" => headline, "description" => description,
|
|
953
|
+
"questions" => questions.to_a, "thank_you" => thank_you,
|
|
954
|
+
"accept_terms" => accept_terms
|
|
955
|
+
}
|
|
956
|
+
)
|
|
957
|
+
)
|
|
958
|
+
end
|
|
959
|
+
|
|
960
|
+
# GET /ads/lead-forms/{formId}. Requires ads:read.
|
|
961
|
+
def get(form_id)
|
|
962
|
+
@client.request("GET", "/ads/lead-forms/#{seg(form_id)}")
|
|
963
|
+
end
|
|
964
|
+
|
|
965
|
+
# PATCH /ads/lead-forms/{formId} - archive or open a form (status
|
|
966
|
+
# "archived" or "active"), or switch its lead sync. Requires ads:write.
|
|
967
|
+
def update(form_id, status: nil, sync_enabled: nil)
|
|
968
|
+
@client.request(
|
|
969
|
+
"PATCH", "/ads/lead-forms/#{seg(form_id)}",
|
|
970
|
+
json: Internal.drop_nil({ "status" => status, "sync_enabled" => sync_enabled })
|
|
971
|
+
)
|
|
972
|
+
end
|
|
973
|
+
|
|
974
|
+
# DELETE /ads/lead-forms/{formId} - archive a form (the leads already
|
|
975
|
+
# copied stay). Requires ads:write.
|
|
976
|
+
def delete(form_id)
|
|
977
|
+
@client.request("DELETE", "/ads/lead-forms/#{seg(form_id)}")
|
|
978
|
+
end
|
|
979
|
+
|
|
980
|
+
# POST /ads/lead-forms/{formId}/test-leads - a test lead (the next sync
|
|
981
|
+
# copies it, marked is_test). Requires ads:write.
|
|
982
|
+
def send_test_lead(form_id, fields: nil)
|
|
983
|
+
@client.request(
|
|
984
|
+
"POST", "/ads/lead-forms/#{seg(form_id)}/test-leads",
|
|
985
|
+
json: Internal.drop_nil({ "fields" => fields })
|
|
986
|
+
)
|
|
987
|
+
end
|
|
988
|
+
end
|
|
989
|
+
|
|
990
|
+
# Leads of the workspace, copied from the networks every 15 minutes
|
|
991
|
+
# (webhook lead.received). The answers are personal data.
|
|
992
|
+
class AdLeads
|
|
993
|
+
include AdPaths
|
|
994
|
+
|
|
995
|
+
def initialize(client)
|
|
996
|
+
@client = client
|
|
997
|
+
end
|
|
998
|
+
|
|
999
|
+
# GET /ads/leads - newest first (limit at most 200). Requires ads:read.
|
|
1000
|
+
def list(form_id: nil, status: nil, since: nil, until_time: nil, limit: nil, cursor: nil)
|
|
1001
|
+
@client.request(
|
|
1002
|
+
"GET", "/ads/leads",
|
|
1003
|
+
query: {
|
|
1004
|
+
"form_id" => form_id, "status" => status, "since" => since,
|
|
1005
|
+
"until" => until_time, "limit" => limit, "cursor" => cursor
|
|
1006
|
+
}
|
|
1007
|
+
)
|
|
1008
|
+
end
|
|
1009
|
+
|
|
1010
|
+
# GET /ads/leads/counts - "total" and "by_status". Requires ads:read.
|
|
1011
|
+
def counts(form_id: nil)
|
|
1012
|
+
@client.request("GET", "/ads/leads/counts", query: { "form_id" => form_id })
|
|
1013
|
+
end
|
|
1014
|
+
|
|
1015
|
+
# PATCH /ads/leads/{leadId} - status is "new", "contacted",
|
|
1016
|
+
# "qualified", "won", "lost" or "spam". Requires ads:write.
|
|
1017
|
+
def update(lead_id, status: nil, note: nil)
|
|
1018
|
+
@client.request(
|
|
1019
|
+
"PATCH", "/ads/leads/#{seg(lead_id)}",
|
|
1020
|
+
json: Internal.drop_nil({ "status" => status, "note" => note })
|
|
1021
|
+
)
|
|
1022
|
+
end
|
|
1023
|
+
end
|
|
1024
|
+
|
|
1025
|
+
# Pixels, conversion goals, custom conversions and server-side
|
|
1026
|
+
# conversion events.
|
|
1027
|
+
class AdConversions
|
|
1028
|
+
def initialize(client)
|
|
1029
|
+
@client = client
|
|
1030
|
+
end
|
|
1031
|
+
|
|
1032
|
+
# GET /ads/conversions/destinations - pixels, datasets, conversion tags
|
|
1033
|
+
# and conversion actions. Requires ads:read.
|
|
1034
|
+
def destinations(ad_account_id:)
|
|
1035
|
+
@client.request(
|
|
1036
|
+
"GET", "/ads/conversions/destinations", query: { "ad_account_id" => ad_account_id }
|
|
1037
|
+
)
|
|
1038
|
+
end
|
|
1039
|
+
|
|
1040
|
+
# GET /ads/conversions/goals - the events a campaign can optimise for.
|
|
1041
|
+
# Requires ads:read.
|
|
1042
|
+
def goals(ad_account_id:)
|
|
1043
|
+
@client.request("GET", "/ads/conversions/goals", query: { "ad_account_id" => ad_account_id })
|
|
1044
|
+
end
|
|
1045
|
+
|
|
1046
|
+
# POST /ads/conversions/custom - a custom conversion (a URL rule and/or
|
|
1047
|
+
# an event on a pixel). Requires ads:write.
|
|
1048
|
+
def create_custom(ad_account_id:, name:, destination_id:, event: nil, url_contains: nil)
|
|
1049
|
+
@client.request(
|
|
1050
|
+
"POST", "/ads/conversions/custom",
|
|
1051
|
+
json: Internal.drop_nil(
|
|
1052
|
+
{
|
|
1053
|
+
"ad_account_id" => ad_account_id, "name" => name,
|
|
1054
|
+
"destination_id" => destination_id, "event" => event,
|
|
1055
|
+
"url_contains" => url_contains
|
|
1056
|
+
}
|
|
1057
|
+
)
|
|
1058
|
+
)
|
|
1059
|
+
end
|
|
1060
|
+
|
|
1061
|
+
# POST /ads/conversions/events - up to 1,000 conversion events from
|
|
1062
|
+
# your server. Send the raw email and phone: OmniSocials normalizes
|
|
1063
|
+
# and SHA-256 hashes them before they leave and stores nothing.
|
|
1064
|
+
# Requires ads:write.
|
|
1065
|
+
def send_events(ad_account_id:, destination_id:, events:)
|
|
1066
|
+
@client.request(
|
|
1067
|
+
"POST", "/ads/conversions/events",
|
|
1068
|
+
json: {
|
|
1069
|
+
"ad_account_id" => ad_account_id, "destination_id" => destination_id,
|
|
1070
|
+
"events" => events.to_a
|
|
1071
|
+
}
|
|
1072
|
+
)
|
|
1073
|
+
end
|
|
1074
|
+
end
|
|
1075
|
+
|
|
1076
|
+
# Body of ads.insights.query and ads.reports.start.
|
|
1077
|
+
module AdInsightsBody
|
|
1078
|
+
private
|
|
1079
|
+
|
|
1080
|
+
def insights_body(ad_account_id:, level:, ids:, metrics:, breakdowns:, from:, to:, time_increment:)
|
|
1081
|
+
Internal.drop_nil(
|
|
1082
|
+
{
|
|
1083
|
+
"ad_account_id" => ad_account_id, "level" => level, "ids" => ids&.to_a,
|
|
1084
|
+
"metrics" => metrics&.to_a, "breakdowns" => breakdowns&.to_a,
|
|
1085
|
+
"from" => from, "to" => to, "time_increment" => time_increment
|
|
1086
|
+
}
|
|
1087
|
+
)
|
|
1088
|
+
end
|
|
1089
|
+
end
|
|
1090
|
+
|
|
1091
|
+
# Numbers: live from the network, per campaign or ad, over time, ranked,
|
|
1092
|
+
# and what needs attention.
|
|
1093
|
+
class AdInsights
|
|
1094
|
+
include AdPaths
|
|
1095
|
+
include AdInsightsBody
|
|
1096
|
+
|
|
1097
|
+
def initialize(client)
|
|
1098
|
+
@client = client
|
|
1099
|
+
end
|
|
1100
|
+
|
|
1101
|
+
# POST /ads/insights - live numbers from the network by day, ad,
|
|
1102
|
+
# country, age, gender, placement, device or platform (at most 2
|
|
1103
|
+
# breakdowns). Read-only. Requires ads:read.
|
|
1104
|
+
def query(ad_account_id:, level: nil, ids: nil, metrics: nil, breakdowns: nil, from: nil,
|
|
1105
|
+
to: nil, time_increment: nil)
|
|
1106
|
+
@client.request(
|
|
1107
|
+
"POST", "/ads/insights",
|
|
1108
|
+
json: insights_body(
|
|
1109
|
+
ad_account_id: ad_account_id, level: level, ids: ids, metrics: metrics,
|
|
1110
|
+
breakdowns: breakdowns, from: from, to: to, time_increment: time_increment
|
|
1111
|
+
)
|
|
1112
|
+
)
|
|
1113
|
+
end
|
|
1114
|
+
|
|
1115
|
+
# GET /ads/campaigns/{id}/analytics - numbers of an OmniSocials campaign
|
|
1116
|
+
# (breakdown: "ad" gives one row per ad). Requires ads:read.
|
|
1117
|
+
def campaign(campaign_id, from: nil, to: nil, breakdown: nil, time_increment: nil, metrics: nil)
|
|
1118
|
+
@client.request(
|
|
1119
|
+
"GET", "/ads/campaigns/#{seg(campaign_id)}/analytics",
|
|
1120
|
+
query: {
|
|
1121
|
+
"from" => from, "to" => to, "breakdown" => breakdown,
|
|
1122
|
+
"time_increment" => time_increment, "metrics" => list_param(metrics)
|
|
1123
|
+
}
|
|
1124
|
+
)
|
|
1125
|
+
end
|
|
1126
|
+
|
|
1127
|
+
# GET /ads/campaigns/{id}/ads/{adId}/analytics - numbers of one ad.
|
|
1128
|
+
# Requires ads:read.
|
|
1129
|
+
def ad(campaign_id, ad_id, from: nil, to: nil, breakdown: nil)
|
|
1130
|
+
@client.request(
|
|
1131
|
+
"GET", "#{ad_path(campaign_id, ad_id)}/analytics",
|
|
1132
|
+
query: { "from" => from, "to" => to, "breakdown" => breakdown }
|
|
1133
|
+
)
|
|
1134
|
+
end
|
|
1135
|
+
|
|
1136
|
+
# GET /ads/timeline - daily totals of the workspace (source "all",
|
|
1137
|
+
# "omnisocials" or "external"). Requires ads:read.
|
|
1138
|
+
def timeline(from: nil, to: nil, platform: nil, source: nil)
|
|
1139
|
+
@client.request(
|
|
1140
|
+
"GET", "/ads/timeline",
|
|
1141
|
+
query: { "from" => from, "to" => to, "platform" => platform, "source" => source }
|
|
1142
|
+
)
|
|
1143
|
+
end
|
|
1144
|
+
|
|
1145
|
+
# GET /ads/performance - campaigns or ads ranked by one metric.
|
|
1146
|
+
# Requires ads:read.
|
|
1147
|
+
def performance(level: nil, metric: nil, order: nil, limit: nil, min_impressions: nil,
|
|
1148
|
+
from: nil, to: nil, platform: nil)
|
|
1149
|
+
@client.request(
|
|
1150
|
+
"GET", "/ads/performance",
|
|
1151
|
+
query: {
|
|
1152
|
+
"level" => level, "metric" => metric, "order" => order, "limit" => limit,
|
|
1153
|
+
"min_impressions" => min_impressions, "from" => from, "to" => to,
|
|
1154
|
+
"platform" => platform
|
|
1155
|
+
}
|
|
1156
|
+
)
|
|
1157
|
+
end
|
|
1158
|
+
|
|
1159
|
+
# GET /ads/alerts - rejected ads, held campaigns, sign-in or payment
|
|
1160
|
+
# problems, no delivery. Requires ads:read.
|
|
1161
|
+
def alerts
|
|
1162
|
+
@client.request("GET", "/ads/alerts")
|
|
1163
|
+
end
|
|
1164
|
+
end
|
|
1165
|
+
|
|
1166
|
+
# Long reports that run in the background (up to 730 days).
|
|
1167
|
+
class AdReports
|
|
1168
|
+
include AdPaths
|
|
1169
|
+
include AdInsightsBody
|
|
1170
|
+
|
|
1171
|
+
def initialize(client)
|
|
1172
|
+
@client = client
|
|
1173
|
+
end
|
|
1174
|
+
|
|
1175
|
+
# GET /ads/insights/reports. Requires ads:read.
|
|
1176
|
+
def list
|
|
1177
|
+
@client.request("GET", "/ads/insights/reports")
|
|
1178
|
+
end
|
|
1179
|
+
|
|
1180
|
+
# POST /ads/insights/reports - start a report with the fields of
|
|
1181
|
+
# ads.insights.query; poll get. Requires ads:read.
|
|
1182
|
+
def start(ad_account_id:, level: nil, ids: nil, metrics: nil, breakdowns: nil, from: nil,
|
|
1183
|
+
to: nil, time_increment: nil)
|
|
1184
|
+
@client.request(
|
|
1185
|
+
"POST", "/ads/insights/reports",
|
|
1186
|
+
json: insights_body(
|
|
1187
|
+
ad_account_id: ad_account_id, level: level, ids: ids, metrics: metrics,
|
|
1188
|
+
breakdowns: breakdowns, from: from, to: to, time_increment: time_increment
|
|
1189
|
+
)
|
|
1190
|
+
)
|
|
1191
|
+
end
|
|
1192
|
+
|
|
1193
|
+
# GET /ads/insights/reports/{reportId} - "running", "done" (with rows)
|
|
1194
|
+
# or "failed". Requires ads:read.
|
|
1195
|
+
def get(report_id)
|
|
1196
|
+
@client.request("GET", "/ads/insights/reports/#{seg(report_id)}")
|
|
1197
|
+
end
|
|
1198
|
+
end
|
|
1199
|
+
|
|
1200
|
+
# Automated rules: check campaigns on a schedule and notify, pause,
|
|
1201
|
+
# activate or adjust the budget. A rule that notifies, pauses or lowers a
|
|
1202
|
+
# budget works with ads:write. A rule that can raise spend ("activate", a
|
|
1203
|
+
# positive "adjust_budget") needs a key with ads:spend (else 403
|
|
1204
|
+
# rule_raises_spend) and action "max_daily_budget", confirmed by the
|
|
1205
|
+
# person as confirm_max_daily_budget; it never acts on Google. create,
|
|
1206
|
+
# update and undo are not retried after a 5xx, a timeout or a lost
|
|
1207
|
+
# connection.
|
|
1208
|
+
class AdRules
|
|
1209
|
+
include AdPaths
|
|
1210
|
+
|
|
1211
|
+
def initialize(client)
|
|
1212
|
+
@client = client
|
|
1213
|
+
end
|
|
1214
|
+
|
|
1215
|
+
# GET /ads/rules. Requires ads:read.
|
|
1216
|
+
def list
|
|
1217
|
+
@client.request("GET", "/ads/rules")
|
|
1218
|
+
end
|
|
1219
|
+
|
|
1220
|
+
# POST /ads/rules - a new rule, off until enabled: true.
|
|
1221
|
+
#
|
|
1222
|
+
# A rule that can RAISE REAL AD SPEND ("activate", a positive
|
|
1223
|
+
# "adjust_budget") needs the person's own ceiling as
|
|
1224
|
+
# confirm_max_daily_budget and a key with ads:spend (else 403
|
|
1225
|
+
# rule_raises_spend). Preview it first with preview. Not retried after a
|
|
1226
|
+
# 5xx, a timeout or a lost connection: read the rules with list.
|
|
1227
|
+
# Requires ads:write.
|
|
1228
|
+
def create(name:, conditions:, action:, ad_account_id: nil, enabled: nil, scope: nil,
|
|
1229
|
+
every_minutes: nil, cooldown_minutes: nil, max_actions_per_run: nil,
|
|
1230
|
+
confirm_max_daily_budget: nil)
|
|
1231
|
+
@client.request(
|
|
1232
|
+
"POST", "/ads/rules",
|
|
1233
|
+
json: rule_body(
|
|
1234
|
+
name: name, conditions: conditions, action: action, ad_account_id: ad_account_id,
|
|
1235
|
+
enabled: enabled, scope: scope, every_minutes: every_minutes,
|
|
1236
|
+
cooldown_minutes: cooldown_minutes, max_actions_per_run: max_actions_per_run,
|
|
1237
|
+
confirm_max_daily_budget: confirm_max_daily_budget
|
|
1238
|
+
),
|
|
1239
|
+
retry_on: :rate_limit
|
|
1240
|
+
)
|
|
1241
|
+
end
|
|
1242
|
+
|
|
1243
|
+
# GET /ads/rules/templates - ready-made rules. Requires ads:read.
|
|
1244
|
+
def templates
|
|
1245
|
+
@client.request("GET", "/ads/rules/templates")
|
|
1246
|
+
end
|
|
1247
|
+
|
|
1248
|
+
# POST /ads/rules/preview - what an unsaved rule would match and do
|
|
1249
|
+
# now. Requires ads:read.
|
|
1250
|
+
def preview(conditions:, action:, name: nil, ad_account_id: nil, scope: nil)
|
|
1251
|
+
@client.request(
|
|
1252
|
+
"POST", "/ads/rules/preview",
|
|
1253
|
+
json: Internal.drop_nil(
|
|
1254
|
+
{
|
|
1255
|
+
"name" => name, "ad_account_id" => ad_account_id, "scope" => scope,
|
|
1256
|
+
"conditions" => conditions.to_a, "action" => action
|
|
1257
|
+
}
|
|
1258
|
+
)
|
|
1259
|
+
)
|
|
1260
|
+
end
|
|
1261
|
+
|
|
1262
|
+
# GET /ads/rules/activity - every change the rules made, with before
|
|
1263
|
+
# and after. Requires ads:read.
|
|
1264
|
+
def activity(rule_id: nil, limit: nil)
|
|
1265
|
+
@client.request("GET", "/ads/rules/activity", query: { "rule_id" => rule_id, "limit" => limit })
|
|
1266
|
+
end
|
|
1267
|
+
|
|
1268
|
+
# POST /ads/rules/activity/{activityId}/undo - undo a change a rule
|
|
1269
|
+
# made.
|
|
1270
|
+
#
|
|
1271
|
+
# Undo of a pause or of a budget cut RESTARTS or RAISES REAL AD SPEND:
|
|
1272
|
+
# pass the amount as confirm_budget_amount after the person agreed, with
|
|
1273
|
+
# a key that has ads:spend (else, and on Google always, 403
|
|
1274
|
+
# start_in_app). Not retried after a 5xx, a timeout or a lost
|
|
1275
|
+
# connection. Requires ads:write.
|
|
1276
|
+
def undo(activity_id, confirm_budget_amount: nil)
|
|
1277
|
+
@client.request(
|
|
1278
|
+
"POST", "/ads/rules/activity/#{seg(activity_id)}/undo",
|
|
1279
|
+
json: Internal.drop_nil({ "confirm_budget_amount" => confirm_budget_amount }),
|
|
1280
|
+
retry_on: :rate_limit
|
|
1281
|
+
)
|
|
1282
|
+
end
|
|
1283
|
+
|
|
1284
|
+
# GET /ads/rules/{ruleId}. Requires ads:read.
|
|
1285
|
+
def get(rule_id)
|
|
1286
|
+
@client.request("GET", "/ads/rules/#{seg(rule_id)}")
|
|
1287
|
+
end
|
|
1288
|
+
|
|
1289
|
+
# PATCH /ads/rules/{ruleId} - change a rule (also enabled). A changed
|
|
1290
|
+
# action that can raise spend needs confirm_max_daily_budget again and a
|
|
1291
|
+
# key with ads:spend (else 403 rule_raises_spend). Not retried after a
|
|
1292
|
+
# 5xx, a timeout or a lost connection. Requires ads:write.
|
|
1293
|
+
def update(rule_id, name: nil, conditions: nil, action: nil, ad_account_id: nil, enabled: nil,
|
|
1294
|
+
scope: nil, every_minutes: nil, cooldown_minutes: nil, max_actions_per_run: nil,
|
|
1295
|
+
confirm_max_daily_budget: nil)
|
|
1296
|
+
@client.request(
|
|
1297
|
+
"PATCH", "/ads/rules/#{seg(rule_id)}",
|
|
1298
|
+
json: rule_body(
|
|
1299
|
+
name: name, conditions: conditions, action: action, ad_account_id: ad_account_id,
|
|
1300
|
+
enabled: enabled, scope: scope, every_minutes: every_minutes,
|
|
1301
|
+
cooldown_minutes: cooldown_minutes, max_actions_per_run: max_actions_per_run,
|
|
1302
|
+
confirm_max_daily_budget: confirm_max_daily_budget
|
|
1303
|
+
),
|
|
1304
|
+
retry_on: :rate_limit
|
|
1305
|
+
)
|
|
1306
|
+
end
|
|
1307
|
+
|
|
1308
|
+
# DELETE /ads/rules/{ruleId}. Requires ads:write.
|
|
1309
|
+
def delete(rule_id)
|
|
1310
|
+
@client.request("DELETE", "/ads/rules/#{seg(rule_id)}")
|
|
1311
|
+
end
|
|
1312
|
+
|
|
1313
|
+
# POST /ads/rules/{ruleId}/preview - what a saved rule would match and
|
|
1314
|
+
# do now. Requires ads:read.
|
|
1315
|
+
def preview_saved(rule_id)
|
|
1316
|
+
@client.request("POST", "/ads/rules/#{seg(rule_id)}/preview")
|
|
1317
|
+
end
|
|
1318
|
+
|
|
1319
|
+
# GET /ads/rules/{ruleId}/runs. Requires ads:read.
|
|
1320
|
+
def runs(rule_id, limit: nil)
|
|
1321
|
+
@client.request("GET", "/ads/rules/#{seg(rule_id)}/runs", query: { "limit" => limit })
|
|
1322
|
+
end
|
|
1323
|
+
|
|
1324
|
+
private
|
|
1325
|
+
|
|
1326
|
+
def rule_body(name:, conditions:, action:, ad_account_id:, enabled:, scope:, every_minutes:,
|
|
1327
|
+
cooldown_minutes:, max_actions_per_run:, confirm_max_daily_budget:)
|
|
1328
|
+
Internal.drop_nil(
|
|
1329
|
+
{
|
|
1330
|
+
"name" => name, "ad_account_id" => ad_account_id, "enabled" => enabled,
|
|
1331
|
+
"scope" => scope, "conditions" => conditions&.to_a, "action" => action,
|
|
1332
|
+
"every_minutes" => every_minutes, "cooldown_minutes" => cooldown_minutes,
|
|
1333
|
+
"max_actions_per_run" => max_actions_per_run,
|
|
1334
|
+
"confirm_max_daily_budget" => confirm_max_daily_budget
|
|
1335
|
+
}
|
|
1336
|
+
)
|
|
1337
|
+
end
|
|
1338
|
+
end
|
|
1339
|
+
|
|
1340
|
+
# Your own numbers per campaign and day (qualified leads, sales,
|
|
1341
|
+
# revenue). Rules read them as results.<metric>.
|
|
1342
|
+
class AdResults
|
|
1343
|
+
include AdPaths
|
|
1344
|
+
|
|
1345
|
+
def initialize(client)
|
|
1346
|
+
@client = client
|
|
1347
|
+
end
|
|
1348
|
+
|
|
1349
|
+
# GET /ads/campaign-results. Requires ads:read.
|
|
1350
|
+
def list(from: nil, to: nil, campaign_id: nil, metric: nil)
|
|
1351
|
+
@client.request(
|
|
1352
|
+
"GET", "/ads/campaign-results",
|
|
1353
|
+
query: { "from" => from, "to" => to, "campaign_id" => campaign_id, "metric" => metric }
|
|
1354
|
+
)
|
|
1355
|
+
end
|
|
1356
|
+
|
|
1357
|
+
# POST /ads/campaign-results - up to 5,000 rows of "day", "metric",
|
|
1358
|
+
# "value" and the campaign ("campaign_id", "external_campaign_id" +
|
|
1359
|
+
# "platform", "utm_campaign" or "campaign_name"). Sending a day again
|
|
1360
|
+
# replaces it. Requires ads:write.
|
|
1361
|
+
def upload(rows)
|
|
1362
|
+
@client.request("POST", "/ads/campaign-results", json: { "rows" => rows.to_a })
|
|
1363
|
+
end
|
|
1364
|
+
|
|
1365
|
+
# GET /ads/campaign-results/totals - totals over a period, with the
|
|
1366
|
+
# formulas. Requires ads:read.
|
|
1367
|
+
def totals(from: nil, to: nil, campaign_id: nil)
|
|
1368
|
+
@client.request(
|
|
1369
|
+
"GET", "/ads/campaign-results/totals",
|
|
1370
|
+
query: { "from" => from, "to" => to, "campaign_id" => campaign_id }
|
|
1371
|
+
)
|
|
1372
|
+
end
|
|
1373
|
+
|
|
1374
|
+
# GET /ads/campaign-results/metrics - your metric names and formulas.
|
|
1375
|
+
# Requires ads:read.
|
|
1376
|
+
def metrics
|
|
1377
|
+
@client.request("GET", "/ads/campaign-results/metrics")
|
|
1378
|
+
end
|
|
1379
|
+
|
|
1380
|
+
# PUT /ads/campaign-results/metrics/{key} - name a metric or define a
|
|
1381
|
+
# formula (unit "number", "money" or "percent"). Requires ads:write.
|
|
1382
|
+
def put_metric(key, label: nil, unit: nil, formula: nil)
|
|
1383
|
+
@client.request(
|
|
1384
|
+
"PUT", "/ads/campaign-results/metrics/#{seg(key)}",
|
|
1385
|
+
json: Internal.drop_nil({ "label" => label, "unit" => unit, "formula" => formula })
|
|
1386
|
+
)
|
|
1387
|
+
end
|
|
1388
|
+
end
|
|
1389
|
+
|
|
1390
|
+
# The network's own image and video library of an ad account. Use an id
|
|
1391
|
+
# in an ad as network[<network>]["media_ref"].
|
|
1392
|
+
class AdMedia
|
|
1393
|
+
include AdPaths
|
|
1394
|
+
|
|
1395
|
+
def initialize(client)
|
|
1396
|
+
@client = client
|
|
1397
|
+
end
|
|
1398
|
+
|
|
1399
|
+
# GET /ads/media. Requires ads:read.
|
|
1400
|
+
def list(ad_account_id:, type: nil, cursor: nil)
|
|
1401
|
+
@client.request(
|
|
1402
|
+
"GET", "/ads/media",
|
|
1403
|
+
query: { "ad_account_id" => ad_account_id, "type" => type, "cursor" => cursor }
|
|
1404
|
+
)
|
|
1405
|
+
end
|
|
1406
|
+
|
|
1407
|
+
# POST /ads/media - upload an image or video to the network ahead of an
|
|
1408
|
+
# ad. Requires ads:write.
|
|
1409
|
+
def upload(ad_account_id:, type:, url:, name: nil)
|
|
1410
|
+
@client.request(
|
|
1411
|
+
"POST", "/ads/media",
|
|
1412
|
+
json: Internal.drop_nil(
|
|
1413
|
+
{ "ad_account_id" => ad_account_id, "type" => type, "url" => url, "name" => name }
|
|
1414
|
+
)
|
|
1415
|
+
)
|
|
1416
|
+
end
|
|
1417
|
+
|
|
1418
|
+
# GET /ads/media/{mediaId} - the processing status of an upload.
|
|
1419
|
+
# Requires ads:read.
|
|
1420
|
+
def get(media_id, ad_account_id:, type: nil)
|
|
1421
|
+
@client.request(
|
|
1422
|
+
"GET", "/ads/media/#{seg(media_id)}",
|
|
1423
|
+
query: { "ad_account_id" => ad_account_id, "type" => type }
|
|
1424
|
+
)
|
|
1425
|
+
end
|
|
1426
|
+
|
|
1427
|
+
# DELETE /ads/media/{mediaId}. Requires ads:write.
|
|
1428
|
+
def delete(media_id, ad_account_id:, type:)
|
|
1429
|
+
@client.request(
|
|
1430
|
+
"DELETE", "/ads/media/#{seg(media_id)}",
|
|
1431
|
+
query: { "ad_account_id" => ad_account_id, "type" => type }
|
|
1432
|
+
)
|
|
1433
|
+
end
|
|
1434
|
+
end
|
|
1435
|
+
|
|
1436
|
+
# Previews drawn by the network.
|
|
1437
|
+
class AdPreviews
|
|
1438
|
+
include AdPaths
|
|
1439
|
+
|
|
1440
|
+
def initialize(client)
|
|
1441
|
+
@client = client
|
|
1442
|
+
end
|
|
1443
|
+
|
|
1444
|
+
# POST /ads/previews - previews of a new ad (the shape of a draft ad).
|
|
1445
|
+
# Read-only. Requires ads:read.
|
|
1446
|
+
def create(ad_account_id:, ad:, placements: nil, objective: nil)
|
|
1447
|
+
@client.request(
|
|
1448
|
+
"POST", "/ads/previews",
|
|
1449
|
+
json: Internal.drop_nil(
|
|
1450
|
+
{
|
|
1451
|
+
"ad_account_id" => ad_account_id, "ad" => ad,
|
|
1452
|
+
"placements" => placements&.to_a, "objective" => objective
|
|
1453
|
+
}
|
|
1454
|
+
)
|
|
1455
|
+
)
|
|
1456
|
+
end
|
|
1457
|
+
|
|
1458
|
+
# GET /ads/campaigns/{id}/ads/{adId}/previews - previews of an existing
|
|
1459
|
+
# ad. Requires ads:read.
|
|
1460
|
+
def for_ad(campaign_id, ad_id, placements: nil)
|
|
1461
|
+
@client.request(
|
|
1462
|
+
"GET", "#{ad_path(campaign_id, ad_id)}/previews",
|
|
1463
|
+
query: { "placements" => list_param(placements) }
|
|
1464
|
+
)
|
|
1465
|
+
end
|
|
1466
|
+
end
|
|
1467
|
+
|
|
1468
|
+
# Partnership ads with creators (Meta).
|
|
1469
|
+
class AdPartnership
|
|
1470
|
+
def initialize(client)
|
|
1471
|
+
@client = client
|
|
1472
|
+
end
|
|
1473
|
+
|
|
1474
|
+
# GET /ads/partnership/content - creator posts you may run as
|
|
1475
|
+
# partnership ads. Requires ads:read.
|
|
1476
|
+
def list_content(ad_account_id:)
|
|
1477
|
+
@client.request("GET", "/ads/partnership/content", query: { "ad_account_id" => ad_account_id })
|
|
1478
|
+
end
|
|
1479
|
+
|
|
1480
|
+
# GET /ads/partnership/permissions. Requires ads:read.
|
|
1481
|
+
def list_permissions(ad_account_id:)
|
|
1482
|
+
@client.request(
|
|
1483
|
+
"GET", "/ads/partnership/permissions", query: { "ad_account_id" => ad_account_id }
|
|
1484
|
+
)
|
|
1485
|
+
end
|
|
1486
|
+
|
|
1487
|
+
# POST /ads/partnership/permissions - ask for or set a permission;
|
|
1488
|
+
# Meta's fields pass through as keyword arguments. Requires ads:write.
|
|
1489
|
+
def set_permission(ad_account_id:, **fields)
|
|
1490
|
+
@client.request(
|
|
1491
|
+
"POST", "/ads/partnership/permissions",
|
|
1492
|
+
json: stringify(fields).merge("ad_account_id" => ad_account_id)
|
|
1493
|
+
)
|
|
1494
|
+
end
|
|
1495
|
+
|
|
1496
|
+
private
|
|
1497
|
+
|
|
1498
|
+
def stringify(fields)
|
|
1499
|
+
fields.each_with_object({}) { |(key, value), out| out[key.to_s] = value }
|
|
1500
|
+
end
|
|
1501
|
+
end
|
|
1502
|
+
|
|
1503
|
+
# Ad account admin: identities, health, finance, settings, people,
|
|
1504
|
+
# change log, businesses, DSA and the manager hierarchy. account_id is
|
|
1505
|
+
# the OmniSocials ad account id.
|
|
1506
|
+
class AdAccountsAdmin
|
|
1507
|
+
include AdPaths
|
|
1508
|
+
|
|
1509
|
+
def initialize(client)
|
|
1510
|
+
@client = client
|
|
1511
|
+
end
|
|
1512
|
+
|
|
1513
|
+
# GET /ads/accounts/{accountId}/identities - Pages, profiles and
|
|
1514
|
+
# identities an ad can run as. Requires ads:read.
|
|
1515
|
+
def identities(account_id)
|
|
1516
|
+
@client.request("GET", account_path(account_id, "identities"))
|
|
1517
|
+
end
|
|
1518
|
+
|
|
1519
|
+
# GET /ads/accounts/{accountId}/health - status, payment, spend limit,
|
|
1520
|
+
# Page and pixel before an ad starts. A check that cannot be read is
|
|
1521
|
+
# "unknown"; failed checks carry a "fix_url". Requires ads:read.
|
|
1522
|
+
def health(account_id)
|
|
1523
|
+
@client.request("GET", account_path(account_id, "health"))
|
|
1524
|
+
end
|
|
1525
|
+
|
|
1526
|
+
# GET /ads/accounts/{accountId}/finance - spend limit, amount spent,
|
|
1527
|
+
# balance and payment method. Requires ads:read.
|
|
1528
|
+
def finance(account_id)
|
|
1529
|
+
@client.request("GET", account_path(account_id, "finance"))
|
|
1530
|
+
end
|
|
1531
|
+
|
|
1532
|
+
# PATCH /ads/accounts/{accountId}/settings - spend cap, DSA payer and
|
|
1533
|
+
# beneficiary, name.
|
|
1534
|
+
#
|
|
1535
|
+
# A higher spend_cap ALLOWS MORE REAL AD SPEND: pass the new cap as
|
|
1536
|
+
# confirm_budget_amount after the person agreed; spend_cap: nil removes
|
|
1537
|
+
# the cap and needs confirm_budget_amount: "remove". A spend cap change:
|
|
1538
|
+
# needs a key with the opt-in ads:spend scope ("Start ads"); without it,
|
|
1539
|
+
# and on Google (api_draft_only) always, the call answers 403
|
|
1540
|
+
# start_in_app with the page where a person does it in the app. The name
|
|
1541
|
+
# and the DSA names stay open. Not retried after a 5xx, a timeout or a
|
|
1542
|
+
# lost connection. Requires ads:write.
|
|
1543
|
+
def update_settings(account_id, spend_cap: OmniSocials::NOT_GIVEN, dsa_beneficiary: nil, dsa_payor: nil,
|
|
1544
|
+
name: nil, confirm_budget_amount: nil)
|
|
1545
|
+
body = Internal.drop_nil(
|
|
1546
|
+
{
|
|
1547
|
+
"dsa_beneficiary" => dsa_beneficiary, "dsa_payor" => dsa_payor, "name" => name,
|
|
1548
|
+
"confirm_budget_amount" => confirm_budget_amount
|
|
1549
|
+
}
|
|
1550
|
+
)
|
|
1551
|
+
body["spend_cap"] = spend_cap unless spend_cap.is_a?(NotGiven)
|
|
1552
|
+
@client.request(
|
|
1553
|
+
"PATCH", account_path(account_id, "settings"), json: body, retry_on: :rate_limit
|
|
1554
|
+
)
|
|
1555
|
+
end
|
|
1556
|
+
|
|
1557
|
+
# GET /ads/accounts/{accountId}/users - people with access. Requires
|
|
1558
|
+
# ads:read.
|
|
1559
|
+
def list_users(account_id)
|
|
1560
|
+
@client.request("GET", account_path(account_id, "users"))
|
|
1561
|
+
end
|
|
1562
|
+
|
|
1563
|
+
# POST /ads/accounts/{accountId}/users - give a person access
|
|
1564
|
+
# (LinkedIn). Requires ads:write.
|
|
1565
|
+
def add_user(account_id, role:, email: nil, member_id: nil)
|
|
1566
|
+
@client.request(
|
|
1567
|
+
"POST", account_path(account_id, "users"),
|
|
1568
|
+
json: Internal.drop_nil({ "email" => email, "member_id" => member_id, "role" => role })
|
|
1569
|
+
)
|
|
1570
|
+
end
|
|
1571
|
+
|
|
1572
|
+
# DELETE /ads/accounts/{accountId}/users/{userId} - remove a person's
|
|
1573
|
+
# access. Requires ads:write.
|
|
1574
|
+
def remove_user(account_id, user_id)
|
|
1575
|
+
@client.request("DELETE", account_path(account_id, "users/#{seg(user_id)}"))
|
|
1576
|
+
end
|
|
1577
|
+
|
|
1578
|
+
# GET /ads/accounts/{accountId}/activity - the change log of the ad
|
|
1579
|
+
# account. Requires ads:read.
|
|
1580
|
+
def activity(account_id, since: nil, until_time: nil, cursor: nil)
|
|
1581
|
+
@client.request(
|
|
1582
|
+
"GET", account_path(account_id, "activity"),
|
|
1583
|
+
query: { "since" => since, "until" => until_time, "cursor" => cursor }
|
|
1584
|
+
)
|
|
1585
|
+
end
|
|
1586
|
+
|
|
1587
|
+
# GET /ads/accounts/{accountId}/businesses - Meta business portfolios
|
|
1588
|
+
# and TikTok Business Centers. Requires ads:read.
|
|
1589
|
+
def businesses(account_id)
|
|
1590
|
+
@client.request("GET", account_path(account_id, "businesses"))
|
|
1591
|
+
end
|
|
1592
|
+
|
|
1593
|
+
# GET /ads/accounts/{accountId}/dsa - the EU DSA payer and beneficiary
|
|
1594
|
+
# (Meta). Requires ads:read.
|
|
1595
|
+
def dsa(account_id)
|
|
1596
|
+
@client.request("GET", account_path(account_id, "dsa"))
|
|
1597
|
+
end
|
|
1598
|
+
|
|
1599
|
+
# GET /ads/accounts/{accountId}/hierarchy - the manager account
|
|
1600
|
+
# hierarchy (Google). Requires ads:read.
|
|
1601
|
+
def hierarchy(account_id)
|
|
1602
|
+
@client.request("GET", account_path(account_id, "hierarchy"))
|
|
1603
|
+
end
|
|
1604
|
+
end
|
|
1605
|
+
|
|
1606
|
+
# Meta reach and frequency buying. A prediction spends nothing; a
|
|
1607
|
+
# reservation does.
|
|
1608
|
+
class AdReachFrequency
|
|
1609
|
+
include AdPaths
|
|
1610
|
+
|
|
1611
|
+
def initialize(client)
|
|
1612
|
+
@client = client
|
|
1613
|
+
end
|
|
1614
|
+
|
|
1615
|
+
# POST /ads/reach-frequency - a prediction (objective "awareness",
|
|
1616
|
+
# "engagement" or "video_views"; exactly one country in targeting;
|
|
1617
|
+
# budget in major units or reach). It spends nothing; Meta needs the
|
|
1618
|
+
# reach and frequency capability on the ad account. Requires
|
|
1619
|
+
# ads:write.
|
|
1620
|
+
def create(ad_account_id:, objective:, targeting:, start_at:, end_at:, budget: nil, reach: nil,
|
|
1621
|
+
frequency_cap: nil, frequency_interval_days: nil)
|
|
1622
|
+
@client.request(
|
|
1623
|
+
"POST", "/ads/reach-frequency",
|
|
1624
|
+
json: Internal.drop_nil(
|
|
1625
|
+
{
|
|
1626
|
+
"ad_account_id" => ad_account_id, "objective" => objective, "targeting" => targeting,
|
|
1627
|
+
"start_at" => start_at, "end_at" => end_at, "budget" => budget, "reach" => reach,
|
|
1628
|
+
"frequency_cap" => frequency_cap, "frequency_interval_days" => frequency_interval_days
|
|
1629
|
+
}
|
|
1630
|
+
)
|
|
1631
|
+
)
|
|
1632
|
+
end
|
|
1633
|
+
|
|
1634
|
+
# GET /ads/reach-frequency/{predictionId}. Requires ads:read.
|
|
1635
|
+
def get(prediction_id, ad_account_id:)
|
|
1636
|
+
@client.request(
|
|
1637
|
+
"GET", "/ads/reach-frequency/#{seg(prediction_id)}",
|
|
1638
|
+
query: { "ad_account_id" => ad_account_id }
|
|
1639
|
+
)
|
|
1640
|
+
end
|
|
1641
|
+
|
|
1642
|
+
# DELETE /ads/reach-frequency/{predictionId} - cancel a prediction or a
|
|
1643
|
+
# reservation. Requires ads:write.
|
|
1644
|
+
def cancel(prediction_id, ad_account_id:)
|
|
1645
|
+
@client.request(
|
|
1646
|
+
"DELETE", "/ads/reach-frequency/#{seg(prediction_id)}",
|
|
1647
|
+
query: { "ad_account_id" => ad_account_id }
|
|
1648
|
+
)
|
|
1649
|
+
end
|
|
1650
|
+
|
|
1651
|
+
# POST /ads/reach-frequency/{predictionId}/reserve - COMMITS REAL AD
|
|
1652
|
+
# SPEND: pass the prediction's budget as confirm_budget_amount after the
|
|
1653
|
+
# person agreed. Needs a key with the opt-in ads:spend scope ("Start
|
|
1654
|
+
# ads"); without it, and on Google (api_draft_only) always, the call
|
|
1655
|
+
# answers 403 start_in_app with the page where a person does it in the
|
|
1656
|
+
# app. Not retried after a 5xx, a timeout or a lost connection: read the
|
|
1657
|
+
# prediction with get. Requires ads:write.
|
|
1658
|
+
def reserve(prediction_id, ad_account_id:, confirm_budget_amount:)
|
|
1659
|
+
@client.request(
|
|
1660
|
+
"POST", "/ads/reach-frequency/#{seg(prediction_id)}/reserve",
|
|
1661
|
+
json: { "ad_account_id" => ad_account_id, "confirm_budget_amount" => confirm_budget_amount },
|
|
1662
|
+
retry_on: :rate_limit
|
|
1663
|
+
)
|
|
1664
|
+
end
|
|
1665
|
+
end
|
|
1666
|
+
|
|
1667
|
+
# A/B tests and lift studies (Meta).
|
|
1668
|
+
class AdStudies
|
|
1669
|
+
def initialize(client)
|
|
1670
|
+
@client = client
|
|
1671
|
+
end
|
|
1672
|
+
|
|
1673
|
+
# GET /ads/studies. Requires ads:read.
|
|
1674
|
+
def list(ad_account_id:)
|
|
1675
|
+
@client.request("GET", "/ads/studies", query: { "ad_account_id" => ad_account_id })
|
|
1676
|
+
end
|
|
1677
|
+
|
|
1678
|
+
# POST /ads/studies - an A/B test between existing campaigns or ad sets;
|
|
1679
|
+
# Meta's fields pass through as keyword arguments. Needs a key with the
|
|
1680
|
+
# opt-in ads:spend scope ("Start ads"); without it, and on Google
|
|
1681
|
+
# (api_draft_only) always, the call answers 403 start_in_app with the
|
|
1682
|
+
# page where a person does it in the app. Requires ads:write.
|
|
1683
|
+
def create(ad_account_id:, **fields)
|
|
1684
|
+
body = fields.each_with_object({}) { |(key, value), out| out[key.to_s] = value }
|
|
1685
|
+
@client.request("POST", "/ads/studies", json: body.merge("ad_account_id" => ad_account_id))
|
|
1686
|
+
end
|
|
1687
|
+
end
|
|
1688
|
+
|
|
1689
|
+
# Planned budget increases of a campaign for high-demand periods (Meta).
|
|
1690
|
+
class AdBudgetSchedules
|
|
1691
|
+
include AdPaths
|
|
1692
|
+
|
|
1693
|
+
def initialize(client)
|
|
1694
|
+
@client = client
|
|
1695
|
+
end
|
|
1696
|
+
|
|
1697
|
+
# GET /ads/campaigns/{id}/budget-schedules. Requires ads:read.
|
|
1698
|
+
def list(campaign_id)
|
|
1699
|
+
@client.request("GET", "/ads/campaigns/#{seg(campaign_id)}/budget-schedules")
|
|
1700
|
+
end
|
|
1701
|
+
|
|
1702
|
+
# POST /ads/campaigns/{id}/budget-schedules - plan a budget increase
|
|
1703
|
+
# (budget_increase: { "type" => "absolute" | "multiplier", "value" =>
|
|
1704
|
+
# ... }).
|
|
1705
|
+
#
|
|
1706
|
+
# NEW REAL AD SPEND in that period: pass the increase per day (absolute)
|
|
1707
|
+
# or the campaign budget times the multiplier as confirm_budget_amount
|
|
1708
|
+
# after the person agreed. Needs a key with the opt-in ads:spend scope
|
|
1709
|
+
# ("Start ads"); without it, and on Google (api_draft_only) always, the
|
|
1710
|
+
# call answers 403 start_in_app with the page where a person does it in
|
|
1711
|
+
# the app. Not retried after a 5xx, a timeout or a lost connection: read
|
|
1712
|
+
# the schedules with list. Requires ads:write.
|
|
1713
|
+
def create(campaign_id, start_at:, end_at:, budget_increase:, confirm_budget_amount:)
|
|
1714
|
+
@client.request(
|
|
1715
|
+
"POST", "/ads/campaigns/#{seg(campaign_id)}/budget-schedules",
|
|
1716
|
+
json: {
|
|
1717
|
+
"start_at" => start_at, "end_at" => end_at, "budget_increase" => budget_increase,
|
|
1718
|
+
"confirm_budget_amount" => confirm_budget_amount
|
|
1719
|
+
},
|
|
1720
|
+
retry_on: :rate_limit
|
|
1721
|
+
)
|
|
1722
|
+
end
|
|
1723
|
+
|
|
1724
|
+
# DELETE /ads/campaigns/{id}/budget-schedules/{scheduleId}. Requires
|
|
1725
|
+
# ads:write.
|
|
1726
|
+
def delete(campaign_id, schedule_id)
|
|
1727
|
+
@client.request(
|
|
1728
|
+
"DELETE", "/ads/campaigns/#{seg(campaign_id)}/budget-schedules/#{seg(schedule_id)}"
|
|
1729
|
+
)
|
|
1730
|
+
end
|
|
1731
|
+
end
|
|
1732
|
+
|
|
1733
|
+
# Google reports (read-only; every API caller stops at the draft on
|
|
1734
|
+
# Google).
|
|
1735
|
+
class AdGoogle
|
|
1736
|
+
include AdPaths
|
|
1737
|
+
|
|
1738
|
+
def initialize(client)
|
|
1739
|
+
@client = client
|
|
1740
|
+
end
|
|
1741
|
+
|
|
1742
|
+
# GET /ads/google/search-terms. Requires ads:read.
|
|
1743
|
+
def search_terms(ad_account_id:, campaign_id: nil, external_campaign_id: nil, from: nil,
|
|
1744
|
+
to: nil, limit: nil)
|
|
1745
|
+
@client.request(
|
|
1746
|
+
"GET", "/ads/google/search-terms",
|
|
1747
|
+
query: {
|
|
1748
|
+
"ad_account_id" => ad_account_id, "campaign_id" => campaign_id,
|
|
1749
|
+
"external_campaign_id" => external_campaign_id, "from" => from, "to" => to,
|
|
1750
|
+
"limit" => limit
|
|
1751
|
+
}
|
|
1752
|
+
)
|
|
1753
|
+
end
|
|
1754
|
+
|
|
1755
|
+
# GET /ads/google/recommendations. Requires ads:read.
|
|
1756
|
+
def recommendations(ad_account_id:, types: nil)
|
|
1757
|
+
@client.request(
|
|
1758
|
+
"GET", "/ads/google/recommendations",
|
|
1759
|
+
query: { "ad_account_id" => ad_account_id, "types" => list_param(types) }
|
|
1760
|
+
)
|
|
1761
|
+
end
|
|
1762
|
+
|
|
1763
|
+
# GET /ads/google/keywords - search keywords and negative keywords.
|
|
1764
|
+
# Requires ads:read.
|
|
1765
|
+
def keywords(ad_account_id:, external_campaign_id: nil, external_ad_set_id: nil)
|
|
1766
|
+
@client.request(
|
|
1767
|
+
"GET", "/ads/google/keywords",
|
|
1768
|
+
query: {
|
|
1769
|
+
"ad_account_id" => ad_account_id, "external_campaign_id" => external_campaign_id,
|
|
1770
|
+
"external_ad_set_id" => external_ad_set_id
|
|
1771
|
+
}
|
|
1772
|
+
)
|
|
1773
|
+
end
|
|
1774
|
+
|
|
1775
|
+
# GET /ads/google/assets - sitelinks, callouts and structured snippets.
|
|
1776
|
+
# Requires ads:read.
|
|
1777
|
+
def assets(ad_account_id:, type: nil)
|
|
1778
|
+
@client.request(
|
|
1779
|
+
"GET", "/ads/google/assets", query: { "ad_account_id" => ad_account_id, "type" => type }
|
|
1780
|
+
)
|
|
1781
|
+
end
|
|
1782
|
+
|
|
1783
|
+
# GET /ads/google/shared-budgets. Requires ads:read.
|
|
1784
|
+
def shared_budgets(ad_account_id:)
|
|
1785
|
+
@client.request("GET", "/ads/google/shared-budgets", query: { "ad_account_id" => ad_account_id })
|
|
1786
|
+
end
|
|
1787
|
+
|
|
1788
|
+
# GET /ads/google/bid-strategies - portfolio bid strategies. Requires
|
|
1789
|
+
# ads:read.
|
|
1790
|
+
def bid_strategies(ad_account_id:)
|
|
1791
|
+
@client.request("GET", "/ads/google/bid-strategies", query: { "ad_account_id" => ad_account_id })
|
|
1792
|
+
end
|
|
1793
|
+
|
|
1794
|
+
# GET /ads/google/ad-schedule - the days and hours of a Google
|
|
1795
|
+
# campaign. Requires ads:read.
|
|
1796
|
+
def ad_schedule(ad_account_id:, external_campaign_id:)
|
|
1797
|
+
@client.request(
|
|
1798
|
+
"GET", "/ads/google/ad-schedule",
|
|
1799
|
+
query: { "ad_account_id" => ad_account_id, "external_campaign_id" => external_campaign_id }
|
|
1800
|
+
)
|
|
1801
|
+
end
|
|
1802
|
+
|
|
1803
|
+
# GET /ads/google/labels. Requires ads:read.
|
|
1804
|
+
def labels(ad_account_id:)
|
|
1805
|
+
@client.request("GET", "/ads/google/labels", query: { "ad_account_id" => ad_account_id })
|
|
1806
|
+
end
|
|
1807
|
+
|
|
1808
|
+
# GET /ads/google/local-services-leads. Requires ads:read.
|
|
1809
|
+
def local_services_leads(ad_account_id:, since: nil)
|
|
1810
|
+
@client.request(
|
|
1811
|
+
"GET", "/ads/google/local-services-leads",
|
|
1812
|
+
query: { "ad_account_id" => ad_account_id, "since" => since }
|
|
1813
|
+
)
|
|
1814
|
+
end
|
|
1815
|
+
end
|
|
1816
|
+
end
|
|
1817
|
+
end
|