Google Ad Manager SOAP API Client Library for Java

This project hosts the Google Ad Manager SOAP API client library for Java.

Features

• Distributed via Maven.
• Uses the SLF4J logging facade to log requests and SOAP messages, letting you plug in a concrete logging framework of your choice.
• Automatic handling of SOAP headers.
• Easy management of credentials, authentication, and session information.
• JavaDoc

Requirements

• Java 1.8+
• Maven 3.0+ not required, but recommended

Announcements and updates

For API and client library updates and news, please follow our Google Ads Developers blog.

Support forum

If you have questions about the client library or the API, you can ask them on our forum:

• Ad Manager API Forum

Maven artifacts

    <dependency>
      <groupId>com.google.api-ads</groupId>
      <artifactId>ads-lib</artifactId>
      <version>RELEASE</version>
    </dependency>
    <dependency>
      <groupId>com.google.api-ads</groupId>
      <artifactId>dfp-axis</artifactId>
      <version>RELEASE</version>
    </dependency>

Note: The following explanation is for Axis, but the general idea applies to both frameworks.

The ads-lib artifact contains all of the library and utility classes for accessing the Google Ad Manager SOAP API, but does not support any specific SOAP framework. All client library classes and utilities are in the package or sub-packages of com.google.api.ads.common.lib. To add support for the Ad Manager SOAP API using the Apache Axis framework, the dfp-axis plugin artifact is also necessary. This artifact also includes autogenerated classes from the Ad Manager SOAP API. They are in the package com.google.api.ads.admanager.{version}.

Getting started

1. Configure your project. You have multiple options for this step. While we suggest using Maven, we understand that not all build environments can handle this.

   • If using Maven with Eclipse

     In the releases section download a file like admanager-axis-maven-and-examples-v.vv.vv.tar.gz and extract its contents to a directory.

     Import the Eclipse project by going to File > Import, then General > Existing projects into workspace`, and selecting the extracted folder.

   • If using Maven from the command line

     In the releases section download a file like admanager-axis-maven-and-examples-v.vv.vv.tar.gz and extract its contents to a directory.

   • If using jars

     In the releases section download a file like admanager-axis-jars-and-examples-v.vv.vv.tar.gz and extract its contents to a directory.

2. Copy the sample ads.properties file to your home directory and fill out the required properties. You can skip the properties ending with clientId, clientSecret, and refreshToken for now. You'll set those in the next step.

   • Ad Manager ads.properties

3. Setup your OAuth2 credentials.

   The Ad Manager SOAP API uses OAuth2 as the authentication mechanism. Follow the appropriate guide below based on your use case.

   If you're accessing an API using your own credentials...

   • Using Ad Manager

   If you're accessing an API on behalf of clients...

   • Developing a web application

4. Run an example.

   • If using Maven with Eclipse

     Navigate in your project to any example (for example, src/main/java/admanager/axis/#AD_MANAGER_API_VERSION#/networkservice/GetAllNetworks.java) and run the example.

   • If using Maven from the command line

     This command runs the GetAllNetworks example, but you can update the -Dexec.mainClass argument with the example of your choice.

     Any parameters required for an example to run can be passed on the command line by using -Dexec.args. To see more information about a particular example, use -Dexec.args="--help".

     $ mvn -X exec:java -Dexec.mainClass="admanager.axis.#AD_MANAGER_API_VERSION#.networkservice.GetAllNetworks" -Dexec.args="--help"
     

   • If using jars

     Navigate in your project to any example (for example, src/admanager/axis/#AD_MANAGER_API_VERSION#/networkservice/GetAllNetworks.java) and run the example.

How do I enable logging?

The client library uses SLF4J for all logging. Check out our logging guide on github for more details.

How do I enable compression?

First, add an entry to your ads.properties file for each API you plan to use.

# Ad Manager
api.admanager.useCompression=true

If using JaxWs, no further steps are required.

If using Axis, no further steps are required unless you are setting the axis.ClientConfigFile system property. If you are setting axis.ClientConfigFile to your own custom WSDD file and you want to use compression, ensure that the http transport defined in your WSDD supports compression.

Using a proxy

We recommend setting JVM arguments on your app for your proxy.

https.proxyHost      Hostname of proxy server                      web-proxy
https.proxyPort      Port on server of proxy                       8080
https.proxyUser      Optional username for proxy authentication    someone
https.proxyPassword  Optional proxy server password                secret

These properties can be set with JVM arguments in your Eclipse run configuration:

-Dhttps.proxyHost=web-proxy -Dhttps.proxyPort=8080 -Dhttps.proxyUser=someone
-Dhttps.proxyPassword=secret ...

If necessary, set this up in code like so:

System.setProperty("https.proxyHost", "web-proxy");
System.setProperty("https.proxyPort", "8080");
System.setProperty("https.proxyUser", "someone");
System.setProperty("https.proxyPassword", "secret");

Utilities

• Ad Manager
  • Report downloader for downloading reports.

Where do I submit bug reports, feature requests and patches?

All of these items can be submitted at https://github.com/googleads/googleads-java-lib/issues.