@guardian/google-admanager-api v2.3.0

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

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,
};