@labring/sealos-gtm-sdk
v1.0.1
Published
Google Tag Manager integration for Sealos applications
Readme
@labring/sealos-gtm-sdk
Google Tag Manager integration for Sealos applications with full TypeScript support.
Features
- 🎯 Simple API: Vercel Analytics-style
track()function - 📝 TypeScript: Complete type safety with Sealos GTM event schema
- ⚡ Fast Setup: Support for both Pages Router and App Router
- 🔧 Flexible: Use predefined events or custom tracking
- 🐛 Debug Mode: Built-in debugging for development
Installation
pnpm add @labring/sealos-gtm-sdkQuick Start
1. Simple Setup (Recommended)
Add GTM component to your _app.tsx:
// pages/_app.tsx
import { GTMScript } from '@labring/sealos-gtm-sdk';
import type { AppProps } from 'next/app';
export default function App({ Component, pageProps }: AppProps) {
return (
<>
<GTMScript
gtmId={process.env.NEXT_PUBLIC_GTM_ID!}
enabled={!!process.env.NEXT_PUBLIC_GTM_ID}
debug={process.env.NODE_ENV === 'development'}
/>
<Component {...pageProps} />
</>
);
}2. App Router
// app/layout.tsx
import { GTMScript } from '@labring/sealos-gtm-sdk';
export default function RootLayout({ children }: { children: React.ReactNode }) {
return (
<html lang="en">
<head>
<GTMScript
gtmId={process.env.NEXT_PUBLIC_GTM_ID!}
enabled={!!process.env.NEXT_PUBLIC_GTM_ID}
debug={process.env.NODE_ENV === 'development'}
/>
</head>
<body>{children}</body>
</html>
);
}3. Advanced Setup (via _document.tsx)
If you need more control, configure in _document.tsx:
// pages/_document.tsx
import { getGTMScripts, getDataLayerScript } from '@labring/sealos-gtm-sdk';
import Document, { DocumentContext, Head, Html, Main, NextScript } from 'next/document';
import Script from 'next/script';
class MyDocument extends Document {
static async getInitialProps(ctx: DocumentContext) {
const initialProps = await Document.getInitialProps(ctx);
const gtmConfig = getGTMScripts({
gtmId: process.env.NEXT_PUBLIC_GTM_ID || '',
enabled: !!process.env.NEXT_PUBLIC_GTM_ID,
debug: process.env.NODE_ENV === 'development'
});
return {
...initialProps,
scripts: [...(scripts || []), ...gtmConfig.scripts],
noscripts: [...(noscripts || []), ...gtmConfig.noscripts]
};
}
render() {
const { scripts = [], noscripts = [] } = this.props;
return (
<Html lang="en">
<Head>
<script dangerouslySetInnerHTML={{ __html: getDataLayerScript() }} />
{scripts?.map((item, i) => (
<Script key={i} {...item} />
))}
</Head>
<body>
{noscripts?.map((item, i) => (
<noscript key={i} {...item} />
))}
<Main />
<NextScript />
</body>
</Html>
);
}
}4. Environment Variables
# .env.local
NEXT_PUBLIC_GTM_ID=GTM-XXXXXXXUsage
Simple Tracking (Vercel Analytics Style)
import { track } from '@labring/sealos-gtm-sdk';
// Simple event tracking
track('module_open', { module: 'devbox' });
// Complex event tracking
track('deployment_create', {
module: 'devbox',
config: { template_name: 'php' },
resources: { cpu_cores: 1, ram_mb: 1024 }
});All Event Types
import { track } from '@labring/sealos-gtm-sdk';
// Module events
track('module_open', { module: 'devbox' });
track('module_view', { module: 'applaunchpad', view_name: 'logs' });
// Deployment events
track('deployment_start', { module: 'devbox' });
track('deployment_create', {
module: 'devbox',
config: { template_name: 'php', template_version: '7.4' },
resources: { cpu_cores: 1, ram_mb: 1024 }
});
// App launch
track('app_launch', {
module: 'desktop',
app_name: 'wordpress',
source: 'appstore'
});
// Auth events
track('login_start', { module: 'auth' });
track('login_success', {
module: 'auth',
method: 'oauth2',
oauth2_provider: 'google',
user_type: 'new'
});
// Workspace events
track('workspace_create', { module: 'workspace' });
track('workspace_invite', { module: 'workspace', invite_role: 'developer' });
// Error tracking
track('error_occurred', { module: 'devbox', error_code: 'NAME_ALREADY_IN_USE' });TypeScript Support
import { track, GTMEvent, DeploymentCreateEvent } from '@labring/sealos-gtm-sdk';
// Type-safe event tracking
const event: DeploymentCreateEvent = {
event: 'deployment_create',
context: 'app',
module: 'devbox',
config: { template_name: 'php' }
};
track(event);Configuration
import { configureGTM } from '@labring/sealos-gtm-sdk';
// Configure debugging and enable/disable tracking
configureGTM({
enabled: process.env.NODE_ENV === 'production',
debug: process.env.NODE_ENV === 'development'
});Supported Events
Module Events
module_open- When a module is openedmodule_view- When navigating within a module
App Events
app_launch- When launching apps from desktop
Deployment Events
deployment_start- Starting a deploymentdeployment_create- Deployment completeddeployment_update- Updating a deploymentdeployment_delete- Deleting a deploymentdeployment_shutdown- Shutting down a deploymentdeployment_details- Viewing deployment details
Workspace Events
workspace_create- Creating a workspaceworkspace_delete- Deleting a workspaceworkspace_switch- Switching workspacesworkspace_invite- Inviting membersworkspace_join- Joining via invite
Guide Events
guide_start- Starting a guideguide_complete- Completing a guideguide_exit- Exiting a guide
Other Events
ide_open- Opening IDErelease_create- Creating a releaseerror_occurred- Error trackingpaywall_triggered- Paywall eventsannouncement_click- Announcement interactions
Module Support
All Sealos modules are supported:
desktop,devbox,database,applaunchpadappstore,costcenter,workspace,guideaiproxy,kubepanel,objectstorage,cronjob,terminal
Development
# Build the package
pnpm build
# Watch mode for development
pnpm dev
# Clean build files
pnpm cleanLicense
MIT