enable-analytics

작성자: vercel

스토어프론트에 Vercel Analytics, Vercel Speed Insights 및 Google Tag Manager를 추가합니다.

npx skills add https://github.com/vercel/shop --skill enable-analytics

Enable Analytics

The current storefront includes support for Vercel Web Analytics and Vercel Speed Insights, with each integration disabled by default in lib/config/index.ts. This skill enables or adds those integrations and can also add Google Tag Manager using the recommended integration.

Before you start

Ask the user two questions in order:

1. Do you need to add or change Vercel Analytics and/or Vercel Speed Insights?

Enable both — page views, custom events, and Core Web Vitals
Analytics only — page view and custom event tracking via @vercel/analytics
Speed Insights only — Core Web Vitals monitoring via @vercel/speed-insights
Neither — keep both integrations disabled

2. Do you want Google Tag Manager?

If yes, ask for the GTM container ID (e.g. GTM-XXXXXX). This will be stored in the NEXT_PUBLIC_GTM_ID environment variable.

Wait for the user to answer both questions before proceeding.

Part A: Vercel Analytics and Speed Insights

If the storefront has analytics configuration in lib/config/index.ts, enable only the selected integrations. If the user selected neither, keep both integration gates disabled and skip the remaining steps in this section.

analytics: {
  shopify: { consentMode: "default-banner", isEnabled: false },
  speedInsights: { isEnabled: false },
  vercel: { isEnabled: false },
},

The shopify gate is separate: it controls Shopify storefront analytics, which the storefront already ships. Leave it alone unless the user asked about Shopify analytics, and see Part D.

A1. Install dependencies

For older storefronts without the integrations, install only the packages the user selected:

# Both
pnpm add @vercel/analytics @vercel/speed-insights

# Analytics only
pnpm add @vercel/analytics

# Speed Insights only
pnpm add @vercel/speed-insights

For older storefronts, create or update the root analytics component described below. Each library handles its own client-side behavior internally.

Part B: Google Tag Manager

Skip this section if the user did not want GTM.

B1. Install dependency

pnpm add @next/third-parties

B2. Add environment variable

Add to .env.example:

# Google Tag Manager (optional)
NEXT_PUBLIC_GTM_ID="GTM-XXXXXX"

Set the actual value in .env.local or in the Vercel dashboard under Environment Variables.

B3. Add GTM to `components/analytics/index.tsx`

Import GoogleTagManager from @next/third-parties/google. Read NEXT_PUBLIC_GTM_ID in the analytics component and render <GoogleTagManager gtmId={gtmId} /> only when the value exists. If the storefront extends lib/config/index.ts with a GTM integration gate, apply that gate inside the same component.

Part C: Root analytics integration

C1. Update `components/analytics/index.tsx`

Extend the existing root analytics component. Do not create a sibling components/analytics.tsx, which would shadow the directory import. Preserve ShopifyScriptsTracker, its shop data, and the existing consent integration while adding the selected providers:

import { GoogleTagManager } from "@next/third-parties/google";
import { Analytics } from "@vercel/analytics/next";
import { SpeedInsights } from "@vercel/speed-insights/next";

import { shopConfig } from "@/lib/config";
import { getShopAnalytics } from "@/lib/analytics/server";

import { ShopifyScriptsTracker } from "./shopify-client";

export async function AnalyticsComponents() {
  const gtmId = process.env.NEXT_PUBLIC_GTM_ID;

  return (
    <>
      {shopConfig.analytics.vercel.isEnabled ? <Analytics /> : null}
      {shopConfig.analytics.speedInsights.isEnabled ? <SpeedInsights /> : null}
      {gtmId ? <GoogleTagManager gtmId={gtmId} /> : null}
      <ShopifyScriptsTracker
        shop={await getShopAnalytics({})}
        storefrontId={process.env.NEXT_PUBLIC_SHOPIFY_STOREFRONT_ID ?? ""}
      />
    </>
  );
}

Remove imports for integrations the storefront does not support.

C2. Update `app/layout.tsx`

Render the root analytics component near the end of <body>. The default has inline component copy, not a translation provider; in an already localized installation, preserve its scoped translation-provider boundaries:

import { AnalyticsComponents } from "@/components/analytics";

<body ...>
  {/* ... existing layout content and scoped providers ... */}
  <Suspense>
    <AnalyticsComponents />
  </Suspense>
</body>

Do not add next-intl or a root message catalog for analytics. In a customized localized storefront, preserve any required commerce locale prop and existing scoped providers; do not pass the complete catalog to a root NextIntlClientProvider. The root component remains mounted as the extension point for current and future analytics providers. Provider gates stay inside it so disabled integrations are not mounted.

Part D: Shopify storefront analytics

Only make changes here if the user asked about Shopify analytics.

The storefront sends page, product, collection, search, cart-view, and confirmed cart-change events through Hydrogen's analytics bus. It is disabled by default and requires no credentials beyond the Storefront API variables the storefront already needs. To turn Shopify's built-in analytics destination on, set analytics.shopify.isEnabled to true in lib/config/index.ts.

Consent mode is set by analytics.shopify.consentMode in lib/config/index.ts and defaults to default-banner, which renders Shopify's hosted privacy banner for visitors in regions that require consent. Use custom-banner when the storefront supplies its own consent UI. Do not ship no-banner in production unless consent is handled elsewhere, because visitors in those regions can never grant consent and their events are dropped.

Third-party analytics can subscribe through the same destination API, so consent gating and buffered replay remain centralized. Register destinations with addAnalyticsDestination() from lib/analytics/client.ts; do not publish cart-change events manually.

Guardrails

Keep root analytics providers and their gates in components/analytics/index.tsx; preserve the existing Shopify scripts and consent integration.
Always mount <AnalyticsComponents /> from the root layout, even when every provider is disabled.
The GTM container ID must come from NEXT_PUBLIC_GTM_ID, never hardcoded. The provider renders nothing if the env var is missing.
Use @next/third-parties/google for GTM, not a manual <script> tag. The Next.js component handles script loading and performance optimization.
Import paths: use @vercel/analytics/next and @vercel/speed-insights/next (the /next subpath), not the root package exports.
Add NEXT_PUBLIC_GTM_ID to .env.example with a placeholder value so other developers know the variable exists.