Miss any of our Open RFC calls?Watch the recordings here! »

gads

201808.0.0 • Public • Published

Google Ads API JS Client Library

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

Guides & samples

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

  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

  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:

Useful References

Install

npm i gads

DownloadsWeekly Downloads

33

Version

201808.0.0

License

MIT

Unpacked Size

1.01 MB

Total Files

4364

Last publish

Collaborators

  • avatar