@pipedream/google_ads 0.1.1 → 0.2.0

package/actions/create-customer-list/create-customer-list.mjs

@@ -0,0 +1,159 @@
+import {
+  USER_LIST_TYPES, USER_LIST_TYPE_OPTIONS,
+} from "./common-constants.mjs";
+import {
+  parseObject, parseStringObject,
+} from "../../common/utils.mjs";
+import common from "../common/common.mjs";
+import {
+  getAdditionalFields, getListTypeInfo,
+} from "../common/props.mjs";
+import { ConfigurationError } from "@pipedream/platform";
+
+export default {
+  ...common,
+  key: "google_ads-create-customer-list",
+  name: "Create Customer List",
+  description:
+    "Create a new customer list in Google Ads. [See the documentation](https://developers.google.com/google-ads/api/rest/reference/rest/v16/UserList)",
+  version: "0.0.1",
+  type: "action",
+  props: {
+    ...common.props,
+    name: {
+      type: "string",
+      label: "Name",
+      description: "The name of the customer list.",
+    },
+    description: {
+      type: "string",
+      label: "Description",
+      description: "Description of the customer list.",
+      optional: true,
+    },
+    listType: {
+      type: "string",
+      label: "List Type",
+      description:
+        "The [type of customer list](https://developers.google.com/google-ads/api/rest/reference/rest/v16/UserList#CrmBasedUserListInfo) to create.",
+      options: USER_LIST_TYPE_OPTIONS.map(({
+        label, value,
+      }) => ({
+        label,
+        value,
+      })),
+      reloadProps: true,
+    },
+  },
+  methods: {
+    parseFields(obj) {
+      switch (this.listType) {
+      case USER_LIST_TYPES.CRM_BASED:
+        break;
+
+      case USER_LIST_TYPES.RULE_BASED:
+        if (obj.prepopulationStatus) {
+          obj.prepopulationStatus = "REQUESTED";
+        }
+        if (obj.flexibleRuleUserList) {
+          obj.flexibleRuleUserList = parseObject(obj.flexibleRuleUserList);
+        }
+        break;
+
+      case USER_LIST_TYPES.LOGICAL: {
+        let { rules } = obj;
+        if (rules) {
+          rules = rules.map?.((rule) => parseStringObject(rule)) ?? parseStringObject(rules);
+        }
+        break;
+      }
+
+      case USER_LIST_TYPES.BASIC:
+        if (obj?.conversionActions?.length || obj?.remarketingActions?.length) {
+          obj.actions = [
+            ...(obj.conversionActions ?? []).map((conversionAction) => ({
+              conversionAction,
+            })),
+            ...(obj.remarketingActions ?? []).map((remarketingAction) => ({
+              remarketingAction,
+            })),
+          ];
+          delete obj.conversionActions;
+          delete obj.remarketingActions;
+        } else {
+          throw new ConfigurationError("Select at least one Conversion or Remarketing action to build the list with");
+        }
+        break;
+
+      case USER_LIST_TYPES.LOOKALIKE:
+        break;
+      }
+
+      return obj;
+    },
+  },
+  additionalProps() {
+    const { listType } = this;
+
+    const option = USER_LIST_TYPE_OPTIONS.find(
+      ({ value }) => value === listType,
+    );
+    if (!option) {
+      throw new ConfigurationError("Select a valid List Type to proceed.");
+    }
+
+    const {
+      docsLink, props,
+    } = option;
+
+    const newProps = {
+      listTypeInfo: getListTypeInfo(docsLink),
+    };
+
+    Object.assign(newProps, props);
+
+    newProps.additionalFields = getAdditionalFields(docsLink);
+
+    return newProps;
+  },
+  async run({ $ }) {
+    const {
+      googleAds,
+      accountId,
+      customerClientId,
+      name,
+      description,
+      listType,
+      additionalFields,
+      ...data
+    } = this;
+    const { results: { [0]: response } } = await googleAds.createUserList({
+      $,
+      accountId,
+      customerClientId,
+      data: {
+        operations: [
+          {
+            create: {
+              name,
+              description,
+              [listType]: this.parseFields(data),
+              ...parseObject(additionalFields),
+            },
+          },
+        ],
+      },
+    });
+
+    const id = response.resourceName.split("/").pop();
+
+    $.export(
+      "$summary",
+      `Created customer list of type \`${listType}\` with ID \`${id}\``,
+    );
+    return {
+      id,
+      ...response,
+    };
+  },
+};

package/actions/create-report/create-report.mjs

@@ -0,0 +1,156 @@
+import common from "../common/common.mjs";
+import { adGroup } from "../../common/resources/adGroup.mjs";
+import { ad } from "../../common/resources/ad.mjs";
+import { campaign } from "../../common/resources/campaign.mjs";
+import { customer } from "../../common/resources/customer.mjs";
+import { ConfigurationError } from "@pipedream/platform";
+
+const RESOURCES = [
+  adGroup,
+  ad,
+  campaign,
+  customer,
+];
+
+export default {
+  ...common,
+  key: "google_ads-create-report",
+  name: "Create Report",
+  description: "Generates a report from your Google Ads data. [See the documentation](https://developers.google.com/google-ads/api/fields/v16/overview)",
+  version: "0.0.1",
+  type: "action",
+  props: {
+    ...common.props,
+    resource: {
+      type: "string",
+      label: "Resource",
+      description: "The resource to generate a report for.",
+      options: RESOURCES.map((r) => r.resourceOption),
+      reloadProps: true,
+    },
+  },
+  additionalProps() {
+    const resource = RESOURCES.find((r) => r.resourceOption.value === this.resource);
+    if (!resource) throw new ConfigurationError("Select one of the available resources.");
+
+    const {
+      label, value,
+    } = resource.resourceOption;
+
+    return {
+      docsAlert: {
+        type: "alert",
+        alertType: "info",
+        content: `[See the documentation](https://developers.google.com/google-ads/api/fields/v16/${value}) for more information on available fields, segments and metrics.`,
+      },
+      fields: {
+        type: "string[]",
+        label: "Fields",
+        description: `${label} data fields to obtain`,
+        options: resource.fields,
+        optional: true,
+        reloadProps: true,
+      },
+      segments: {
+        type: "string[]",
+        label: "Segments",
+        description: `${label} segments to obtain [more info on the documentation](https://developers.google.com/google-ads/api/fields/v16/segments)`,
+        options: resource.segments,
+        optional: true,
+        reloadProps: true,
+      },
+      metrics: {
+        type: "string[]",
+        label: "Metrics",
+        description: `${label} metrics to obtain [more info on the documentation](https://developers.google.com/google-ads/api/fields/v16/metrics)`,
+        options: resource.metrics,
+        optional: true,
+        reloadProps: true,
+      },
+      orderBy: {
+        type: "string",
+        label: "Order By",
+        description: "The field to order the results by",
+        optional: true,
+        options: [
+          ...(this.fields ?? []),
+          ...(this.segments ?? []),
+          ...(this.metrics ?? []),
+        ],
+      },
+      direction: {
+        type: "string",
+        label: "Direction",
+        description: "The direction to order the results by, if `Order By` is specified",
+        optional: true,
+        options: [
+          {
+            label: "Ascending",
+            value: "ASC",
+          },
+          {
+            label: "Descending",
+            value: "DESC",
+          },
+        ],
+        default: "ASC",
+      },
+      limit: {
+        type: "integer",
+        label: "Limit",
+        description: "The maximum number of results to return",
+        optional: true,
+      },
+    };
+  },
+  methods: {
+    buildQuery() {
+      const {
+        resource, limit, orderBy, direction,
+      } = this;
+      const fields = this.fields?.map((i) => `${resource}.${i}`) ?? [];
+      const segments = this.segments?.map((i) => `segments.${i}`) ?? [];
+      const metrics = this.metrics?.map((i) => `metrics.${i}`) ?? [];
+      const selection = [
+        ...fields,
+        ...segments,
+        ...metrics,
+      ];
+
+      if (!selection.length) {
+        throw new ConfigurationError("Select at least one field, segment or metric.");
+      }
+
+      let query = `SELECT ${selection.join(", ")} FROM ${resource}`;
+      if (orderBy && direction) {
+        query += ` ORDER BY ${`${resource}.${orderBy}`} ${direction}`;
+      }
+      if (limit) {
+        query += ` LIMIT ${limit}`;
+      }
+
+      return query;
+    },
+  },
+  async run({ $ }) {
+    const query = this.buildQuery();
+    const results = (await this.googleAds.createReport({
+      $,
+      accountId: this.accountId,
+      customerClientId: this.customerClientId,
+      data: {
+        query,
+      },
+    })) ?? [];
+
+    const { length } = results;
+
+    $.export("$summary", `Sucessfully obtained ${length} result${length === 1
+      ? ""
+      : "s"}`);
+    return {
+      query,
+      results,
+    };
+  },
+};

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

@@ -0,0 +1,40 @@
+export const CONVERSION_TYPE_OPTIONS = [
+  {
+    label:
+      "Conversions that occur when a user clicks on an ad's call extension.",
+    value: "AD_CALL",
+  },
+  {
+    label:
+      "Conversions that occur when a user on a mobile device clicks a phone number.",
+    value: "CLICK_TO_CALL",
+  },
+  {
+    label:
+      "Conversions that occur when a user downloads a mobile app from the Google Play Store.",
+    value: "GOOGLE_PLAY_DOWNLOAD",
+  },
+  {
+    label:
+      "Conversions that occur when a user makes a purchase in an app through Android billing.",
+    value: "GOOGLE_PLAY_IN_APP_PURCHASE",
+  },
+  {
+    label: "Call conversions that are tracked by the advertiser and uploaded.",
+    value: "UPLOAD_CALLS",
+  },
+  {
+    label:
+      "Conversions that are tracked by the advertiser and uploaded with attributed clicks.",
+    value: "UPLOAD_CLICKS",
+  },
+  {
+    label: "Conversions that occur on a webpage.",
+    value: "WEBPAGE",
+  },
+  {
+    label:
+      "Conversions that occur when a user calls a dynamically-generated phone number from an advertiser's website.",
+    value: "WEBSITE_CALL",
+  },
+];

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

@@ -0,0 +1,56 @@
+import { parseObject } from "../../common/utils.mjs";
+import common from "../common/common.mjs";
+import { getAdditionalFields } from "../common/props.mjs";
+import { CONVERSION_TYPE_OPTIONS } from "./common-constants.mjs";
+
+export default {
+  ...common,
+  key: "google_ads-send-offline-conversion",
+  name: "Send Offline Conversion",
+  description: "Send an event from to Google Ads to track offline conversions. [See the documentation](https://developers.google.com/google-ads/api/rest/reference/rest/v16/ConversionAction)",
+  version: "0.0.1",
+  type: "action",
+  props: {
+    ...common.props,
+    name: {
+      type: "string",
+      label: "Name",
+      description: "The name of the conversion action.",
+    },
+    type: {
+      type: "string",
+      label: "Type",
+      description: "[The type](https://developers.google.com/google-ads/api/rest/reference/rest/v16/ConversionAction#ConversionActionType) of the conversion action.",
+      options: CONVERSION_TYPE_OPTIONS,
+    },
+    additionalFields: getAdditionalFields("https://developers.google.com/google-ads/api/rest/reference/rest/v16/ConversionAction"),
+  },
+  async run({ $ }) {
+    const {
+      googleAds, accountId, customerClientId, additionalFields, ...data
+    } = this;
+    const { results: { [0]: response } } = await googleAds.createConversionAction({
+      $,
+      accountId,
+      customerClientId,
+      data: {
+        operations: [
+          {
+            create: {
+              ...data,
+              ...parseObject(additionalFields),
+            },
+          },
+        ],
+      },
+    });
+
+    const id = response.resourceName.split("/").pop();
+
+    $.export("$summary", `Created conversion action with ID ${id}`);
+    return {
+      id,
+      ...response,
+    };
+  },
+};

package/common/props.mjs

@@ -0,0 +1,20 @@
+import googleAds from "../google_ads.app.mjs";
+
+export default {
+  googleAds,
+  accountId: {
+    propDefinition: [
+      googleAds,
+      "accountId",
+    ],
+  },
+  customerClientId: {
+    propDefinition: [
+      googleAds,
+      "customerClientId",
+      ({ accountId }) => ({
+        accountId,
+      }),
+    ],
+  },
+};

package/common/queries.mjs

@@ -0,0 +1,105 @@
+function listCustomerClients(query) {
+  const fields = [
+    "client_customer",
+    "descriptive_name",
+    "id",
+    "level",
+    "manager",
+  ]
+    .map((s) => `customer_client.${s}`)
+    .join(", ");
+
+  const condition = query
+    ? `customer_client.descriptive_name LIKE '%${query}%'`
+    : "customer_client.level <= 3";
+
+  return `SELECT ${fields} FROM customer_client WHERE ${condition}`;
+}
+
+function listUserLists() {
+  const fields = [
+    "id",
+    "name",
+  ].map((s) => `user_list.${s}`).join(", ");
+
+  return `SELECT ${fields} FROM user_list`;
+}
+
+function listConversionActions() {
+  const fields = [
+    "name",
+  ].map((s) => `conversion_action.${s}`).join(", ");
+
+  return `SELECT ${fields} FROM conversion_action`;
+}
+
+function listRemarketingActions() {
+  const fields = [
+    "name",
+  ].map((s) => `remarketing_action.${s}`).join(", ");
+
+  return `SELECT ${fields} FROM remarketing_action`;
+}
+
+function listLeadForms() {
+  const assetFields = [
+    "id",
+  ].map(((s) => `asset.${s}`));
+  const leadFormFields = [
+    "business_name",
+    "headline",
+  ].map((s) => `asset.lead_form_asset.${s}`);
+
+  return `SELECT ${[
+    ...assetFields,
+    ...leadFormFields,
+  ].join(", ")} FROM asset WHERE asset.type = 'LEAD_FORM'`;
+}
+
+function listLeadFormSubmissionData(id) {
+  const fields = [
+    "custom_lead_form_submission_fields",
+    "gclid",
+    "id",
+    "lead_form_submission_fields",
+    "submission_date_time",
+  ].map((s) => `lead_form_submission_data.${s}`).join(", ");
+  return `SELECT ${fields} FROM lead_form_submission_data WHERE asset.id = '${id}'`;
+}
+
+function listCampaigns({
+  fields, savedIds,
+}) {
+  const defaultFields = [
+    "id",
+    "name",
+  ];
+  if (typeof fields === "string") {
+    fields = fields.split(",").map((s) => s.trim());
+  }
+  if (!fields?.length) {
+    fields = defaultFields;
+  } else {
+    defaultFields.forEach((f) => {
+      if (!fields.includes(f)) {
+        fields.push(f);
+      }
+    });
+  }
+
+  const filter = savedIds?.length
+    ? ` WHERE ${savedIds.map((id) => `campaign.id != ${id}`).join(" AND ")}`
+    : "";
+
+  return `SELECT ${fields.map((s) => `campaign.${s}`).join(", ")} FROM campaign${filter}`;
+}
+
+export const QUERIES = {
+  listCampaigns,
+  listConversionActions,
+  listCustomerClients,
+  listLeadForms,
+  listLeadFormSubmissionData,
+  listRemarketingActions,
+  listUserLists,
+};