Version 6 breaking changes

Simplified API

The problem with the old API surface is that there were a lot of very specific functions which are trying to do multiple things at the same time. Important: You might have to migrate to new API

As of version 6, these functions have been removed:

• createNewSession(screenName)
• trackPurchaseEvent(product, transaction, eventCategory, eventAction)
• trackMultiProductsPurchaseEvent(products, transaction, eventCategory, eventAction)
• trackMultiProductsPurchaseEventWithCustomDimensionValues(products, transaction, eventCategory, eventAction, dimensionIndexValueDict)
• trackScreenViewWithCustomDimensionValues(screenName, dimensionIndexValueDict)
• trackEventWithCustomDimensionValues(category, action, optionalValues, dimensionIndexValueDict)
• trackEventWithCustomDimensionAndMetricValues(category, action, optionalValues, dimensionIndexValueDict)

These have been replaced by extending the other track functions to instead take an optional HitPayload parameter:

• trackScreenView(screenName, payload)
• trackEvent(category, action, eventMetadata, payload)
• trackTiming(category, interval, timingMetadata, payload)
• trackException(error, fatal, payload)
• trackSocialInteraction(network, action, targetUrl, payload)

These functions are backwards-compatible with the old API; the only change is that they also accept an optional payload parameter.

The available HitPayload parameters are:

• products Array<Product> (Optional) Used for ecommerce
• impressionProducts Array<Product> (Optional) Used for ecommerce
• impressionList string (Optional) Used for ecommerce
• impressionSource string (Optional) Used for ecommerce
• productAction ProductAction (Optional) Used for ecommerce
• customDimensions (CustomDimensionsByIndex | CustomDimensionsByField) (Optional)
• customMetrics CustomMetrics (Optional)
• utmCampaignUrl string (Optional) Used for campaigns
• session string (Optional) Only two possible values, "start" or "end". This will either start or end a session.

This will not only cover the scenarios in the removed functions, but also give you a lot more options in how you want to send hit metadata.

With this release, we also have support for a lot more enhanced ecommerce scenarios. Like impressions, and all product actions.

Migrating to new API

The following shows how to migrate from certain functions which have been removed from the API:

createNewSession(screenName)

You do not have to start a session with a screen view anymore. You can also do it with an event:

const payload = { session: "start" };
tracker.trackEvent("User", "Login", null, payload);
// or with a screen view if you like:
tracker.trackScreenView("Home", payload);
// ending a session:
tracker.trackEvent("User", "Logout", null, { session: "end" });

trackPurchaseEvent(product, transaction, eventCategory, eventAction)

As well as:

• trackMultiProductsPurchaseEvent(products, transaction, eventCategory, eventAction)
• trackMultiProductsPurchaseEventWithCustomDimensionValues(products, transaction, eventCategory, eventAction, dimensionIndexValueDict)

Any ecommerce event now can be sent with a payload. To track a purchase, you can do it like this:

const product = {
  id: "P12345",
  name: "Android Warhol T-Shirt",
  category: "Apparel/T-Shirts",
  brand: "Google",
  variant: "Black",
  price: 29.2,
  quantity: 1,
  couponCode: "APPARELSALE"
};
const transaction = {
  id: "T12345",
  affiliation: "Google Store - Online",
  revenue: 37.39,
  tax: 2.85,
  shipping: 5.34,
  couponCode: "SUMMER2013"
};
const productAction = {
  transaction,
  action: 7 // Purchase action, see ProductActionEnum
}
const payload = { products: [ product ], productAction: productAction }
tracker.trackEvent("FinalizeOrderButton", "Click", null, payload);

As you can tell, the payload takes an array of Product (even if there is only one product), so this also covers trackMultiProductsPurchaseEvent. See section below how to track custom dimensions as well (as in trackMultiProductsPurchaseEventWithCustomDimensionValues).

You now also have more enhanced ecommerce options.

The action parameter in ProductAction can have several values to tell GA how users interact with products:

• Detail = 1,
• Click = 2,
• Add = 3,
• Remove = 4,
• Checkout = 5,
• CheckoutOption = 6,
• Purchase = 7,
• Refund = 8

You can also track impressions with impressionProducts, impressionList and impressionSource in HitPayload.

trackScreenViewWithCustomDimensionValues(screenName, dimensionIndexValueDict)

As well as:

• trackEventWithCustomDimensionValues(category, action, optionalValues, dimensionIndexValueDict)
• trackEventWithCustomDimensionAndMetricValues(category, action, optionalValues, dimensionIndexValueDict)

Tracking custom dimensions and metrics is quite simple now:

const customDimensions = { 1: "Premium", 3: "Beta", 5: 1200 };
const customMetrics = { 1: 2389, 4: 15000 };
const payload = { customDimensions, customMetrics };
tracker.trackScreenView("Home", payload);
// or with event:
tracker.trackEvent("DetailsButton", "Click", null, payload);

If you want to combine dimensions/metrics and ecommerce, just put it in the same payload:

const payload = { customDimensions, customMetrics, products: [ product ], productAction: productAction  };