google-ads-api Node.js Client Library

Hooks allow you to execute logic before, after, or on error for various operations.

Pre-request hooks (executed before)

• onQueryStart: For query and report.
• onStreamStart: For reportStream and reportStreamRaw.
• onMutationStart: For mutations.
• onServiceStart: For services.

Capabilities:

• cancel(alternativeValue): Cancels the action. The alternativeValue becomes the return value of the operation.
• editOptions(options): Modifies request options (e.g., setting validate_only: true).

Error hooks (executed on error)

• onQueryError: For query and report.
• onStreamError: For reportStream (not reportStreamRaw).
• onMutationError: For mutations.
• onServiceError: For services.

Post-request hooks (executed after)

• onQueryEnd: For query and report.
• onMutationEnd: For mutations.
• onServiceEnd: For services.

Note: There is no onStreamEnd hook to avoid blocking the thread or accumulating stream results.

import { OnQueryStart, OnQueryError, OnQueryEnd } from "google-ads-api";

// Example: Pre-request hook
const onQueryStart: OnQueryStart = async ({ cancel, editOptions }) => {
  if (env.mode === "test") {
    cancel([]); // Cancels and returns [] as the result
  }
  if (env.mode === "dev") {
    editOptions({ validate_only: true });
  }
};

// Example: Error hook
const onQueryError: OnQueryError = async ({ error }) => {
  console.log(error.message);
};

// Example: Post-request hook
const onQueryEnd: OnQueryEnd = async ({ response, resolve }) => {
  const [first] = response;
  resolve([first]);
};

const customer = client.Customer(
  { clientOptions, customerOptions },
  { onQueryStart, onQueryError, onQueryEnd }
);

When using the report method, you can request a summary row by setting return_summary_row: true in search_settings. The summary row will be returned as the first element in the results array.

When using the reportStream method, the summary row will be the final iterated row in the stream.

// Using report method (summary is first)
const [summaryRow, ...response] = await customer.report({
  entity: "campaign",
  metrics: ["metrics.clicks", "metrics.all_conversions"],
  search_settings: {
    return_summary_row: true,
  },
});

// Using reportStream method (summary is last)
const stream = customer.reportStream({
  entity: "campaign",
  metrics: ["metrics.clicks", "metrics.all_conversions"],
  search_settings: {
    return_summary_row: true,
  },
});

const accumulator = [];
for await (const row of stream) {
  accumulator.push(row);
}
const summaryRow = accumulator.slice(-1)[0];

Constraints allow you to filter report results. You can provide constraints in several formats:

1. Simple String: A raw GAQL-style constraint string.
2. ConstraintType1 (Key-Op-Value): An object specifying a key, an operator, and a value.
3. ConstraintType2 (Key-Value mapping): An object mapping keys directly to values (implies equality).
4. Array of Constraints: An array containing any of the above.

Supported Operators (ConstraintOperation): = , !=, >, >=, <, <=, IN, NOT IN, LIKE, NOT LIKE, CONTAINS ANY, CONTAINS ALL, CONTAINS NONE, IS NULL, IS NOT NULL, DURING, BETWEEN, REGEXP_MATCH, NOT REGEXP_MATCH.

ConstraintKey: Can be any fields.Attribute, fields.Metric, or fields.Segment.

// Example of ConstraintType1
const constraints: Constraints = [
  {
    key: fields.Attribute.CampaignStatus,
    op: '=',
    val: 'ENABLED'
  },
  {
    key: fields.Metric.Clicks,
    op: '>',
    val: 10
  }
];

// Example of ConstraintType2
const simpleConstraints: Constraints = {
  [fields.Attribute.CampaignName]: 'Summer_Sale'
};

The Hooks interface allows you to intercept and modify the lifecycle of queries, streams, mutations, and service calls. You can use these hooks to log activity, modify request options, cancel operations, or provide alternative responses.

Available Hook Categories

1. Query Hooks (query and report methods)

Used for standard GAQL queries.

• onQueryStart: Called before execution. Provides cancel and editOptions.
• onQueryError: Called when a query throws an error.
• onQueryEnd: Called after successful execution. Provides response and resolve.

2. Stream Hooks (reportStream and reportStreamRaw methods)

Used for streaming report data.

• onStreamStart: Called before the stream begins. Provides cancel and editOptions.
• onStreamError: Called when the stream throws an error (Note: This is not called for errors in reportStreamRaw).

3. Mutation Hooks (mutateResources or service-specific mutations)

Used for operations that change data.

• onMutationStart: Called before execution. Provides cancel and editOptions.
• onMutationError: Called when a mutation fails.
• onMutationEnd: Called after successful execution. Provides response and resolve.

4. Service Hooks (Direct service calls like customer.campaigns.create)

Used for individual service method calls.

• onServiceStart: Called before the service method executes. Provides cancel and editOptions.
• onServiceError: Called when a service method fails.
• onServiceEnd: Called after successful execution. Provides response and resolve.

Common Hook Utilities

When using Start hooks, you are provided with two critical utility functions:

• cancel(args?): Cancels the operation. If you pass an argument to cancel, the original method call will return that argument instead of the actual API response.
• editOptions(options): A function to modify the request or mutation options (e.g., RequestOptions or MutateOptions) before the request is sent.

The ResourceNames module provides type-safe builders for constructing Google Ads resource name strings. These strings are required for identifying specific entities (like campaigns, ad groups, or customers) in API requests. Each builder function accepts string | number arguments and returns a template literal type that ensures the resulting string follows the exact format required by the Google Ads API.

Common patterns include:

• Simple resources: customer(id), campaign(customerId, campaignId)
• Hierarchical resources: campaignAsset(customerId, campaignId, assetId, fieldType)
• Complex/View resources: campaignSimulation(customerId, campaignId, type, modificationMethod, startDate, endDate)

// Example: Creating a Campaign resource name
const campaignName = ResourceNames.campaign(1234567890, 987654321);
// Result: "customers/1234567890/campaigns/987654321"

// Example: Creating a CampaignAsset resource name
const assetName = ResourceNames.campaignAsset(1234567890, 987654321, 11223344, 55667788);
// Result: "customers/1234567890/campaignAssets/987654321~11223344~55667788"

To create an expanded text ad, define a resources.Ad object with the expanded_text_ad details and the appropriate type. Then, create a resources.AdGroupAd to link the ad to an ad group and use customer.adGroupAds.create() to perform the mutation.

import { resources, enums, ResourceNames } from "google-ads-api";

const ad = new resources.Ad({
  expanded_text_ad: {
    headline_part1: "Cruise to Mars",
    headline_part2: "Best Space Cruise Line",
    description: "Buy your tickets now!",
    path1: "cruises",
    path2: "mars",
  },
  final_urls: ["https://example.com"],
  type: enums.AdType.EXPANDED_TEXT_AD,
});

const adGroup = ResourceNames.adGroup(cus.credentials.customerId, "123");

const adGroupAd = new resources.AdGroupAd({
  status: enums.AdGroupAdStatus.PAUSED,
  ad_group,
  ad,
});

// Returns an array of newly created resource names if successful
const { results } = await cus.adGroupAds.create([adGroupAd]);