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.V14.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(
MutateUserListsRequest::build($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::V14::Common::UserListActionInfo->new({
conversionAction =>
Google::Ads::GoogleAds::V14::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::V14::Common::BasicUserListInfo->new({
actions => $user_list_action_info_list
});
# Create the basic user list.
my $basic_user_list = Google::Ads::GoogleAds::V14::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::V14::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.