You can populate your audience list with people who have taken specific actions on your website. If you're using conversion tracking, you can target ads to people who previously triggered a conversion (such as a purchase) on your website.
You can also target ads to people who have taken a particular action on your website that you do not consider a conversion, such as when a person adds but then deletes an item from their shopping cart without making a purchase.
In either case, you would set the
basic_user_list field of a
UserList with a
BasicUserListInfo object containing
references to the conversions you are targeting.
Triggered a conversion
If you haven't yet created a conversion tracker, you can do so using
ConversionActionService. You can then
install the conversion tracker tag on your website.
A basic user list defines its membership as people who had triggered one or more
conversion trackers on your website. When you create a basic user list, you
provide the resource name of the
ConversionAction to a
UserListActionInfo object, which is
ultimately passed to the UserList.
The following example creates a basic user list associated with two existing conversion trackers:
Java
private void runExample(
GoogleAdsClient googleAdsClient, long customerId, List<Long> conversionActionIds) {
List<UserListActionInfo> userListActionInfoList = new ArrayList<>();
for (long conversionActionId : conversionActionIds) {
// Creates the UserListActionInfo object for a given conversion action. This specifies the
// conversion action that, when triggered, will cause a user to be added to a UserList.
UserListActionInfo userListActionInfo =
UserListActionInfo.newBuilder()
.setConversionAction(ResourceNames.conversionAction(customerId, conversionActionId))
.build();
userListActionInfoList.add(userListActionInfo);
}
// Creates a basic user list info object with all of the conversion actions.
BasicUserListInfo basicUserListInfo =
BasicUserListInfo.newBuilder().addAllActions(userListActionInfoList).build();
// Creates the basic user list.
UserList basicUserList =
UserList.newBuilder()
.setName("Example BasicUserList #" + getPrintableDateTime())
.setDescription("A list of people who have triggered one or more conversion actions")
.setMembershipLifeSpan(365)
.setBasicUserList(basicUserListInfo)
.setMembershipStatus(UserListMembershipStatus.OPEN)
.build();
// Creates the operation.
UserListOperation operation = UserListOperation.newBuilder().setCreate(basicUserList).build();
// Creates the service client.
try (UserListServiceClient userListServiceClient =
googleAdsClient.getLatestVersion().createUserListServiceClient()) {
// Adds the basic user list.
MutateUserListsResponse response =
userListServiceClient.mutateUserLists(
Long.toString(customerId), ImmutableList.of(operation));
// Prints the results.
System.out.printf(
"Created basic user list with resource name '%s'.%n",
response.getResults(0).getResourceName());
}
}
C#
public void Run(GoogleAdsClient client, long customerId, long[] conversionActionIds)
{
// Creates the service client.
UserListServiceClient userListServiceClient =
client.GetService(Services.V13.UserListService);
List<UserListActionInfo> userListActionInfoList = new List<UserListActionInfo>();
foreach (long conversionActionId in conversionActionIds)
{
// Creates the UserListActionInfo object for a given conversion action. This
// specifies the conversion action that, when triggered, will cause a user to be
// added to a UserList.
userListActionInfoList.Add(new UserListActionInfo
{
ConversionAction =
ResourceNames.ConversionAction(customerId, conversionActionId)
});
}
// Creates a basic user list info object with all of the conversion actions.
BasicUserListInfo basicUserListInfo = new BasicUserListInfo();
basicUserListInfo.Actions.Add(userListActionInfoList);
// Creates the basic user list.
UserList basicUserList = new UserList
{
Name = $"Example BasicUserList #{ExampleUtilities.GetShortRandomString()}",
Description = "A list of people who have triggered one or more conversion actions",
MembershipLifeSpan = 365L,
BasicUserList = basicUserListInfo,
MembershipStatus = UserListMembershipStatus.Open
};
// Creates the operation.
UserListOperation operation = new UserListOperation
{
Create = basicUserList
};
try
{
// Adds the new user list.
MutateUserListsResponse response = userListServiceClient.MutateUserLists
(customerId.ToString(), new[] { operation });
// Prints the result.
Console.WriteLine("Created basic user list with resource name: " +
$"{response.Results.First().ResourceName}");
}
catch (GoogleAdsException e)
{
Console.WriteLine("Failure:");
Console.WriteLine($"Message: {e.Message}");
Console.WriteLine($"Failure: {e.Failure}");
Console.WriteLine($"Request ID: {e.RequestId}");
throw;
}
}
PHP
public static function runExample(
GoogleAdsClient $googleAdsClient,
int $customerId,
array $conversionActionIds
) {
$userListActionInfoList = [];
foreach ($conversionActionIds as $conversionActionId) {
// Creates the UserListActionInfo object for a given conversion action. This specifies
// the conversion action that, when triggered, will cause a user to be added to a
// UserList.
$userListActionInfoList[] = new UserListActionInfo([
'conversion_action' => ResourceNames::forConversionAction(
$customerId,
$conversionActionId
)
]);
}
// Creates a basic user list info object with all of the conversion actions.
$basicUserListInfo = new BasicUserListInfo(['actions' => $userListActionInfoList]);
// Creates the basic user list.
$basicUserList = new UserList([
'name' => 'Example BasicUserList #' . Helper::getPrintableDatetime(),
'description' => 'A list of people who have triggered one or more conversion actions',
'membership_status' => UserListMembershipStatus::OPEN,
'membership_life_span' => 365,
'basic_user_list' => $basicUserListInfo
]);
// Creates the operation.
$operation = new UserListOperation();
$operation->setCreate($basicUserList);
// Issues a mutate request to add the user list and prints some information.
$userListServiceClient = $googleAdsClient->getUserListServiceClient();
$response = $userListServiceClient->mutateUserLists($customerId, [$operation]);
printf(
"Created basic user list with resource name '%s'.%s",
$response->getResults()[0]->getResourceName(),
PHP_EOL
);
}
Python
def main(client, customer_id, conversion_action_ids):
"""Creates a combination user list.
Args:
client: The Google Ads client.
customer_id: The customer ID for which to add the user list.
conversion_action_ids: The IDs of the conversion actions for the basic
user list.
"""
# Get the UserListService and ConversionActionService clients.
user_list_service = client.get_service("UserListService")
conversion_action_service = client.get_service("ConversionActionService")
# Create a list of UserListActionInfo objects for the given conversion
# actions. These specify the conversion actions that, when triggered, will
# cause a user to be added to a UserList.
user_list_action_info_list = []
for conversion_action_id in conversion_action_ids:
user_list_action_info = client.get_type("UserListActionInfo")
user_list_action_info.conversion_action = conversion_action_service.conversion_action_path(
customer_id, conversion_action_id
)
user_list_action_info_list.append(user_list_action_info)
# Create a UserListOperation and populate the UserList.
user_list_operation = client.get_type("UserListOperation")
user_list = user_list_operation.create
user_list.name = f"Example BasicUserList #{uuid4()}"
user_list.description = (
"A list of people who have triggered one or more conversion actions"
)
user_list.membership_status = client.enums.UserListMembershipStatusEnum.OPEN
user_list.membership_life_span = 365
# The basic user list info object contains the conversion action info.
user_list.basic_user_list.actions.extend(user_list_action_info_list)
# Issue a mutate request to add the user list, then print the results.
response = user_list_service.mutate_user_lists(
customer_id=customer_id, operations=[user_list_operation]
)
print(
"Created basic user list with resource name "
f"'{response.results[0].resource_name}.'"
)
Ruby
def add_conversion_based_user_list(customer_id, conversion_action_ids)
# GoogleAdsClient will read a config file from
# ENV['HOME']/google_ads_config.rb when called without parameters
client = Google::Ads::GoogleAds::GoogleAdsClient.new
# Creates the basic user list.
operation = client.operation.create_resource.user_list do |u|
u.name = "Example BasicUserList ##{(Time.new.to_f * 100).to_i}"
u.description = "A list of people who have triggered one or more conversion actions"
u.membership_status = :OPEN
u.membership_life_span = 365
# Creates a basic user list info object with all of the conversion actions.
u.basic_user_list = client.resource.basic_user_list_info do |info|
conversion_action_ids.each do |conversion_action_id|
# Creates the UserListActionInfo object for a given conversion action.
# This specifies the conversion action that, when triggered, will cause a
# user to be added to a user_list.
info.actions << client.resource.user_list_action_info do |action|
action.conversion_action =
client.path.conversion_action(customer_id, conversion_action_id)
end
end
end
end
# Issues a mutate request to add the user list and prints some information.
response = client.service.user_list.mutate_user_lists(
customer_id: customer_id,
operations: [operation],
)
puts "Created basic user list with resource name " \
"#{response.results.first.resource_name}"
end
Perl
sub add_conversion_based_user_list {
my ($api_client, $customer_id, $conversion_action_ids) = @_;
my $user_list_action_info_list = [];
foreach my $conversion_action_id (@$conversion_action_ids) {
# Create the UserListActionInfo object for a given conversion action. This
# specifies the conversion action that, when triggered, will cause a user to
# be added to a UserList.
push @$user_list_action_info_list,
Google::Ads::GoogleAds::V13::Common::UserListActionInfo->new({
conversionAction =>
Google::Ads::GoogleAds::V13::Utils::ResourceNames::conversion_action(
$customer_id, $conversion_action_id
)});
}
# Create a basic user list info object with all of the conversion actions.
my $basic_user_list_info =
Google::Ads::GoogleAds::V13::Common::BasicUserListInfo->new({
actions => $user_list_action_info_list
});
# Create the basic user list.
my $basic_user_list = Google::Ads::GoogleAds::V13::Resources::UserList->new({
name => "Example BasicUserList #" . uniqid(),
description =>
"A list of people who have triggered one or more conversion actions",
membershipStatus => OPEN,
membershipLifeSpan => 365,
basicUserList => $basic_user_list_info
});
# Create the operation.
my $user_list_operation =
Google::Ads::GoogleAds::V13::Services::UserListService::UserListOperation->
new({
create => $basic_user_list
});
# Issue a mutate request to add the user list and print some information.
my $user_lists_response = $api_client->UserListService()->mutate({
customerId => $customer_id,
operations => [$user_list_operation]});
printf
"Created basic user list with resource name '%s'.\n",
$user_lists_response->{results}[0]{resourceName};
return 1;
}
Non-conversion actions
You can create a basic user list for people who took actions on your website
that you do not consider conversions by associating it with a
RemarketingAction instead of a ConversionAction.
The example below demonstrates how to create a RemarketingAction and retrieve
the associated site tags.
Java
private void runExample(GoogleAdsClient googleAdsClient, long customerId) {
// Creates a remarketing action with the specified name.
RemarketingAction remarketingAction =
RemarketingAction.newBuilder()
.setName("Remarketing action #" + getPrintableDateTime())
.build();
// Creates a remarketing action operation.
RemarketingActionOperation operation =
RemarketingActionOperation.newBuilder().setCreate(remarketingAction).build();
// Issues a mutate request to add the remarketing action and prints out some information.
String remarketingActionResourceName;
try (RemarketingActionServiceClient conversionActionServiceClient =
googleAdsClient.getLatestVersion().createRemarketingActionServiceClient()) {
MutateRemarketingActionsResponse response =
conversionActionServiceClient.mutateRemarketingActions(
Long.toString(customerId), Collections.singletonList(operation));
remarketingActionResourceName = response.getResults(0).getResourceName();
System.out.printf(
"Added remarketing action with resource name '%s'.%n", remarketingActionResourceName);
}
// Creates a query that retrieves the previously created remarketing action with its generated
// tag snippets.
String query =
String.format(
"SELECT remarketing_action.id,"
+ " remarketing_action.name,"
+ " remarketing_action.tag_snippets "
+ "FROM remarketing_action "
+ "WHERE remarketing_action.resource_name = '%s'",
remarketingActionResourceName);
try (GoogleAdsServiceClient googleAdsServiceClient =
googleAdsClient.getLatestVersion().createGoogleAdsServiceClient()) {
// Issues a search request.
SearchPagedResponse searchPagedResponse =
googleAdsServiceClient.search(Long.toString(customerId), query);
// There is only one row because we limited the search using the resource name, which is
// unique.
GoogleAdsRow googleAdsRow = searchPagedResponse.iterateAll().iterator().next();
// Prints some attributes of the remarketing action. The ID and tag snippets are generated by
// the API.
RemarketingAction newRemarketingAction = googleAdsRow.getRemarketingAction();
System.out.printf(
"Remarketing action has ID %d and name '%s'.%n%n",
newRemarketingAction.getId(), newRemarketingAction.getName());
System.out.println("It has the following generated tag snippets:");
for (TagSnippet tagSnippet : newRemarketingAction.getTagSnippetsList()) {
System.out.printf(
"Tag snippet with code type '%s' and code page format '%s' has the following global"
+ " site tag:%n%s%n",
tagSnippet.getType(), tagSnippet.getPageFormat(), tagSnippet.getGlobalSiteTag());
System.out.printf("and the following event snippet:%n%s%n%n", tagSnippet.getEventSnippet());
}
}
}
C#
public void Run(GoogleAdsClient client, long customerId)
{
// Get the RemarketingActionService.
RemarketingActionServiceClient remarketingActionService =
client.GetService(Services.V13.RemarketingActionService);
// Get the GoogleAdsService.
GoogleAdsServiceClient googleAdsService =
client.GetService(Services.V13.GoogleAdsService);
try
{
// Creates a remarketing action with the specified name.
RemarketingAction remarketingAction = new RemarketingAction()
{
Name = $"Remarketing action # {ExampleUtilities.GetRandomString()}"
};
// Creates a remarketing action operation.
RemarketingActionOperation remarketingActionOperation =
new RemarketingActionOperation()
{
Create = remarketingAction
};
// Issues a mutate request to add the remarketing action and prints out
// some information.
MutateRemarketingActionsResponse response =
remarketingActionService.MutateRemarketingActions(
customerId.ToString(), new[] { remarketingActionOperation });
string remarketingActionResourceName = response.Results[0].ResourceName;
Console.WriteLine($"Added remarketing action with resource name " +
$"'{remarketingActionResourceName}'.");
// Creates a query that retrieves the previously created remarketing action
// with its generated tag snippets.
var query = $"SELECT remarketing_action.id, remarketing_action.name, " +
$"remarketing_action.tag_snippets FROM remarketing_action " +
$"WHERE remarketing_action.resource_name = '{remarketingActionResourceName}'";
// Issues a search request and retrieve the results. There is only one row
// because we limited the search using the resource name, which is unique.
RemarketingAction result = googleAdsService.Search(customerId.ToString(), query)
.First()
.RemarketingAction;
// Display the result.
Console.WriteLine($"Remarketing action has ID {result.Id} and name" +
$" '{result.Id}'.");
Console.WriteLine("It has the following generated tag snippets:");
foreach (TagSnippet tagSnippet in result.TagSnippets)
{
Console.WriteLine($"Tag snippet with code type '{tagSnippet.Type}' and code " +
$"page format '{tagSnippet.PageFormat}' has the following global site " +
$"tag:{tagSnippet.GlobalSiteTag} \n\nand the following event snippet:" +
$"{tagSnippet.EventSnippet}.");
}
}
catch (GoogleAdsException e)
{
Console.WriteLine("Failure:");
Console.WriteLine($"Message: {e.Message}");
Console.WriteLine($"Failure: {e.Failure}");
Console.WriteLine($"Request ID: {e.RequestId}");
throw;
}
}
}
}
PHP
public static function runExample(GoogleAdsClient $googleAdsClient, int $customerId)
{
// Creates a remarketing action with the specified name.
$remarketingAction = new RemarketingAction([
'name' => 'Remarketing action #' . Helper::getPrintableDatetime()
]);
// Creates a remarketing action operation.
$remarketingActionOperation =
new RemarketingActionOperation(['create' => $remarketingAction]);
// Issues a mutate request to add the remarketing action and prints out some information.
$remarketingActionServiceClient = $googleAdsClient->getRemarketingActionServiceClient();
$response = $remarketingActionServiceClient->mutateRemarketingActions(
$customerId,
[$remarketingActionOperation]
);
$remarketingActionResourceName = $response->getResults()[0]->getResourceName();
printf(
"Added remarketing action with resource name '%s'.%s",
$remarketingActionResourceName,
PHP_EOL
);
// Creates a query that retrieves the previously created remarketing action with its
// generated tag snippets.
$query =
"SELECT remarketing_action.id, "
. "remarketing_action.name, "
. "remarketing_action.tag_snippets "
. "FROM remarketing_action "
. "WHERE remarketing_action.resource_name = '$remarketingActionResourceName'";
// Issues a search request by specifying page size.
$googleAdsServiceClient = $googleAdsClient->getGoogleAdsServiceClient();
$response =
$googleAdsServiceClient->search($customerId, $query, ['pageSize' => self::PAGE_SIZE]);
// There is only one row because we limited the search using the resource name, which is
// unique.
/** @var GoogleAdsRow $googleAdsRow */
$googleAdsRow = $response->iterateAllElements()->current();
// Prints some attributes of the remarketing action. The ID and tag snippets are generated
// by the API.
printf(
"Remarketing action has ID %d and name '%s'.%s%s",
$googleAdsRow->getRemarketingAction()->getId(),
$googleAdsRow->getRemarketingAction()->getName(),
PHP_EOL,
PHP_EOL
);
print 'It has the following generated tag snippets:' . PHP_EOL;
foreach ($googleAdsRow->getRemarketingAction()->getTagSnippets() as $tagSnippet) {
/** @var TagSnippet $tagSnippet */
printf(
"Tag snippet with code type '%s' and code page format '%s' has the following"
. " global site tag:%s%s%s",
TrackingCodeType::name($tagSnippet->getType()),
TrackingCodePageFormat::name($tagSnippet->getPageFormat()),
PHP_EOL,
$tagSnippet->getGlobalSiteTag(),
PHP_EOL
);
printf(
"and the following event snippet:%s%s%s%s",
PHP_EOL,
$tagSnippet->getEventSnippet(),
PHP_EOL,
PHP_EOL
);
}
}
Python
def add_remarketing_action(client, customer_id):
remarketing_action_service = client.get_service("RemarketingActionService")
remarketing_action_operation = client.get_type("RemarketingActionOperation")
remarketing_action = remarketing_action_operation.create
remarketing_action.name = f"Remarketing action #{uuid4()}"
try:
remarketing_action_response = remarketing_action_service.mutate_remarketing_actions(
customer_id=customer_id, operations=[remarketing_action_operation],
)
except GoogleAdsException as ex:
print(
f'Request with ID "{ex.request_id}" failed with status '
f'"{ex.error.code().name}" and includes the following errors:'
)
for error in ex.failure.errors:
print(f'\tError with message "{error.message}".')
if error.location:
for field_path_element in error.location.field_path_elements:
print(f"\t\tOn field: {field_path_element.field_name}")
sys.exit(1)
return remarketing_action_response.results[0].resource_name
Ruby
def add_remarketing_action(customer_id)
# GoogleAdsClient will read a config file from
# ENV['HOME']/google_ads_config.rb when called without parameters
client = Google::Ads::GoogleAds::GoogleAdsClient.new
# Step 1: Create a remarketing action.
operation = client.operation.create_resource.remarketing_action do |action|
action.name = "Remarketing action ##{(Time.new.to_f * 100).to_i}"
end
response = client.service.remarketing_action.mutate_remarketing_actions(
customer_id: customer_id,
operations: [operation],
)
remarketing_action_resource_name = response.results.first.resource_name
# Step 2: Look up the remarketing action we created to get some extra
# information about it, like its tag snippets.
query = <<~EOQUERY
SELECT
remarketing_action.id,
remarketing_action.name,
remarketing_action.tag_snippets
FROM
remarketing_action
WHERE
remarketing_action.resource_name = "#{remarketing_action_resource_name}"
EOQUERY
response = client.service.google_ads.search(
customer_id: customer_id,
query: query,
)
action = response.first.remarketing_action
puts "Remarking action has ID #{action.id} and name '#{action.name}.'"
puts "It has the following generated tag snippets:"
action.tag_snippets.each do |ts|
puts "Tag snippet with code type '#{ts.type}' and code page format " \
"'#{ts.page_format}' has the following global site tag:\n#{ts.global_site_tag}"
puts "and the following event snippet:\n#{ts.event_snippet}"
end
end
Perl
sub add_remarketing_action {
my ($api_client, $customer_id) = @_;
# Create a remarketing action with the specified name.
my $remarketing_action =
Google::Ads::GoogleAds::V13::Resources::RemarketingAction->new({
name => "Remarketing action #" . uniqid()});
# Create a remarketing action operation.
my $remarketing_action_operation =
Google::Ads::GoogleAds::V13::Services::RemarketingActionService::RemarketingActionOperation
->new({
create => $remarketing_action
});
# Issue a mutate request to add the remarketing action and print out some information.
my $remarketing_actions_response =
$api_client->RemarketingActionService()->mutate({
customerId => $customer_id,
operations => [$remarketing_action_operation]});
my $remarketing_action_resource_name =
$remarketing_actions_response->{results}[0]{resourceName};
printf
"Added remarketing action with resource name '%s'.\n",
$remarketing_action_resource_name;
# Create a query that retrieves the previously created remarketing action with
# its generated tag snippets.
my $search_query =
sprintf "SELECT remarketing_action.id, remarketing_action.name, " .
"remarketing_action.tag_snippets FROM remarketing_action " .
"WHERE remarketing_action.resource_name = '%s'",
$remarketing_action_resource_name;
# Issue a search request by specifying page size.
my $search_response = $api_client->GoogleAdsService()->search({
customerId => $customer_id,
query => $search_query,
pageSize => PAGE_SIZE
});
# There is only one row because we limited the search using the resource name,
# which is unique.
my $google_ads_row = $search_response->{results}[0];
# Print some attributes of the remarketing action. The ID and tag snippets are
# generated by the API.
printf
"Remarketing action has ID %d and name '%s'.\n\n",
$google_ads_row->{remarketingAction}{id},
$google_ads_row->{remarketingAction}{name};
print "It has the following generated tag snippets:\n";
foreach my $tag_snippet (@{$google_ads_row->{remarketingAction}{tagSnippets}})
{
printf "Tag snippet with code type '%s' and code page format '%s' " .
"has the following global site tag:\n%s\n",
$tag_snippet->{type},
$tag_snippet->{pageFormat},
$tag_snippet->{globalSiteTag};
printf "and the following event snippet:\n%s\n\n",
$tag_snippet->{eventSnippet};
}
return 1;
}