Configuration

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

Configure the library at runtime

The preferred way to configure the client library is to initialize a GoogleAdsConfig object at runtime:

GoogleAdsConfig config = new GoogleAdsConfig()
{
    DeveloperToken = "******",
    OAuth2Mode = OAuth2Flow.APPLICATION,
    OAuth2ClientId = "******.apps.googleusercontent.com",
    OAuth2ClientSecret = "******",
    OAuth2RefreshToken = "******"
};

GoogleAdsClient client = new GoogleAdsClient(config);

Alternate configuration options

We also provide some additional options to configure the client library: to enable them, add a Nuget reference to the Google.Ads.GoogleAds.Extensions package in your project.

If you use one of these options, configuration settings are not picked up automatically: you should explicitly load them as shown below.

Configure using App.config

All the settings specific to Google Ads API are stored in the GoogleAdsApi node of the App.config file. A typical configuration App.config is as follows:

<?xml version="1.0" encoding="utf-8"?>
<configuration>
  <configSections>
    <section name="GoogleAdsApi" type="System.Configuration.DictionarySectionHandler" />
  </configSections>
  <GoogleAdsApi>
    <!-- Set the service timeout in milliseconds. -->
    <add key="Timeout" value="2000" />

    <!-- Proxy settings for library. -->
    <add key="ProxyServer" value="http://localhost:8888"/>
    <add key="ProxyUser" value=""/>
    <add key="ProxyPassword" value=""/>
    <add key="ProxyDomain" value=""/>

    <!-- API-specific settings -->
    <add key="DeveloperToken" value="******"/>

    <!-- OAuth2 settings -->
    <add key = "OAuth2Mode" value="APPLICATION"/>
    <add key = "OAuth2ClientId" value = "******.apps.googleusercontent.com" />
    <add key = "OAuth2ClientSecret" value = "******" />
    <add key = "OAuth2RefreshToken" value = "******" />
  </GoogleAdsApi>
  <startup>
    <supportedRuntime version="v4.0" sku=".NETFramework,Version=v4.5.2" />
  </startup>
</configuration>

To load configuration settings from an App.config file, call the LoadFromDefaultAppConfigSection method on a GoogleAdsConfig object:

GoogleAdsConfig config = new GoogleAdsConfig();
config.LoadFromDefaultAppConfigSection();
GoogleAdsClient client = new GoogleAdsClient(config);

Specify a separate App.config file

If you don't want to get your App.config cluttered, you could move the library-specific configuration into its own configuration file using the configSource property.

Step 1: Specify a configSource in your App.config

Modify your App.config to look like this:

<?xml version="1.0" encoding="utf-8" ?>
<configuration>
  <configSections>
    <section name="GoogleAdsApi" type="System.Configuration.DictionarySectionHandler"/>
  </configSections>
  <GoogleAdsApi configSource="GoogleAdsApi.config"/>
...
</configuration>

Step 2: Specify the contents of your config file

Now create another config file with the name you specified on configSource, and move the configuration node from your App.config into this file:

<?xml version="1.0" encoding="utf-8" ?>
<GoogleAdsApi>
  ... More settings.
</GoogleAdsApi>

Step 3: Fix the build rules in your csproj

Finally, include new configuration file in your project. Change the properties of this file to Always copy to output folder.

Now build and run your project. Your application will start picking up values from the new configuration file.

Configuration using a custom JSON file

You can use an IConfigurationRoot instance to configure the client library.

Create a JSON file

Create a JSON file named GoogleAdsApi.json that has a similar structure as the App.config file.

{
    "Timeout": "2000",

    "ProxyServer": "http://localhost:8888",
    "ProxyUser": "",
    "ProxyPassword": "",
    "ProxyDomain": "",

    "DeveloperToken": "******",

    "OAuth2Mode": "APPLICATION",
    "OAuth2ClientId": "******.apps.googleusercontent.com",
    "OAuth2ClientSecret": "******",
    "OAuth2RefreshToken": "******",
}

Load the configuration

Next, load the JSON file into an IConfigurationRoot.

ConfigurationBuilder builder = new ConfigurationBuilder()
    .SetBasePath(Directory.GetCurrentDirectory())
    .AddJsonFile("GoogleAdsApi.json");
IConfigurationRoot configRoot = builder.Build();

GoogleAdsConfig config = new GoogleAdsConfig();
config.LoadFromConfigurationRoot(configRoot);
GoogleAdsClient client = new GoogleAdsClient(config);

Configuration using settings.json

The process here is similar to using a custom JSON, except that the keys should be in a section named GoogleAdsApi:

{
    "GoogleAdsApi":
    {
        "DeveloperToken": "******",
        "OAuth2Mode": "APPLICATION",
        "OAuth2ClientId": "******.apps.googleusercontent.com",
        "OAuth2ClientSecret": "******",
        "OAuth2RefreshToken": "******",
        ...
    }
    // More settings...
}

Next, you can use the IConfiguration instance in your page:

IConfigurationSection section = Configuration.GetSection("GoogleAdsApi");
GoogleAdsConfig config = new GoogleAdsConfig();
config.LoadFromConfigurationSection(section);
GoogleAdsClient client = new GoogleAdsClient(config);

Configuration using environment variables

You can also initialize the GoogleAdsClient using environment variables:

GoogleAdsConfig config = new GoogleAdsConfig();
config.LoadFromEnvironmentVariables();
GoogleAdsClient client = new GoogleAdsClient(config);

See the full list of supported environment variables.

Configuration fields

The following are the list of settings supported by the Google Ads .NET library.

Connectivity settings

  • Timeout: Use this key to set the service timeout in milliseconds. The default value is set based on the method_config/timeout setting in googleads_grpc_service_config.json. Set a lower value if you need to enforce a shorter limit on the maximum time for an API call. You can set the timeout to 2 hours or more, but the API may still time out extremely long-running requests and return a DEADLINE_EXCEEDED error.
  • ProxyServer: Set this to the HTTP proxy server URL if you are using a proxy to connect to the internet.
  • ProxyUser: Set this to the username you require to authenticate against the proxy server. Leave this empty if a username is not required.
  • ProxyPassword: Set this to the password of ProxyUser if you set a value for ProxyUser.
  • ProxyDomain: Set this to the domain for ProxyUser if your proxy server requires one to be set.
  • MaxReceiveMessageLengthInBytes: Use this setting to increase the maximum size of the API response that the client library can handle. The default value is 64 MB.
  • MaxMetadataSizeInBytes: Use this setting to increase the maximum size of the API error response that the client library can handle. The default value is 16 MB.

Adjust the MaxReceiveMessageLengthInBytes and MaxMetadataSizeInBytes settings to fix certain ResourceExhausted errors. These settings address errors of the form Status(StatusCode="ResourceExhausted",Detail="Received message larger than max (423184132 versus 67108864)".

In this example, the error is due to the message size (423184132 bytes) being larger than what the library can handle (67108864 bytes). Increase MaxReceiveMessageLengthInBytes to 500000000 to avoid this error.

Note that the error also indicates that your code handled a significantly large Response object (such as a large SearchGoogleAdsResponse). This could have performance implications for your code due to .NET's Large Object Heap. If this becomes a performance concern, then you might have to explore how to reorganize your API calls or redesign parts of your app.

OAuth2 settings

When using OAuth2 to authorize your calls against the Google Ads API servers, you should set the following configuration keys:

  • AuthorizationMethod: Set to OAuth2.
  • OAuth2Mode: Set to APPLICATION or SERVICE_ACCOUNT.
  • OAuth2ClientId: Set this value to your OAuth2 client ID.
  • OAuth2ClientSecret: Set this value to your OAuth2 client secret.
  • OAuth2Scope: Set this value to different scopes if you want to authorize OAuth2 tokens for multiple APIs. This setting is optional.

If you're using OAuth2Mode == APPLICATION, then you need to set the following additional configuration keys.

  • OAuth2RefreshToken: Set this value to a pre-generated OAuth2 refresh token if you want to reuse OAuth2 tokens. This setting is optional.
  • OAuth2RedirectUri: Set this value to the OAuth2 redirect URL. This setting is optional.

See the following guides for more details:

If you are using OAuth2Mode == SERVICE_ACCOUNT, then you need to set the following additional configuration keys.

  • OAuth2PrnEmail: Set this value to the email address of the account you are impersonating.
  • OAuth2SecretsJsonPath: Set this value to the OAuth2 JSON configuration file path.

See the OAuth service account flow guide for more details.

Transportation settings

Google Ads API settings

The following settings are specific to the Google Ads API.

  • DeveloperToken: Set this to your developer token.
  • LoginCustomerId: This is the customer ID of the authorized customer to use in the request, without hyphens (-).
  • LinkedCustomerId: This header is only required for methods that update the resources of an entity when permissioned through Linked Accounts in the Google Ads UI (AccountLink resource in the Google Ads API). Set this value to the customer ID of the data provider that updates the resources of the specified customer ID. It should be set without hyphens (-). Learn more about Linked Accounts.