Google Ads API JS Client Library

An unofficial JS client library for the SOAP-based DFP Ads API.

Guides & samples

• Server-side
• Client-side

To get started quickly, use one of the step by step guides above for the environment of your choice. Otherwise, below is a general walkthrough of using this library.

Setup

Follow steps 1 - 3 of the Authentication guide to create a Google API Console project, generate your OAuth2 credentials, and configure your DFP network

• Service account: Securely store the downloaded private key in a location accessible to your node project. The project will need it to make authorized API calls.

• Web application: Securely store the client ID and client secret in a location accessible to your node project. You will need them to make authorized API calls.

Use server-side

1. Install Node.js and NPM

   Option A: Install using NVM (see here for installing NVM)

   $ nvm install node

   Option B: Install from nodejs.org

2. Initialize a node project

   $ npm init -y

3. Install this client library as a dependency

   $ npm install -S gads

4. (Optional) Setup Typescript for your node project

   $ npm install -D typescript @types/node
   $ node ./node_modules/typescript/lib/tsc --init --lib es6 --outDir build --strictNullChecks false

5. Include an authentication library of your choice that implements the OAuth2 service account or web app flow. A good option is the Google APIs Node.js Client, made for OAuth2 authorization and authentication with Google APIs.

   $ npm install -S google-auth-library

6. Implement the GoogleOAuth2Client interface using your authentication library. The interface should be implemented to meet your environment, OAuth2 workflow, and application requirements

   • Service account: See GoogleOAuth2ServiceClient
   • Web application: See GoogleOAuth2WebAppClient

7. Initialize your GoogleOAuth2Client with your OAuth2 credentials

   • Service account

     Note: Make sure your credentials are accessible to your project (see here for details)

     const oauth2Client: GoogleOAuth2Client = new GoogleServiceAccountClient();

   • Web application

     // ...
     const oauth2Client: GoogleOauth2Client = new GoogleWebAppRefreshTokenClient(clientId, clientSecret, refreshToken);

8. Initialize a DFP Client

   // ...
   const dfpClient = new dfp.DfpClient(oauth2Client, applicationName, networkCode/*,...*/);

9. Construct a SOAP client to a service and perform an operation. See the DFP API reference docs for available services / operations

   • Using callbacks

   // Create a network service
   dfpClient.getService<dfp.NetworkService>('NetworkService', (err, service) => {
      if (err) {
         // ...
      }
   
      // Request the current network and get the response
      service.getCurrentNetwork({}, (err, res) => {
         if (err) {
            // ...
         }
   
         // Print out some network information
         const network = res.rval;
         console.log(`Current network has network code ${network.networkCode}`);
         console.log(`Current network has display name "${network.displayName}"`);
      });

   • Using promises

   // Create a network service
   dfpClient.getService<dfp.NetworkService>('NetworkService')
   
   // Request the current network and get the response
   .then(service => service.getCurrentNetwork({}))
   
   // Print out some network information
   .then(res => {
      const network = res.rval;
      console.log(`Current network has network code ${network.networkCode}`);
      console.log(`Current network has display name "${network.displayName}"`);
   });

   • Using async / await

    // Create a network service
    const service = await dfpClient.getService<dfp.NetworkService>('NetworkService');
   
    // Request the current network and get the response
    const res = await service.getCurrentNetwork({});
   
    // Print out some network information
    const network = res.rval;
    console.log(`Current network has network code ${network.networkCode}`);
    console.log(`Current network has display name "${network.displayName}"`);

Use client-side

1. Download the minified library (from here) and include it on your site

   <script type="text/javascript" src="./PATH/TO/googleads.dfp.min.js"></script>
   <script type="text/javascript" src="./PATH/TO/googleads.oauth2.min.js"></script>

2. Include an authentication library of your choice that implements the OAuth2 web app flow. A good option is the Google JS Client library, made for OAuth2 authorization and authentication with Google APIs. See here for an example

   <script type="text/javascript" src="https://apis.google.com/js/api.js"></script>

3. Implement the GoogleOAuth2Client interface using your authentication library. The interface should be implemented to meet your environment, OAuth2 workflow, and application requirements

   • Web application: See GoogleOAuth2WebAppClient

4. Setup a proxy server & initialize a DFP Proxy

   Note: Not required for Chrome extensions. See here for more details

   DFP API servers are not currently setup for CORS, so a proxy must be used to forward the HTTPS SOAP requests. You can choose to use a trusted proxy or implement one yourself. See here for a simple example

   const proxy = new dfp.Proxy({
      hostname: proxyHostname, //e.g. localhost
      port: proxyPort, // e.g. 80
      path: proxyPath, // e.g. /foo/bar
      protocol: proxyPortocol // e.g. http or https
   });

5. Initialize your GoogleOAuth2Client with your OAuth2 credentials

   // ...
   const oauth2Client = new GoogleWebAppOauth2Client(gapi);

6. Initialize a DFP Client

   // ...
   const dfpClient = new dfp.DfpClient(oauth2Client, applicationName, networkCode, cache, proxy /*, ...*/);

7. Construct a SOAP client to a service and perform an operation. See the DFP API reference docs for available services / operations

   • Using callbacks

   // Create a network service
   dfpClient.getService('NetworkService', (err, service) => {
      if (err) {
         // ...
      }
   
      // Request the current network and get the response
      service.getCurrentNetwork({}, (err, res) => {
         if (err) {
            // ...
         }
   
         // Print out some network information
         const network = res.rval;
         console.log(`Current network has network code ${network.networkCode}`);
         console.log(`Current network has display name "${network.displayName}"`);
      });

   • Using promises

   // Create a network service
   dfpClient.getService('NetworkService')
   
   // Request the current network and get the response
   .then(service => service.getCurrentNetwork({}))
   
   // Print out some network information
   .then(res => {
      const network = res.rval;
      console.log(`Current network has network code ${network.networkCode}`);
      console.log(`Current network has display name "${network.displayName}"`);
   });

   • Using async / await

    // Create a network service
    const service = await dfpClient.getService('NetworkService')
   
    // Request the current network and get the response
    const res = await service.getCurrentNetwork({});
   
    // Print out some network information
    const network = res.rval;
    console.log(`Current network has network code ${network.networkCode}`);
    console.log(`Current network has display name "${network.displayName}"`);

Getting support

For client library specific bug reports and patches, please create an issue on the issue tracker.

For general DFP API questions, bug reports, or feature requests, please post to the official API forums:

• AdWords API Forum
• DoubleClick for Publishers API Forum

Useful References

• The DFP API Reference Guide for Developers
  • Get Started
  • Authentication
  • Release Notes

• The Google Auth Library for Node.js

• The Google API Client Library for JavaScript