@ad-execute-manager/analytics

A collection of analytics tools for tracking user behavior and ad execution metrics including AdAnalyticsJS.

Installation

npm install @ad-execute-manager/analytics

Features

• AdAnalyticsJS: A comprehensive analytics SDK for collecting user behavior data and tracking events

Usage

AdAnalyticsJS

import { AdAnalyticsJS } from '@ad-execute-manager/analytics';

// Create analytics instance
const analytics = AdAnalyticsJS.new({
  sign: 'app',
  log: true,
  needReport: true,
  commonConfig: {
    app_version: '1.0.0',
    platform: 'web'
  }
});

// Initialize analytics
analytics.initialize({
  sign: 'app',
  log: true,
  needReport: true,
  commonConfig: {
    app_version: '1.0.0',
    platform: 'web'
  }
});

// Track custom event
analytics.track('button_click', {
  button_name: 'submit',
  page: 'home'
});

// Identify user
analytics.identify('user123', {
  name: 'John Doe',
  email: '[email protected]'
});

// Track page view
analytics.page('cpage', {
  page_name: 'home',
  page_url: '/home'
});

// Track current page
analytics.cpage({
  page_name: 'home',
  page_url: '/home'
});

Examples

实际应用场景示例

1. 用户行为追踪

import { AdAnalyticsJS } from '@ad-execute-manager/analytics';

// 创建分析实例
const analytics = AdAnalyticsJS.new({
  sign: 'app',
  log: true,
  needReport: true,
  commonConfig: {
    app_version: '1.0.0',
    platform: 'web'
  }
});

// 初始化分析
analytics.initialize({
  sign: 'app',
  log: true,
  needReport: true,
  commonConfig: {
    app_version: '1.0.0',
    platform: 'web'
  }
});

// 追踪按钮点击事件
function trackButtonClick(buttonName, page) {
  analytics.track('button_click', {
    button_name: buttonName,
    page: page,
    timestamp: Date.now()
  });
}

// 追踪表单提交事件
function trackFormSubmit(formName, formData) {
  analytics.track('form_submit', {
    form_name: formName,
    form_data: formData,
    timestamp: Date.now()
  });
}

// 使用示例
trackButtonClick('submit', 'home');
trackFormSubmit('login', { username: 'john' });

2. 用户身份识别

import { AdAnalyticsJS } from '@ad-execute-manager/analytics';

// 创建分析实例
const analytics = AdAnalyticsJS.new({
  sign: 'app',
  log: true,
  needReport: true
});

// 用户登录后识别用户身份
function handleUserLogin(user) {
  analytics.identify(user.id, {
    name: user.name,
    email: user.email,
    role: user.role
  });
  
  // 追踪登录事件
  analytics.track('user_login', {
    user_id: user.id,
    login_method: 'email'
  });
}

// 用户登出时清除用户信息
function handleUserLogout() {
  analytics.identify(null, {});
  
  // 追踪登出事件
  analytics.track('user_logout', {
    timestamp: Date.now()
  });
}

// 使用示例
handleUserLogin({
  id: 'user123',
  name: 'John Doe',
  email: '[email protected]',
  role: 'admin'
});

3. 页面浏览追踪

import { AdAnalyticsJS } from '@ad-execute-manager/analytics';

// 创建分析实例
const analytics = AdAnalyticsJS.new({
  sign: 'app',
  log: true,
  needReport: true
});

// 页面路由变化时追踪页面浏览
function trackPageView(pageName, pageUrl) {
  analytics.cpage({
    page_name: pageName,
    page_url: pageUrl,
    timestamp: Date.now()
  });
}

// SPA 路由变化监听
function setupRouteTracking() {
  window.addEventListener('popstate', () => {
    const currentPath = window.location.pathname;
    trackPageView('route_change', currentPath);
  });
}

// 手动触发页面浏览
function navigateToPage(pageName, pageUrl) {
  // 导航逻辑
  window.history.pushState({}, '', pageUrl);
  
  // 追踪页面浏览
  trackPageView(pageName, pageUrl);
}

// 使用示例
setupRouteTracking();
navigateToPage('home', '/home');
navigateToPage('profile', '/profile');

4. 广告执行分析

import { AdAnalyticsJS } from '@ad-execute-manager/analytics';

// 创建分析实例
const analytics = AdAnalyticsJS.new({
  sign: 'app',
  log: true,
  needReport: true,
  commonConfig: {
    app_version: '1.0.0',
    platform: 'web'
  }
});

// 追踪广告展示事件
function trackAdShow(adData) {
  analytics.track('ad_show', {
    ad_unit_id: adData.adUnitId,
    ad_type: adData.adType,
    scene: adData.scene,
    timestamp: Date.now()
  });
}

// 追踪广告点击事件
function trackAdClick(adData) {
  analytics.track('ad_click', {
    ad_unit_id: adData.adUnitId,
    ad_type: adData.adType,
    scene: adData.scene,
    timestamp: Date.now()
  });
}

// 追踪广告完成事件
function trackAdComplete(adData) {
  analytics.track('ad_complete', {
    ad_unit_id: adData.adUnitId,
    ad_type: adData.adType,
    scene: adData.scene,
    duration: adData.duration,
    timestamp: Date.now()
  });
}

// 追踪广告失败事件
function trackAdFail(adData, error) {
  analytics.track('ad_fail', {
    ad_unit_id: adData.adUnitId,
    ad_type: adData.adType,
    scene: adData.scene,
    error_message: error.message,
    error_code: error.code,
    timestamp: Date.now()
  });
}

// 使用示例
trackAdShow({
  adUnitId: 'reward_ad_1',
  adType: 'rewarded_video',
  scene: 'home_page'
});

trackAdClick({
  adUnitId: 'reward_ad_1',
  adType: 'rewarded_video',
  scene: 'home_page'
});

trackAdComplete({
  adUnitId: 'reward_ad_1',
  adType: 'rewarded_video',
  scene: 'home_page',
  duration: 30000
});

trackAdFail({
  adUnitId: 'reward_ad_1',
  adType: 'rewarded_video',
  scene: 'home_page'
}, {
  message: 'Ad load failed',
  code: 'LOAD_ERROR'
});

API

AdAnalyticsJS

Constructor

new AdAnalyticsJS(args)

• args (Object): 构造函数参数
  • sign (String): 初始化标识
  • log (Boolean, optional): 是否开启日志，默认 true
  • needReport (Boolean, optional): 是否需要上报，默认 false
  • commonConfig (Object, optional): 公共用户信息

Methods

• initialize(args): 初始化方法，用于环境配置、API 地址、日志等级等

  • args (Object): 初始化参数
    • sign (String): 初始化标识
    • log (Boolean, optional): 是否开启日志
    • needReport (Boolean, optional): 是否需要上报
    • commonConfig (Object, optional): 公共用户信息
  • 返回: 初始化参数

• track(eventName, properties, debugParams): 追踪自定义事件

  • eventName (String): 事件名称
  • properties (Object): 事件属性
  • debugParams (Object, optional): 调试参数
    • sign (String, optional): 是否启用调试模式
  • 返回: void

• page(eventName, properties): 追踪页面浏览

  • eventName (String): 事件名称
  • properties (Object): 事件属性
  • 返回: void

• cpage(properties): 追踪当前页面

  • properties (Object): 事件属性
  • 返回: void

• identify(user_id, info): 识别用户身份

  • user_id (String|Number): 用户 ID
  • info (Object): 用户信息
  • 返回: AdAnalyticsJS 实例，支持链式调用

• alias(): 合并用户身份，匿名用户转为登录用户

  • 返回: null

• pages(): 追踪页面浏览，SPA 路由切换，或手动触发页面事件

  • 返回: null

• getCommonInfo(): 获取公共用户信息

  • 返回: Object，公共用户信息

• placeholder(): 站位方法，没有任何作用

  • 返回: null

• static build(args): 获取单例实例

  • args (Object): 构造函数参数
  • 返回: AdAnalyticsJS 实例

• static getInstance(): 获取单例实例

  • 返回: AdAnalyticsJS 实例

• static new(args): 创建新实例

  • args (Object): 构造函数参数
  • 返回: AdAnalyticsJS 实例

License

MIT