# @ad-execute-manager/analytics

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

## Installation

```bash
npm install @ad-execute-manager/analytics
```

## Features

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

## Usage

### AdAnalyticsJS

```javascript
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: 'john@example.com'
});

// 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. 用户行为追踪

```javascript
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. 用户身份识别

```javascript
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: 'john@example.com',
  role: 'admin'
});
```

#### 3. 页面浏览追踪

```javascript
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. 广告执行分析

```javascript
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

```javascript
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