From 9725fce564474adedcc759ad46aaf4e1bc13e100 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=C3=8Dcaro=20Azevedo?= Date: Thu, 14 Jul 2022 11:34:33 -0300 Subject: [PATCH 1/4] docs: analytics on faststore blog post --- apps/docs/blog/analytics-on-faststore.md | 80 +++++++++++++++++++ .../sdk/analytics/how-to-extend-types.md | 2 +- 2 files changed, 81 insertions(+), 1 deletion(-) create mode 100644 apps/docs/blog/analytics-on-faststore.md diff --git a/apps/docs/blog/analytics-on-faststore.md b/apps/docs/blog/analytics-on-faststore.md new file mode 100644 index 0000000000..cb6e21006d --- /dev/null +++ b/apps/docs/blog/analytics-on-faststore.md @@ -0,0 +1,80 @@ +--- +title: Analytics on FastStore +description: An overview of our analytics solutions for FastStore. +tags: [ga, gtm, google analytics, google tag manager, google, analytics, sdk, faststore] +hide_table_of_contents: false +--- + +# Analytics on FastStore + +The FastStore team is committed to building a great analytics experience for customers and developers. We understand a good analytics implementation is key for decision-making, marketing and sales in an ecommerce, so we've built tools and resources to help stores fulfill their analytics requirements. + +Stores usually need to add 3rd party scripts to their webpage to integrate with analytics solutions. These scripts require running javascript on the browser, which often makes web pages slow and consequently hurts SEO performance and conversion rates. + +Remember: FastStore is the fullstack toolkit for building high-performance stores. Delivering bad performance is not an option, so we've built our analytics tools with performance in mind. We've also made it easy for developers to add and manage analytics integrations while maintaining great scores, so FastStore users don't have to choose between performance and analytics. For that, we had to be mindful to make decisions that make this possible. + +## Google Analytics native support + +The market for analytics solutions has been increasingly more competitive over the past few years, but one player takes the lead: Google Analytics. According to [W3Tech](https://w3techs.com/technologies/history_overview/traffic_analysis/ms/y), Google Analytics leads with 85.9% (2022 numbers) of the market. We see this trend among our user base as well, so it made sense to build solutions that work well with Google Analytics. + +Google Analytics has two major versions today: Universal Analytics (UA) and Google Analytics 4 (GA4). Support for UA is set to end by July 2023, while GA4 takes its place with a new UI for building reports, new ways of sending data and data analysis tools. Google Analytics offers a set of ecommerce-focused capabilities that help developers and management teams to organize their data and build their reports. These capabilities are encapsulated in what Google calls [Enhanced Ecommerce](https://developers.google.com/tag-manager/enhanced-ecommerce). + +For many, GA4 represents the future of Google Analytics. For us, it is the present (more on that later). That's why FastStore natively supports all GA4 Enhanced Ecommerce capabilities. If you are developing with FastStore and use one of [our official starters](https://www.faststore.dev/starters), your store already includes everything needed to work with Google Analytics 4 Enhanced Ecommerce. + +## It starts with FastStore SDK + +FastStore SDK is a simple, framework-agnostic implementation of Commerce APIs that is composed of modules, and the [analytics module](https://www.faststore.dev/reference/sdk/analytics) is one of them. The analytics module is where our commitment to analytics in FastStore starts. This module provides ways of sending and intercepting events that by default follow GA4 Enhanced Ecommerce guidelines, that can be [extended and customized](https://www.faststore.dev/reference/sdk/analytics/how-to-extend-types). + +Interacting with the analytics module is very simple. You can use the [sendAnalyticsEvent](https://www.faststore.dev/reference/sdk/analytics/sendAnalyticsEvent) function to send events and the [useAnalyticsEvent](https://www.faststore.dev/reference/sdk/analytics/useAnalyticsEvent) hook to intercept them. It was built to give freedom to developers to [send and handle events of any kind](https://www.faststore.dev/reference/sdk/analytics/how-to-send-custom-events). + +It's important to note that FastStore SDK's analytics module is not a VTEX IO app nor does it work similarly. It merely provides an interface for sending and receiving events more easily, in part thanks to autocomplete features provided by TypeScript and code editors. Events are not automatically sent to any analytics provider, so to visualize data on Google Analytics per se, the store has to manually push these events into the `dataLayer` (which we do in our official starters). + +## Partytown and 3rd party scripts + +3rd party scripts are the standard way of integrating an ecommerce with an analytics provider. The problem with these 3rd party scripts is that they are usually very heavy and compete for browser resources when processing and executing javascript as the user loads the page, and that's all bad for performance. + +As stated before, delivering bad performance is not an option for FastStore, so that's where [Partytown](https://partytown.builder.io/) comes into play. Partytown goal is "to help speed up sites by dedicating the main thread to your code, and offloading third-party scripts to a web worker", so scripts that usually compete for browser resources that are used to render the page, per se, no longer do. + +While we recommend using Partytown along with FastStore, we recognize it's not a silver bullet just yet. To start, it doesn't fix the whole problem: stores will still need to download the script bundles. This is not a major issue, but it still (lightly) affects performance when browsing a store using a low bandwidth connection. + +Also, there may be compatibility issues with a few 3rd party scripts. Check out this [Partytown and analytics troubleshooting](https://www.faststore.dev/how-to-guides/troubleshooting/analytics-and-partytown) doc: it goes through the most common issues users may face when using Partytown inside a FastStore project. + +Since Partytown is in the beta stage, some issues are expected to happen. Despite this, what we like most about Partytown is the flexibility it offers: you don't need to use it for every 3rd party script in our store. If you face compatibility issues that cannot be easily resolved, you can move that script (or part of it) outside Partytown, and continue using it for the other scripts that work just fine. + +## Analytics on official starters + +We're always perfecting our official starters to include everything you need to have your store 100% compatible with GA4 Enhanced Ecommerce and Partytown from day 1. When you start your store from one of our official starters, Google Tag Manager and Partytown are automatically included with your store, so you don't have to worry about adding them manually. + +We also use FastStore SDK's analytics module to send and intercept events, concentrating all analytics-related code in a single folder for better understanding and use. + +To understand more about some decisions we had to make and how it all works behind the scenes, read the Analytics on official starters companion blog post (coming soon). + +## The future + +Before we start describing the vision for the future of analytics on FastStore, it's important to highlight that this is just it: a vision. We are not committing to any of the following topics, and we have no clue when they're going to happen or even if they'll come to be. + +That being said, we envision an ever-evolving analytics solution for FastStore. The next topics describe a few things we think are worth considering for the future. + +### Universal Analytics + +We want to make it easy to migrate to FastStore, regardless of where you are coming from. To address that, we intend to support Universal Analytics on our official starters. We still plan to recommend and enforce Google Analytics 4 whenever possible, but we want to give our users and developers the time they need to fully understand and migrate to the new version of Google Analytics. + +### `dataLayer` completeness + +To have rich reports about ecommerce operations, you have to collect rich data. When using Google Analytics and Google Tag Manager, pushing data to the `dataLayer` is the way developers can feed reports with information. + +Currently, our official starters support only GA4 Enhanced Ecommerce capabilities. This is not enough for most stores, which need more data powering their reports, and we want to address this issue. + +There's no definitive answer for which properties we should include in our official starters' `dataLayer` by default, and that's why we want to hear from you. Let us know the most commonly used properties and events you had to include manually in the dataLayer, why they're important and why they should be built into our starters. + +### Analytics libraries for store segments + +Stores usually focus on selling a specific category of products, such as grocery items. That's what we call a store segment. Grocery, fashion, and appliances are all store segments that have specific needs when it comes to design, functionality, and, of course, analytics. + +We think it makes sense to have custom-built events targeted to specific store segments so these stores can fully understand the user behavior. For grocery, per se, it would be super useful to know how many users try to enter their address but there's no store near them or the most popular stores in a given area. + +These libraries would be accompanied by extensive documentation explaining the meaning behind each event, when to fire them, which information to put it, autocomplete for its properties, how to integrate it with Google Analytics, etc. Also, the use of these kinds of libraries would be optional. + +## Zooming out + +FastStore SDK's analytics module, Partytown and the built-in integration offered by official starters make us really excited about our analytics solutions and what's to come. We have a great opportunity to offer a delightful experience to our users, and still not limit them to the choices we've made along the path. The future can also look bright, and we want to hear from you: what would you like to see from the FastStore team regarding analytics? \ No newline at end of file diff --git a/apps/docs/docs/reference/sdk/analytics/how-to-extend-types.md b/apps/docs/docs/reference/sdk/analytics/how-to-extend-types.md index eee454dd00..e81f6eb7b8 100644 --- a/apps/docs/docs/reference/sdk/analytics/how-to-extend-types.md +++ b/apps/docs/docs/reference/sdk/analytics/how-to-extend-types.md @@ -2,7 +2,7 @@ One of the major features the analytics module offers are its types. They're all based on [Google Analytics 4 (GA4) data model](https://developers.google.com/analytics/devguides/collection/ga4/reference/events), and they're especially focused on the [Enhanced Ecommerce](https://support.google.com/tagmanager/answer/6107169) capabilities. -Although the recommended parameters by each analytics providers are often the most important ones, it's quite common to send additional properties to them in order to monitor specific behaviors that are uniquely valuable to a store or a store sectors. +Although the recommended parameters by each analytics providers are often the most important ones, it's quite common to send additional properties to them in order to monitor specific behaviors that are uniquely valuable to a store or a store segment. The analytics module supports this behavior natively and offers ways to make it easy to incorporate it without losing code safety features. It does that by accepting custom types and exporting its own types so that users don't have the need to rewrite all of them to add minor additions. Also, these types are built with generics, which means you can rewrite only a small part of them if you really need to. From a5d3e66c0628f01a8da381139d0ec3613fe46ca8 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=C3=8Dcaro=20Azevedo?= Date: Thu, 14 Jul 2022 11:48:55 -0300 Subject: [PATCH 2/4] chore: moving blog post and adjusting side bar --- .../conceptual-guides}/analytics-on-faststore.md | 0 apps/docs/sidebars.js | 4 +++- 2 files changed, 3 insertions(+), 1 deletion(-) rename apps/docs/{blog => docs/conceptual-guides}/analytics-on-faststore.md (100%) diff --git a/apps/docs/blog/analytics-on-faststore.md b/apps/docs/docs/conceptual-guides/analytics-on-faststore.md similarity index 100% rename from apps/docs/blog/analytics-on-faststore.md rename to apps/docs/docs/conceptual-guides/analytics-on-faststore.md diff --git a/apps/docs/sidebars.js b/apps/docs/sidebars.js index fbb951a524..90a9ce1054 100644 --- a/apps/docs/sidebars.js +++ b/apps/docs/sidebars.js @@ -323,7 +323,9 @@ module.exports = { label: 'Concepts', collapsed: true, link: { type: 'doc', id: 'conceptual-guides' }, - items: ['conceptual-guides/jamstack'], + items: [ + 'conceptual-guides/analytics-on-faststore', + ], }, 'faq', 'resources', From 9ba3aec4a0da0c867706839696c945d38096fe6c Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=C3=8Dcaro=20Azevedo?= Date: Mon, 18 Jul 2022 17:23:13 -0300 Subject: [PATCH 3/4] docs: add Analytics on official starers blog post --- .../analytics-on-faststore.md | 2 +- .../analytics-on-official-starters.md | 106 ++++++++++++++++++ apps/docs/sidebars.js | 1 + 3 files changed, 108 insertions(+), 1 deletion(-) create mode 100644 apps/docs/docs/conceptual-guides/analytics-on-official-starters.md diff --git a/apps/docs/docs/conceptual-guides/analytics-on-faststore.md b/apps/docs/docs/conceptual-guides/analytics-on-faststore.md index cb6e21006d..c2e175b09d 100644 --- a/apps/docs/docs/conceptual-guides/analytics-on-faststore.md +++ b/apps/docs/docs/conceptual-guides/analytics-on-faststore.md @@ -47,7 +47,7 @@ We're always perfecting our official starters to include everything you need to We also use FastStore SDK's analytics module to send and intercept events, concentrating all analytics-related code in a single folder for better understanding and use. -To understand more about some decisions we had to make and how it all works behind the scenes, read the Analytics on official starters companion blog post (coming soon). +To understand more about some decisions we had to make and how it all works behind the scenes, read the [Analytics on official starters](/conceptual-guides/analytics-on-official-starters) companion blog post (coming soon). ## The future diff --git a/apps/docs/docs/conceptual-guides/analytics-on-official-starters.md b/apps/docs/docs/conceptual-guides/analytics-on-official-starters.md new file mode 100644 index 0000000000..8ed8de6c98 --- /dev/null +++ b/apps/docs/docs/conceptual-guides/analytics-on-official-starters.md @@ -0,0 +1,106 @@ +--- +title: Analytics on official starters +description: An overview of our analytics solutions implemented by our official starters and a brief comparison with Store Framework's approach to analytics. +tags: [ga, gtm, google analytics, google tag manager, google, analytics, sdk, faststore, starters, store framework, AnalyticsHandler, gtmContainerId] +hide_table_of_contents: false +--- + +# Analytics on official starters + +:::info +Before reading this article, please read the companion post [Analytics on FastStore](/conceptual-guides/analytics-on-faststore). +::: + +Our official starters are the recommended way to start building with FastStore. These starters are essentially functional stores that are built following performance and accessibility best practices. They serve as our guideline on how you should build your stores and how to leverage the most of the FastStore toolkit. + +All of our official starters have analytics capabilities built-in. We follow the guidelines of the tools we've chosen so we can offer the best experience to developers and achieve completeness of ecommerce tracking capabilities. This article explains how we did it, some of the techniques we used and the main differences from the Store Framework approach to analytics in general. + + +## Official Starters: how we did it + +### Google Tag Manager + +Our official starters include Google Tag Manager (GTM) scripts built-in. This means that developers don't have to worry about adding the GTM script to their page nor configuring debug query strings due to [Partytown limitations](https://www.faststore.dev/how-to-guides/troubleshooting/analytics-and-partytown#google-tag-assistant-is-not-working). Due to this, you'll be able to see two scripts in the `src/components/ThirdPartyScripts/GoogleTagManager.tsx` component: one that runs inside Partytown if the `gtm_debug` query string is not present, and one that runs outside Partytown otherwise. This does not affect performance, since the actual GTM script is only downloaded once. + +### Store config + +You can configure which GTM container you want to use in your store by accessing the file `store.config.js`. There, search for the `gtmContainerId` variable inside the `analytics` object. If no GTM container is provided, the GTM script is not included on the page. + +### Firing events + +In FastStore, you can fire analytics events using the [sendAnalyticsEvent](https://www.faststore.dev/reference/sdk/analytics/sendAnalyticsEvent) function. All [GA4 Enhanced Commerce events](https://developers.google.com/analytics/devguides/collection/ga4/reference/events) are bundled with official starters. They are fired in different places, depending on what should trigger them. + +Official starters also include VTEX Intelligent Search (IS) events. These events are not sent to the dataLayer and are handled differently (more on this in the next sections). They're intentionally different from the ones fired for Google Analytics, so it's easy to add properties to events and to distinguish which properties are relevant to each analytics provider. + +It's every store's responsibility to fire analytics events and to add the appropriate properties to them. No automatic hook or library is doing this magically. If the code that sends these events is deleted, the events will resume being fired. You should always keep an eye when moving or deleting code: you might be removing portions of code that are important to analytics. Always make sure that E2E tests for analytics continue passing. + +### `AnalyticsHandler` component + +When talking about FastStore SDK's analytics module, we usually say it does not automatically send events to any analytics provider, although our official starters do. That's `AnalyticsHandler`'s role. The `AnalyticsHandler` (`src/analytics/index.tsx`) component calls the [useAnalyticsHandler](https://www.faststore.dev/reference/sdk/analytics/useAnalyticsEvent) hook to intercept analytics events. It's in the AnalyticsHandler component events are sent to the appropriate analytics provider, such as GTM, IS or VTEX Request Capture (RC). + +To do all that, this component has to be included in every page, which means it usually lives alongside context providers at the root of the application (`gatsby.(browser-server).tsx` in Gatsby and `src/pages/_app.tsx` in NextJS). + +### Dynamic imports + +Some analytics providers do not require their scripts to be executed as soon as the page is rendered. This is great because it means the code required to do it doesn't have to be downloaded and parsed as soon as a user enters the page, which is important for performance. That's why we use dynamic imports for all VTEX-specific events. + +The code that sends and manages events related to Intelligent Search and Request Capture is only downloaded when an event is sent. We do that by dynamically and lazily importing their scripts. Developers can and should do that with any other analytics provider integrations they add to their store. + +```tsx +import type { AnalyticsEvent } from '@faststore/sdk' +import { useAnalyticsEvent } from '@faststore/sdk' + +import storeConfig from '../../../store.config' + +export const AnalyticsHandler = () => { + useAnalyticsEvent((event: AnalyticsEvent) => { + /* ... */ + + import(`./platform/${storeConfig.platform}`).then( + ({ default: sendEvent }) => { + sendEvent(event) + } + ) + }) + + return null +} +``` + +### Page View events + +Page View events represent the action of visiting a web page. These events can be automatically tracked by Google Analytics 4, but for limitations imposed by Partytown, collecting this metric automatically does not work. To compensate for that, your store should fire these events manually. Unfortunately, official starters do not include this event yet, but we plan to add it soon. Meanwhile, developers can still use the FastStore SDK to manage this event. + +### Partytown proxy + +Partytown requires a proxy for some 3rd party scripts to work. You can see a more detailed explanation [here](https://partytown.builder.io/proxying-requests). This script isn't necessary for GTM and gtag (Google's script used by GA and other solutions), so we haven't added it yet to our starter, but we'll include it in the future. Meanwhile, you can implement your own proxy and follow Partytown's guide on how to set it up. + +## Store Framework contrast + +[VTEX Store Framework](https://vtex.com/br-pt/store-framework/) deals with analytics in its own way. It provides a Google Tag Manager app that is responsible for including the GTM script, including event properties, and adding the events to the dataLayer. In FastStore, there's no equivalent piece. All of that is done in the store itself. Both paradigms bring positive and negative implications. In this section, we'll go through important topics that highlight the contrast between the FastStore approach and the Store Framework approach when handling analytics. + +### Freedom + +The FastStore way of approaching analytics gives developers freedom. They are not tied in any way to any of the choices we've made for starters or FastStore SDK. You can fire your own events, customize them with your own types, and add your properties of choice. This empowers developers and store managers to collect data in the way they prefer, to achieve their unique objectives. We have guides on [How to extend and customize types](https://www.faststore.dev/reference/sdk/analytics/how-to-extend-types) and [How to send custom events](https://www.faststore.dev/reference/sdk/analytics/how-to-send-custom-events). + +This is quite different from the Store Framework approach. If you need to deviate even a little from the Google Tag Manager app choices, events and properties, you'll need to detach from the whole app, creating your own implementation. Still, you'll be limited by the DOM events fired by native apps and blocks and the information they contain. If you want to change that, you'll have to detach from the native apps, which defeats the purpose of using Store Framework. + +While Store Framework offers a more all-or-nothing approach to analytics that is easier to handle and maintain, FastStore focus on the freedom and power analytics solutions usually require to fulfill the needs of every store, offering more nuanced tools. FastStore also makes using [GA custom dimensions](https://support.google.com/analytics/answer/2709828) very easy, which is great for building custom reports and adding custom data to reports. + +### Responsibility + +With great power comes great responsibility. While FastStore gives the freedom developers need to build the analytics solutions they need, it deposits the responsibility of doing so on these developers. The events won't fire if you simply install FastStore SDK, nor will they be complete for every case. You have to fire the event you want at the right moment with the information you need, and that's up to you. Of course, official starters include GA4 Enhanced Ecommerce events, but that can also be deleted if developers are negligent. Maintainers have to actively care about their analytics implementation. + +Store Framework gives analytics events for free. You barely have to worry about it if you use the native GTM app and native blocks to compose your pages. This is great, but it comes with the limitations we've talked about in the previous section. The main takeaway here is that with FastStore, you'll have to worry about if your analytics implementation is correct, and we think that's a good thing. + +### Visibility + +With Store Framework, it's very hard to know where or when an event is fired. This makes it difficult to debug problems and customize events. In FastStore, everything lives in your store repository. Just search for [sendAnalyticsEvent](https://www.faststore.dev/reference/sdk/analytics/sendAnalyticsEvent) calls and you'll see where events are being fired and the conditions for that to happen. + +Also, FastStore provides E2E tests for all GA4 Enhanced Ecommerce analytics events it includes, so you can quickly know if something wrong with your analytics implementation. You'll be able to fix these issues before you start to lose valuable user data. + +## Help us + +As we've mentioned before, we include GA4 Enhanced Ecommerce events with FastStore starters. We're always trying to follow Google guidelines on how to implement these events, but it's possible we made some mistakes while doing so. We want developers to use the freedom, responsibility and visibility they have to fix these issues in the stores they are working on, but we also want to improve our starters so that other developers can have the best experience using FastStore and our analytics tools. + +Help us! If you've found any inconsistency between GA4 Enhanced Ecommerce guidelines and our implementation or you just wish we added something to our starters to help you build your analytics solutions, please let us know. diff --git a/apps/docs/sidebars.js b/apps/docs/sidebars.js index 90a9ce1054..35783f876b 100644 --- a/apps/docs/sidebars.js +++ b/apps/docs/sidebars.js @@ -325,6 +325,7 @@ module.exports = { link: { type: 'doc', id: 'conceptual-guides' }, items: [ 'conceptual-guides/analytics-on-faststore', + 'conceptual-guides/analytics-on-starters', ], }, 'faq', From f2dfecdecc826c83c49d2e9e9cd0bb5b30d4317e Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=C3=8Dcaro=20Azevedo?= Date: Mon, 18 Jul 2022 17:31:31 -0300 Subject: [PATCH 4/4] fix: sidebar link --- apps/docs/sidebars.js | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/apps/docs/sidebars.js b/apps/docs/sidebars.js index 35783f876b..9125bc0392 100644 --- a/apps/docs/sidebars.js +++ b/apps/docs/sidebars.js @@ -325,7 +325,7 @@ module.exports = { link: { type: 'doc', id: 'conceptual-guides' }, items: [ 'conceptual-guides/analytics-on-faststore', - 'conceptual-guides/analytics-on-starters', + 'conceptual-guides/analytics-on-official-starters', ], }, 'faq',