@pipedream/google_ads 0.7.0 → 1.0.0

package/actions/list-shared-criteria/list-shared-criteria.mjs

@@ -0,0 +1,55 @@
+import googleAds from "../../google_ads.app.mjs";
+
+export default {
+  key: "google_ads-list-shared-criteria",
+  name: "List Shared Criteria",
+  description: "List criteria within shared sets for a customer account. [See the documentation](https://developers.google.com/google-ads/api/reference/rpc/v25/GoogleAdsService/Search?transport=rest)",
+  version: "0.0.2",
+  type: "action",
+  annotations: {
+    destructiveHint: false,
+    openWorldHint: true,
+    readOnlyHint: true,
+  },
+  props: {
+    googleAds,
+    accountId: {
+      propDefinition: [
+        googleAds,
+        "accountId",
+      ],
+    },
+    customerClientId: {
+      propDefinition: [
+        googleAds,
+        "customerClientId",
+        ({ accountId }) => ({
+          accountId,
+        }),
+      ],
+      optional: true,
+    },
+    query: {
+      type: "string",
+      label: "Query",
+      description: "Filter by shared set name (partial match).",
+      optional: true,
+    },
+  },
+  async run({ $ }) {
+    const { results } = await this.googleAds.listAllSharedCriteria({
+      $,
+      accountId: this.accountId,
+      customerClientId: this.customerClientId,
+      query: this.query,
+    });
+    const items = results ?? [];
+    $.export(
+      "$summary",
+      `Successfully retrieved ${items.length} shared ${items.length === 1
+        ? "criterion"
+        : "criteria"}.`,
+    );
+    return items;
+  },
+};

package/actions/list-shared-sets/list-shared-sets.mjs

@@ -0,0 +1,55 @@
+import googleAds from "../../google_ads.app.mjs";
+
+export default {
+  key: "google_ads-list-shared-sets",
+  name: "List Shared Sets",
+  description: "List shared sets for a customer account. [See the documentation](https://developers.google.com/google-ads/api/reference/rpc/v25/GoogleAdsService/Search?transport=rest)",
+  version: "0.0.2",
+  type: "action",
+  annotations: {
+    destructiveHint: false,
+    openWorldHint: true,
+    readOnlyHint: true,
+  },
+  props: {
+    googleAds,
+    accountId: {
+      propDefinition: [
+        googleAds,
+        "accountId",
+      ],
+    },
+    customerClientId: {
+      propDefinition: [
+        googleAds,
+        "customerClientId",
+        ({ accountId }) => ({
+          accountId,
+        }),
+      ],
+      optional: true,
+    },
+    query: {
+      type: "string",
+      label: "Query",
+      description: "Filter by shared set name (partial match).",
+      optional: true,
+    },
+  },
+  async run({ $ }) {
+    const { results } = await this.googleAds.listAllSharedSets({
+      $,
+      accountId: this.accountId,
+      customerClientId: this.customerClientId,
+      query: this.query,
+    });
+    const items = results ?? [];
+    $.export(
+      "$summary",
+      `Successfully retrieved ${items.length} shared set${items.length === 1
+        ? ""
+        : "s"}.`,
+    );
+    return items;
+  },
+};

package/actions/send-offline-conversion/send-offline-conversion.mjs

@@ -7,8 +7,8 @@ export default {
   ...common,
   key: "google_ads-send-offline-conversion",
   name: "Send Offline Conversion",
-  description: "Send an event to Google Ads to track offline conversions. [See the documentation](https://developers.google.com/google-ads/api/reference/rpc/v21/ConversionAction)",
-  version: "0.0.9",
+  description: "Create a Google Ads conversion action. To record conversions against an upload-type action, use **Upload Click Conversion** or **Upload Call Conversion**. [See the documentation](https://developers.google.com/google-ads/api/reference/rpc/v25/ConversionAction)",
+  version: "0.0.11",
   annotations: {
     destructiveHint: false,
     openWorldHint: true,
@@ -25,10 +25,10 @@ export default {
     type: {
       type: "string",
       label: "Type",
-      description: "[The type](https://developers.google.com/google-ads/api/reference/rpc/v21/ConversionActionTypeEnum.ConversionActionType) of the conversion action.",
+      description: "[The type](https://developers.google.com/google-ads/api/reference/rpc/v25/ConversionActionTypeEnum.ConversionActionType) of the conversion action.",
       options: CONVERSION_TYPE_OPTIONS,
     },
-    additionalFields: getAdditionalFields("https://developers.google.com/google-ads/api/reference/rpc/v21/ConversionAction"),
+    additionalFields: getAdditionalFields("https://developers.google.com/google-ads/api/reference/rpc/v25/ConversionAction"),
   },
   async run({ $ }) {
     const {

package/actions/update-campaign-ai-max-settings/update-campaign-ai-max-settings.mjs

@@ -0,0 +1,167 @@
+import { ConfigurationError } from "@pipedream/platform";
+import googleAds from "../../google_ads.app.mjs";
+import { ASSET_AUTOMATION_STATUSES } from "../../common/constants.mjs";
+import { parseObject } from "../../common/utils.mjs";
+import { getAdditionalFields } from "../common/props.mjs";
+
+const docLink =
+  "https://developers.google.com/google-ads/api/docs/campaigns/ai-max-for-search-campaigns/getting-started";
+
+export default {
+  key: "google_ads-update-campaign-ai-max-settings",
+  name: "Update Campaign AI Max Settings",
+  description: `Enables or configures AI Max for Search settings on a campaign. Only supported on Search campaigns. Toggling AI Max while simultaneously editing brand or text customization settings on the same campaign may fail — update them separately. Ad group-level search term matching is controlled via the **Create or Update Ad Group** action. [See the documentation](${docLink})`,
+  version: "0.0.2",
+  type: "action",
+  annotations: {
+    destructiveHint: false,
+    openWorldHint: true,
+    readOnlyHint: false,
+  },
+  props: {
+    googleAds,
+    accountId: {
+      propDefinition: [
+        googleAds,
+        "accountId",
+      ],
+    },
+    customerClientId: {
+      propDefinition: [
+        googleAds,
+        "customerClientId",
+        ({ accountId }) => ({
+          accountId,
+        }),
+      ],
+      optional: true,
+    },
+    campaignId: {
+      propDefinition: [
+        googleAds,
+        "campaignId",
+        ({
+          accountId, customerClientId,
+        }) => ({
+          accountId,
+          customerClientId,
+        }),
+      ],
+    },
+    enableAiMax: {
+      type: "boolean",
+      label: "Enable AI Max",
+      description: "Whether to enable AI Max for Search on this campaign (`aiMaxSetting.enableAiMax`).",
+      optional: true,
+    },
+    bundlingRequired: {
+      type: "boolean",
+      label: "Bundling Required",
+      description: "Whether bundling is required for AI Max asset serving (`aiMaxSetting.bundlingRequired`).",
+      optional: true,
+    },
+    textAssetAutomation: {
+      type: "string",
+      label: "Text Asset Automation",
+      description: "Opt in or out of automatically generated text assets (`TEXT_ASSET_AUTOMATION`).",
+      options: ASSET_AUTOMATION_STATUSES,
+      optional: true,
+    },
+    finalUrlExpansionAutomation: {
+      type: "string",
+      label: "Final URL Expansion Automation",
+      description: "Opt in or out of automatically expanding final URLs (`FINAL_URL_EXPANSION_TEXT_ASSET_AUTOMATION`).",
+      options: ASSET_AUTOMATION_STATUSES,
+      optional: true,
+    },
+    additionalFields: getAdditionalFields(docLink),
+  },
+  async run({ $ }) {
+    const {
+      googleAds,
+      accountId,
+      customerClientId,
+      campaignId,
+      enableAiMax,
+      bundlingRequired,
+      textAssetAutomation,
+      finalUrlExpansionAutomation,
+      additionalFields,
+    } = this;
+
+    const updateMaskFields = [];
+    const aiMaxSetting = {};
+
+    if (enableAiMax !== undefined) {
+      aiMaxSetting.enableAiMax = enableAiMax;
+      updateMaskFields.push("aiMaxSetting.enableAiMax");
+    }
+    if (bundlingRequired !== undefined) {
+      aiMaxSetting.bundlingRequired = bundlingRequired;
+      updateMaskFields.push("aiMaxSetting.bundlingRequired");
+    }
+
+    const assetAutomationSettings = [];
+    if (textAssetAutomation) {
+      assetAutomationSettings.push({
+        assetAutomationType: "TEXT_ASSET_AUTOMATION",
+        assetAutomationStatus: textAssetAutomation,
+      });
+    }
+    if (finalUrlExpansionAutomation) {
+      assetAutomationSettings.push({
+        assetAutomationType: "FINAL_URL_EXPANSION_TEXT_ASSET_AUTOMATION",
+        assetAutomationStatus: finalUrlExpansionAutomation,
+      });
+    }
+    if (assetAutomationSettings.length) {
+      updateMaskFields.push("assetAutomationSettings");
+    }
+
+    const extraFields = parseObject(additionalFields);
+    const extraKeys = Object.keys(extraFields);
+    if (extraKeys.length) {
+      updateMaskFields.push(...extraKeys);
+    }
+
+    if (!updateMaskFields.length) {
+      throw new ConfigurationError(
+        "At least one AI Max setting must be provided.",
+      );
+    }
+
+    const customerId = customerClientId ?? accountId;
+    const resourceName = `customers/${customerId}/campaigns/${campaignId}`;
+
+    const campaignData = {
+      resourceName,
+      ...(Object.keys(aiMaxSetting).length && {
+        aiMaxSetting,
+      }),
+      ...(assetAutomationSettings.length && {
+        assetAutomationSettings,
+      }),
+      ...extraFields,
+    };
+
+    const response = await googleAds.mutateCampaign({
+      $,
+      accountId,
+      customerClientId,
+      data: {
+        operations: [
+          {
+            update: campaignData,
+            updateMask: updateMaskFields.join(","),
+          },
+        ],
+      },
+    });
+
+    $.export(
+      "$summary",
+      `Successfully updated AI Max settings for campaign \`${campaignId}\`.`,
+    );
+    return response;
+  },
+};

package/actions/upload-call-conversion/upload-call-conversion.mjs

@@ -0,0 +1,65 @@
+import {
+  buildBaseConversion, commonProps, DATE_TIME_HINT, DOC_LINK, uploadConversion,
+} from "../common/conversion-upload.mjs";
+
+const CALL_DOC_LINK = `${DOC_LINK}/UploadCallConversions?transport=rest`;
+
+export default {
+  key: "google_ads-upload-call-conversion",
+  name: "Upload Call Conversion",
+  description: `Uploads an offline conversion attributed to a phone call. [See the documentation](${CALL_DOC_LINK})`,
+  version: "0.0.1",
+  type: "action",
+  annotations: {
+    destructiveHint: false,
+    openWorldHint: true,
+    readOnlyHint: false,
+  },
+  props: {
+    ...commonProps,
+    callerId: {
+      type: "string",
+      label: "Caller ID",
+      description: "The phone number the call was placed from, in E.164 format with a leading `+` (e.g. `+16502531234`).",
+    },
+    callStartDateTime: {
+      type: "string",
+      label: "Call Start Date Time",
+      description: `When the call occurred. Must be before the conversion. ${DATE_TIME_HINT}`,
+    },
+  },
+  async run({ $ }) {
+    const {
+      googleAds,
+      accountId,
+      customerClientId,
+      callerId,
+      callStartDateTime,
+      validateOnly,
+    } = this;
+
+    const conversion = {
+      ...buildBaseConversion(this),
+      callerId,
+      callStartDateTime,
+    };
+
+    const response = await uploadConversion({
+      $,
+      googleAds,
+      method: "uploadCallConversions",
+      accountId,
+      customerClientId,
+      conversion,
+      validateOnly,
+    });
+
+    $.export(
+      "$summary",
+      validateOnly
+        ? "Call conversion payload validated successfully (not recorded)."
+        : "Successfully uploaded call conversion.",
+    );
+    return response;
+  },
+};

package/actions/upload-click-conversion/upload-click-conversion.mjs

@@ -0,0 +1,121 @@
+import { ConfigurationError } from "@pipedream/platform";
+import { CONVERSION_ENVIRONMENTS } from "../../common/constants.mjs";
+import {
+  buildBaseConversion, commonProps, DOC_LINK, uploadConversion,
+} from "../common/conversion-upload.mjs";
+
+const CLICK_DOC_LINK = `${DOC_LINK}/UploadClickConversions?transport=rest`;
+
+export default {
+  key: "google_ads-upload-click-conversion",
+  name: "Upload Click Conversion",
+  description: `Uploads an offline conversion attributed to an ad click. [See the documentation](${CLICK_DOC_LINK})`,
+  version: "0.0.1",
+  type: "action",
+  annotations: {
+    destructiveHint: false,
+    openWorldHint: true,
+    readOnlyHint: false,
+  },
+  props: {
+    ...commonProps,
+    gclid: {
+      type: "string",
+      label: "GCLID",
+      description: "The Google click ID from the ad click that led to this conversion. Provide this, **GBRAID**, or **WBRAID**.",
+      optional: true,
+    },
+    gbraid: {
+      type: "string",
+      label: "GBRAID",
+      description: "The click identifier for iOS app-to-web conversions. Provide this, **GCLID**, or **WBRAID**.",
+      optional: true,
+    },
+    wbraid: {
+      type: "string",
+      label: "WBRAID",
+      description: "The click identifier for iOS web-to-web conversions. Provide this, **GCLID**, or **GBRAID**.",
+      optional: true,
+    },
+    orderId: {
+      type: "string",
+      label: "Order ID",
+      description: "Transaction ID for this conversion. An order ID can only be used once per conversion action.",
+      optional: true,
+    },
+    conversionEnvironment: {
+      type: "string",
+      label: "Conversion Environment",
+      description: "Where the conversion was recorded.",
+      options: CONVERSION_ENVIRONMENTS,
+      optional: true,
+    },
+  },
+  async run({ $ }) {
+    const {
+      googleAds,
+      accountId,
+      customerClientId,
+      gclid,
+      gbraid,
+      wbraid,
+      orderId,
+      conversionEnvironment,
+      validateOnly,
+    } = this;
+
+    // Google rejects two identifiers with `GBRAID_WBRAID_BOTH_SET`.
+    const identifiers = [
+      gclid,
+      gbraid,
+      wbraid,
+    ].filter(Boolean);
+    if (!identifiers.length) {
+      throw new ConfigurationError(
+        "One of **GCLID**, **GBRAID**, or **WBRAID** is required to attribute a click conversion.",
+      );
+    }
+    if (identifiers.length > 1) {
+      throw new ConfigurationError(
+        "Set only one of **GCLID**, **GBRAID**, or **WBRAID** - each click has a single identifier.",
+      );
+    }
+
+    const conversion = {
+      ...buildBaseConversion(this),
+      ...(gclid && {
+        gclid,
+      }),
+      ...(gbraid && {
+        gbraid,
+      }),
+      ...(wbraid && {
+        wbraid,
+      }),
+      ...(orderId && {
+        orderId,
+      }),
+      ...(conversionEnvironment && {
+        conversionEnvironment,
+      }),
+    };
+
+    const response = await uploadConversion({
+      $,
+      googleAds,
+      method: "uploadClickConversions",
+      accountId,
+      customerClientId,
+      conversion,
+      validateOnly,
+    });
+
+    $.export(
+      "$summary",
+      validateOnly
+        ? "Click conversion payload validated successfully (not recorded)."
+        : "Successfully uploaded click conversion.",
+    );
+    return response;
+  },
+};

package/common/common-report.mjs

@@ -17,7 +17,7 @@ export function createReportComponent(resource) {
       docsAlert: {
         type: "alert",
         alertType: "info",
-        content: `[See the documentation](https://developers.google.com/google-ads/api/fields/v21/${value}) for more information on available fields, segments and metrics.`,
+        content: `[See the documentation](https://developers.google.com/google-ads/api/fields/v25/${value}) for more information on available fields, segments and metrics.`,
       },
       objectFilter: {
         propDefinition: [
@@ -56,14 +56,14 @@ export function createReportComponent(resource) {
       fields: {
         type: "string[]",
         label: `${label} Fields`,
-        description: `Select the ${label} fields to include in the report`,
+        description: `Array of ${label} field names to include in the report, e.g. \`["status"]\`. The \`${value}.\` prefix is added automatically. [See the field reference](https://developers.google.com/google-ads/api/fields/v25/${value})`,
         options: resource.fields,
         optional: true,
       },
       segments: {
         type: "string[]",
         label: "Segments",
-        description: "Select any segments to include in the report. See the documentation [here](https://developers.google.com/google-ads/api/reference/rpc/v21/Segments)",
+        description: "Array of segment names to break the report down by, e.g. `[\"date\"]`. The `segments.` prefix is added automatically. [See the documentation](https://developers.google.com/google-ads/api/reference/rpc/v25/Segments)",
         options: resource.segments,
         default: [
           "segments.date",
@@ -73,7 +73,7 @@ export function createReportComponent(resource) {
       metrics: {
         type: "string[]",
         label: "Metrics",
-        description: "Select any metrics to include in the report. See the documentation [here](https://developers.google.com/google-ads/api/reference/rpc/v21/Metrics)",
+        description: "Array of metric names to include in the report, e.g. `[\"clicks\"]`. The `metrics.` prefix is added automatically. [See the documentation](https://developers.google.com/google-ads/api/reference/rpc/v25/Metrics)",
         options: resource.metrics,
         optional: true,
       },
@@ -174,9 +174,7 @@ export function createReportComponent(resource) {
         $,
         accountId: this.accountId,
         customerClientId: this.customerClientId,
-        data: {
-          query,
-        },
+        query,
       })) ?? [];
 
       const { length } = results;