Configuration

Page Summary

The Ads API Client library offers various configuration settings to customize its behavior.
Configuration can be specified using a googleads.properties file, either in the home directory or at a specified path.
Dynamic configuration is possible during instantiation or after, allowing modification of settings like developer token and login customer ID.
Certain configuration settings can also be loaded from environment variables using the configure_from_environment_variables function.
Key configuration fields include client_id, client_secret, refresh_token, developer_token, login_customer_id, and proxy.

The Google Ads API Perl client library provides several configuration settings that you can use to customize library behavior.

Configuration file

You can specify a googleads.properties file to use when instantiating the client.

If you use no arguments when instantiating:

my $api_client = Google::Ads::GoogleAds::Client->new();

then the library looks in your HOME directory for the file, or at the path specified in the GOOGLE_ADS_CONFIGURATION_FILE_PATH environment variable if it is set.

Alternatively, you can specify a path explicitly:

my $properties_file = "/path/to/googleads.properties";

my $api_client = Google::Ads::GoogleAds::Client->new({
  properties_file => $properties_file,
});

in which case the client looks for the file at that path.

The easiest way to generate this file is to copy googleads.properties from the GitHub repository and modify it to include your client ID, client secret, and refresh token.

Dynamic configuration

You can set up the configuration dynamically when instantiating the library, or after instantiation:

my $api_client = Google::Ads::GoogleAds::Client->new({
  login_customer_id => "INSERT_LOGIN_CUSTOMER_ID_HERE",
});

You can also modify the configuration after instantiation:

$api_client->set_login_customer_id("INSERT_LOGIN_CUSTOMER_ID_HERE");

You can also get an OAuth2ApplicationsHandler object from the Client instance, and change the client ID, client secret, and refresh token at runtime:

my $oauth2_applications_handler =
  $api_client->get_oauth2_applications_handler();
$oauth2_applications_handler->set_client_id("INSERT_CLIENT_ID_HERE");
$oauth2_applications_handler->set_client_secret("INSERT_CLIENT_SECRET_HERE");
$oauth2_applications_handler->set_refresh_token("INSERT_REFRESH_TOKEN_HERE");

Configuration environment variables

You can set some of the configuration settings from environment variables when instantiating clients (see the standard environment variables).

The Client module provides the configure_from_environment_variables function to load values from environment variables.

# Get the Google Ads API Client. By default, any credentials are read from
# ~/googleads.properties, or, if set, from the file specified in the
# GOOGLE_ADS_CONFIGURATION_FILE_PATH environment variable.
my $api_client = Google::Ads::GoogleAds::Client->new();

# Load the configuration from any set environment variables.
$api_client->configure_from_environment_variables();

Configuration fields

Note that googleads.properties keys use camelCase (such as loginCustomerId and linkedCustomerId), whereas Client->new({...}) constructor arguments and handler methods use snake_case (such as login_customer_id and linked_customer_id).

Fields persisted in OAuth2ApplicationsHandler:

client_id (clientId in googleads.properties, GOOGLE_ADS_CLIENT_ID): Your OAuth2 client ID.
client_secret (clientSecret in googleads.properties, GOOGLE_ADS_CLIENT_SECRET): Your OAuth2 client secret.
refresh_token (refreshToken in googleads.properties, GOOGLE_ADS_REFRESH_TOKEN): Your OAuth2 refresh token.
additional_scopes (additionalScopes in googleads.properties): Additional OAuth2 scopes to request.

Fields persisted in OAuth2ServiceAccountsHandler:

json_key_file_path (jsonKeyFilePath in googleads.properties, GOOGLE_ADS_JSON_KEY_FILE_PATH): The path to your service account JSON key file.
impersonated_email (impersonatedEmail in googleads.properties, GOOGLE_ADS_IMPERSONATED_EMAIL): The email address to impersonate when using Google Workspace domain-wide delegation.
additional_scopes (additionalScopes in googleads.properties): Additional OAuth2 scopes to request.

Fields persisted in Client:

developer_token (developerToken in googleads.properties, GOOGLE_ADS_DEVELOPER_TOKEN): (Sunset on September 9, 2026) Your Google Ads API developer token. Optional, ignored by API servers regardless of client library version, and will be rejected in a future major version of the Google Ads API.
- v35.0.0 and later: Not required at client initialization (local client-side developerToken validation was removed in v35.0.0).
- Versions prior to v35.0.0: Required by local client-side configuration validation if you have not upgraded to v35.0.0 or later.
login_customer_id (loginCustomerId in googleads.properties, GOOGLE_ADS_LOGIN_CUSTOMER_ID): The ID of the manager account used to access the client account. See the login-customer-id documentation.
linked_customer_id (linkedCustomerId in googleads.properties, GOOGLE_ADS_LINKED_CUSTOMER_ID): The linked customer ID.
service_address (serviceAddress in googleads.properties, GOOGLE_ADS_ENDPOINT): The Google Ads API service address URL (defaults to "https://googleads.googleapis.com").
user_agent (userAgent in googleads.properties, GOOGLE_ADS_PERL_USER_AGENT): Custom user-agent header prefix included in HTTP requests.
proxy (proxy in googleads.properties, GOOGLE_ADS_PERL_PROXY): The proxy server URL used for internet connectivity.
version (Client->new or set_version): The Google Ads API version module to use (defaults to "V25").
die_on_faults (Client->new or set_die_on_faults): Set to 1 to make service methods call die() with the raw response payload on API errors instead of returning a Google::Ads::GoogleAds::GoogleAdsException object (defaults to 0).
http_timeout (Client->new or set_http_timeout): The HTTP timeout in seconds (defaults to 3600).
http_retry_timing (Client->new or set_http_retry_timing): Retry pause intervals in seconds for transient HTTP 503 and 504 errors (defaults to "5,10,15").