@guardian/google-admanager-api

Google Ad Manager API Client Library for NodeJs.

Description

Forked from https://github.com/Niurmiguel/google-admanager-api as the original package was not maintained.

Developers can use the Google Ad Manager API to build applications that manage inventory, create orders, pull reports, and more.

Installing the library

$ npm install @guardian/google-admanager-api
$ yarn add @guardian/google-admanager-api
$ pnpm add @guardian/google-admanager-api

Overview

Authentication

All Google Ad Manager API calls must be authorized through OAuth2 an open standard that allows users to grant permissions to third-party applications, so the application can interact with web services on the user's behalf. OAuth2 enables your Ad Manager API client application to access a user's Ad Manager account without having to handle or store the user's username or password.

Generate service account credentials

const credential = new GoogleSACredential({
    type: "service_account",
    project_id: "...",
    private_key_id: "...",
    private_key: "...",
    client_email: "...",
    client_id: "...",
    auth_uri: "...",
    token_uri: "...",
    ...
});

//or

const credential = new GoogleSAFileCredential('./credentials.json');

Generate user account credentials

Using the API on behalf of a real user is slightly more complicated than using a service account. The user must grant your application access to their Ad Manager account. This is done by redirecting the user to Google's OAuth2 consent screen, where they will be asked to grant your application access to their Ad Manager account.

There is an example of how to generate user account credentials in the example folder.

It uses the refresh token generation example to generate the refresh token.

There is also an option to use an access token directly. As access tokens are short-lived, you will need to refresh them yourself.

Use a client library

const adManagerClient = new AdManagerClient('networkCode',credential,'applicationName');

const orderService = await adManagerClient.getService("OrderService");
const statement = new StatementBuilder().limit(10);
const orderPage = await orderService.getOrdersByStatement(statement.toStatement())

/**
 * {
 *  results: [],
 *  totalResultSetSize: 0,
 *  startIndex: 0
 * }
 * /

Options

networkCode	Number	The network code of the network being addressed (required).
credential	SACredential	OAuth2 credential (required).
applicationName	String	An arbitrary string name identifying your application. This will be shown in Google's log files. For example: "My Inventory Application" or "App_1" (optional).
apiVersion	String	Ad Mananger API version, if you want to define a different version than the default version, i.e. v202405 (optional).

Debugging

Enable request and response logging by setting logRequests and/or logResponses to true on the service object.

const orderService = await adManagerClient.getService("OrderService");
orderService.logRequests = true;
orderService.logResponses = true;

Known issues/gotchas

SOAP requires object properties to be in the correct order

The properties of objects sent using this library need to be in the correct order (the same order as the type definitions) or you may encounter an Unmarshalling Error response.

For example for a line item the orderName must be before the startDateTime.

// will not work
lineItemService.createLineitem({
  priority: 12,
  orderId: 123,
  ...
})

// must be
lineItemService.createLineitem({
  orderId: 123,
  priority: 12,
  ...
})

Some objects need additional attributes

In some cases where multiple shapes of objects are accepted, the type need to be specified under a special attributes property.

For example, for custom targeting, the objects need to have their type specified whether they are a CustomCriteriaSet or CustomTargeting like so:

const customTargeting: CustomCriteriaSet = {
  attributes: {
    "xsi:type": "CustomCriteriaSet",
  },
  logicalOperator: LogicalOperator.OR,
  children: [{
    attributes: {
      "xsi:type": "CustomCriteriaSet",
    },
    logicalOperator: LogicalOperator.AND,
    children: [{
      attributes: {
        "xsi:type": "CustomCriteria",
      },
      keyId: 123,
      valueIds: [123],
      operator: ComparisonOperator.IS,
    }],
  }],
};

lineItemService.createLineitem({
  ...
  targeting: {
    customTargeting
  }
  ...
})

This also applies to creatives, as there are many types of creatives:

const creative: Creative = {
  attributes: {
    "xsi:type": "ThirdPartyCreative",
  },
  advertiserId,
  name: creativeName,
  size,
  snippet,
  isSafeFrameCompatible: false,
};