The code samples below provide examples of common remarketing functions using the AdWords API. Client Library.
Add audience
// Copyright 2017 Google Inc. All Rights Reserved.
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
// http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.
package adwords.axis.v201708.remarketing;
import com.google.api.ads.adwords.axis.factory.AdWordsServices;
import com.google.api.ads.adwords.axis.v201708.cm.AdWordsConversionTracker;
import com.google.api.ads.adwords.axis.v201708.cm.ConversionTracker;
import com.google.api.ads.adwords.axis.v201708.cm.ConversionTrackerPage;
import com.google.api.ads.adwords.axis.v201708.cm.ConversionTrackerServiceInterface;
import com.google.api.ads.adwords.axis.v201708.cm.Operator;
import com.google.api.ads.adwords.axis.v201708.cm.Predicate;
import com.google.api.ads.adwords.axis.v201708.cm.PredicateOperator;
import com.google.api.ads.adwords.axis.v201708.cm.Selector;
import com.google.api.ads.adwords.axis.v201708.rm.AdwordsUserListServiceInterface;
import com.google.api.ads.adwords.axis.v201708.rm.BasicUserList;
import com.google.api.ads.adwords.axis.v201708.rm.UserList;
import com.google.api.ads.adwords.axis.v201708.rm.UserListConversionType;
import com.google.api.ads.adwords.axis.v201708.rm.UserListMembershipStatus;
import com.google.api.ads.adwords.axis.v201708.rm.UserListOperation;
import com.google.api.ads.adwords.axis.v201708.rm.UserListReturnValue;
import com.google.api.ads.adwords.lib.client.AdWordsSession;
import com.google.api.ads.adwords.lib.factory.AdWordsServicesInterface;
import com.google.api.ads.common.lib.auth.OfflineCredentials;
import com.google.api.ads.common.lib.auth.OfflineCredentials.Api;
import com.google.api.client.auth.oauth2.Credential;
import java.util.ArrayList;
import java.util.HashMap;
import java.util.List;
import java.util.Map;
/**
* This example adds a remarketing user list (a.k.a. audience).
*
* <p>Credentials and properties in {@code fromFile()} are pulled from the
* "ads.properties" file. See README for more info.
*/
public class AddAudience {
public static void main(String[] args) throws Exception {
// Generate a refreshable OAuth2 credential.
Credential oAuth2Credential = new OfflineCredentials.Builder()
.forApi(Api.ADWORDS)
.fromFile()
.build()
.generateCredential();
// Construct an AdWordsSession.
AdWordsSession session = new AdWordsSession.Builder()
.fromFile()
.withOAuth2Credential(oAuth2Credential)
.build();
AdWordsServicesInterface adWordsServices = AdWordsServices.getInstance();
runExample(adWordsServices, session);
}
public static void runExample(
AdWordsServicesInterface adWordsServices, AdWordsSession session) throws Exception {
// Get the UserListService.
AdwordsUserListServiceInterface userListService =
adWordsServices.get(session, AdwordsUserListServiceInterface.class);
// Get the ConversionTrackerService.
ConversionTrackerServiceInterface conversionTrackerService =
adWordsServices.get(session, ConversionTrackerServiceInterface.class);
// Create conversion type (tag).
UserListConversionType conversionType = new UserListConversionType();
conversionType.setName("Mars cruise customers #" + System.currentTimeMillis());
// Create remarketing user list.
BasicUserList userList = new BasicUserList();
userList.setName("Mars cruise customers #" + System.currentTimeMillis());
userList.setDescription("A list of mars cruise customers in the last year");
userList.setMembershipLifeSpan(365L);
userList.setConversionTypes(new UserListConversionType[] {conversionType});
// You can optionally provide these field(s).
userList.setStatus(UserListMembershipStatus.OPEN);
// Create operations.
UserListOperation operation = new UserListOperation();
operation.setOperand(userList);
operation.setOperator(Operator.ADD);
UserListOperation[] operations = new UserListOperation[] {operation};
// Add user list.
UserListReturnValue result = userListService.mutate(operations);
// Display results.
// Capture the ID(s) of the conversion.
List<String> conversionIds = new ArrayList<String>();
for (UserList userListResult : result.getValue()) {
if (userListResult instanceof BasicUserList) {
BasicUserList remarketingUserList = (BasicUserList) userListResult;
for (UserListConversionType userListConversionType : remarketingUserList
.getConversionTypes()) {
conversionIds.add(userListConversionType.getId().toString());
}
}
}
// Create predicate and selector.
Predicate predicate = new Predicate();
predicate.setField("Id");
predicate.setOperator(PredicateOperator.IN);
predicate.setValues(conversionIds.toArray(new String[0]));
Selector selector = new Selector();
selector.setFields(new String[] {"Id"});
selector.setPredicates(new Predicate[] {predicate});
// Get all conversion trackers.
Map<Long, AdWordsConversionTracker> conversionTrackers =
new HashMap<Long, AdWordsConversionTracker>();
ConversionTrackerPage page = conversionTrackerService.get(selector);
if (page != null && page.getEntries() != null) {
for (ConversionTracker conversionTracker : page.getEntries()) {
conversionTrackers.put(conversionTracker.getId(),
(AdWordsConversionTracker) conversionTracker);
}
}
// Display user lists.
for (UserList userListResult : result.getValue()) {
System.out.printf("User list with name '%s' and ID %d was added.%n",
userListResult.getName(), userListResult.getId());
// Display user list associated conversion code snippets.
if (userListResult instanceof BasicUserList) {
BasicUserList remarketingUserList = (BasicUserList) userListResult;
for (UserListConversionType userListConversionType : remarketingUserList
.getConversionTypes()) {
System.out.printf("Conversion type code snippet associated to the list:%n%s%n",
conversionTrackers.get(userListConversionType.getId()).getSnippet());
}
}
}
}
}
Add conversion trackers
// Copyright 2017 Google Inc. All Rights Reserved.
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
// http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.
package adwords.axis.v201708.remarketing;
import com.google.api.ads.adwords.axis.factory.AdWordsServices;
import com.google.api.ads.adwords.axis.v201708.cm.AdWordsConversionTracker;
import com.google.api.ads.adwords.axis.v201708.cm.AdWordsConversionTrackerTextFormat;
import com.google.api.ads.adwords.axis.v201708.cm.ConversionTracker;
import com.google.api.ads.adwords.axis.v201708.cm.ConversionTrackerCategory;
import com.google.api.ads.adwords.axis.v201708.cm.ConversionTrackerOperation;
import com.google.api.ads.adwords.axis.v201708.cm.ConversionTrackerReturnValue;
import com.google.api.ads.adwords.axis.v201708.cm.ConversionTrackerServiceInterface;
import com.google.api.ads.adwords.axis.v201708.cm.ConversionTrackerStatus;
import com.google.api.ads.adwords.axis.v201708.cm.Operator;
import com.google.api.ads.adwords.axis.v201708.cm.UploadConversion;
import com.google.api.ads.adwords.lib.client.AdWordsSession;
import com.google.api.ads.adwords.lib.factory.AdWordsServicesInterface;
import com.google.api.ads.common.lib.auth.OfflineCredentials;
import com.google.api.ads.common.lib.auth.OfflineCredentials.Api;
import com.google.api.client.auth.oauth2.Credential;
import java.util.ArrayList;
import java.util.List;
/**
* This example adds an AdWords conversion and an upload conversion tracker.
*
* <p>Credentials and properties in {@code fromFile()} are pulled from the
* "ads.properties" file. See README for more info.
*/
public class AddConversionTrackers {
public static void main(String[] args) throws Exception {
// Generate a refreshable OAuth2 credential.
Credential oAuth2Credential = new OfflineCredentials.Builder()
.forApi(Api.ADWORDS)
.fromFile()
.build()
.generateCredential();
// Construct an AdWordsSession.
AdWordsSession session = new AdWordsSession.Builder()
.fromFile()
.withOAuth2Credential(oAuth2Credential)
.build();
AdWordsServicesInterface adWordsServices = AdWordsServices.getInstance();
runExample(adWordsServices, session);
}
public static void runExample(
AdWordsServicesInterface adWordsServices, AdWordsSession session) throws Exception {
// Get the ConversionTrackerService.
ConversionTrackerServiceInterface service =
adWordsServices.get(session, ConversionTrackerServiceInterface.class);
List<ConversionTracker> conversionTrackers = new ArrayList<>();
// Create an AdWords conversion tracker.
AdWordsConversionTracker adWordsConversionTracker = new AdWordsConversionTracker();
adWordsConversionTracker.setName("Earth to Mars Cruises Conversion # "
+ System.currentTimeMillis());
adWordsConversionTracker.setCategory(ConversionTrackerCategory.DEFAULT);
adWordsConversionTracker.setTextFormat(AdWordsConversionTrackerTextFormat.HIDDEN);
// You can optionally provide these field(s).
adWordsConversionTracker.setStatus(ConversionTrackerStatus.ENABLED);
adWordsConversionTracker.setViewthroughLookbackWindow(15);
adWordsConversionTracker.setConversionPageLanguage("en");
adWordsConversionTracker.setBackgroundColor("#0000FF");
adWordsConversionTracker.setDefaultRevenueValue(1d);
adWordsConversionTracker.setAlwaysUseDefaultRevenueValue(Boolean.TRUE);
conversionTrackers.add(adWordsConversionTracker);
// Create an upload conversion for offline conversion imports.
UploadConversion uploadConversion = new UploadConversion();
// Set an appropriate category. This field is optional, and will be set to
// DEFAULT if not mentioned.
uploadConversion.setCategory(ConversionTrackerCategory.LEAD);
uploadConversion.setName("Upload Conversion #" + System.currentTimeMillis());
uploadConversion.setViewthroughLookbackWindow(30);
uploadConversion.setCtcLookbackWindow(90);
// Optional: Set the default currency code to use for conversions
// that do not specify a conversion currency. This must be an ISO 4217
// 3-character currency code such as "EUR" or "USD".
// If this field is not set on this UploadConversion, AdWords will use
// the account's currency.
uploadConversion.setDefaultRevenueCurrencyCode("EUR");
// Optional: Set the default revenue value to use for conversions
// that do not specify a conversion value. Note that this value
// should NOT be in micros.
uploadConversion.setDefaultRevenueValue(2.50);
// Optional: To upload fractional conversion credits, mark the upload conversion
// as externally attributed. See
// https://developers.google.com/adwords/api/docs/guides/conversion-tracking#importing_externally_attributed_conversions
// to learn more about importing externally attributed conversions.
// uploadConversion.setIsExternallyAttributed(true);
conversionTrackers.add(uploadConversion);
// Create operations.
List<ConversionTrackerOperation> operations = new ArrayList<>();
for (ConversionTracker conversionTracker : conversionTrackers) {
ConversionTrackerOperation operation = new ConversionTrackerOperation();
operation.setOperator(Operator.ADD);
operation.setOperand(conversionTracker);
operations.add(operation);
}
// Add the conversions.
ConversionTrackerReturnValue result =
service.mutate(operations.toArray(new ConversionTrackerOperation[operations.size()]));
// Display conversion.
for (ConversionTracker conversionTracker : result.getValue()) {
if (conversionTracker instanceof AdWordsConversionTracker) {
AdWordsConversionTracker newAdWordsConversionTracker =
(AdWordsConversionTracker) conversionTracker;
System.out.printf(
"Conversion with ID %d, name '%s', status '%s', "
+ "category '%s' and snippet '%s' was added.%n",
newAdWordsConversionTracker.getId(),
newAdWordsConversionTracker.getName(),
newAdWordsConversionTracker.getStatus(),
newAdWordsConversionTracker.getCategory(),
newAdWordsConversionTracker.getSnippet());
} else {
System.out.printf(
"Conversion with ID %d, name '%s', status '%s', " + "category '%s' was added.%n",
conversionTracker.getId(),
conversionTracker.getName(),
conversionTracker.getStatus(),
conversionTracker.getCategory());
}
}
}
}
Add CRM-based user list
// Copyright 2017 Google Inc. All Rights Reserved.
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
// http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.
package adwords.axis.v201708.remarketing;
import com.google.api.ads.adwords.axis.factory.AdWordsServices;
import com.google.api.ads.adwords.axis.v201708.cm.Operator;
import com.google.api.ads.adwords.axis.v201708.rm.AdwordsUserListServiceInterface;
import com.google.api.ads.adwords.axis.v201708.rm.CrmBasedUserList;
import com.google.api.ads.adwords.axis.v201708.rm.Member;
import com.google.api.ads.adwords.axis.v201708.rm.MutateMembersOperand;
import com.google.api.ads.adwords.axis.v201708.rm.MutateMembersOperation;
import com.google.api.ads.adwords.axis.v201708.rm.MutateMembersReturnValue;
import com.google.api.ads.adwords.axis.v201708.rm.UserList;
import com.google.api.ads.adwords.axis.v201708.rm.UserListOperation;
import com.google.api.ads.adwords.axis.v201708.rm.UserListReturnValue;
import com.google.api.ads.adwords.lib.client.AdWordsSession;
import com.google.api.ads.adwords.lib.factory.AdWordsServicesInterface;
import com.google.api.ads.common.lib.auth.OfflineCredentials;
import com.google.api.ads.common.lib.auth.OfflineCredentials.Api;
import com.google.api.client.auth.oauth2.Credential;
import com.google.common.collect.ImmutableList;
import java.io.UnsupportedEncodingException;
import java.security.MessageDigest;
import java.security.NoSuchAlgorithmException;
import java.util.ArrayList;
import java.util.List;
/**
* This example adds a user list (a.k.a. audience) and uploads members to populate the list.
*
* <p>
* <em>Note:</em> It may take up to several hours for the list to be populated with members.
* Email addresses must be associated with a Google account.
* For privacy purposes, the user list size will show as zero until the list has at least 1,000
* members. After that, the size will be rounded to the two most significant digits.
* </p>
*
* <p>
* <p>Credentials and properties in {@code fromFile()} are pulled from the
* "ads.properties" file. See README for more info.
* </p>
*/
public class AddCrmBasedUserList {
private static final ImmutableList<String> EMAILS =
ImmutableList.of("client1@example.com", "client2@example.com", " Client3@example.com ");
private static final MessageDigest digest = getSHA256MessageDigest();
public static void main(String[] args) throws Exception {
// Generate a refreshable OAuth2 credential.
Credential oAuth2Credential = new OfflineCredentials.Builder()
.forApi(Api.ADWORDS)
.fromFile()
.build()
.generateCredential();
// Construct an AdWordsSession.
AdWordsSession session = new AdWordsSession.Builder()
.fromFile()
.withOAuth2Credential(oAuth2Credential)
.build();
AdWordsServicesInterface adWordsServices = AdWordsServices.getInstance();
runExample(adWordsServices, session);
}
public static void runExample(AdWordsServicesInterface adWordsServices, AdWordsSession session)
throws Exception {
// Get the UserListService.
AdwordsUserListServiceInterface userListService =
adWordsServices.get(session, AdwordsUserListServiceInterface.class);
// Create a user list.
CrmBasedUserList userList = new CrmBasedUserList();
userList.setName("Customer relationship management list #" + System.currentTimeMillis());
userList.setDescription("A list of customers that originated from email addresses");
// See limit here: https://support.google.com/adwords/answer/6276125#requirements.
userList.setMembershipLifeSpan(30L);
// Create operation.
UserListOperation operation = new UserListOperation();
operation.setOperand(userList);
operation.setOperator(Operator.ADD);
// Add user list.
UserListReturnValue result = userListService.mutate(new UserListOperation[] {operation});
// Display user list.
UserList userListAdded = result.getValue(0);
System.out.printf(
"User list with name '%s' and ID %d was added.%n",
userListAdded.getName(), userListAdded.getId());
// Get user list ID.
Long userListId = userListAdded.getId();
// Create operation to add members to the user list based on email addresses.
MutateMembersOperation mutateMembersOperation = new MutateMembersOperation();
MutateMembersOperand operand = new MutateMembersOperand();
operand.setUserListId(userListId);
// Hash normalized email addresses based on SHA-256 hashing algorithm.
List<Member> members = new ArrayList<>(EMAILS.size());
for (String email : EMAILS) {
String normalizedEmail = toNormalizedString(email);
Member member = new Member();
member.setHashedEmail(toSHA256String(normalizedEmail));
members.add(member);
}
// Adding address info is currently available on a whitelist-only basis. This code demonstrates
// how to do it, and you can uncomment it if you are on the whitelist.
// String firstName = "John";
// String lastName = "Doe";
// String countryCode = "US";
// String zipCode = "10011";
//
// com.google.api.ads.adwords.axis.v201708.rm.AddressInfo addressInfo = new AddressInfo();
// // First and last name must be normalized and hashed.
// addressInfo.setHashedFirstName(toSHA256String(toNormalizedString(firstName)));
// addressInfo.setHashedLastName(toSHA256String(toNormalizedString(lastName)));
// // Country code and zip code are sent in plaintext.
// addressInfo.setCountryCode(countryCode);
// addressInfo.setZipCode(zipCode);
//
// Member memberByAddress = new Member();
// memberByAddress.setAddressInfo(addressInfo);
// members.add(memberByAddress);
operand.setMembersList(members.toArray(new Member[members.size()]));
mutateMembersOperation.setOperand(operand);
mutateMembersOperation.setOperator(Operator.ADD);
// Add members to the user list based on email addresses.
MutateMembersReturnValue mutateMembersResult =
userListService.mutateMembers(new MutateMembersOperation[] {mutateMembersOperation});
// Display results.
// Reminder: it may take several hours for the list to be populated with members.
for (UserList userListResult : mutateMembersResult.getUserLists()) {
System.out.printf(
"%d email addresses were uploaded to user list with name '%s' and ID %d "
+ "and are scheduled for review.%n",
EMAILS.size(), userListResult.getName(), userListResult.getId());
}
}
/**
* Hash a string using SHA-256 hashing algorithm.
*
* @param str the string to hash.
* @return the SHA-256 hash string representation.
* @throws UnsupportedEncodingException If UTF-8 charset is not supported.
*/
private static String toSHA256String(String str) throws UnsupportedEncodingException {
byte[] hash = digest.digest(str.getBytes("UTF-8"));
StringBuilder result = new StringBuilder();
for (byte b : hash) {
result.append(String.format("%02x", b));
}
return result.toString();
}
/**
* Removes leading and trailing whitespace and converts all characters to lower case.
*
* @param value the string to normalize.
* @return a normalized copy of the string.
*/
private static String toNormalizedString(String value) {
return value.trim().toLowerCase();
}
/** Returns SHA-256 hashing algorithm. */
private static MessageDigest getSHA256MessageDigest() {
try {
return MessageDigest.getInstance("SHA-256");
} catch (NoSuchAlgorithmException e) {
throw new RuntimeException("Missing SHA-256 algorithm implementation.", e);
}
}
}
Add rule-based user list
// Copyright 2017 Google Inc. All Rights Reserved.
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
// http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.
package adwords.axis.v201708.remarketing;
import com.google.api.ads.adwords.axis.factory.AdWordsServices;
import com.google.api.ads.adwords.axis.v201708.cm.Operator;
import com.google.api.ads.adwords.axis.v201708.rm.AdwordsUserListServiceInterface;
import com.google.api.ads.adwords.axis.v201708.rm.CombinedRuleUserList;
import com.google.api.ads.adwords.axis.v201708.rm.CombinedRuleUserListRuleOperator;
import com.google.api.ads.adwords.axis.v201708.rm.DateKey;
import com.google.api.ads.adwords.axis.v201708.rm.DateRuleItem;
import com.google.api.ads.adwords.axis.v201708.rm.DateRuleItemDateOperator;
import com.google.api.ads.adwords.axis.v201708.rm.DateSpecificRuleUserList;
import com.google.api.ads.adwords.axis.v201708.rm.ExpressionRuleUserList;
import com.google.api.ads.adwords.axis.v201708.rm.NumberKey;
import com.google.api.ads.adwords.axis.v201708.rm.NumberRuleItem;
import com.google.api.ads.adwords.axis.v201708.rm.NumberRuleItemNumberOperator;
import com.google.api.ads.adwords.axis.v201708.rm.Rule;
import com.google.api.ads.adwords.axis.v201708.rm.RuleBasedUserListPrepopulationStatus;
import com.google.api.ads.adwords.axis.v201708.rm.RuleItem;
import com.google.api.ads.adwords.axis.v201708.rm.RuleItemGroup;
import com.google.api.ads.adwords.axis.v201708.rm.StringKey;
import com.google.api.ads.adwords.axis.v201708.rm.StringRuleItem;
import com.google.api.ads.adwords.axis.v201708.rm.StringRuleItemStringOperator;
import com.google.api.ads.adwords.axis.v201708.rm.UserList;
import com.google.api.ads.adwords.axis.v201708.rm.UserListOperation;
import com.google.api.ads.adwords.axis.v201708.rm.UserListReturnValue;
import com.google.api.ads.adwords.axis.v201708.rm.UserListRuleTypeEnumsEnum;
import com.google.api.ads.adwords.lib.client.AdWordsSession;
import com.google.api.ads.adwords.lib.factory.AdWordsServicesInterface;
import com.google.api.ads.common.lib.auth.OfflineCredentials;
import com.google.api.ads.common.lib.auth.OfflineCredentials.Api;
import com.google.api.client.auth.oauth2.Credential;
import java.util.ArrayList;
import java.util.List;
import org.joda.time.DateTime;
/**
* This example adds two rule-based remarketing user lists: one with no site visit date
* restrictions, and another that will only include users who visit your site in the
* next six months.
*
* <p>Credentials and properties in {@code fromFile()} are pulled from the
* "ads.properties" file. See README for more info.
*/
public class AddRuleBasedUserLists {
private static final String DATE_FORMAT_STRING = "yyyyMMdd";
public static void main(String[] args) throws Exception {
// Generate a refreshable OAuth2 credential.
Credential oAuth2Credential = new OfflineCredentials.Builder()
.forApi(Api.ADWORDS)
.fromFile()
.build()
.generateCredential();
// Construct an AdWordsSession.
AdWordsSession session = new AdWordsSession.Builder()
.fromFile()
.withOAuth2Credential(oAuth2Credential)
.build();
AdWordsServicesInterface adWordsServices = AdWordsServices.getInstance();
runExample(adWordsServices, session);
}
public static void runExample(AdWordsServicesInterface adWordsServices, AdWordsSession session)
throws Exception {
// Get the AdwordsUserListService.
AdwordsUserListServiceInterface userListService =
adWordsServices.get(session, AdwordsUserListServiceInterface.class);
// First rule item group - users who visited the checkout page and had more than one item
// in their shopping cart.
StringKey pageTypeKey = new StringKey("ecomm_pagetype");
StringRuleItem checkoutStringRuleItem = new StringRuleItem();
checkoutStringRuleItem.setKey(pageTypeKey);
checkoutStringRuleItem.setOp(StringRuleItemStringOperator.EQUALS);
checkoutStringRuleItem.setValue("checkout");
RuleItem checkoutRuleItem = new RuleItem();
checkoutRuleItem.setStringRuleItem(checkoutStringRuleItem);
NumberKey cartSizeKey = new NumberKey("cartsize");
NumberRuleItem cartSizeNumberRuleItem = new NumberRuleItem();
cartSizeNumberRuleItem.setKey(cartSizeKey);
cartSizeNumberRuleItem.setOp(NumberRuleItemNumberOperator.GREATER_THAN);
cartSizeNumberRuleItem.setValue(1.0);
RuleItem cartSizeRuleItem = new RuleItem();
cartSizeRuleItem.setNumberRuleItem(cartSizeNumberRuleItem);
// Combine the two rule items into a RuleItemGroup so AdWords will AND their rules
// together.
RuleItemGroup checkoutMultipleItemGroup = new RuleItemGroup();
checkoutMultipleItemGroup.setItems(new RuleItem[] {checkoutRuleItem, cartSizeRuleItem});
// Second rule item group - users who checked out within the next 3 months.
DateKey checkoutDateKey = new DateKey("checkoutdate");
DateRuleItem startDateDateRuleItem = new DateRuleItem();
startDateDateRuleItem.setKey(checkoutDateKey);
startDateDateRuleItem.setOp(DateRuleItemDateOperator.AFTER);
startDateDateRuleItem.setValue(new DateTime().toString(DATE_FORMAT_STRING));
RuleItem startDateRuleItem = new RuleItem();
startDateRuleItem.setDateRuleItem(startDateDateRuleItem);
DateRuleItem endDateDateRuleItem = new DateRuleItem();
endDateDateRuleItem.setKey(checkoutDateKey);
endDateDateRuleItem.setOp(DateRuleItemDateOperator.BEFORE);
endDateDateRuleItem.setValue(new DateTime().plusMonths(3).toString(DATE_FORMAT_STRING));
RuleItem endDateRuleItem = new RuleItem();
endDateRuleItem.setDateRuleItem(endDateDateRuleItem);
// Combine the date rule items into a RuleItemGroup.
RuleItemGroup checkedOutNextThreeMonthsItemGroup = new RuleItemGroup();
checkedOutNextThreeMonthsItemGroup.setItems(
new RuleItem[] {startDateRuleItem, endDateRuleItem});
// Combine the rule item groups into a Rule so AdWords knows how to apply the rules.
Rule rule = new Rule();
rule.setGroups(
new RuleItemGroup[] {checkoutMultipleItemGroup, checkedOutNextThreeMonthsItemGroup});
// ExpressionRuleUserLists can use either CNF or DNF for matching. CNF means 'at least one item
// in each rule item group must match', and DNF means 'at least one entire rule item group must
// match'. DateSpecificRuleUserList only supports DNF. You can also omit the rule type
// altogether to default to DNF.
rule.setRuleType(UserListRuleTypeEnumsEnum.DNF);
// Third and fourth rule item groups.
// Visitors of a page who visited another page.
StringKey urlStringKey = new StringKey("url__");
StringRuleItem site1StringRuleItem = new StringRuleItem();
site1StringRuleItem.setKey(urlStringKey);
site1StringRuleItem.setOp(StringRuleItemStringOperator.EQUALS);
site1StringRuleItem.setValue("example.com/example1");
RuleItem site1RuleItem = new RuleItem();
site1RuleItem.setStringRuleItem(site1StringRuleItem);
StringRuleItem site2StringRuleItem = new StringRuleItem();
site2StringRuleItem.setKey(urlStringKey);
site2StringRuleItem.setOp(StringRuleItemStringOperator.EQUALS);
site2StringRuleItem.setValue("example.com/example2");
RuleItem site2RuleItem = new RuleItem();
site2RuleItem.setStringRuleItem(site2StringRuleItem);
// Create two RuleItemGroups to show that a visitor browsed two sites.
RuleItemGroup site1RuleItemGroup = new RuleItemGroup();
site1RuleItemGroup.setItems(new RuleItem[]{site1RuleItem});
RuleItemGroup site2RuleItemGroup = new RuleItemGroup();
site2RuleItemGroup.setItems(new RuleItem[]{site2RuleItem});
// Create two rules to show that a visitor browsed two sites.
Rule userVisitedSite1Rule = new Rule();
userVisitedSite1Rule.setGroups(new RuleItemGroup[]{site1RuleItemGroup});
Rule userVisitedSite2Rule = new Rule();
userVisitedSite2Rule.setGroups(new RuleItemGroup[]{site2RuleItemGroup});
// Create the user list with no restrictions on site visit date.
ExpressionRuleUserList expressionUserList = new ExpressionRuleUserList();
String creationTimeString = new DateTime().toString("yyyyMMdd_HHmmss");
expressionUserList.setName(
"Expression based user list created at " + creationTimeString);
expressionUserList.setDescription(
"Users who checked out in three month window OR visited the checkout page "
+ "with more than one item in their cart");
expressionUserList.setRule(rule);
// Optional: Set the prepopulationStatus to REQUESTED to include past users in the user list.
expressionUserList.setPrepopulationStatus(RuleBasedUserListPrepopulationStatus.REQUESTED);
// Create the user list restricted to users who visit your site within the next six months.
DateTime startDate = new DateTime();
DateTime endDate = startDate.plusMonths(6);
DateSpecificRuleUserList dateUserList = new DateSpecificRuleUserList();
dateUserList.setName(
"Date rule user list created at " + creationTimeString);
dateUserList.setDescription(String.format("Users who visited the site between %s and %s and "
+ "checked out in three month window OR visited the checkout page "
+ "with more than one item in their cart", startDate.toString(DATE_FORMAT_STRING),
endDate.toString(DATE_FORMAT_STRING)));
dateUserList.setRule(rule);
// Set the start and end dates of the user list.
dateUserList.setStartDate(startDate.toString(DATE_FORMAT_STRING));
dateUserList.setEndDate(endDate.toString(DATE_FORMAT_STRING));
// Create the user list where "Visitors of a page who did visit another page".
// To create a user list where "Visitors of a page who did not visit another
// page", change the ruleOperator from AND to AND_NOT.
CombinedRuleUserList combinedRuleUserList = new CombinedRuleUserList();
combinedRuleUserList.setName("Combined rule user list created at " + creationTimeString);
combinedRuleUserList.setDescription("Users who visited two sites.");
combinedRuleUserList.setLeftOperand(userVisitedSite1Rule);
combinedRuleUserList.setRightOperand(userVisitedSite2Rule);
combinedRuleUserList.setRuleOperator(CombinedRuleUserListRuleOperator.AND);
// Create operations to add the user lists.
List<UserListOperation> operations = new ArrayList<>();
for (UserList userList :
new UserList[] {expressionUserList, dateUserList, combinedRuleUserList}) {
UserListOperation operation = new UserListOperation();
operation.setOperand(userList);
operation.setOperator(Operator.ADD);
operations.add(operation);
}
// Submit the operations.
UserListReturnValue result =
userListService.mutate(operations.toArray(new UserListOperation[operations.size()]));
// Display the results.
for (UserList userListResult : result.getValue()) {
System.out.printf("User list added with ID %d, name '%s', status '%s', list type '%s',"
+ " accountUserListStatus '%s', description '%s'.%n",
userListResult.getId(),
userListResult.getName(),
userListResult.getStatus().getValue(),
userListResult.getListType() == null ? null : userListResult.getListType().getValue(),
userListResult.getAccountUserListStatus().getValue(),
userListResult.getDescription());
}
}
}
Upload offline conversions
// Copyright 2017 Google Inc. All Rights Reserved.
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
// http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.
package adwords.axis.v201708.remarketing;
import com.beust.jcommander.Parameter;
import com.google.api.ads.adwords.axis.factory.AdWordsServices;
import com.google.api.ads.adwords.axis.v201708.cm.OfflineConversionFeed;
import com.google.api.ads.adwords.axis.v201708.cm.OfflineConversionFeedOperation;
import com.google.api.ads.adwords.axis.v201708.cm.OfflineConversionFeedReturnValue;
import com.google.api.ads.adwords.axis.v201708.cm.OfflineConversionFeedServiceInterface;
import com.google.api.ads.adwords.axis.v201708.cm.Operator;
import com.google.api.ads.adwords.lib.client.AdWordsSession;
import com.google.api.ads.adwords.lib.factory.AdWordsServicesInterface;
import com.google.api.ads.adwords.lib.utils.examples.ArgumentNames;
import com.google.api.ads.common.lib.auth.OfflineCredentials;
import com.google.api.ads.common.lib.auth.OfflineCredentials.Api;
import com.google.api.ads.common.lib.utils.examples.CodeSampleParams;
import com.google.api.client.auth.oauth2.Credential;
/**
* This code example imports offline conversion values for specific clicks to
* your account. To get Google Click ID for a click, run
* CLICK_PERFORMANCE_REPORT. To set up a conversion tracker, run the
* AddConversionTrackers.java example.
*/
public class UploadOfflineConversions {
private static class UploadOfflineConversionsParams extends CodeSampleParams {
@Parameter(names = ArgumentNames.CONVERSION_NAME, required = true,
description = "Name of the conversion tracker to upload to.")
private String conversionName;
@Parameter(names = ArgumentNames.GCL_ID, required = true,
description = "Google Click ID should be newer than 30 days.")
private String gclId;
@Parameter(names = ArgumentNames.CONVERSION_TIME, required = true,
description = "Conversion time should be after the click time.")
private String conversionTime;
@Parameter(names = ArgumentNames.CONVERSION_VALUE, required = true)
private Double conversionValue;
}
public static void main(String[] args) throws Exception {
// Generate a refreshable OAuth2 credential.
Credential oAuth2Credential = new OfflineCredentials.Builder()
.forApi(Api.ADWORDS)
.fromFile()
.build()
.generateCredential();
// Construct an AdWordsSession.
AdWordsSession session = new AdWordsSession.Builder()
.fromFile()
.withOAuth2Credential(oAuth2Credential)
.build();
AdWordsServicesInterface adWordsServices = AdWordsServices.getInstance();
UploadOfflineConversionsParams params = new UploadOfflineConversionsParams();
if (!params.parseArguments(args)) {
// Either pass the required parameters for this example on the command line, or insert them
// into the code here. See the parameter class definition above for descriptions.
params.conversionName = "INSERT_CONVERSION_NAME_HERE";
params.gclId = "INSERT_GCL_ID_HERE";
params.conversionTime = "INSERT_CONVERSION_TIME_HERE";
params.conversionValue = Double.parseDouble("INSERT_CONVERSION_VALUE_HERE");
}
runExample(adWordsServices, session, params.conversionName, params.gclId, params.conversionTime,
params.conversionValue);
}
public static void runExample(AdWordsServicesInterface adWordsServices, AdWordsSession session,
String conversionName, String gClid, String conversionTime,
double conversionValue) throws Exception {
// Get the OfflineConversionFeedService.
OfflineConversionFeedServiceInterface offlineConversionFeedService =
adWordsServices.get(session, OfflineConversionFeedServiceInterface.class);
// Associate offline conversions with the existing named conversion tracker. If this tracker
// was newly created, it may be a few hours before it can accept conversions.
OfflineConversionFeed feed = new OfflineConversionFeed();
feed.setConversionName(conversionName);
feed.setConversionTime(conversionTime);
feed.setConversionValue(conversionValue);
feed.setGoogleClickId(gClid);
OfflineConversionFeedOperation offlineConversionOperation =
new OfflineConversionFeedOperation();
offlineConversionOperation.setOperator(Operator.ADD);
offlineConversionOperation.setOperand(feed);
OfflineConversionFeedReturnValue offlineConversionReturnValue = offlineConversionFeedService
.mutate(new OfflineConversionFeedOperation[] {offlineConversionOperation});
OfflineConversionFeed newFeed = offlineConversionReturnValue.getValue(0);
System.out.printf(
"Uploaded offline conversion value of %.4f for Google Click ID '%s' to '%s'.%n",
newFeed.getConversionValue(), newFeed.getGoogleClickId(), newFeed.getConversionName());
}
}
Upload offline call conversions
// Copyright 2017 Google Inc. All Rights Reserved.
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
// http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.
package adwords.axis.v201708.remarketing;
import com.google.api.ads.adwords.axis.factory.AdWordsServices;
import com.google.api.ads.adwords.axis.v201708.cm.OfflineCallConversionFeed;
import com.google.api.ads.adwords.axis.v201708.cm.OfflineCallConversionFeedOperation;
import com.google.api.ads.adwords.axis.v201708.cm.OfflineCallConversionFeedReturnValue;
import com.google.api.ads.adwords.axis.v201708.cm.OfflineCallConversionFeedServiceInterface;
import com.google.api.ads.adwords.axis.v201708.cm.Operator;
import com.google.api.ads.adwords.lib.client.AdWordsSession;
import com.google.api.ads.adwords.lib.factory.AdWordsServicesInterface;
import com.google.api.ads.common.lib.auth.OfflineCredentials;
import com.google.api.ads.common.lib.auth.OfflineCredentials.Api;
import com.google.api.client.auth.oauth2.Credential;
/**
* This example imports offline call conversion values for calls related to the ads in your account.
*
* <p>Credentials and properties in {@code fromFile()} are pulled from the "ads.properties" file.
* See README for more info.
*/
public class UploadOfflineCallConversions {
public static void main(String[] args) throws Exception {
// Generate a refreshable OAuth2 credential.
Credential oAuth2Credential =
new OfflineCredentials.Builder()
.forApi(Api.ADWORDS)
.fromFile()
.build()
.generateCredential();
// Construct an AdWordsSession.
AdWordsSession session =
new AdWordsSession.Builder().fromFile().withOAuth2Credential(oAuth2Credential).build();
AdWordsServicesInterface adWordsServices = AdWordsServices.getInstance();
// Replace with valid values of your account.
String callerId = "INSERT_CALLER_ID_HERE";
// For times, use the format yyyyMMdd HHmmss tz. For more details on formats, see:
// https://developers.google.com/adwords/api/docs/appendix/codes-formats#date-and-time-formats
// For time zones, see:
// https://developers.google.com/adwords/api/docs/appendix/codes-formats#timezone-ids
String callStartTime = "INSERT_CALL_START_TIME_HERE";
// Name of the conversion tracker to upload to.
String conversionName = "INSERT_CONVERSION_NAME_HERE";
String conversionTime = "INSERT_CONVERSION_TIME_HERE";
Double conversionValue = Double.valueOf("INSERT_CONVERSION_VALUE_HERE");
runExample(
adWordsServices,
session,
callerId,
callStartTime,
conversionName,
conversionTime,
conversionValue);
}
public static void runExample(
AdWordsServicesInterface adWordsServices,
AdWordsSession session,
String callerId,
String callStartTime,
String conversionName,
String conversionTime,
double conversionValue)
throws Exception {
// Get the OfflineCallConversionFeedService.
OfflineCallConversionFeedServiceInterface offlineCallConversionFeedService =
adWordsServices.get(session, OfflineCallConversionFeedServiceInterface.class);
// Associate offline call conversions with the existing named conversion tracker. If this
// tracker was newly created, it may be a few hours before it can accept conversions.
OfflineCallConversionFeed feed = new OfflineCallConversionFeed();
feed.setCallerId(callerId);
feed.setCallStartTime(callStartTime);
feed.setConversionName(conversionName);
feed.setConversionTime(conversionTime);
feed.setConversionValue(conversionValue);
OfflineCallConversionFeedOperation offlineCallConversionOperation =
new OfflineCallConversionFeedOperation();
offlineCallConversionOperation.setOperator(Operator.ADD);
offlineCallConversionOperation.setOperand(feed);
// This example uploads only one call conversion, but you can upload multiple call conversions
// by passing additional operations.
OfflineCallConversionFeedReturnValue offlineCallConversionReturnValue =
offlineCallConversionFeedService.mutate(
new OfflineCallConversionFeedOperation[] {offlineCallConversionOperation});
// Display results.
for (OfflineCallConversionFeed feedResult : offlineCallConversionReturnValue.getValue()) {
System.out.printf(
"Uploaded offline conversion value of %.4f for caller ID '%s'.%n",
feedResult.getConversionValue(), feedResult.getCallerId());
}
}
}
Need help? Visit our