Register for one of our Google Ads API Migration Workshops (October 5, 2021 - October 14, 2021)

Configuration

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

Configuring 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>

Specifying 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.

Configuring using a custom JSON file

You may 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(configRoot);
GoogleAdsClient client = new GoogleAdsClient(config);

Configuring 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(section);
GoogleAdsClient client = new GoogleAdsClient(config);

Configuring the library at runtime

You can also initialize the GoogleAdsClient at runtime.

Example 1: Initialize the configuration at runtime

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

GoogleAdsClient client = new GoogleAdsClient(config);

Example 2: Load from App.config, but override a setting

GoogleAdsClient client = new GoogleAdsClient(config);
client.Config.DeveloperToken = "******";

Configuring the library using environment variables

You can also initialize the GoogleAdsClient using environment variables. These settings are not picked up automatically, you should also load the settings from the environment variables as shown below.

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

See the full list of supported environment variables here.

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 1 hour (3600000 ms). Set a lower value if you need to enforce a shorter limit on the maximum time for an API call.
  • 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.

OAuth2 settings

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

  • AuthorizationMethod: This should be set to OAuth2.
  • OAuth2Mode: This should be 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 are 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.

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 (-). To learn more about Linked Accounts, visit the Help Center.