Schema compatibility changes announcement.

On December 1st 2022, the following breaking changes will occur:

  1. Attribution dimensions like source are becoming incompatible with some event-scoped metrics like eventCount. Attribution dimensions will still be compatible with attributable metrics like conversions, user-based metrics like activeUsers, and session-based metrics like sessions.

  2. Dimensions that include the query string like pagePathPlusQueryString will only be compatible with a limited set of dimensions & metrics.

The following changes were originally scheduled for December 1st 2022. However, the changes to Item-scoped dimensions will happen at a later date in early 2023.

  1. Item-scoped dimensions like itemName are becoming incompatible with event-scoped metrics like eventCount. Item-scoped dimensions will still be compatible with item-scoped metrics like itemRevenue, user-based metrics like activeUsers, and session-based metrics like sessions.

In addition, the Google Analytics is renaming the following metrics:

Current API name Future API name
itemListClicks itemListClickEvents
itemListViews itemListViewEvents
itemPromotionClicks promotionClicks
itemPromotionViews promotionViews
itemViews itemViewEvents
itemPurchaseQuantity itemsPurchased

Actions needed

  • If you are only relying on default reports in the Google Analytics UI (GA4), no action needed. These reports will be migrated automatically.

  • If you are using explorations or custom reports in the Google Analytics UI (GA4) , update the saved explorations and reports to only use the compatible fields.

  • If you are creating custom reports using the Google Analytics Data API v1, update your code to reflect the schema compatibility changes.

Item-scoped dimensions

Item-scoped dimensions include: itemAffiliation, itemBrand, itemCategory, itemCategory2, itemCategory3, itemCategory4, itemCategory5, itemId, itemListId, itemListName, itemName, itemPromotionCreativeName, itemPromotionId, itemPromotionName, & itemVariant.

Event-scoped metrics incompatible with item-scoped dimensions

The event-scoped metrics that are becoming incompatible with item-scoped dimensions include: eventCount, adUnitExposure, addToCarts, averagePurchaseRevenue, checkouts, conversions, ecommercePurchases, eventCountPerUser, eventValue, eventsPerSession, firstTimePurchasersPerNewUser, itemListClicks, itemListViews, itemPromotionClicks, itemPromotionViews, itemViews, newUsers, publisherAdClicks, publisherAdImpressions, purchaseRevenue, screenPageViews, screenPageViewsPerSession, shippingAmount, taxAmount, transactions, transactionsPerPurchaser & userEngagementDuration.

Event-scoped metrics incompatible with attribution dimensions

The event-scoped metrics that are becoming incompatible with attribution dimensions include: eventCount, adUnitExposure, addToCarts, averagePurchaseRevenue, checkouts, ecommercePurchases, eventCountPerUser, eventsPerSession, firstTimePurchasersPerNewUser, itemListClicks, itemListViews, itemPromotionClicks, itemPromotionViews, itemViews, newUsers, publisherAdClicks, publisherAdImpressions, screenPageViews, screenPageViewsPerSession, shippingAmount, taxAmount, transactions, transactionsPerPurchaser, & userEngagementDuration.

Item scope metrics

Item-scoped metrics include: itemRevenue & itemPurchaseQuantity.

User-based metrics

User-based metrics include: activeUsers, active1DayUsers, active28DayUsers, active7DayUsers, totalUsers, cartToViewRate, cohortActiveUsers, cohortTotalUsers, dauPerMau, dauPerWau, firstTimePurchaserConversionRate, firstTimePurchasers, itemListClickThroughRate, itemPromotionClickThroughRate, purchaseToViewRate, purchaserConversionRate, userConversionRate, sessionsPerUser, & wauPerMau.

Session-based metrics

Session-based metrics include: sessions, engagedSessions, sessionConversionRate & bounceRate.

Attribution dimensions

Attribution dimensions include: source, campaignId, campaignName, defaultChannelGrouping, medium, sourcePlatform, googleAdsAccountName, googleAdsAdGroupId, googleAdsAdGroupName, googleAdsAdNetworkType, googleAdsCampaignId, googleAdsCampaignName, googleAdsCampaignType, googleAdsCreativeId, googleAdsCustomerId, googleAdsKeyword, googleAdsQuery.

Attributable metrics

Attributable metrics include: conversions, eventValue, purchaseRevenue, totalRevenue, & totalAdRevenue.

Dimensions compatible with query string dimensions

Dimensions that will be compatible with query string dimensions include: pagePathPlusQueryString, unifiedPageScreen, pageLocation, fullPageUrl, hostName, pageTitle, eventName, platform, countryId, date, and country.

Metrics compatible with query string dimensions

Metrics that will be compatible with query string dimensions include: screenPageViews, userEngagementDuration, eventCount, activeUsers, conversions, totalUsers, totalSessions, & engagedSessions.