@pipedream/google_ads 0.8.0 → 1.0.0

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;

package/common/constants.mjs

@@ -1,3 +1,22 @@
+export const API_VERSION = "v25";
+
+// Conversion payload fields the upload actions set and validate themselves. Includes the
+// click and call identifiers: injecting those here would bypass the exactly-one-identifier
+// check, which runs against the props before the payload is assembled.
+export const RESERVED_CONVERSION_FIELDS = [
+  "callStartDateTime",
+  "callerId",
+  "conversionAction",
+  "conversionDateTime",
+  "conversionEnvironment",
+  "conversionValue",
+  "currencyCode",
+  "gbraid",
+  "gclid",
+  "orderId",
+  "wbraid",
+];
+
 export const SHARED_SET_TYPES = [
   {
     label: "Negative Keywords",
@@ -82,10 +101,6 @@ export const ADVERTISING_CHANNEL_TYPES = [
     label: "Local Services",
     value: "LOCAL_SERVICES",
   },
-  {
-    label: "Discovery",
-    value: "DISCOVERY",
-  },
   {
     label: "Travel",
     value: "TRAVEL",
@@ -154,10 +169,6 @@ export const AD_GROUP_TYPES = [
     label: "Video Non-Skippable In-Stream",
     value: "VIDEO_NON_SKIPPABLE_IN_STREAM",
   },
-  {
-    label: "Video Outstream",
-    value: "VIDEO_OUTSTREAM",
-  },
   {
     label: "Search Dynamic Ads",
     value: "SEARCH_DYNAMIC_ADS",
@@ -186,6 +197,10 @@ export const AD_GROUP_TYPES = [
     label: "Travel Ads",
     value: "TRAVEL_ADS",
   },
+  {
+    label: "YouTube Audio",
+    value: "YOUTUBE_AUDIO",
+  },
 ];
 
 export const AD_ROTATION_MODES = [
@@ -232,6 +247,8 @@ export const ASSET_AUTOMATION_STATUSES = [
   },
 ];
 
+// `PERCENT_CPC` is deliberately absent: v25 exposes no `bidding_strategy.percent_cpc`
+// scheme, so a portfolio strategy cannot be created with that type.
 export const PORTFOLIO_BIDDING_STRATEGY_TYPES = [
   {
     label: "Target CPA",
@@ -261,12 +278,95 @@ export const PORTFOLIO_BIDDING_STRATEGY_TYPES = [
     label: "Enhanced CPC",
     value: "ENHANCED_CPC",
   },
+];
+
+export const CAMPAIGN_BIDDING_STRATEGY_TYPES = [
+  {
+    label: "Manual CPC",
+    value: "MANUAL_CPC",
+  },
+  {
+    label: "Manual CPM",
+    value: "MANUAL_CPM",
+  },
+  {
+    label: "Target CPA",
+    value: "TARGET_CPA",
+  },
+  {
+    label: "Target ROAS",
+    value: "TARGET_ROAS",
+  },
+  {
+    label: "Target Spend",
+    value: "TARGET_SPEND",
+  },
+  {
+    label: "Maximize Conversions",
+    value: "MAXIMIZE_CONVERSIONS",
+  },
+  {
+    label: "Maximize Conversion Value",
+    value: "MAXIMIZE_CONVERSION_VALUE",
+  },
+  {
+    label: "Target Impression Share",
+    value: "TARGET_IMPRESSION_SHARE",
+  },
   {
     label: "Percent CPC",
     value: "PERCENT_CPC",
   },
 ];
 
+export const TARGET_IMPRESSION_SHARE_LOCATIONS = [
+  {
+    label: "Anywhere on page",
+    value: "ANYWHERE_ON_PAGE",
+  },
+  {
+    label: "Top of page",
+    value: "TOP_OF_PAGE",
+  },
+  {
+    label: "Absolute top of page",
+    value: "ABSOLUTE_TOP_OF_PAGE",
+  },
+];
+
+export const UPLOAD_CONVERSION_TYPES = [
+  {
+    label: "Click conversion (attributed to an ad click via GCLID)",
+    value: "CLICK",
+  },
+  {
+    label: "Call conversion (attributed to a phone call)",
+    value: "CALL",
+  },
+];
+
+export const CONVERSION_ENVIRONMENTS = [
+  {
+    label: "Web",
+    value: "WEB",
+  },
+  {
+    label: "App",
+    value: "APP",
+  },
+];
+
+export const EU_POLITICAL_ADVERTISING_STATUSES = [
+  {
+    label: "Does not contain EU political advertising",
+    value: "DOES_NOT_CONTAIN_EU_POLITICAL_ADVERTISING",
+  },
+  {
+    label: "Contains EU political advertising",
+    value: "CONTAINS_EU_POLITICAL_ADVERTISING",
+  },
+];
+
 export const CORE_DATE_SEGMENTS = [
   "segments.date",
   "segments.week",

package/common/resources/ad.mjs

@@ -6,84 +6,50 @@ const fields = [
   "ad.app_ad.descriptions",
   "ad.app_ad.headlines",
   "ad.app_ad.html5_media_bundles",
-  "ad.app_ad.html5_media_bundles.asset",
   "ad.app_ad.images",
-  "ad.app_ad.images.asset",
   "ad.app_ad.mandatory_ad_text",
   "ad.app_ad.youtube_videos",
-  "ad.app_ad.youtube_videos.asset",
   "ad.app_engagement_ad.descriptions",
   "ad.app_engagement_ad.headlines",
   "ad.app_engagement_ad.images",
-  "ad.app_engagement_ad.images.asset",
   "ad.app_engagement_ad.videos",
-  "ad.app_engagement_ad.videos.asset",
   "ad.app_pre_registration_ad.descriptions",
   "ad.app_pre_registration_ad.headlines",
   "ad.app_pre_registration_ad.images",
-  "ad.app_pre_registration_ad.images.asset",
   "ad.app_pre_registration_ad.youtube_videos",
-  "ad.app_pre_registration_ad.youtube_videos.asset",
-  "ad.call_ad.business_name",
-  "ad.call_ad.call_tracked",
-  "ad.call_ad.conversion_action",
-  "ad.call_ad.conversion_reporting_state",
-  "ad.call_ad.country_code",
-  "ad.call_ad.description1",
-  "ad.call_ad.description2",
-  "ad.call_ad.disable_call_conversion",
-  "ad.call_ad.headline1",
-  "ad.call_ad.headline2",
-  "ad.call_ad.path1",
-  "ad.call_ad.path2",
-  "ad.call_ad.phone_number",
-  "ad.call_ad.phone_number_verification_url",
+  "ad.demand_gen_carousel_ad.business_name",
+  "ad.demand_gen_carousel_ad.call_to_action_text",
+  "ad.demand_gen_carousel_ad.carousel_cards",
+  "ad.demand_gen_carousel_ad.description",
+  "ad.demand_gen_carousel_ad.headline",
+  "ad.demand_gen_carousel_ad.logo_image",
+  "ad.demand_gen_multi_asset_ad.business_name",
+  "ad.demand_gen_multi_asset_ad.call_to_action_text",
+  "ad.demand_gen_multi_asset_ad.descriptions",
+  "ad.demand_gen_multi_asset_ad.headlines",
+  "ad.demand_gen_multi_asset_ad.logo_images",
+  "ad.demand_gen_multi_asset_ad.marketing_images",
+  "ad.demand_gen_multi_asset_ad.portrait_marketing_images",
+  "ad.demand_gen_multi_asset_ad.square_marketing_images",
   "ad.demand_gen_product_ad.breadcrumb1",
   "ad.demand_gen_product_ad.breadcrumb2",
   "ad.demand_gen_product_ad.business_name",
   "ad.demand_gen_product_ad.call_to_action",
-  "ad.demand_gen_product_ad.call_to_action.asset",
   "ad.demand_gen_product_ad.description",
   "ad.demand_gen_product_ad.headline",
   "ad.demand_gen_product_ad.logo_image",
-  "ad.demand_gen_product_ad.logo_image.asset",
+  "ad.demand_gen_video_responsive_ad.breadcrumb1",
+  "ad.demand_gen_video_responsive_ad.breadcrumb2",
+  "ad.demand_gen_video_responsive_ad.business_name",
+  "ad.demand_gen_video_responsive_ad.call_to_actions",
+  "ad.demand_gen_video_responsive_ad.descriptions",
+  "ad.demand_gen_video_responsive_ad.headlines",
+  "ad.demand_gen_video_responsive_ad.logo_images",
+  "ad.demand_gen_video_responsive_ad.long_headlines",
+  "ad.demand_gen_video_responsive_ad.videos",
   "ad.device_preference",
-  "ad.discovery_carousel_ad.business_name",
-  "ad.discovery_carousel_ad.call_to_action_text",
-  "ad.discovery_carousel_ad.carousel_cards",
-  "ad.discovery_carousel_ad.carousel_cards.asset",
-  "ad.discovery_carousel_ad.description",
-  "ad.discovery_carousel_ad.headline",
-  "ad.discovery_carousel_ad.logo_image",
-  "ad.discovery_carousel_ad.logo_image.asset",
-  "ad.discovery_multi_asset_ad.business_name",
-  "ad.discovery_multi_asset_ad.call_to_action_text",
-  "ad.discovery_multi_asset_ad.descriptions",
-  "ad.discovery_multi_asset_ad.headlines",
-  "ad.discovery_multi_asset_ad.lead_form_only",
-  "ad.discovery_multi_asset_ad.logo_images",
-  "ad.discovery_multi_asset_ad.logo_images.asset",
-  "ad.discovery_multi_asset_ad.marketing_images",
-  "ad.discovery_multi_asset_ad.marketing_images.asset",
-  "ad.discovery_multi_asset_ad.portrait_marketing_images",
-  "ad.discovery_multi_asset_ad.portrait_marketing_images.asset",
-  "ad.discovery_multi_asset_ad.square_marketing_images",
-  "ad.discovery_multi_asset_ad.square_marketing_images.asset",
-  "ad.discovery_video_responsive_ad.breadcrumb1",
-  "ad.discovery_video_responsive_ad.breadcrumb2",
-  "ad.discovery_video_responsive_ad.business_name",
-  "ad.discovery_video_responsive_ad.call_to_actions",
-  "ad.discovery_video_responsive_ad.call_to_actions.asset",
-  "ad.discovery_video_responsive_ad.descriptions",
-  "ad.discovery_video_responsive_ad.headlines",
-  "ad.discovery_video_responsive_ad.logo_images",
-  "ad.discovery_video_responsive_ad.logo_images.asset",
-  "ad.discovery_video_responsive_ad.long_headlines",
-  "ad.discovery_video_responsive_ad.videos",
-  "ad.discovery_video_responsive_ad.videos.asset",
   "ad.display_upload_ad.display_upload_product_type",
   "ad.display_upload_ad.media_bundle",
-  "ad.display_upload_ad.media_bundle.asset",
   "ad.display_url",
   "ad.expanded_dynamic_search_ad.description",
   "ad.expanded_dynamic_search_ad.description2",
@@ -129,13 +95,10 @@ const fields = [
   "ad.local_ad.descriptions",
   "ad.local_ad.headlines",
   "ad.local_ad.logo_images",
-  "ad.local_ad.logo_images.asset",
   "ad.local_ad.marketing_images",
-  "ad.local_ad.marketing_images.asset",
   "ad.local_ad.path1",
   "ad.local_ad.path2",
   "ad.local_ad.videos",
-  "ad.local_ad.videos.asset",
   "ad.name",
   "ad.resource_name",
   "ad.responsive_display_ad.accent_color",
@@ -148,19 +111,14 @@ const fields = [
   "ad.responsive_display_ad.format_setting",
   "ad.responsive_display_ad.headlines",
   "ad.responsive_display_ad.logo_images",
-  "ad.responsive_display_ad.logo_images.asset",
   "ad.responsive_display_ad.long_headline",
   "ad.responsive_display_ad.main_color",
   "ad.responsive_display_ad.marketing_images",
-  "ad.responsive_display_ad.marketing_images.asset",
   "ad.responsive_display_ad.price_prefix",
   "ad.responsive_display_ad.promo_text",
   "ad.responsive_display_ad.square_logo_images",
-  "ad.responsive_display_ad.square_logo_images.asset",
   "ad.responsive_display_ad.square_marketing_images",
-  "ad.responsive_display_ad.square_marketing_images.asset",
   "ad.responsive_display_ad.youtube_videos",
-  "ad.responsive_display_ad.youtube_videos.asset",
   "ad.responsive_search_ad.descriptions",
   "ad.responsive_search_ad.headlines",
   "ad.responsive_search_ad.path1",
@@ -199,12 +157,10 @@ const fields = [
   "ad.video_responsive_ad.breadcrumb2",
   "ad.video_responsive_ad.call_to_actions",
   "ad.video_responsive_ad.companion_banners",
-  "ad.video_responsive_ad.companion_banners.asset",
   "ad.video_responsive_ad.descriptions",
   "ad.video_responsive_ad.headlines",
   "ad.video_responsive_ad.long_headlines",
   "ad.video_responsive_ad.videos",
-  "ad.video_responsive_ad.videos.asset",
   "ad_group",
   "ad_strength",
   "labels",
@@ -257,7 +213,6 @@ const metrics = [
   "average_cpc",
   "average_cpe",
   "average_cpm",
-  "average_cpv",
   "average_order_value_micros",
   "average_page_views",
   "average_time_on_site",
@@ -312,8 +267,8 @@ const metrics = [
   "video_quartile_p25_rate",
   "video_quartile_p50_rate",
   "video_quartile_p75_rate",
-  "video_view_rate",
-  "video_views",
+  "video_trueview_view_rate",
+  "video_trueview_views",
   "view_through_conversions",
 ].map((f) => getOption(f, "metrics"));
 

package/common/resources/adGroup.mjs

@@ -82,7 +82,6 @@ const metrics = [
   "average_cpc",
   "average_cpe",
   "average_cpm",
-  "average_cpv",
   "average_order_value_micros",
   "average_page_views",
   "average_time_on_site",
@@ -152,8 +151,8 @@ const metrics = [
   "video_quartile_p25_rate",
   "video_quartile_p50_rate",
   "video_quartile_p75_rate",
-  "video_view_rate",
-  "video_views",
+  "video_trueview_view_rate",
+  "video_trueview_views",
   "view_through_conversions",
 ].map((f) => getOption(f, "metrics"));
 

package/common/resources/campaign.mjs

@@ -17,12 +17,12 @@ const fields = [
   "campaign_budget",
   "campaign_group",
   "commission.commission_rate_micros",
-  "discovery_campaign_settings.upgraded_targeting",
+  "contains_eu_political_advertising",
+  "demand_gen_campaign_settings.upgraded_targeting",
   "dynamic_search_ads_setting.domain_name",
-  "dynamic_search_ads_setting.feeds",
   "dynamic_search_ads_setting.language_code",
   "dynamic_search_ads_setting.use_supplied_urls_only",
-  "end_date",
+  "end_date_time",
   "excluded_parent_asset_field_types",
   "excluded_parent_asset_set_types",
   "experiment_type",
@@ -71,7 +71,7 @@ const fields = [
   "shopping_setting.feed_label",
   "shopping_setting.merchant_id",
   "shopping_setting.use_vehicle_inventory",
-  "start_date",
+  "start_date_time",
   "status",
   "target_cpa.cpc_bid_ceiling_micros",
   "target_cpa.cpc_bid_floor_micros",
@@ -91,10 +91,8 @@ const fields = [
   "tracking_url_template",
   "travel_campaign_settings.travel_account_id",
   "url_custom_parameters",
-  "url_expansion_opt_out",
   "vanity_pharma.vanity_pharma_display_url_mode",
   "vanity_pharma.vanity_pharma_text",
-  "video_brand_safety_suitability",
 ].map((f) => getOption(f, "campaign"));
 
 const segments = [
@@ -121,7 +119,7 @@ const segments = [
   "sk_ad_network_ad_event_type",
   "sk_ad_network_attribution_credit",
   "sk_ad_network_coarse_conversion_value",
-  "sk_ad_network_conversion_value",
+  "sk_ad_network_fine_conversion_value",
   "sk_ad_network_postback_sequence_index",
   "sk_ad_network_source_app.sk_ad_network_source_app_id",
   "sk_ad_network_source_domain",
@@ -170,7 +168,6 @@ const metrics = [
   "average_cpc",
   "average_cpe",
   "average_cpm",
-  "average_cpv",
   "average_impression_frequency_per_user",
   "average_order_value_micros",
   "average_page_views",
@@ -260,8 +257,8 @@ const metrics = [
   "video_quartile_p25_rate",
   "video_quartile_p50_rate",
   "video_quartile_p75_rate",
-  "video_view_rate",
-  "video_views",
+  "video_trueview_view_rate",
+  "video_trueview_views",
   "view_through_conversions",
   "view_through_conversions_from_location_asset_click_to_call",
   "view_through_conversions_from_location_asset_directions",

package/common/resources/customer.mjs

@@ -56,7 +56,7 @@ const segments = [
   "sk_ad_network_ad_event_type",
   "sk_ad_network_attribution_credit",
   "sk_ad_network_coarse_conversion_value",
-  "sk_ad_network_conversion_value",
+  "sk_ad_network_fine_conversion_value",
   "sk_ad_network_postback_sequence_index",
   "sk_ad_network_source_app.sk_ad_network_source_app_id",
   "sk_ad_network_source_domain",
@@ -98,7 +98,6 @@ const metrics = [
   "average_cpc",
   "average_cpe",
   "average_cpm",
-  "average_cpv",
   "average_order_value_micros",
   "clicks",
   "content_budget_lost_impression_share",
@@ -152,8 +151,8 @@ const metrics = [
   "value_per_all_conversions_by_conversion_date",
   "value_per_conversion",
   "value_per_conversions_by_conversion_date",
-  "video_view_rate",
-  "video_views",
+  "video_trueview_view_rate",
+  "video_trueview_views",
   "view_through_conversions",
   "view_through_conversions_from_location_asset_click_to_call",
   "view_through_conversions_from_location_asset_directions",