Changes for release v19_1. (#930)

Author: BenRKarl

ChangeLog

@@ -1,3 +1,9 @@
+* 26.1.0
+- Google Ads API v19_1 release.
+- Add two new examples for budget recommendations.
+- Fix bug in normalize_and_hash function in enhanced conversions examples.
+- Update enhanced conversions for leads example to include session attributes.
+
 * 26.0.1
 - Rename constraints file to resolve install issues on Windows
 - Update add_customer_match_user_list.py to remove mention of unlimited list expiry (#921)

examples/remarketing/upload_enhanced_conversions_for_leads.py

@@ -39,6 +39,8 @@ def main(
     order_id,
     gclid,
     ad_user_data_consent,
+    session_attributes_encoded=None,
+    session_attributes_dict=None,
 ):
     """The main method that creates all necessary entities for the example.
 
@@ -52,7 +54,19 @@ def main(
         gclid: The Google click ID for the click.
         ad_user_data_consent: The consent status for ad user data for all
             members in the job.
+        session_attributes_encoded: a str token of encoded session atttributes.
+            Only one of session_attributes_encoded or session_attributes_dict
+            should be passed.
+        session_attributes_dict: a dict[str, str] of session attribute
+            key value pairs. Only one of session_attributes_encoded or
+            session_attributes_dict should be passed.
     """
+    if session_attributes_encoded and session_attributes_dict:
+        raise ValueError(
+            "Only one of 'session_attributes_encoded' or "
+            "'session_attributes_dict' can be set."
+        )
+
     # [START add_user_identifiers]
     # Extract user email and phone from the raw data, normalize and hash it,
     # then wrap it in UserIdentifier objects. Create a separate UserIdentifier
@@ -146,7 +160,22 @@ def main(
         click_conversion.consent.ad_user_data = client.enums.ConsentStatusEnum[
             raw_record["ad_user_data_consent"]
         ]
-        # [END add_conversion_details]
+
+    # [START add_session_attributes]
+    # Set one of the session_attributes_encoded or
+    # session_attributes_key_value_pairs fields if either are provided.
+    if session_attributes_encoded:
+        click_conversion.session_attributes_encoded = session_attributes_encoded
+    elif session_attributes_dict:
+        for key, value in session_attributes_dict.items():
+            pair = client.get_type("SessionAttributeKeyValuePair")
+            pair.session_attribute_key = key
+            pair.session_attribute_value = value
+            click_conversion.session_attributes_key_value_pairs.key_value_pairs.append(
+                pair
+            )
+            # [END add_session_attributes]
+            # [END add_conversion_details]
 
     # [START upload_conversion]
     # Creates the conversion upload service client.
@@ -230,6 +259,10 @@ def normalize_and_hash(s):
 
 
 if __name__ == "__main__":
+    # GoogleAdsClient will read the google-ads.yaml configuration file in the
+    # home directory if none is specified.
+    googleads_client = GoogleAdsClient.load_from_storage(version="v19")
+
     parser = argparse.ArgumentParser(
         description="Imports offline call conversion values for calls related "
         "to your ads."
@@ -278,7 +311,7 @@ def normalize_and_hash(s):
         help="the Google click ID (gclid) for the click.",
     )
     parser.add_argument(
-        "-d",
+        "-n",
         "--ad_user_data_consent",
         type=str,
         choices=[e.name for e in googleads_client.enums.ConsentStatusEnum],
@@ -287,11 +320,35 @@ def normalize_and_hash(s):
             "the job."
         ),
     )
+    # A mutually exclusive group means that session_attributes_encoded and
+    # session_attributes_key_value_pairs cannot be passed in at the same time.
+    session_attributes = parser.add_mutually_exclusive_group()
+    session_attributes.add_argument(
+        "-e",
+        "--session_attributes_encoded",
+        type=str,
+        default=None,
+        help=("A session attributes token."),
+    )
+    session_attributes.add_argument(
+        "-k",
+        "--session_attributes_key_value_pairs",
+        nargs="+",
+        type=str,
+        default=None,
+        help=(
+            "A space-delimited list of session attribute key value pairs. Each "
+            "pair should be separated by an equal sign, for example: "
+            "'-k gad_campaignid=12345 gad_source=1'"
+        ),
+    )
     args = parser.parse_args()
 
-    # GoogleAdsClient will read the google-ads.yaml configuration file in the
-    # home directory if none is specified.
-    googleads_client = GoogleAdsClient.load_from_storage(version="v19")
+    if args.session_attributes_key_value_pairs:
+        # Convert the string-based input to a dict
+        session_attributes_dict = dict(
+            pair.split("=") for pair in args.session_attributes_key_value_pairs
+        )
 
     try:
         main(
@@ -303,6 +360,11 @@ def normalize_and_hash(s):
             args.order_id,
             args.gclid,
             args.ad_user_data_consent,
+            # Only one of 'session_attributes_encoded' or
+            # 'session_attributes_dict' can be passed at a time. If both are
+            # passed the example will fail with a ValueError.
+            session_attributes_encoded=args.session_attributes_encoded,
+            session_attributes_dict=session_attributes_dict,
         )
     except GoogleAdsException as ex:
         print(

google/ads/googleads/__init__.py

@@ -19,4 +19,4 @@
 import google.ads.googleads.errors
 import google.ads.googleads.util
 
-VERSION = "26.0.1"
+VERSION = "26.1.0"

google/ads/googleads/v19/__init__.py

@@ -1,5 +1,5 @@
 # -*- coding: utf-8 -*-
-# Copyright 2024 Google LLC
+# Copyright 2025 Google LLC
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
 # you may not use this file except in compliance with the License.

google/ads/googleads/v19/common/__init__.py

@@ -1,5 +1,5 @@
 # -*- coding: utf-8 -*-
-# Copyright 2024 Google LLC
+# Copyright 2025 Google LLC
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
 # you may not use this file except in compliance with the License.
@@ -59,6 +59,7 @@
 from .types.ad_type_infos import VideoOutstreamAdInfo
 from .types.ad_type_infos import VideoResponsiveAdInfo
 from .types.ad_type_infos import VideoTrueViewInStreamAdInfo
+from .types.ad_type_infos import YouTubeAudioAdInfo
 from .types.asset_policy import AdAssetPolicySummary
 from .types.asset_policy import AssetDisapproved
 from .types.asset_policy import AssetLinkPrimaryStatusDetails
@@ -633,6 +634,7 @@
     "WhatsappBusinessMessageInfo",
     "YearMonth",
     "YearMonthRange",
+    "YouTubeAudioAdInfo",
     "YouTubeChannelAttributeMetadata",
     "YouTubeChannelInfo",
     "YouTubeVideoAttributeMetadata",

google/ads/googleads/v19/common/services/__init__.py

@@ -1,5 +1,5 @@
 # -*- coding: utf-8 -*-
-# Copyright 2024 Google LLC
+# Copyright 2025 Google LLC
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
 # you may not use this file except in compliance with the License.

google/ads/googleads/v19/common/types/__init__.py

@@ -1,5 +1,5 @@
 # -*- coding: utf-8 -*-
-# Copyright 2024 Google LLC
+# Copyright 2025 Google LLC
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
 # you may not use this file except in compliance with the License.
@@ -57,6 +57,7 @@
     VideoOutstreamAdInfo,
     VideoResponsiveAdInfo,
     VideoTrueViewInStreamAdInfo,
+    YouTubeAudioAdInfo,
 )
 from .asset_policy import (
     AdAssetPolicySummary,
@@ -116,7 +117,9 @@
     WhatsappBusinessMessageInfo,
     YoutubeVideoAsset,
 )
-from .asset_usage import AssetUsage
+from .asset_usage import (
+    AssetUsage,
+)
 from .audience_insights_attribute import (
     AudienceInsightsAttribute,
     AudienceInsightsAttributeMetadata,
@@ -168,8 +171,12 @@
     TargetRoas,
     TargetSpend,
 )
-from .click_location import ClickLocation
-from .consent import Consent
+from .click_location import (
+    ClickLocation,
+)
+from .consent import (
+    Consent,
+)
 from .criteria import (
     ActivityCityInfo,
     ActivityCountryInfo,
@@ -251,8 +258,12 @@
     CriterionCategoryChannelAvailability,
     CriterionCategoryLocaleAvailability,
 )
-from .custom_parameter import CustomParameter
-from .customizer_value import CustomizerValue
+from .custom_parameter import (
+    CustomParameter,
+)
+from .customizer_value import (
+    CustomizerValue,
+)
 from .dates import (
     DateRange,
     YearMonth,
@@ -263,8 +274,12 @@
     CalloutFeedItem,
     SitelinkFeedItem,
 )
-from .feed_common import Money
-from .final_app_url import FinalAppUrl
+from .feed_common import (
+    Money,
+)
+from .final_app_url import (
+    FinalAppUrl,
+)
 from .frequency_cap import (
     FrequencyCapEntry,
     FrequencyCapKey,
@@ -280,9 +295,15 @@
     KeywordPlanHistoricalMetrics,
     MonthlySearchVolume,
 )
-from .lifecycle_goals import LifecycleGoalValueSettings
-from .local_services import LocalServicesDocumentReadOnly
-from .metric_goal import MetricGoal
+from .lifecycle_goals import (
+    LifecycleGoalValueSettings,
+)
+from .local_services import (
+    LocalServicesDocumentReadOnly,
+)
+from .metric_goal import (
+    MetricGoal,
+)
 from .metrics import (
     Metrics,
     SearchVolumeRange,
@@ -309,8 +330,12 @@
     PolicyValidationParameter,
     PolicyViolationKey,
 )
-from .policy_summary import PolicySummary
-from .real_time_bidding_setting import RealTimeBiddingSetting
+from .policy_summary import (
+    PolicySummary,
+)
+from .real_time_bidding_setting import (
+    RealTimeBiddingSetting,
+)
 from .segments import (
     AssetInteractionTarget,
     BudgetCampaignAssociationStatus,
@@ -334,14 +359,20 @@
     TargetRoasSimulationPoint,
     TargetRoasSimulationPointList,
 )
-from .tag_snippet import TagSnippet
+from .tag_snippet import (
+    TagSnippet,
+)
 from .targeting_setting import (
     TargetingSetting,
     TargetRestriction,
     TargetRestrictionOperation,
 )
-from .text_label import TextLabel
-from .url_collection import UrlCollection
+from .text_label import (
+    TextLabel,
+)
+from .url_collection import (
+    UrlCollection,
+)
 from .user_lists import (
     BasicUserListInfo,
     CrmBasedUserListInfo,
@@ -361,7 +392,9 @@
     UserListRuleItemInfo,
     UserListStringRuleItemInfo,
 )
-from .value import Value
+from .value import (
+    Value,
+)
 
 __all__ = (
     "AdAppDeepLinkAsset",
@@ -405,6 +438,7 @@
     "VideoOutstreamAdInfo",
     "VideoResponsiveAdInfo",
     "VideoTrueViewInStreamAdInfo",
+    "YouTubeAudioAdInfo",
     "AdAssetPolicySummary",
     "AssetDisapproved",
     "AssetLinkPrimaryStatusDetails",

google/ads/googleads/v19/common/types/ad_asset.py

@@ -1,5 +1,5 @@
 # -*- coding: utf-8 -*-
-# Copyright 2024 Google LLC
+# Copyright 2025 Google LLC
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
 # you may not use this file except in compliance with the License.

google/ads/googleads/v19/common/types/ad_type_infos.py

@@ -1,5 +1,5 @@
 # -*- coding: utf-8 -*-
-# Copyright 2024 Google LLC
+# Copyright 2025 Google LLC
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
 # you may not use this file except in compliance with the License.
@@ -48,6 +48,7 @@
         "VideoTrueViewInStreamAdInfo",
         "VideoOutstreamAdInfo",
         "InFeedVideoAdInfo",
+        "YouTubeAudioAdInfo",
         "VideoAdInfo",
         "VideoResponsiveAdInfo",
         "ResponsiveSearchAdInfo",
@@ -515,6 +516,10 @@ class InFeedVideoAdInfo(proto.Message):
     )
 
 
+class YouTubeAudioAdInfo(proto.Message):
+    r"""Representation of YouTube Audio ad format."""
+
+
 class VideoAdInfo(proto.Message):
     r"""A video ad.
 
@@ -547,6 +552,10 @@ class VideoAdInfo(proto.Message):
         in_feed (google.ads.googleads.v19.common.types.InFeedVideoAdInfo):
             In-feed video ad format.
 
+            This field is a member of `oneof`_ ``format``.
+        audio (google.ads.googleads.v19.common.types.YouTubeAudioAdInfo):
+            YouTube Audio ad format.
+
             This field is a member of `oneof`_ ``format``.
     """
 
@@ -585,6 +594,12 @@ class VideoAdInfo(proto.Message):
         oneof="format",
         message="InFeedVideoAdInfo",
     )
+    audio: "YouTubeAudioAdInfo" = proto.Field(
+        proto.MESSAGE,
+        number=10,
+        oneof="format",
+        message="YouTubeAudioAdInfo",
+    )
 
 
 class VideoResponsiveAdInfo(proto.Message):

google/ads/googleads/v19/common/types/asset_policy.py

@@ -1,5 +1,5 @@
 # -*- coding: utf-8 -*-
-# Copyright 2024 Google LLC
+# Copyright 2025 Google LLC
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
 # you may not use this file except in compliance with the License.