Skip to content

Commit 85d5120

Browse files
jradcliffjradcliff
authored
Update Performance Max examples for listing groups and signals (#594)
* Add listing group filters in Performance Max retail campaign example * Add asset group signals in Performance Max campaign example
1 parent 8dcd8e6 commit 85d5120

3 files changed

Lines changed: 139 additions & 32 deletions

File tree

‎google-ads-examples/src/main/java/com/google/ads/googleads/examples/advancedoperations/AddPerformanceMaxCampaign.java‎

Lines changed: 52 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -20,6 +20,7 @@
2020
import com.google.ads.googleads.examples.utils.ArgumentNames;
2121
import com.google.ads.googleads.examples.utils.CodeSampleParams;
2222
import com.google.ads.googleads.lib.GoogleAdsClient;
23+
import com.google.ads.googleads.v10.common.AudienceInfo;
2324
import com.google.ads.googleads.v10.common.ImageAsset;
2425
import com.google.ads.googleads.v10.common.LanguageInfo;
2526
import com.google.ads.googleads.v10.common.LocationInfo;
@@ -35,11 +36,13 @@
3536
import com.google.ads.googleads.v10.resources.Asset;
3637
import com.google.ads.googleads.v10.resources.AssetGroup;
3738
import com.google.ads.googleads.v10.resources.AssetGroupAsset;
39+
import com.google.ads.googleads.v10.resources.AssetGroupSignal;
3840
import com.google.ads.googleads.v10.resources.Campaign;
3941
import com.google.ads.googleads.v10.resources.CampaignBudget;
4042
import com.google.ads.googleads.v10.resources.CampaignCriterion;
4143
import com.google.ads.googleads.v10.services.AssetGroupAssetOperation;
4244
import com.google.ads.googleads.v10.services.AssetGroupOperation;
45+
import com.google.ads.googleads.v10.services.AssetGroupSignalOperation;
4346
import com.google.ads.googleads.v10.services.AssetOperation;
4447
import com.google.ads.googleads.v10.services.CampaignBudgetOperation;
4548
import com.google.ads.googleads.v10.services.CampaignCriterionOperation;
@@ -97,6 +100,12 @@ private static class AddPerformanceMaxCampaignParams extends CodeSampleParams {
97100

98101
@Parameter(names = ArgumentNames.CUSTOMER_ID, required = true)
99102
private Long customerId;
103+
104+
@Parameter(
105+
names = ArgumentNames.AUDIENCE_ID,
106+
description =
107+
"An audience ID to use to improve the targeting of the Performance Max campaign")
108+
private Long audienceId;
100109
}
101110

102111
public static void main(String[] args) throws IOException {
@@ -106,6 +115,9 @@ public static void main(String[] args) throws IOException {
106115
// Either pass the required parameters for this example on the command line, or insert them
107116
// into the code here. See the parameter class definition above for descriptions.
108117
params.customerId = Long.parseLong("INSERT_CUSTOMER_ID_HERE");
118+
119+
// Optional: Specify an audience ID.
120+
// params.audienceId = Long.parseLong("INSERT_AUDIENCE_ID_HERE");
109121
}
110122

111123
GoogleAdsClient googleAdsClient = null;
@@ -121,7 +133,8 @@ public static void main(String[] args) throws IOException {
121133
}
122134

123135
try {
124-
new AddPerformanceMaxCampaign().runExample(googleAdsClient, params.customerId);
136+
new AddPerformanceMaxCampaign()
137+
.runExample(googleAdsClient, params.customerId, params.audienceId);
125138
} catch (GoogleAdsException gae) {
126139
// GoogleAdsException is the base class for most exceptions thrown by an API request.
127140
// Instances of this exception have a message and a GoogleAdsFailure that contains a
@@ -144,8 +157,10 @@ public static void main(String[] args) throws IOException {
144157
*
145158
* @param googleAdsClient the Google Ads API client.
146159
* @param customerId the client customer ID.
160+
* @param audienceId the optional audience ID.
147161
*/
148-
private void runExample(GoogleAdsClient googleAdsClient, long customerId) throws IOException {
162+
private void runExample(GoogleAdsClient googleAdsClient, long customerId, Long audienceId)
163+
throws IOException {
149164
// [START add_performance_max_campaign_1]
150165
// Performance Max campaigns require that repeated assets such as headlines
151166
// and descriptions be created before the campaign.
@@ -172,9 +187,17 @@ private void runExample(GoogleAdsClient googleAdsClient, long customerId) throws
172187
mutateOperations.add(createCampaignBudgetOperation(customerId));
173188
mutateOperations.add(createPerformanceMaxCampaignOperation(customerId));
174189
mutateOperations.addAll(createCampaignCriterionOperations(customerId));
190+
String assetGroupResourceName = ResourceNames.assetGroup(customerId, ASSET_GROUP_TEMPORARY_ID);
175191
mutateOperations.addAll(
176192
createAssetGroupOperations(
177-
customerId, headlineAssetResourceNames, descriptionAssetResourceNames));
193+
customerId,
194+
assetGroupResourceName,
195+
headlineAssetResourceNames,
196+
descriptionAssetResourceNames));
197+
if (audienceId != null) {
198+
mutateOperations.addAll(
199+
createAssetGroupSignalOperations(customerId, assetGroupResourceName, audienceId));
200+
}
178201

179202
try (GoogleAdsServiceClient googleAdsServiceClient =
180203
googleAdsClient.getLatestVersion().createGoogleAdsServiceClient()) {
@@ -349,13 +372,13 @@ private List<String> createMultipleTextAssets(
349372
/** Creates a list of MutateOperations that create a new AssetGroup. */
350373
private List<MutateOperation> createAssetGroupOperations(
351374
long customerId,
375+
String assetGroupResourceName,
352376
List<String> headlineAssetResourceNames,
353377
List<String> descriptionAssetResourceNames)
354378
throws IOException {
355379
List<MutateOperation> mutateOperations = new ArrayList<>();
356380
String campaignResourceName =
357381
ResourceNames.campaign(customerId, PERFORMANCE_MAX_CAMPAIGN_TEMPORARY_ID);
358-
String assetGroupResourceName = ResourceNames.assetGroup(customerId, ASSET_GROUP_TEMPORARY_ID);
359382
// Creates the AssetGroup.
360383
AssetGroup assetGroup =
361384
AssetGroup.newBuilder()
@@ -527,6 +550,31 @@ List<MutateOperation> createAndLinkImageAsset(
527550
}
528551
// [END add_performance_max_campaign_8]
529552

553+
// [START add_performance_max_campaign_9]
554+
/**
555+
* Creates a list of MutateOperations that create {@link
556+
* com.google.ads.googleads.v10.resources.AssetGroupSignal} objects.
557+
*/
558+
private List<MutateOperation> createAssetGroupSignalOperations(
559+
long customerId, String assetGroupResourceName, Long audienceId) {
560+
List<MutateOperation> mutateOperations = new ArrayList<>();
561+
AssetGroupSignal assetGroupSignal =
562+
AssetGroupSignal.newBuilder()
563+
.setAssetGroup(assetGroupResourceName)
564+
.setAudience(
565+
AudienceInfo.newBuilder()
566+
.setAudience(ResourceNames.audience(customerId, audienceId)))
567+
.build();
568+
// Adds an operation to the list to create the asset group signal.
569+
mutateOperations.add(
570+
MutateOperation.newBuilder()
571+
.setAssetGroupSignalOperation(
572+
AssetGroupSignalOperation.newBuilder().setCreate(assetGroupSignal))
573+
.build());
574+
return mutateOperations;
575+
}
576+
// [END add_performance_max_campaign_9]
577+
530578
/**
531579
* Prints the details of a MutateGoogleAdsResponse.
532580
*

‎google-ads-examples/src/main/java/com/google/ads/googleads/examples/shoppingads/AddPerformanceMaxRetailCampaign.java‎

Lines changed: 86 additions & 28 deletions
Original file line numberDiff line numberDiff line change
@@ -33,18 +33,22 @@
3333
import com.google.ads.googleads.v10.enums.CampaignStatusEnum.CampaignStatus;
3434
import com.google.ads.googleads.v10.enums.ConversionActionCategoryEnum.ConversionActionCategory;
3535
import com.google.ads.googleads.v10.enums.ConversionOriginEnum.ConversionOrigin;
36+
import com.google.ads.googleads.v10.enums.ListingGroupFilterTypeEnum.ListingGroupFilterType;
37+
import com.google.ads.googleads.v10.enums.ListingGroupFilterVerticalEnum.ListingGroupFilterVertical;
3638
import com.google.ads.googleads.v10.errors.GoogleAdsError;
3739
import com.google.ads.googleads.v10.errors.GoogleAdsException;
3840
import com.google.ads.googleads.v10.resources.Asset;
3941
import com.google.ads.googleads.v10.resources.AssetGroup;
4042
import com.google.ads.googleads.v10.resources.AssetGroupAsset;
43+
import com.google.ads.googleads.v10.resources.AssetGroupListingGroupFilter;
4144
import com.google.ads.googleads.v10.resources.Campaign;
4245
import com.google.ads.googleads.v10.resources.Campaign.ShoppingSetting;
4346
import com.google.ads.googleads.v10.resources.CampaignBudget;
4447
import com.google.ads.googleads.v10.resources.CampaignConversionGoal;
4548
import com.google.ads.googleads.v10.resources.CampaignCriterion;
4649
import com.google.ads.googleads.v10.resources.CustomerConversionGoal;
4750
import com.google.ads.googleads.v10.services.AssetGroupAssetOperation;
51+
import com.google.ads.googleads.v10.services.AssetGroupListingGroupFilterOperation;
4852
import com.google.ads.googleads.v10.services.AssetGroupOperation;
4953
import com.google.ads.googleads.v10.services.AssetOperation;
5054
import com.google.ads.googleads.v10.services.CampaignBudgetOperation;
@@ -124,8 +128,11 @@ private static class AddPerformanceMaxRetailCampaignParams extends CodeSamplePar
124128

125129
@Parameter(
126130
names = ArgumentNames.FINAL_URL,
127-
description = "The final URL for the asset group of the campaign.")
128-
private String finalUrl = "http://www.example.com";
131+
required = true,
132+
description =
133+
"The final url for the generated ads. Must have the same domain as the Merchant Center"
134+
+ " account.")
135+
private String finalUrl;
129136
}
130137

131138
public static void main(String[] args) throws IOException {
@@ -136,10 +143,10 @@ public static void main(String[] args) throws IOException {
136143
// into the code here. See the parameter class definition above for descriptions.
137144
params.customerId = Long.parseLong("INSERT_CUSTOMER_ID_HERE");
138145
params.merchantCenterAccountId = Long.parseLong("INSERT_MERCHANT_CENTER_ACCOUNT_ID_HERE");
146+
params.finalUrl = "INSERT_FINAL_URL_HERE";
139147

140-
// Optionally set custom values for the parameters below.
148+
// Optionally set the country code.
141149
// params.countryCode = "INSERT_COUNTRY_CODE_HERE";
142-
// params.finalUrl = "INSERT_FINAL_URL_HERE";
143150
}
144151

145152
GoogleAdsClient googleAdsClient = null;
@@ -228,10 +235,18 @@ private void runExample(
228235
mutateOperations.add(
229236
createPerformanceMaxCampaignOperation(customerId, merchantCenterAccountId, countryCode));
230237
mutateOperations.addAll(createCampaignCriterionOperations(customerId));
238+
String assetGroupResourceName = ResourceNames.assetGroup(customerId, ASSET_GROUP_TEMPORARY_ID);
231239
mutateOperations.addAll(
232240
createAssetGroupOperations(
233-
customerId, headlineAssetResourceNames, descriptionAssetResourceNames, finalUrl));
241+
customerId,
242+
assetGroupResourceName,
243+
headlineAssetResourceNames,
244+
descriptionAssetResourceNames,
245+
finalUrl));
234246
mutateOperations.addAll(createConversionGoalOperations(customerId, customerConversionGoals));
247+
// Retail Performance Max campaigns require listing groups, which are created via the
248+
// AssetGroupListingGroupFilter resource.
249+
mutateOperations.add(createAssetGroupListingGroupFilterOperation(assetGroupResourceName));
235250

236251
try (GoogleAdsServiceClient googleAdsServiceClient =
237252
googleAdsClient.getLatestVersion().createGoogleAdsServiceClient()) {
@@ -297,13 +312,17 @@ private MutateOperation createPerformanceMaxCampaignOperation(
297312
.setSalesCountry(countryCode)
298313
.build())
299314
// Sets the Final URL expansion opt out. This flag is specific to
300-
// Performance Max campaigns. If opted out (True), only the final URLs in
315+
// Performance Max campaigns. If opted out (true), only the final URLs in
301316
// the asset group or URLs specified in the advertiser's Google Merchant
302317
// Center or business data feeds are targeted.
303-
// If opted in (False), the entire domain will be targeted. For best
318+
//
319+
// If opted in (false), the entire domain will be targeted. For best
304320
// results, set this value to false to opt in and allow URL expansions. You
305321
// can optionally add exclusions to limit traffic to parts of your website.
306-
.setUrlExpansionOptOut(false)
322+
//
323+
// Sets to true for this Retail campaign so the final URLs will be limited to those
324+
// explicitly surfaced via Google Merchant Center.
325+
.setUrlExpansionOptOut(true)
307326
// Assigns the resource name with a temporary ID.
308327
.setResourceName(
309328
ResourceNames.campaign(customerId, PERFORMANCE_MAX_CAMPAIGN_TEMPORARY_ID))
@@ -413,14 +432,14 @@ private List<String> createMultipleTextAssets(
413432
/** Creates a list of MutateOperations that create a new AssetGroup. */
414433
private List<MutateOperation> createAssetGroupOperations(
415434
long customerId,
435+
String assetGroupResourceName,
416436
List<String> headlineAssetResourceNames,
417437
List<String> descriptionAssetResourceNames,
418438
String finalUrl)
419439
throws IOException {
420440
List<MutateOperation> mutateOperations = new ArrayList<>();
421441
String campaignResourceName =
422442
ResourceNames.campaign(customerId, PERFORMANCE_MAX_CAMPAIGN_TEMPORARY_ID);
423-
String assetGroupResourceName = ResourceNames.assetGroup(customerId, ASSET_GROUP_TEMPORARY_ID);
424443
// Creates the AssetGroup.
425444
AssetGroup assetGroup =
426445
AssetGroup.newBuilder()
@@ -483,40 +502,46 @@ private List<MutateOperation> createAssetGroupOperations(
483502
}
484503

485504
// Creates and links the long headline text asset.
486-
List<MutateOperation> createAndLinkTextAssetOperations =
487-
createAndLinkTextAsset(customerId, "Travel the World", AssetFieldType.LONG_HEADLINE);
488-
mutateOperations.addAll(createAndLinkTextAssetOperations);
505+
mutateOperations.addAll(
506+
createAndLinkTextAsset(
507+
customerId, assetGroupResourceName, "Travel the World", AssetFieldType.LONG_HEADLINE));
489508

490509
// Creates and links the business name text asset.
491-
createAndLinkTextAssetOperations =
492-
createAndLinkTextAsset(customerId, "Interplanetary Cruises", AssetFieldType.BUSINESS_NAME);
493-
mutateOperations.addAll(createAndLinkTextAssetOperations);
510+
mutateOperations.addAll(
511+
createAndLinkTextAsset(
512+
customerId,
513+
assetGroupResourceName,
514+
"Interplanetary Cruises",
515+
AssetFieldType.BUSINESS_NAME));
494516

495517
// Creates and links the image assets.
496518

497519
// Creates and links the Logo Asset.
498-
createAndLinkTextAssetOperations =
520+
mutateOperations.addAll(
499521
createAndLinkImageAsset(
500-
customerId, "https://gaagl.page.link/bjYi", AssetFieldType.LOGO, "Logo Image");
501-
mutateOperations.addAll(createAndLinkTextAssetOperations);
522+
customerId,
523+
assetGroupResourceName,
524+
"https://gaagl.page.link/bjYi",
525+
AssetFieldType.LOGO,
526+
"Logo Image"));
502527

503528
// Creates and links the Marketing Image Asset.
504-
createAndLinkTextAssetOperations =
529+
mutateOperations.addAll(
505530
createAndLinkImageAsset(
506531
customerId,
532+
assetGroupResourceName,
507533
"https://gaagl.page.link/Eit5",
508534
AssetFieldType.MARKETING_IMAGE,
509-
"Marketing Image");
510-
mutateOperations.addAll(createAndLinkTextAssetOperations);
535+
"Marketing Image"));
511536

512537
// Creates and links the Square Marketing Image Asset.
513-
createAndLinkTextAssetOperations =
538+
mutateOperations.addAll(
514539
createAndLinkImageAsset(
515540
customerId,
541+
assetGroupResourceName,
516542
"https://gaagl.page.link/bjYi",
517543
AssetFieldType.SQUARE_MARKETING_IMAGE,
518-
"Square Marketing Image");
519-
mutateOperations.addAll(createAndLinkTextAssetOperations);
544+
"Square Marketing Image"));
520545

521546
return mutateOperations;
522547
}
@@ -525,7 +550,7 @@ private List<MutateOperation> createAssetGroupOperations(
525550
// [START add_performance_max_retail_campaign_7]
526551
/** Creates a list of MutateOperations that create a new linked text asset. */
527552
List<MutateOperation> createAndLinkTextAsset(
528-
long customerId, String text, AssetFieldType assetFieldType) {
553+
long customerId, String assetGroupResourceName, String text, AssetFieldType assetFieldType) {
529554
List<MutateOperation> mutateOperations = new ArrayList<>();
530555
String assetResourceName = ResourceNames.asset(customerId, getNextTemporaryId());
531556
// Creates the Text Asset.
@@ -541,7 +566,7 @@ List<MutateOperation> createAndLinkTextAsset(
541566
AssetGroupAsset assetGroupAsset =
542567
AssetGroupAsset.newBuilder()
543568
.setFieldType(assetFieldType)
544-
.setAssetGroup(ResourceNames.assetGroup(customerId, ASSET_GROUP_TEMPORARY_ID))
569+
.setAssetGroup(assetGroupResourceName)
545570
.setAsset(assetResourceName)
546571
.build();
547572
AssetGroupAssetOperation assetGroupAssetOperation =
@@ -556,7 +581,11 @@ List<MutateOperation> createAndLinkTextAsset(
556581
// [START add_performance_max_retail_campaign_8]
557582
/** Creates a list of MutateOperations that create a new linked image asset. */
558583
List<MutateOperation> createAndLinkImageAsset(
559-
long customerId, String url, AssetFieldType assetFieldType, String assetName)
584+
long customerId,
585+
String assetGroupResourceName,
586+
String url,
587+
AssetFieldType assetFieldType,
588+
String assetName)
560589
throws IOException {
561590
List<MutateOperation> mutateOperations = new ArrayList<>();
562591
String assetResourceName = ResourceNames.asset(customerId, getNextTemporaryId());
@@ -580,7 +609,7 @@ List<MutateOperation> createAndLinkImageAsset(
580609
AssetGroupAsset assetGroupAsset =
581610
AssetGroupAsset.newBuilder()
582611
.setFieldType(assetFieldType)
583-
.setAssetGroup(ResourceNames.assetGroup(customerId, ASSET_GROUP_TEMPORARY_ID))
612+
.setAssetGroup(assetGroupResourceName)
584613
.setAsset(assetResourceName)
585614
.build();
586615
AssetGroupAssetOperation assetGroupAssetOperation =
@@ -658,6 +687,35 @@ private static List<MutateOperation> createConversionGoalOperations(
658687
}
659688
// [END add_performance_max_retail_campaign_9]
660689

690+
// [START add_performance_max_retail_campaign_10]
691+
/** Creates a MutateOperation that creates a new asset group listing group filter. */
692+
private MutateOperation createAssetGroupListingGroupFilterOperation(
693+
String assetGroupResourceName) {
694+
695+
// Creates a new asset group listing group filter containing the "default" listing group (All
696+
// products).
697+
AssetGroupListingGroupFilter listingGroupFilter =
698+
AssetGroupListingGroupFilter.newBuilder()
699+
.setAssetGroup(assetGroupResourceName)
700+
// Does not set the parentListingGroupFilter since this is the root node. For all other
701+
// nodes, this would refer to the parent listing group filter resource name.
702+
// .setParentListingGroupFilter("<PARENT FILTER RESOURCE NAME>")
703+
704+
// Sets the type to UNIT_INCLUDED since this node has no children.
705+
.setType(ListingGroupFilterType.UNIT_INCLUDED)
706+
// Specifies that this is in the SHOPPING vertical, as required for a Performance Max
707+
// retail campaign.
708+
.setVertical(ListingGroupFilterVertical.SHOPPING)
709+
.build();
710+
711+
// Returns an operation to the list to create the listing group filter.
712+
return MutateOperation.newBuilder()
713+
.setAssetGroupListingGroupFilterOperation(
714+
AssetGroupListingGroupFilterOperation.newBuilder().setCreate(listingGroupFilter))
715+
.build();
716+
}
717+
// [END add_performance_max_retail_campaign_10]
718+
661719
/**
662720
* Prints the details of a MutateGoogleAdsResponse.
663721
*

‎google-ads-examples/src/main/java/com/google/ads/googleads/examples/utils/ArgumentNames.java‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -28,6 +28,7 @@ public final class ArgumentNames {
2828
public static final String ARTIFACT_NAME = "--artifactName";
2929
public static final String ASSET_GROUP_ID = "--assetGroupId";
3030
public static final String ATTRIBUTE_VALUE = "--attributeValue";
31+
public static final String AUDIENCE_ID = "--audienceId";
3132
public static final String BASE_CAMPAIGN_ID = "--baseCampaignId";
3233
public static final String BID_MODIFIER_VALUE = "--bidModifierValue";
3334
public static final String BILLING_SETUP_ID = "--billingSetupId";

0 commit comments

Comments
 (0)