ngx-umami (英语)

角库 Umami 分析 - 一个注重隐私、轻量级分析平台.

特征

• 🚀 简单设置 - 简单的独立配置 provideUmami()
• 📊 事件跟踪 - 跟踪带有可选数据有效载荷的自定义事件
• 🔄 路由器集成 - 在路由更改时自动查看页面
• 🎯 指令 - 申报活动跟踪 umamiTrack 指令
• 🔒 隐私第一 - 尊重不跟踪,符合GDPR
• 🌐 SSR 兼容性 - 与Angular Universal/SSR合作
• 📦 树能震动 - 只包括你使用的东西

兼容性

安装

# Recommended
pnpm add @cacic-fct/ngx-umami

# Or with npm
npm install @cacic-fct/ngx-umami

# Or with yarn
yarn add @cacic-fct/ngx-umami

说明: 我们建议使用 小时 用于更快的安装和更好的磁盘空间效率.

快速启动

1. 在应用程序中配置

// app.config.ts
import { ApplicationConfig } from '@angular/core';
import { provideRouter } from '@angular/router';
import { provideUmami, withRouterTracking } from '@cacic-fct/ngx-umami';

export const appConfig: ApplicationConfig = {
  providers: [
    provideRouter(routes),
    provideUmami({
      websiteId: 'your-website-id',
      src: 'https://analytics.yourdomain.com/script.js'
    }),
    // Optional: Enable automatic page view tracking on route changes
    withRouterTracking()
  ]
};

2. 各组成部分的跟踪活动

import { Component } from '@angular/core';
import { injectUmami } from '@cacic-fct/ngx-umami';

@Component({
  selector: 'app-checkout',
  template: `<button (click)="onPurchase()">Buy Now</button>`
})
export class CheckoutComponent {
  private umami = injectUmami();

  onPurchase() {
    this.umami.trackEvent('purchase', {
      product: 'Premium Plan',
      price: 99.99,
      currency: 'USD'
    });
  }
}

3. 或使用指令

import { Component } from '@angular/core';
import { UmamiTrackDirective } from '@cacic-fct/ngx-umami';

@Component({
  selector: 'app-signup',
  standalone: true,
  imports: [UmamiTrackDirective],
  template: `
    <button umamiTrack="signup_click">Sign Up</button>

    <button
      umamiTrack="cta_click"
      [umamiTrackData]="{ location: 'header', variant: 'blue' }">
      Get Started
    </button>
  `
})
export class SignupComponent {}

配置选项

provideUmami({
  // Required
  websiteId: 'your-website-id',  // From Umami dashboard
  src: 'https://analytics.example.com/script.js',  // Your Umami script URL

  // Optional
  enabled: true,              // Enable/disable tracking (default: true)
  autoTrack: true,            // Auto track page views (default: true)
  doNotTrack: false,          // Honor browser DNT setting (default: false)
  domains: ['example.com'],   // Restrict to specific domains
  tag: 'production',          // Tag for filtering in dashboard
  excludeSearch: false,       // Exclude URL search params
  excludeHash: false,         // Exclude URL hash
  hostUrl: 'https://proxy.example.com'  // Custom data endpoint
})

API 参考

Umami服务

trackPageView(payload?)

手动跟踪页面视图.

umami.trackPageView();

umami.trackPageView({
  url: '/custom-page',
  title: 'Custom Page Title',
  referrer: 'https://google.com'
});

trackEvent(eventName, eventData?)

跟踪自定义事件 .

// Simple event
umami.trackEvent('button_click');

// Event with data (max 50 properties)
umami.trackEvent('form_submit', {
  formName: 'contact',
  fields: 5,
  hasAttachment: true
});

identify(sessionIdOrData, sessionData?)

识别用户会话.

// With session ID
umami.identify('user-123');

// With session ID and data
umami.identify('user-123', {
  plan: 'premium',
  role: 'admin'
});

// With data only
umami.identify({
  plan: 'premium',
  signupDate: '2024-01-15'
});

isAvailable()

检查是否有可用的跟踪 .

if (umami.isAvailable()) {
  umami.trackEvent('ready');
}

disable()

程序上禁用跟踪 .

umami.disable();

Umami 跟踪指令

关于DOM元素的宣告事件跟踪.

<!-- Track click events -->
<button umamiTrack="signup">Sign Up</button>

<!-- With event data -->
<button
  umamiTrack="download"
  [umamiTrackData]="{ file: 'report.pdf', size: 1024 }">
  Download
</button>

<!-- Track different events -->
<input
  umamiTrack="search_focus"
  umamiTrackOn="focus"
  placeholder="Search...">

<form
  umamiTrack="form_submit"
  umamiTrackOn="submit">
  <!-- form fields -->
</form>

支持的活动 : click, (中文(简体) ), focus, (中文(简体) ), blur, (中文(简体) ), mouseenter, (中文(简体) ), mouseleave, (中文(简体) ), submit

与鲁特跟踪( )

在角路由器导航上启用自动页面视图跟踪 .

// app.config.ts
providers: [
  provideRouter(routes),
  provideUmami({
    websiteId: 'xxx',
    src: 'https://...',
    autoTrack: false  // Disable Umami's auto-track since router handles it
  }),
  withRouterTracking()
]

提供Umami与事实( )

使用工厂功能配置有依赖性注射的 Umami .

import { provideUmamiWithFactory } from '@cacic-fct/ngx-umami';
import { ConfigService } from './config.service';

providers: [
  provideUmamiWithFactory(
    (config: ConfigService) => ({
      websiteId: config.umamiWebsiteId,
      src: config.umamiSrc,
      enabled: config.isProduction
    }),
    [ConfigService]
  )
]

环境配置

// environments/environment.ts
export const environment = {
  production: false,
  umami: {
    websiteId: 'dev-website-id',
    src: 'https://analytics.example.com/script.js',
    enabled: false  // Disable in development
  }
};

// environments/environment.prod.ts
export const environment = {
  production: true,
  umami: {
    websiteId: 'prod-website-id',
    src: 'https://analytics.example.com/script.js',
    enabled: true
  }
};

// app.config.ts
import { environment } from './environments/environment';

providers: [
  provideUmami(environment.umami)
]

安全部门改革的考虑因素

库会自动处理服务器侧渲染. 跟踪只在浏览器环境中活动 - 不需要配置 .

许可证

麻省理工学院