Subversion Repositories SmartDukaan

AdWords API Java Client Library
===============================

The client library is distributed in two Maven artifacts. They are:

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

The "ads-lib" artifact contains all of the library and utility classes for
accessing the AdWords 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.adwords.lib". To add support for the Apache Axis framework,
the "adwords-axis" plugin artifact is also necessary. This artifact also
includes autogenerated classes from the AdWords API. They are in the package
"com.google.api.ads.adwords.axis.{version}".


Quick Start Guide
-----------------

Before you begin, make sure retrieve your client ID and secret from
https://code.google.com/apis/console#access

Examples can be compiled and run by Maven by executing the following on the
command line:

    $ cd path/to/extracted/distribution
    $ cd src/main/resources

    Modify file with settings. This can be moved (not copied) to your home
    directory as well.

    $ vim ads.properties

    Generate OAuth2 credentials to be used with other examples

    $ cd ../../../
    $ mvn -X compile
    $ mvn -X exec:java -Dexec.mainClass="adwords.axis.auth.GetRefreshToken

    Copy the refresh token into your ads.properties file as you just did
    with your general settings and client ID/secret.

    $ vim src/main/resources/ads.properties

    You must have Maven recompile every time you modify the source code or resources
    in order for your changes to take effect.

    $ mvn -X compile
    $ mvn -X exec:java -Dexec.mainClass="adwords.axis.v201302.basicoperations.GetCampaigns"


What's in the client library?
-----------------------------

The client library provides full access to all the functionality of the AdWords
API web services plus more. It includes:

  - Generated code: Classes and service clients generated automatically from
    the WSDLs.

  - AdWordsSession class: The AdWordsSession class represents one session of
    AdWords API use. It is used to request the services the API offers. It will
    keep track of state information, such as authentication information
    generated from the API.

  - AdWordsServices class: This factory class is responsible for creating API
    service clients. It requires an AdWordsSession and the service interface
    from the autogenerated code.

  - ads.properties file: This file in the src/main/resources directory is a
    sample that shows you how to specify your credentials for the client library
    to read in. To use the credentials in an ads.properties file, make an
    AdWordsSession using the following code:

    new AdWordsSession.Builder().fromFile().build();

    The library will search for an ads.properties file in the following places
    in order: in the user's home directory, in the current directory, and
    finally in the classpath. Files in the src/main/resources directory show up
    on classpath. Every time you modify a file in src/main/resources, you must
    have Maven recompile the project to pick up the changes. If you copy it
    to your home directory, you will not need to recompile every time.

  - Examples: This distribution contains examples in the "src/main/java"
    directory. We encourage you to use code samples to get started writing your
    own application. All the code samples are runnable out of the box, but you
    will have to set your credentials in "resources/ads.properties". You may
    also have to substitute in actual values places that are marked with the
    string "INSERT_{SOMETHING}_HERE".


Basic usage
-----------

To write a program that accesses AdWords accounts with the client library, do
the following:

  1) Import the following packages or classes:

     // Contains the data classes and service classes.
     import com.google.api.ads.adwords.axis.v201306.*;

     import com.google.api.ads.adwords.lib.client.AdWordsSession;
     import com.google.api.ads.adwords.lib.axis.factory.AdWordsServices;

  2a) Create an AdWordsSession instance, loading credentials from the properties
      file:

      // Get an OAuth2 credential.
      Credential credential = new OfflineCredentials.Builder()
          .forApi(OfflineCredentials.Api.AdWords)
          .fromFile()
          .build()
          .generateCredential();

      // Construct an AdWordsSession.
      AdWordsSession session = new AdWordsSession.Builder()
          .fromFile()
          .withOAuth2Credential(credential)
          .build();

  2b) Alternatively, you can specify your credentials in the constructor:

      // Get an OAuth2 credential.
      Credential credential = new OfflineCredentials.Builder()
          .forApi(OfflineCredentials.Api.AdWords)
          .withClientSecrets(clientId, clientSecret)
          .withRefreshToken(refreshToken)
          .build()
          .generateCredential();

      // Construct an AdWordsSession.
      AdWordsSession session = new AdWordsSession.Builder()
          .withDeveloperToken(developerToken)
          // ...
          .withOAuth2Credential(credential)
          .build();

  3) Instantiate the desired service class using the AdWordsServices utility and
     a Class object representing your service.

     // Get the CampaignService.
     CampaignServiceInterface campaignService =
         new AdWordsServices().get(session, CampaignServiceInterface.class);

  4) Create data objects and invoke methods on the service class instance. The
     data objects and methods map directly to the data objects and requests for
     the corresponding web service.

      // Create selector.
      Selector selector = new Selector();
      selector.setFields(new String[] {"Id", "Name"});

      // Get all campaigns.
      CampaignPage page = campaignService.get(selector);

You'll need to pull in the library as dependencies. This example project
contains a full pom.xml that will pull in all of the necessary artifacts. There
is no need to worry about accessing the WSDLs for the web services; the classes
in the client library do it for you. Examples in the "src/main/java" directory
can be used to get started writing your own client.


OAuth2 authentication
---------------------

There are two ways to authenticate with OAuth2 in the library:

  - Use the OfflineCredentials utility to generate a simple refreshable
    Credential for small applications. You will find that all of our examples
    use this utility.

  - Create a Credential object from scratch using a GoogleAuthorizationCodeFlow
    and a CredentialStore. You may want to go this route if you are creating
    a complicated application. See the AdvancedCreateCredentialFromScratch
    example for more information.


How do I use OfflineCredentials?
--------------------------------

OfflineCredentials can use your ads.properties file to create a refreshable
Credential. It will not create a refresh token for you, or walk the user
through an authorization flow. To get a refresh token, run the GetRefreshToken
example as shown in the Quick Start Guide section.


Service accounts
----------------

You may be tempted to use a service account to access the API. However, to use
a service account, you must be a Google Apps for Business customer, with the
ability to impersonate users of your network.

If you are a Google Apps for Business customer, then you can use the
AdvancedCreateCredentialFromScratch example as a starting point for constructing
a service account Credential. See
https://code.google.com/p/google-api-java-client/wiki/OAuth2#Service_Accounts
on how to do this.

If you are unable to use service accounts, but still want to only perform the
OAuth2 flow once, consider creating an offline credential using the
OfflineCredentials utility.


How do I enable logging?
------------------------

The client library uses SLF4J for all logging. If you want to turn logging on,
you must include a plugin that bridges SLF4J with a concrete logging framework.
To quickly get you started and to serve as an example of how to do this, this
example distribution uses the log4j framework.

There are the following loggers within the library:

  - com.google.api.ads.adwords.lib.client.AdWordsServiceClient.soapXmlLogger

    Logs incoming and outgoing SOAP requests/responses. SOAP requests and
    responses are logged as WARN for exceptions and INFO for all other requests.
    You can configure your logging framework to accept logs on these parameters.
    See the example resources/log4j.properties for more information.

  - com.google.api.ads.adwords.lib.client.AdWordsServiceClient.requestInfoLogger

    Logs all requests from the client library along with information such as the
    timestamp, service, method, endpoint URL.

To bridge SLF4J for a logging framework, you must do the following:

  1) Include the plugin and logging framework dependencies in the pom.xml file's
     dependencies list.

     <!-- Adds the log4j framework -->
     <dependency>
       <groupId>log4j</groupId>
       <artifactId>log4j</artifactId>
       <version>1.2.16</version>
     </dependency>
     <!-- Make SLF4J use log4j as the logging framework -->
     <dependency>
       <groupId>org.slf4j</groupId>
       <artifactId>slf4j-log4j12</artifactId>
       <version>1.6.2</version>
     </dependency>

  2) If your logging framework requires a configuration file, you must place it
     in the resources directory. This distribution includes an example
     configuration for log4j named "log4j.properties".

Because the client library uses SLF4J, the behavior of these loggers is highly
customizable. Please see the "resources/log4j.properties" file for details on
the default behavior in this example project.


What if I am behind an HTTP Proxy server?
----------------------------------------

It is recommended that the user set JVM arguments to configure this application
for their 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 within the command line such as:

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

If necessary, set this up in code by doing the following:

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


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

All of these items can be submitted at
http://code.google.com/p/google-api-ads-java/issues/list.

Make sure to subscribe to our Google Plus page for API change announcements and
other news:

  https://plus.google.com/+GoogleAdsDevelopers

Authors:
    Adam Rogal
    Joseph DiLallo

Maintainer:
    Kevin Winter