Migrate from v20 to v21

What Changed

ad_group_ad.ad.id

ad_group_ad.ad.final_urls

campaign.bidding_strategy_type

campaign.campaign_budget

Migration Steps

1. 1

   Review API Release Notes

   code

   Thoroughly read the official Google Ads API v21 release notes. Pay close attention to any announced breaking changes, new features, and deprecations.

   • ↳Focus on sections detailing resource naming conventions and field removals.
2. 2

   Update Resource Name Handling

   code

   Identify and update all instances where resource names are constructed or parsed. Adapt your code to the new formats specified in the v21 release notes, particularly for Ad Group Ads and Campaign Budgets.

   • ↳Use helper functions for resource name generation to simplify updates.
   • ↳Test resource name parsing logic carefully.
3. 3

   Remove Usage of Deprecated Fields

   code

   Scan your codebase for any fields that have been deprecated and removed in v21. Replace these fields with their recommended alternatives or remove the logic entirely if no direct replacement exists.

   • ↳Consult the v21 documentation for suggested replacements.
   • ↳Comment out or temporarily remove code using deprecated fields before permanent removal.
4. 4

   Update SDKs and Libraries

   config

   Ensure you are using the latest client libraries and SDKs that support Google Ads API v21. Outdated libraries may not be compatible with the new API version.

   • ↳Check your dependency management tool (e.g., pip, npm, Maven) for available updates.
   • ↳Verify compatibility of updated libraries with your existing codebase.
5. 5

   Implement Comprehensive Testing

   test

   Write and execute unit tests, integration tests, and end-to-end tests to cover all affected areas. Focus on scenarios involving resource creation, updates, and reporting.

   • ↳Use mock data that mimics v21 resource structures.
   • ↳Ensure tests cover both successful operations and error handling.
6. 6

   Staging Environment Deployment and Testing

   deploy

   Deploy your updated application to a staging environment that uses the Google Ads API v21. Perform manual testing and monitor logs for any unexpected behavior or errors.

   • ↳Utilize a dedicated test account in your staging environment.
   • ↳Check API response codes and error messages for clarity.
7. 7

   Production Deployment

   deploy

   Once confident after staging, deploy the changes to your production environment. Monitor performance and error rates closely immediately after deployment.

   • ↳Consider a phased rollout if possible.
   • ↳Have a rollback plan ready in case of critical issues.
8. 8

   Post-Migration Monitoring

   verify

   Continuously monitor your application's performance and accuracy in production. Compare key metrics before and after the migration to ensure no regressions.

   • ↳Track API call success rates and latency.
   • ↳Verify reporting accuracy against Google Ads UI data.

Testing Checklist

1. 1.

   Ad Group Ad Resource Name Generation

   Verify that new Ad Group Ads are created with the correct resource name format in v21.

2. 2.

   Campaign Budget Update

   Confirm that campaign budgets can be updated using the correct fields in v21.

3. 3.

   Reporting Queries

   Run various reporting queries and compare results against v20 and Google Ads UI for accuracy.

4. 4.

   Error Handling for Deprecated Fields

   Attempt to use a removed field and confirm that a proper error is returned and handled.

5. 5.

   Bulk Operations

   Test mutations (create, update, delete) for multiple resources in a single API call.

Common Mistakes