The best way to set up new conversion actions in the API is to use the
Add Conversion Action code example
in the Remarketing folder of your client library. The sample handles all the
background authentication tasks for you, and walks you through creating a
ConversionAction
.
The Google Ads API will set the primary_for_goal
field automatically, but you can
set this field explicitly to control how a conversion action will impact
reporting and bidding in your account when combined with your conversion
goals.
Java
private void runExample(GoogleAdsClient googleAdsClient, long customerId) { // Creates a ConversionAction. ConversionAction conversionAction = ConversionAction.newBuilder() .setName("Earth to Mars Cruises Conversion #" + getPrintableDateTime()) .setCategory(ConversionActionCategory.DEFAULT) .setType(ConversionActionType.WEBPAGE) .setStatus(ConversionActionStatus.ENABLED) .setViewThroughLookbackWindowDays(15L) .setValueSettings( ValueSettings.newBuilder() .setDefaultValue(23.41) .setAlwaysUseDefaultValue(true) .build()) .build(); // Creates the operation. ConversionActionOperation operation = ConversionActionOperation.newBuilder().setCreate(conversionAction).build(); try (ConversionActionServiceClient conversionActionServiceClient = googleAdsClient.getLatestVersion().createConversionActionServiceClient()) { MutateConversionActionsResponse response = conversionActionServiceClient.mutateConversionActions( Long.toString(customerId), Collections.singletonList(operation)); System.out.printf("Added %d conversion actions:%n", response.getResultsCount()); for (MutateConversionActionResult result : response.getResultsList()) { System.out.printf( "New conversion action added with resource name: '%s'%n", result.getResourceName()); } } }
C#
public void Run(GoogleAdsClient client, long customerId) { // Get the ConversionActionService. ConversionActionServiceClient conversionActionService = client.GetService(Services.V13.ConversionActionService); // Add a conversion action. ConversionAction conversionAction = new ConversionAction() { Name = "Earth to Mars Cruises Conversion #" + ExampleUtilities.GetRandomString(), Category = ConversionActionCategory.Default, Type = ConversionActionType.Webpage, Status = ConversionActionStatus.Enabled, ViewThroughLookbackWindowDays = 15, ValueSettings = new ConversionAction.Types.ValueSettings() { DefaultValue = 23.41, AlwaysUseDefaultValue = true } }; // Create the operation. ConversionActionOperation operation = new ConversionActionOperation() { Create = conversionAction }; try { // Create the conversion action. MutateConversionActionsResponse response = conversionActionService.MutateConversionActions(customerId.ToString(), new ConversionActionOperation[] { operation }); // Display the results. foreach (MutateConversionActionResult newConversionAction in response.Results) { Console.WriteLine($"New conversion action with resource name = " + $"'{newConversionAction.ResourceName}' was added."); } } 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 conversion action. $conversionAction = new ConversionAction([ 'name' => 'Earth to Mars Cruises Conversion #' . Helper::getPrintableDatetime(), 'category' => ConversionActionCategory::PBDEFAULT, 'type' => ConversionActionType::WEBPAGE, 'status' => ConversionActionStatus::ENABLED, 'view_through_lookback_window_days' => 15, 'value_settings' => new ValueSettings([ 'default_value' => 23.41, 'always_use_default_value' => true ]) ]); // Creates a conversion action operation. $conversionActionOperation = new ConversionActionOperation(); $conversionActionOperation->setCreate($conversionAction); // Issues a mutate request to add the conversion action. $conversionActionServiceClient = $googleAdsClient->getConversionActionServiceClient(); $response = $conversionActionServiceClient->mutateConversionActions( $customerId, [$conversionActionOperation] ); printf("Added %d conversion actions:%s", $response->getResults()->count(), PHP_EOL); foreach ($response->getResults() as $addedConversionAction) { /** @var ConversionAction $addedConversionAction */ printf( "New conversion action added with resource name: '%s'%s", $addedConversionAction->getResourceName(), PHP_EOL ); } }
Python
def main(client, customer_id): conversion_action_service = client.get_service("ConversionActionService") # Create the operation. conversion_action_operation = client.get_type("ConversionActionOperation") # Create conversion action. conversion_action = conversion_action_operation.create conversion_action.name = f"Earth to Mars Cruises Conversion {uuid.uuid4()}" conversion_action.type_ = ( client.enums.ConversionActionTypeEnum.UPLOAD_CLICKS ) conversion_action.category = ( client.enums.ConversionActionCategoryEnum.DEFAULT ) conversion_action.status = client.enums.ConversionActionStatusEnum.ENABLED conversion_action.view_through_lookback_window_days = 15 # Create a value settings object. value_settings = conversion_action.value_settings value_settings.default_value = 15.0 value_settings.always_use_default_value = True # Add the conversion action. conversion_action_response = conversion_action_service.mutate_conversion_actions( customer_id=customer_id, operations=[conversion_action_operation], ) print( "Created conversion action " f'"{conversion_action_response.results[0].resource_name}".' )
Ruby
def add_conversion_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 # Add a conversion action. conversion_action = client.resource.conversion_action do |ca| ca.name = "Earth to Mars Cruises Conversion #{(Time.new.to_f * 100).to_i}" ca.type = :UPLOAD_CLICKS ca.category = :DEFAULT ca.status = :ENABLED ca.view_through_lookback_window_days = 15 # Create a value settings object. ca.value_settings = client.resource.value_settings do |vs| vs.default_value = 15 vs.always_use_default_value = true end end # Create the operation. conversion_action_operation = client.operation.create_resource.conversion_action(conversion_action) # Add the ad group ad. response = client.service.conversion_action.mutate_conversion_actions( customer_id: customer_id, operations: [conversion_action_operation], ) puts "New conversion action with resource name = #{response.results.first.resource_name}." end
Perl
sub add_conversion_action { my ($api_client, $customer_id) = @_; # Create a conversion action. my $conversion_action = Google::Ads::GoogleAds::V14::Resources::ConversionAction->new({ name => "Earth to Mars Cruises Conversion #" . uniqid(), category => DEFAULT, type => WEBPAGE, status => ENABLED, viewThroughLookbackWindowDays => 15, valueSettings => Google::Ads::GoogleAds::V14::Resources::ValueSettings->new({ defaultValue => 23.41, alwaysUseDefaultValue => "true" })}); # Create a conversion action operation. my $conversion_action_operation = Google::Ads::GoogleAds::V14::Services::ConversionActionService::ConversionActionOperation ->new({create => $conversion_action}); # Add the conversion action. my $conversion_actions_response = $api_client->ConversionActionService()->mutate({ customerId => $customer_id, operations => [$conversion_action_operation]}); printf "New conversion action added with resource name: '%s'.\n", $conversion_actions_response->{results}[0]{resourceName}; return 1; }
Validations
Google Ads and the Google Ads API support a wide variety of conversion actions, so some
validation rules vary based on the type
of
action. Below is a list of some rules to be mindful of when creating a
ConversionAction
.
- All enum fields
- Attempting to set any enum field to
UNKNOWN
results in aRequestError.INVALID_ENUM_VALUE
error. app_id
- The
app_id
attribute is immutable and can only be set when creating a new app conversion. click_through_lookback_window_days
Setting this attribute to a value outside of the allowed range results in a
RangeError.TOO_LOW
orRangeError.TOO_HIGH
error.This attribute must be in the range
[1,60]
for anAD_CALL
orWEBSITE_CALL
conversion action. For most other conversion actions, the allowed range is[1,30]
.include_in_conversions_metric
Setting this value in a
create
orupdate
operation will fail after August 22, 2022 with aFieldError.IMMUTABLE_FIELD
error. Instead, setprimary_for_goal
as described in the Conversion goals guide.phone_call_duration_seconds
Attempting to set this attribute on a conversion action that is not for calls results in a
FieldError.VALUE_MUST_BE_UNSET
error.type
The
type
attribute is immutable and can only be set when creating a new conversion.Updating a conversion action with
type
equal toUNKNOWN
results in aMutateError.MUTATE_NOT_ALLOWED
error.value_settings
The
value_settings
for aWEBSITE_CALL
orAD_CALL
conversion action must havealways_use_default_value
set totrue
. Specifying a value offalse
when creating or updating this value results in anINVALID_VALUE
error.view_through_lookback_window_days
Setting this attribute to a value outside of the allowed range results in a
RangeError.TOO_LOW
orRangeError.TOO_HIGH
error. For most conversion actions, the allowed range is[1,30]
.This attribute cannot be set on
AD_CALL
orWEBSITE_CALL
conversion actions. Specifying a value results in aVALUE_MUST_BE_UNSET
error.