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`](https://github.com/googleads/google-ads-perl/blob/HEAD/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`](https://github.com/googleads/google-ads-perl/blob/HEAD/lib/Google/Ads/GoogleAds/OAuth2ApplicationsHandler.pm) 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");

> [!NOTE]
> **Note:** Storing hardcoded secrets in source code is not recommended. Use environment variables or a secure properties file for production environments.

## Configuration environment variables

You can set some of the configuration settings from environment variables when
instantiating clients (see the [standard environment variables](https://developers.google.com/google-ads/api/docs/client-libs#configuration)).

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

> [!NOTE]
> **Note:** Unset environment variables are *not* taken into account.

    # 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`](https://github.com/googleads/google-ads-perl/blob/HEAD/lib/Google/Ads/GoogleAds/OAuth2ApplicationsHandler.pm):

- `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`](https://github.com/googleads/google-ads-perl/blob/HEAD/lib/Google/Ads/GoogleAds/OAuth2ServiceAccountsHandler.pm):

- `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`](https://github.com/googleads/google-ads-perl/blob/HEAD/lib/Google/Ads/GoogleAds/Client.pm):

- `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](https://developers.google.com/google-ads/api/docs/concepts/call-structure#cid).
- `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 `"V26"`).
- `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"`).