# Ads Tracking Service - Dịch vụ Theo dõi Quảng cáo

> Microservice xử lý pixel tracking, attribution và conversion tracking cho quảng cáo.

## Tổng Quan

Ads Tracking Service theo dõi hành trình người dùng sau khi tương tác với quảng cáo:

- **Pixel Tracking** - Theo dõi hành vi trên website/app
- **Server-side Tracking** - Conversion API không phụ thuộc cookies
- **Attribution** - Xác định nguồn conversion
- **Multi-touch Attribution** - Phân bổ công lao cho nhiều touchpoints

## Yêu Cầu

| Yêu cầu | Phiên bản |
|---------|-----------|
| .NET SDK | 10.0.101+ |
| Docker | 24.0+ |
| PostgreSQL/TimescaleDB | 15+ |

## Bắt Đầu Nhanh

```bash
cd services/ads-tracking-service-net
docker-compose up -d
```

## Cấu Trúc Dự Án

```
ads-tracking-service-net/
├── src/
│   ├── AdsTrackingService.API/
│   │   ├── Controllers/
│   │   │   ├── PixelsController.cs
│   │   │   ├── EventsController.cs
│   │   │   └── ConversionsController.cs
│   │   └── Application/
│   │
│   ├── AdsTrackingService.Domain/
│   │   └── AggregatesModel/
│   │       ├── TrackingPixelAggregate/
│   │       ├── ConversionAggregate/
│   │       └── AttributionAggregate/
│   │
│   └── AdsTrackingService.Infrastructure/
│
└── AdsTrackingService.slnx
```

## Pixel Events

| Event | Mô tả |
|-------|-------|
| `PageView` | Xem trang |
| `ViewContent` | Xem sản phẩm |
| `AddToCart` | Thêm vào giỏ |
| `InitiateCheckout` | Bắt đầu thanh toán |
| `Purchase` | Hoàn tất mua hàng |
| `Lead` | Đăng ký thông tin |

## Attribution Windows

| Model | Click Window | View Window |
|-------|--------------|-------------|
| **7-day click** | 7 ngày | - |
| **1-day view** | - | 1 ngày |
| **7/1** (default) | 7 ngày | 1 ngày |
| **28/1** | 28 ngày | 1 ngày |

## API Endpoints

### Pixels

| Method | Endpoint | Mô tả |
|--------|----------|-------|
| `GET` | `/api/v1/ads-tracking/pixels/{advertiserId}` | Lấy pixel code |
| `POST` | `/api/v1/ads-tracking/pixels` | Tạo pixel mới |

### Events

| Method | Endpoint | Mô tả |
|--------|----------|-------|
| `POST` | `/api/v1/ads-tracking/events` | Gửi event (pixel) |
| `POST` | `/api/v1/ads-tracking/events/server` | Server-side event |

### Conversions

| Method | Endpoint | Mô tả |
|--------|----------|-------|
| `GET` | `/api/v1/ads-tracking/conversions` | Danh sách conversions |
| `GET` | `/api/v1/ads-tracking/conversions/{id}/attribution` | Chi tiết attribution |

## Admin Office APIs

### Admin Pixels Management

| Method | Endpoint | Mô tả |
|--------|----------|-------|
| `GET` | `/api/v1/admin/ads-tracking/pixels` | Danh sách tất cả pixels (phân trang) |
| `GET` | `/api/v1/admin/ads-tracking/pixels/{id}/events` | Lịch sử events của pixel |
| `GET` | `/api/v1/admin/ads-tracking/pixels/{id}/stats` | Thống kê pixel |
| `PUT` | `/api/v1/admin/ads-tracking/pixels/{id}/activate` | Kích hoạt pixel |
| `PUT` | `/api/v1/admin/ads-tracking/pixels/{id}/deactivate` | Vô hiệu hóa pixel |

### Admin Conversions Analytics

| Method | Endpoint | Mô tả |
|--------|----------|-------|
| `GET` | `/api/v1/admin/ads-tracking/conversions` | Danh sách conversions (có bộ lọc) |
| `GET` | `/api/v1/admin/ads-tracking/conversions/stats` | Thống kê conversions |
| `GET` | `/api/v1/admin/ads-tracking/conversions/{id}` | Chi tiết conversion |

### Admin Attribution Reports

| Method | Endpoint | Mô tả |
|--------|----------|-------|
| `GET` | `/api/v1/admin/ads-tracking/attribution/stats` | Thống kê attribution theo model |
| `GET` | `/api/v1/admin/ads-tracking/attribution/campaigns/{id}` | Báo cáo attribution theo campaign |

## Pixel Integration

```html
<!-- Paste this code in your website <head> -->
<script>
!function(g,o,od,go){g.ggq=g.ggq||[];var n=o.createElement('script');
n.async=1;n.src='https://tracking.goodgo.com/pixel.js';
o.body.appendChild(n)}(window,document);
ggq('init', 'PIXEL_ID');
ggq('track', 'PageView');
</script>
```

## Tích Hợp

| Service | Tích hợp |
|---------|---------|
| **ads-serving-service** | Consume impression/click events |
| **ads-analytics-service** | Publish attributed conversions |

## Giấy Phép

Độc quyền - GoodGo Platform
