Za pomocą interfejsu Google Ads API można przesłać wywołanie offline konwersje na konto Google Ads. aby śledzić, kiedy reklamy prowadzą do połączeń telefonicznych, a kiedy te połączenia. na wartościowe działania klientów.
Nie można przesłać kliknięcia mobilnego typu „kliknij, aby połączyć” jako konwersji, jeśli nie ma Numer Google do przekazywania połączeń powiązany z połączeniem. Bez przekierowania Google nie ma pewności, że kliknięcie doprowadziło do połączenia, do konwersji. Jeśli prześlesz kliknięcie w ten sposób, zostanie ono zignorowane przez działanie powodujące konwersję.
Mapowanie na interfejs Google Ads wygląda tak samo jak w przypadku konwersji Przesłane pliki. Źródło, a potem kliknij Konwersje telefoniczne.
Tworzenie konwersji telefonicznej
Kilka kwestii, o których warto pamiętać podczas tworzenia obiektu CallConversion:
Od wersji 15 interfejsu Google Ads API musisz wypełniać pola
consentparametruCallConversionobiekt.Atrybut
partial_failureelementuUploadCallConversionsRequest. powinna zawsze mieć wartośćtrue. Postępuj zgodnie z częściowymi błędami podczas obsługi prawidłowych operacji zakończonych niepowodzeniem.Jeśli natrafisz na
TOO_RECENT_CONVERSION_ACTIONlubTOO_RECENT_CALLwiadomość z odpowiedzią na prośbę o przesłanie konwersji, odczekaj 6 lub 12 godzin, , zanim spróbujesz ponownie pobrać wiersze z błędami.Statystyki zaimportowanych konwersji pojawią się na Twoim koncie w ciągu maksymalnie 3 godzin koncie Google Ads.
Jeśli prześlesz zduplikowane konwersje (czyli tag
CallConversionzecaller_id,conversion_date_timeiconversion_action, który był poprzednio przesłany), zwracany jest błądCALL_CONVERSION_ALREADY_EXISTS.- Jeśli jedno żądanie zawiera wiele operacji dla tej samej konwersji,
zwracany jest błąd
DUPLICATE_CALL_CONVERSION_IN_REQUEST.
- Jeśli jedno żądanie zawiera wiele operacji dla tej samej konwersji,
zwracany jest błąd
Przesyłanie konwersji telefonicznej
Aby powiązać konwersje telefoniczne offline z działaniem powodującym konwersję,
Potrzebne są następujące informacje: ID rozmówcy (numer telefonu),
data i godzina konwersji, nazwa zasobu działania powodującego konwersję oraz opcjonalnie
wartości konwersji i waluty na
ConversionUploadService
Więcej informacji o różnych danych wejściowych znajdziesz w Centrum pomocy
Centrum pomocy. Kod
opisuje też formaty różnych danych wejściowych.
Wymagania
Przy przesyłaniu pliku
CallConversion
Aby uniknąć błędu ConversionUploadError.INVALID_CONVERSION_ACTION, funkcja
Atrybut conversion_action
musi odnosić się do ConversionAction, gdzie:
ConversionActionTypetoUPLOAD_CALLSstatuszConversionActionjestENABLED. W przeciwnym razie operacja zakończy się niepowodzeniem zNO_CONVERSION_ACTION_FOUND.ConversionActionwystępuje w kliencie konwersji Google Ads konto Google Ads tego kliknięcia.
Zalecamy też ustawienie wartości parametru
ConversionAction.category na
kategoria, która najlepiej opisuje Twoje konwersje.
Dodatkowo muszą być spełnione te warunki:
W czasie połączenia śledzenie konwersji było włączone Klient konwersji Google Ads konta Google Ads połączenia.
customer_idUploadCallConversionsRequest. musi być identyfikatorem klienta konwersji Google Ads klient konto Google Ads połączenia. W przeciwnym razie przesłanie konwersji spowoduje wygenerowanieConversionUploadError.INVALID_CUSTOMER_FOR_CALLbłąd.Wartość
conversion_valuemusi być większa niż lub równa 0.Element
conversion_date_timemusi mieć określoną strefę czasową i format to jakoyyyy-mm-dd HH:mm:ss+|-HH:mm, na przykład:2022-01-01 19:32:45-05:00(ignoruj czas letni) , Strefa czasowa może mieć dowolną prawidłową wartość: nie muszą odpowiadać strefie czasowej konta.
Przykładowy kod
Java
private void runExample(
GoogleAdsClient googleAdsClient,
long customerId,
String conversionActionId,
String callerId,
String callStartDateTime,
double conversionValue,
Long conversionCustomVariableId,
String conversionCustomVariableValue,
ConsentStatus adUserDataConsent) {
// Create a call conversion by specifying currency as USD.
CallConversion.Builder conversionBuilder =
CallConversion.newBuilder()
.setConversionAction(conversionActionId)
.setCallerId(callerId)
.setCallStartDateTime(callStartDateTime)
.setConversionValue(conversionValue)
.setCurrencyCode("USD");
if (conversionCustomVariableId != null && conversionCustomVariableValue != null) {
conversionBuilder.addCustomVariables(
CustomVariable.newBuilder()
.setConversionCustomVariable(
ResourceNames.conversionCustomVariable(customerId, conversionCustomVariableId))
.setValue(conversionCustomVariableValue));
}
// Sets the consent information, if provided.
if (adUserDataConsent != null) {
// Specifies whether user consent was obtained for the data you are uploading. See
// https://www.google.com/about/company/user-consent-policy for details.
conversionBuilder.setConsent(Consent.newBuilder().setAdUserData(adUserDataConsent));
}
CallConversion conversion = conversionBuilder.build();
// Uploads the call conversion to the API.
try (ConversionUploadServiceClient conversionUploadServiceClient =
googleAdsClient.getLatestVersion().createConversionUploadServiceClient()) {
// Partial failure MUST be enabled for this request.
// NOTE: This request contains a single conversion as a demonstration. However, if you have
// multiple conversions to upload, it's best to upload multiple conversions per request
// instead of sending a separate request per conversion. See the following for per-request
// limits:
// https://developers.google.com/google-ads/api/docs/best-practices/quotas#conversion_upload_service
UploadCallConversionsResponse response =
conversionUploadServiceClient.uploadCallConversions(
UploadCallConversionsRequest.newBuilder()
.setCustomerId(String.valueOf(customerId))
.setCustomerId(Long.toString(customerId))
.addConversions(conversion)
.setPartialFailure(true)
.build());
// Prints any partial failure errors returned.
if (response.hasPartialFailureError()) {
GoogleAdsFailure googleAdsFailure =
ErrorUtils.getInstance().getGoogleAdsFailure(response.getPartialFailureError());
googleAdsFailure
.getErrorsList()
.forEach(e -> System.out.println("Partial failure occurred: " + e.getMessage()));
throw new RuntimeException(
"Partial failure occurred " + response.getPartialFailureError().getMessage());
}
// Prints the result if valid.
CallConversionResult result = response.getResults(0);
System.out.printf(
"Uploaded call conversion that occurred at '%' for caller ID '%' to the conversion"
+ " action with resource name '%'.%n",
result.getCallStartDateTime(), result.getCallerId(), result.getConversionAction());
}
}
C#
public void Run(GoogleAdsClient client, long customerId,
long conversionActionId, string callerId, string callStartTime,
string conversionTime, double conversionValue,
long? conversionCustomVariableId, string conversionCustomVariableValue,
ConsentStatus? adUserDataConsent)
{
// Get the ConversionUploadService.
ConversionUploadServiceClient conversionUploadService =
client.GetService(Services.V17.ConversionUploadService);
// Create a call conversion by specifying currency as USD.
CallConversion callConversion = new CallConversion()
{
ConversionAction = ResourceNames.ConversionAction(customerId, conversionActionId),
CallerId = callerId,
CallStartDateTime = callStartTime,
ConversionDateTime = conversionTime,
ConversionValue = conversionValue,
CurrencyCode = "USD",
};
if (adUserDataConsent != null)
{
// Specifies whether user consent was obtained for the data you are uploading. See
// https://www.google.com/about/company/user-consent-policy
// for details.
callConversion.Consent = new Consent()
{
AdUserData = (ConsentStatus)adUserDataConsent
};
}
if (conversionCustomVariableId != null &&
!string.IsNullOrEmpty(conversionCustomVariableValue))
{
callConversion.CustomVariables.Add(new CustomVariable()
{
ConversionCustomVariable = ResourceNames.ConversionCustomVariable(
customerId, conversionCustomVariableId.Value),
Value = conversionCustomVariableValue
});
}
UploadCallConversionsRequest request = new UploadCallConversionsRequest()
{
CustomerId = customerId.ToString(),
Conversions = { callConversion },
PartialFailure = true
};
try
{
// Issues a request to upload the call conversion. The partialFailure parameter
// is set to true, and validateOnly parameter to false as required by this method
// call.
// NOTE: This request contains a single conversion as a demonstration. However, if
// you have multiple conversions to upload, it's best to upload multiple conversions
// per request instead of sending a separate request per conversion. See the
// following for per-request limits:
// https://developers.google.com/google-ads/api/docs/best-practices/quotas#conversion_upload_service
UploadCallConversionsResponse response =
conversionUploadService.UploadCallConversions(request);
// Since we set partialFailure = true, we can retrieve error messages (if any) from
// the operation response.
if (response.PartialFailureError != null)
{
Console.WriteLine("Call conversion upload failed.");
// Retrieves the errors from the partial failure and prints them.
List<GoogleAdsError> errors =
response.PartialFailure.GetErrorsByOperationIndex(0);
foreach (GoogleAdsError error in errors)
{
Console.WriteLine($"Operation failed with error: {error}.");
}
}
else
{
// Prints the result.
CallConversionResult uploadedCallConversion = response.Results[0];
Console.WriteLine($"Uploaded call conversion that occurred at " +
$"'{uploadedCallConversion.CallStartDateTime}' for caller ID " +
$"'{uploadedCallConversion.CallerId}' to the conversion action with " +
$"resource name '{uploadedCallConversion.ConversionAction}'.");
}
}
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,
int $conversionActionId,
string $callerId,
string $callStartDateTime,
string $conversionDateTime,
float $conversionValue,
?string $conversionCustomVariableId,
?string $conversionCustomVariableValue,
?int $adUserDataConsent
) {
// Creates a call conversion by specifying currency as USD.
$callConversion = new CallConversion([
'conversion_action' =>
ResourceNames::forConversionAction($customerId, $conversionActionId),
'caller_id' => $callerId,
'call_start_date_time' => $callStartDateTime,
'conversion_date_time' => $conversionDateTime,
'conversion_value' => $conversionValue,
'currency_code' => 'USD'
]);
if (!is_null($conversionCustomVariableId) && !is_null($conversionCustomVariableValue)) {
$callConversion->setCustomVariables([new CustomVariable([
'conversion_custom_variable' => ResourceNames::forConversionCustomVariable(
$customerId,
$conversionCustomVariableId
),
'value' => $conversionCustomVariableValue
])]);
}
// Sets the consent information, if provided.
if (!empty($adUserDataConsent)) {
// Specifies whether user consent was obtained for the data you are uploading. See
// https://www.google.com/about/company/user-consent-policy for details.
$callConversion->setConsent(new Consent(['ad_user_data' => $adUserDataConsent]));
}
// Issues a request to upload the call conversion.
$conversionUploadServiceClient = $googleAdsClient->getConversionUploadServiceClient();
// NOTE: This request contains a single conversion as a demonstration. However, if you have
// multiple conversions to upload, it's best to upload multiple conversions per request
// instead of sending a separate request per conversion. See the following for per-request
// limits:
// https://developers.google.com/google-ads/api/docs/best-practices/quotas#conversion_upload_service
$response = $conversionUploadServiceClient->uploadCallConversions(
// Partial failure MUST be enabled for this request.
UploadCallConversionsRequest::build($customerId, [$callConversion], true)
);
// Prints the status message if any partial failure error is returned.
// Note: The details of each partial failure error are not printed here, you can refer to
// the example HandlePartialFailure.php to learn more.
if ($response->hasPartialFailureError()) {
printf(
"Partial failures occurred: '%s'.%s",
$response->getPartialFailureError()->getMessage(),
PHP_EOL
);
} else {
// Prints the result if exists.
/** @var CallConversionResult $uploadedCallConversion */
$uploadedCallConversion = $response->getResults()[0];
printf(
"Uploaded call conversion that occurred at '%s' for caller ID '%s' to the "
. "conversion action with resource name '%s'.%s",
$uploadedCallConversion->getCallStartDateTime(),
$uploadedCallConversion->getCallerId(),
$uploadedCallConversion->getConversionAction(),
PHP_EOL
);
}
}
Python
def main(
client,
customer_id,
conversion_action_id,
caller_id,
call_start_date_time,
conversion_date_time,
conversion_value,
conversion_custom_variable_id,
conversion_custom_variable_value,
ad_user_data_consent,
):
"""Imports offline call conversion values for calls related to your ads.
Args:
client: An initialized GoogleAdsClient instance.
customer_id: The client customer ID string.
conversion_action_id: The ID of the conversion action to upload to.
caller_id: The caller ID from which this call was placed. Caller ID is
expected to be in E.164 format with preceding '+' sign,
e.g. '+18005550100'.
call_start_date_time: The date and time at which the call occurred. The
format is 'yyyy-mm-dd hh:mm:ss+|-hh:mm',
e.g. '2021-01-01 12:32:45-08:00'.
conversion_date_time: The the date and time of the conversion (should be
after the click time). The format is 'yyyy-mm-dd hh:mm:ss+|-hh:mm',
e.g. '2021-01-01 12:32:45-08:00'.
conversion_value: The conversion value in the desired currency.
conversion_custom_variable_id: The ID of the conversion custom
variable to associate with the upload.
conversion_custom_variable_value: The str value of the conversion custom
variable to associate with the upload.
ad_user_data_consent: The consent status for ad user data for all
members in the job.
"""
# Get the ConversionUploadService client.
conversion_upload_service = client.get_service("ConversionUploadService")
# Create a call conversion in USD currency.
call_conversion = client.get_type("CallConversion")
call_conversion.conversion_action = client.get_service(
"ConversionActionService"
).conversion_action_path(customer_id, conversion_action_id)
call_conversion.caller_id = caller_id
call_conversion.call_start_date_time = call_start_date_time
call_conversion.conversion_date_time = conversion_date_time
call_conversion.conversion_value = conversion_value
call_conversion.currency_code = "USD"
if conversion_custom_variable_id and conversion_custom_variable_value:
conversion_custom_variable = client.get_type("CustomVariable")
conversion_custom_variable.conversion_custom_variable = (
conversion_custom_variable_id
)
conversion_custom_variable.value = conversion_custom_variable_value
call_conversion.custom_variables.append(conversion_custom_variable)
# Specifies whether user consent was obtained for the data you are
# uploading. For more details. see:
# https://www.google.com/about/company/user-consent-policy
if ad_user_data_consent:
call_conversion.consent.ad_user_data = client.enums.ConsentStatusEnum[
ad_user_data_consent
]
# Issue a request to upload the call conversion.
# Partial failure MUST be enabled for this request.
request = client.get_type("UploadCallConversionsRequest")
request.customer_id = customer_id
request.conversions = [call_conversion]
request.partial_failure = True
# NOTE: This request only uploads a single conversion, but if you have
# multiple conversions to upload, it's most efficient to upload them in a
# single request. See the following for per-request limits for reference:
# https://developers.google.com/google-ads/api/docs/best-practices/quotas#conversion_upload_service
upload_call_conversions_response = (
conversion_upload_service.upload_call_conversions(request=request)
)
# Print any partial errors returned.
if upload_call_conversions_response.partial_failure_error:
print(
"Partial error occurred: "
f"'{upload_call_conversions_response.partial_failure_error.message}'"
)
# Print the result if valid.
uploaded_call_conversion = upload_call_conversions_response.results[0]
if uploaded_call_conversion.call_start_date_time:
print(
"Uploaded call conversion that occurred at "
f"'{uploaded_call_conversion.call_start_date_time}' "
f"for caller ID '{uploaded_call_conversion.caller_id}' "
"to the conversion action with resource name "
f"'{uploaded_call_conversion.conversion_action}'."
)
Ruby
def upload_call_conversion(
customer_id,
conversion_action_id,
caller_id,
call_start_date_time,
conversion_date_time,
conversion_value,
conversion_custom_variable_id,
conversion_custom_variable_value,
ad_user_data_consent)
# GoogleAdsClient will read a config file from
# ENV['HOME']/google_ads_config.rb when called without parameters
client = Google::Ads::GoogleAds::GoogleAdsClient.new
# Create a call conversion by specifying currency as USD.
call_conversion = client.resource.call_conversion do |c|
c.conversion_action = client.path.conversion_action(
customer_id, conversion_action_id)
c.caller_id = caller_id
c.call_start_date_time = call_start_date_time
c.conversion_date_time = conversion_date_time
c.conversion_value = conversion_value
c.currency_code = "USD"
if conversion_custom_variable_id && conversion_custom_variable_value
c.custom_variables << client.resource.custom_variable do |cv|
cv.conversion_custom_variable = client.path.conversion_custom_variable(
customer_id, conversion_custom_variable_id)
cv.value = conversion_custom_variable_value
end
end
unless ad_user_data_consent.nil?
c.consent = client.resource.consent do |c|
# Specifies whether user consent was obtained for the data you are
# uploading. For more details, see:
# https://www.google.com/about/company/user-consent-policy
c.ad_user_data = ad_user_data_consent
end
end
end
# Issues a request to upload the call conversion.
response = client.service.conversion_upload.upload_call_conversions(
customer_id: customer_id,
# NOTE: This request only uploads a single conversion, but if you have
# multiple conversions to upload, it's most efficient to upload them in a
# single request. See the following for per-request limits for reference:
# https://developers.google.com/google-ads/api/docs/best-practices/quotas#conversion_upload_service
conversions: [call_conversion],
partial_failure: true
)
# Prints errors if any partial failure error is returned.
if response.partial_failure_error
failures = client.decode_partial_failure_error(response.partial_failure_error)
failures.each do |failure|
failure.errors.each do |error|
human_readable_error_path = error
.location
.field_path_elements
.map { |location_info|
if location_info.index
"#{location_info.field_name}[#{location_info.index}]"
else
"#{location_info.field_name}"
end
}.join(" > ")
errmsg = "error occured while adding operations " \
"#{human_readable_error_path}" \
" with value: #{error.trigger.string_value}" \
" because #{error.message.downcase}"
puts errmsg
end
end
else
# Print the result if valid.
uploaded_call_conversion = response.results.first
puts "Uploaded call conversion that occurred at " \
"#{uploaded_call_conversion.call_start_date_time} " \
"for caller ID " \
"#{uploaded_call_conversion.caller_id} " \
"to the conversion action with resource name " \
"#{uploaded_call_conversion.conversion_action}"
end
end
Perl
sub upload_call_conversion {
my (
$api_client, $customer_id,
$conversion_action_id, $caller_id,
$call_start_date_time, $conversion_date_time,
$conversion_value, $conversion_custom_variable_id,
$conversion_custom_variable_value, $ad_user_data_consent
) = @_;
# Create a call conversion by specifying currency as USD.
my $call_conversion =
Google::Ads::GoogleAds::V17::Services::ConversionUploadService::CallConversion
->new({
conversionAction =>
Google::Ads::GoogleAds::V17::Utils::ResourceNames::conversion_action(
$customer_id, $conversion_action_id
),
callerId => $caller_id,
callStartDateTime => $call_start_date_time,
conversionDateTime => $conversion_date_time,
conversionValue => $conversion_value,
currencyCode => "USD"
});
if ($conversion_custom_variable_id && $conversion_custom_variable_value) {
$call_conversion->{customVariables} = [
Google::Ads::GoogleAds::V17::Services::ConversionUploadService::CustomVariable
->new({
conversionCustomVariable =>
Google::Ads::GoogleAds::V17::Utils::ResourceNames::conversion_custom_variable(
$customer_id, $conversion_custom_variable_id
),
value => $conversion_custom_variable_value
})];
}
# Set the consent information, if provided.
if ($ad_user_data_consent) {
# Specify whether user consent was obtained for the data you are uploading.
# See https://www.google.com/about/company/user-consent-policy for details.
$call_conversion->{consent} =
Google::Ads::GoogleAds::V17::Common::Consent->new({
adUserData => $ad_user_data_consent
});
}
# Issue a request to upload the call conversion.
# NOTE: This request contains a single conversion as a demonstration.
# However, if you have multiple conversions to upload, it's best to
# upload multiple conversions per request instead of sending a separate
# request per conversion. See the following for per-request limits:
# https://developers.google.com/google-ads/api/docs/best-practices/quotas#conversion_upload_service
my $upload_call_conversions_response =
$api_client->ConversionUploadService()->upload_call_conversions({
customerId => $customer_id,
conversions => [$call_conversion],
partialFailure => "true"
});
# Print any partial errors returned.
if ($upload_call_conversions_response->{partialFailureError}) {
printf "Partial error encountered: '%s'.\n",
$upload_call_conversions_response->{partialFailureError}{message};
}
# Print the result if valid.
my $uploaded_call_conversion =
$upload_call_conversions_response->{results}[0];
if (%$uploaded_call_conversion) {
printf "Uploaded call conversion that occurred at '%s' " .
"for caller ID '%s' to the conversion action with resource name '%s'.\n",
$uploaded_call_conversion->{callStartDateTime},
$uploaded_call_conversion->{callerId},
$uploaded_call_conversion->{conversionAction};
}
return 1;
}