Represents a shopping campaign.
Methods:
Member | Type | Description |
adGroups |
AdsApp.ShoppingAdGroupSelector |
Returns the selector of all shopping ad groups in the shopping campaign. |
addAdSchedule |
AdsApp.AdScheduleOperation |
Creates an ad schedule criterion from an ad schedule object. |
addAdSchedule |
AdsApp.AdScheduleOperation |
Creates an ad schedule criterion. |
addLocation |
AdsApp.TargetedLocationOperation |
Creates a location target in this campaign from a location ID. |
addLocation |
AdsApp.TargetedLocationOperation |
Creates a location target in this campaign from a location. |
addLocation |
AdsApp.TargetedLocationOperation |
Creates a location target in this campaign from a location JSON. |
addLocation |
AdsApp.TargetedLocationOperation |
Creates a location target in this campaign from a location ID and bid
modifier. |
addNegativeKeywordList |
void |
Adds a negative keyword list to this campaign. |
addProximity |
AdsApp.TargetedProximityOperation |
Creates a proximity target in this campaign from a proximity object. |
addProximity |
AdsApp.TargetedProximityOperation |
Creates a proximity target in this campaign. |
ads |
AdsApp.ProductAdSelector |
Returns the selector of all product ads in the shopping campaign. |
applyLabel |
void |
Applies a label to the shopping campaign. |
bidding |
AdsApp.ShoppingCampaignBidding |
Provides access to this shopping campaign's bidding fields. |
createNegativeKeyword |
void |
Creates a new campaign-level negative keyword with the specified text. |
enable |
void |
Enables the shopping campaign. |
excludeLocation |
AdsApp.ExcludedLocationOperation |
Creates a location exclusion in this campaign. |
excludeLocation |
AdsApp.ExcludedLocationOperation |
Creates a location exclusion in this campaign. |
excludeLocation |
AdsApp.ExcludedLocationOperation |
Creates a location exclusion in this campaign. |
getAdRotationType |
String |
Returns the ad rotation type of the shopping campaign. |
getBiddingStrategyType |
String |
Returns the bidding strategy type of the shopping campaign. |
getBudget |
AdsApp.Budget |
Returns the budget of the shopping campaign. |
getEndDate |
AdsApp.GoogleAdsDate |
Returns the shopping campaign's end date, or null if there is
no end date. |
getEntityType |
String |
Returns the type of this entity as a String , in this case,
"ShoppingCampaign" . |
getId |
String |
Returns the ID of the shopping campaign. |
getName |
String |
Returns the name of the shopping campaign. |
getResourceName |
String |
Returns the resource name of the shopping campaign. |
getSalesCountry |
String |
Returns the country code for the country the shopping campaign is specified
to sell in, or null for countryless campaigns. |
getStartDate |
AdsApp.GoogleAdsDate |
Returns the shopping campaign's start date. |
getStatsFor |
AdsApp.Stats |
Returns stats for the specified date range. |
getStatsFor |
AdsApp.Stats |
Returns stats for the specified custom date range. |
isDeleted |
boolean |
Returns true if the shopping campaign is deleted. |
isEnabled |
boolean |
Returns true if the shopping campaign is enabled. |
isPaused |
boolean |
Returns true if the shopping campaign is paused. |
labels |
AdsApp.LabelSelector |
Creates a selector of all labels applied to the shopping campaign. |
negativeKeywordLists |
AdsApp.NegativeKeywordListSelector |
Returns a selector of negative keyword lists associated with this campaign. |
negativeKeywords |
AdsApp.NegativeKeywordSelector |
Returns a selector of the campaign-level negative keywords belonging to
this campaign. |
newAdGroupBuilder |
AdsApp.ShoppingAdGroupBuilder |
Returns a new shopping ad group builder for this shopping campaign. |
pause |
void |
Pauses the shopping campaign. |
productGroups |
AdsApp.ProductGroupSelector |
Returns the selector of all product groups in the campaign. |
recommendations |
AdsApp.RecommendationSelector |
Returns the selector of all recommendations for this campaign. |
removeLabel |
void |
Removes a label from the shopping campaign. |
removeNegativeKeywordList |
void |
Removes a negative keyword list from this campaign. |
setAdRotationType |
void |
Sets the ad rotation type of the shopping campaign. |
setEndDate |
void |
Sets the shopping campaign's end date from either an object containing
year, month, and day fields, or an 8-digit string in YYYYMMDD
format. |
setName |
void |
Sets the name of the shopping campaign. |
setStartDate |
void |
Sets the shopping campaign's start date from either an object containing
year, month, and day fields, or an 8-digit string in YYYYMMDD
format. |
targeting |
AdsApp.ShoppingCampaignTargeting |
Provides access to campaign-level targeting criteria: device targeting, ad
scheduling, location targeting, and audiences. |
urls |
AdsApp.CampaignUrls |
Provides access to this shopping campaign's URL fields. |
adGroups()
Returns the selector of all shopping ad groups in the shopping campaign.
Return values:
addAdSchedule(adSchedule)
Creates an ad schedule criterion from an ad schedule object. Once created,
the shopping campaign will start showing ads during the specified time.
When called with one argument, addAdSchedule
supports two
kinds of input:
- Existing AdSchedule objects,
perhaps from another campaign:
var campaigns = AdsApp.campaigns().get();
var campaign1 = campaigns.next();
var campaign2 = campaigns.next();
var schedule = campaign1.targeting().adSchedules().get().next();
campaign2.addAdSchedule(schedule);
- Plain JavaScript objects describing an ad schedule. For instance,
this will create an ad schedule covering Saturday mornings:
var campaign = AdsApp.campaigns().get().next();
campaign.addAdSchedule({
dayOfWeek: "SATURDAY",
startHour: 7,
startMinute: 0,
endHour: 11,
endMinute: 0,
bidModifier: 1.1
});
This will look at the following properties of the given object:
dayOfWeek
: Required. Must be one
of "MONDAY"
, "TUESDAY"
,
"WEDNESDAY"
, "THURSDAY"
,
"FRIDAY"
, "SATURDAY"
, or
"SUNDAY"
.
startHour
and startMinute
:
Required. The starting time of this segment of
the ad schedule. startHour
must be an integer
between 0
and 23
, and
startMinute
must be either 0
,
15
, 30
, or 45
. For
instance, a startHour
of 18
and a
startMinute
of 30
would result in an
ad schedule starting at 6:30PM. Acceptable starting times range
from 00:00
to 23:45
.
endHour
and endMinute
:
Required. The ending time of this segment of
the ad schedule. endHour
must be an integer
between 0
and 24
, and
endMinute
must be either 0
,
15
, 30
, or 45
. For
instance, a endHour
of 18
and a
endMinute
of 30
would result in an ad
schedule ending at 6:30PM. Acceptable ending times range from
00:15
to 24:00
.
bidModifier
: Optional. The bid
modifier for this segment of the ad schedule.
One thing to keep in mind is that, by default, campaigns have no ad
schedule criteria and hence serve ads at all times. Adding the first ad
schedule to a campaign will cause ads to be shown during that time only.
Arguments:
Name | Type | Description |
adSchedule |
Object |
The schedule to create. |
Return values:
addAdSchedule(dayOfWeek, startHour, startMinute, endHour, endMinute, bidModifier)
Creates an ad schedule criterion. Once created, the shopping campaign will
start showing ads during the specified time.
For instance, this will create an ad schedule covering Saturday
mornings:
var campaign = AdsApp.campaigns().get().next();
campaign.addAdSchedule("SATURDAY", 7, 0, 11, 0);
This will create the same schedule, but with a bid modifier of
1.1
:
var campaign = AdsApp.campaigns().get().next();
campaign.addAdSchedule("SATURDAY", 7, 0, 11, 0, 1.1);
One thing to keep in mind is that, by default, campaigns have no ad
schedule criteria and hence serve ads at all times. Adding the first ad
schedule to a campaign will cause ads to be shown during that time only.
Arguments:
Name | Type | Description |
dayOfWeek |
String |
The day of week. Must be one of "MONDAY" ,
"TUESDAY" , "WEDNESDAY" ,
"THURSDAY" , "FRIDAY" ,
"SATURDAY" , or "SUNDAY" . |
startHour |
int |
The start hour. Must be an integer between 0
and 23 . Acceptable starting times range from
00:00 to 23:45 . |
startMinute |
int |
The start minute. Must be either 0 ,
15 , 30 , or 45 . Acceptable
starting times range from 00:00 to 23:45 . |
endHour |
int |
The end hour. Must be an integer between 0 and
24 . Acceptable ending times range from 00:15
to 24:00 . |
endMinute |
int |
The end minute. Must be either 0 ,
15 , 30 , or 45 . Acceptable ending
times range from 00:15 to 24:00 . |
bidModifier |
double |
Optional. The bid modifier to use for
the newly created ad schedule. |
Return values:
addLocation(locationId)
Creates a location target in this campaign from a location ID. Once
created, the campaign will start showing ads to the location with the given
location ID.
You must specify a location ID. For a list of locations and their
corresponding IDs, see the API documentation on
geotargeting.
Arguments:
Name | Type | Description |
locationId |
int |
The location ID to target. |
Return values:
addLocation(location)
Creates a location target in this campaign from a location. Once created,
the campaign will start showing ads to the location with the given location
ID.
You must specify an existing TargetedLocation object, perhaps
from another campaign:
var campaigns = AdsApp.campaigns().get();
var campaign1 = campaigns.next();
var campaign2 = campaigns.next();
var location = campaign1.targeting().targetedLocations().get().next();
campaign2.addLocation(location);
Arguments:
Return values:
addLocation(location)
Creates a location target in this campaign from a location JSON. Once
created, the campaign will start showing ads to the location with the given
location ID.
You must specify a plain JavaScript object describing a location. For
instance, this would create a location target for Tennessee:
var campaign = AdsApp.campaigns().get().next();
campaign.addLocation({
id: 21175,
bidModifier: 1.2,
});
This will look at the following properties of the given object:
id
: Required. The ID of the location to
target. For a list of locations and their corresponding IDs, see the
API documentation
on geotargeting.
bidModifier
: Optional. The bid modifier
for this location.
Arguments:
Name | Type | Description |
location |
Object |
JSON representation of the location to target. |
Return values:
addLocation(locationId, bidModifier)
Creates a location target in this campaign from a location ID and bid
modifier. Once created, the campaign will start showing ads to the location
with the given location ID.
For instance, this will create a location target for Tennessee with a
bid modifier of 1.15
:
var campaign = AdsApp.campaigns().get().next();
campaign.addLocation(21175, 1.15);
Arguments:
Name | Type | Description |
locationId |
int |
The ID of the location to target. For a list of locations
and their corresponding IDs, see the API documentation on
geotargeting. |
bidModifier |
double |
The desired bid modifier for the new location target. |
Return values:
addNegativeKeywordList(negativeKeywordList)
Adds a negative keyword list to this campaign.
Returns nothing.
Arguments:
addProximity(proximity)
Creates a proximity target in this campaign from a proximity object. Once
created, the shopping campaign will start showing ads to geographical
points within the specified radius of the specified central point.
When called with one argument, addProximity
supports two
kinds of input:
- Existing
TargetedProximity
objects, perhaps from another campaign:
var campaigns = AdsApp.campaigns().get();
var campaign1 = campaigns.next();
var campaign2 = campaigns.next();
var proximity = campaign1.targeting().targetedProximities().get().next();
campaign2.addProximity(proximity);
- Plain JavaScript objects describing a proximity. For instance, this
would create a proximity targeting 20km around Google headquarters:
var campaign = AdsApp.campaigns().get().next();
campaign.addProximity({
latitude: 37.423021,
longitude: -122.083739,
radius: 20,
radiusUnits: "KILOMETERS",
bidModifier: 0.75,
address: {
streetAddress: "1600 Amphitheatre Parkway",
cityName: "Mountain View",
provinceName: "California",
provinceCode: "CA",
postalCode: "94043",
countryCode: "US"
}
});
This will look at the following properties of the given object:
latitude
and longitude
:
Required. The central geographic point of the
proximity to target.
radius
and radiusUnits
:
Required. The radius around the central point
to target. radiusUnits
must be either
"MILES"
or "KILOMETERS"
.
bidModifier
: Optional. The bid
modifier for this proximity.
address
: Optional. The address
associated with the central geographical point.
If present, this is expected to be an object, which contains
any of streetAddress
, streetAddress2
,
cityName
, provinceName
,
provinceCode
, postalCode
, and
countryCode
as properties with string values. This
corresponds to the Address
objects returned by existing proximity targets.
There is no validation to check that the address actually
belongs to the given latitude and longitude. It has no
functionality except to change what shows up in the Campaign
Management interface.
Arguments:
Name | Type | Description |
proximity |
Object |
The proximity to target. |
Return values:
addProximity(latitude, longitude, radius, radiusUnits, optArgs)
Creates a proximity target in this campaign. Once created, the shopping
campaign will start showing ads to geographical points within the specified
radius of the specified central point.
For instance, this will create a proximity targeting 20km around Google
headquarters:
var campaign = AdsApp.campaigns().get().next();
campaign.addProximity(37.423021, -122.083739, 20, "KILOMETERS");
Similarly, to create the same proximity target with a bid modifier and
address:
campaign.addProximity(37.423021, -122.083739, 20, "KILOMETERS", {
bidModifier: 1.15,
address: {
streetAddress: "1600 Amphitheatre Parkway",
cityName: "Mountain View",
provinceName: "California",
provinceCode: "CA",
postalCode: "94043",
countryCode: "US"
}
});
Arguments:
Name | Type | Description |
latitude |
double |
The latitude of the central point. |
longitude |
double |
The longitude of the central point. |
radius |
double |
The radius of the proximity target. |
radiusUnits |
String |
The units of the radius, either "MILES" or
"KILOMETERS" . |
optArgs |
Object |
Optional. Either a number, which will be
interpreted as the desired bid modifier for the proximity, or an object
containing extra additional arguments.
For TargetedProximities , there are two supported
optional arguments:
bidModifier : The bid modifier for this proximity.
address : The address associated with the central
geographical point.
If present, this is expected to be an object, which contains
any of streetAddress , streetAddress2 ,
cityName , provinceName ,
provinceCode , postalCode , and
countryCode as properties with string values. This
corresponds to the Address
objects returned by existing proximity targets.
There is no validation to check that the address actually
belongs to the given latitude and longitude. It has no
functionality except to change what shows up in the Campaign
Management interface.
|
Return values:
ads()
Returns the selector of all product ads in the shopping campaign.
Return values:
applyLabel(name)
Applies a label to the shopping campaign.
name
of the label
is case-sensitive. Operation will fail if the label with the specified name
does not already exist in the account.
Note that the shopping campaign cannot not have more than 50 labels.
Returns nothing.
Arguments:
Name | Type | Description |
name |
String |
Name of the label to apply. |
bidding()
Provides access to this shopping campaign's bidding fields.
Return values:
createNegativeKeyword(keywordText)
Creates a new campaign-level negative keyword with the specified text.
Match type for the new negative keyword is specified as follows:
createNegativeKeyword("shoes")
- broad match.
createNegativeKeyword("\"shoes\"")
- phrase match.
createNegativeKeyword("[leather shoes]")
- exact match.
Returns nothing.
Arguments:
Name | Type | Description |
keywordText |
String |
The text of the new negative keyword. |
enable()
Enables the shopping campaign.
Returns nothing.
excludeLocation(locationId)
Creates a location exclusion in this campaign. Once created, the campaign
will not show ads to the location with the given location ID.
You must specify a location ID. For a list of locations and their
corresponding IDs, see the API documentation on
geotargeting:
var campaign = AdsApp.campaigns().get().next();
campaign.excludeLocation(21175);
Arguments:
Name | Type | Description |
locationId |
int |
The ID of the location to exclude. |
Return values:
excludeLocation(location)
Creates a location exclusion in this campaign. Once created, the campaign
will not show ads to the location with the given location ID.
You must specify a plain JavaScript object describing a location. For
instance, this would create a location exclusion for Tennessee:
var campaign = AdsApp.campaigns().get().next();
campaign.excludeLocation({
id: 21175
});
The only field of the object which will be looked at is
id
,
which represents the location ID.
Arguments:
Name | Type | Description |
location |
Object |
JSON representation of the location to exclude. |
Return values:
excludeLocation(location)
Creates a location exclusion in this campaign. Once created, the campaign
will not show ads to the location with the given location ID.
You must specify an existing ExcludedLocation object, perhaps
from another campaign:
var campaigns = AdsApp.campaigns().get();
var campaign1 = campaigns.next();
var campaign2 = campaigns.next();
var location = campaign1.targeting().excludedLocations().get().next();
campaign2.excludeLocation(location);
Arguments:
Return values:
getAdRotationType()
Returns the ad rotation type of the shopping campaign. Possible return
values:
OPTIMIZE, CONVERSION_OPTIMIZE, ROTATE, ROTATE_FOREVER
Return values:
Type | Description |
String |
The ad rotation type of the shopping campaign. |
getBiddingStrategyType()
Returns the bidding strategy type of the shopping campaign. Possible return
values:
MANUAL_CPC, MANUAL_CPM, TARGET_CPA, TARGET_SPEND, TARGET_ROAS,
MAXIMIZE_CONVERSIONS, MAXIMIZE_CONVERSION_VALUE,
TARGET_IMPRESSION_SHARE
Return values:
Type | Description |
String |
The bidding strategy type of the shopping campaign. |
getBudget()
Returns the budget of the shopping campaign. In order to change the
shopping campaign's budget, use
Budget.setAmount(double).
Return values:
getEndDate()
Returns the shopping campaign's end date, or
null
if there is
no end date.
For instance, if a campaign ended on May 3, 2013, this would return the
following object: {year: 2013, month: 5, day: 3}
.
Return values:
Type | Description |
AdsApp.GoogleAdsDate |
The shopping campaign's end date, or null if there's
no end date. |
getEntityType()
Returns the type of this entity as a
String
, in this case,
"ShoppingCampaign"
.
Return values:
Type | Description |
String |
Type of this entity: "ShoppingCampaign" . |
getId()
Returns the ID of the shopping campaign.
Return values:
Type | Description |
String |
The ID of the shopping campaign. |
getName()
Returns the name of the shopping campaign.
Return values:
Type | Description |
String |
The name of the shopping campaign. |
getResourceName()
Returns the resource name of the shopping campaign.
Return values:
Type | Description |
String |
The resource name of the shopping campaign. |
getSalesCountry()
Returns the country code for the country the shopping campaign is specified
to sell in, or
null
for countryless campaigns.
Return values:
Type | Description |
String |
The country code for the country the shopping campaign is specified
to sell in, or null for countryless campaigns. |
getStartDate()
Returns the shopping campaign's start date.
For instance, if a campaign started on May 3, 2013, this would return
the following object: {year: 2013, month: 5, day: 3}
.
Return values:
getStatsFor(dateRange)
Returns stats for the specified date range. Supported values:
TODAY, YESTERDAY, LAST_7_DAYS, THIS_WEEK_SUN_TODAY, LAST_WEEK,
LAST_14_DAYS, LAST_30_DAYS, LAST_BUSINESS_WEEK, LAST_WEEK_SUN_SAT,
THIS_MONTH, LAST_MONTH, ALL_TIME
.
Example:
var stats = shoppingCampaign.getStatsFor("THIS_MONTH");
Arguments:
Name | Type | Description |
dateRange |
String |
Date range for which the stats are requested. |
Return values:
Type | Description |
AdsApp.Stats |
The stats for the specified date range. |
getStatsFor(dateFrom, dateTo)
Returns stats for the specified custom date range. Both parameters can be
either an object containing year, month, and day fields, or an 8-digit
string in
YYYYMMDD
form. For instance,
March 24th,
2013
is represented as either
{year: 2013, month: 3, day:
24}
or
"20130324"
. The date range is inclusive on both
ends, so
forDateRange("20130324", "20130324")
defines a range
of a single day.
Arguments:
Name | Type | Description |
dateFrom |
Object |
Start date of the date range. Must be either a string in
YYYYMMDD form, or an object with year ,
month and day properties. |
dateTo |
Object |
End date of the date range. Must be either a string in
YYYYMMDD form, or an object with year ,
month and day properties. |
Return values:
Type | Description |
AdsApp.Stats |
The stats for the specified date range. |
isDeleted()
Returns
true
if the shopping campaign is deleted.
Return values:
Type | Description |
boolean |
true if the shopping campaign is deleted. |
isEnabled()
Returns
true
if the shopping campaign is enabled.
Return values:
Type | Description |
boolean |
true if the shopping campaign is enabled. |
isPaused()
Returns
true
if the shopping campaign is paused.
Return values:
Type | Description |
boolean |
true if the shopping campaign is paused. |
labels()
Creates a selector of all labels applied to the shopping campaign.
Return values:
negativeKeywordLists()
Returns a selector of negative keyword lists associated with this campaign.
Return values:
negativeKeywords()
Returns a selector of the campaign-level negative keywords belonging to
this campaign.
Note that this selector will not return any
negative keywords belonging to this campaign's child ad groups — it only
returns campaign-level negative keywords.
Return values:
newAdGroupBuilder()
Returns a new shopping ad group builder for this shopping campaign.
Return values:
pause()
Pauses the shopping campaign.
Returns nothing.
productGroups()
Returns the selector of all product groups in the campaign.
Return values:
recommendations()
Returns the selector of all recommendations for this campaign.
Return values:
removeLabel(name)
Removes a label from the shopping campaign.
name
of the
label is case-sensitive. Operation will fail if the label with the
specified name does not already exist in the account.
Returns nothing.
Arguments:
Name | Type | Description |
name |
String |
Name of the label. |
removeNegativeKeywordList(negativeKeywordList)
Removes a negative keyword list from this campaign.
Returns nothing.
Arguments:
setAdRotationType(adRotationType)
Sets the ad rotation type of the shopping campaign.
For instance, campaign.setAdRotationType("OPTIMIZE");
instructs Google Ads to optimize ad serving based on the shopping
campaign's CTR. For more information, see Choose an ad delivery
method help article.
Returns nothing.
Arguments:
Name | Type | Description |
adRotationType |
String |
The new ad rotation type of the shopping campaign.
Must be one of "OPTIMIZE" ,
"CONVERSION_OPTIMIZE" , "ROTATE" , or
"ROTATE_FOREVER" . |
setEndDate(date)
Sets the shopping campaign's end date from either an object containing
year, month, and day fields, or an 8-digit string in
YYYYMMDD
format.
For instance, campaign.setEndDate("20130503");
is
equivalent to campaign.setEndDate({year: 2013, month: 5, day:
3});
.
The change will fail and report an error if:
- the given date is invalid (e.g.,
{year: 2013, month: 5, day: 55}
),
- it's a date in the past, or
- it's a date after the latest allowed end date of December 30, 2037.
Returns nothing.
Arguments:
Name | Type | Description |
date |
Object |
The new campaign end date. |
setName(name)
Sets the name of the shopping campaign.
Returns nothing.
Arguments:
Name | Type | Description |
name |
String |
The new name for the shopping campaign. |
setStartDate(date)
Sets the shopping campaign's start date from either an object containing
year, month, and day fields, or an 8-digit string in
YYYYMMDD
format.
For instance, campaign.setStartDate("20130503");
is
equivalent to campaign.setStartDate({year: 2013, month: 5, day:
3});
.
The change will fail and report an error if:
- the shopping campaign has already started,
- the given date is invalid (e.g.,
{year: 2013, month: 5, day: 55}
),
- the given date is after the shopping campaign's end date,
- it's a date in the past, or
- it's a date after the latest allowed end date of December 30, 2037.
Returns nothing.
Arguments:
Name | Type | Description |
date |
Object |
The new campaign end date. |
targeting()
Provides access to campaign-level targeting criteria: device targeting, ad
scheduling, location targeting, and audiences.
Return values:
urls()
Provides access to this shopping campaign's URL fields. See
Final URL for
more information.
Return values: