# Quang Cao Shopee (Shopee Ads Management)

## Tong quan

Chuc nang **Quang cao Shopee** cho phep nguoi ban quan ly cac chien dich quang cao (Shopee Ads / PAS - Product Ads Service) truc tiep tu AutoShopee Kit. Thay vi thao tac tren Shopee Seller Center, nguoi ban co the xem danh sach chien dich, quan ly tu khoa (keyword) va cap nhat gia thau hang loat.

**Tinh nang chinh:**
- Xem danh sach tat ca chien dich quang cao (Campaign)
- Quan ly tu khoa cho tung chien dich
- Them tu khoa don le hoac hang loat
- Cap nhat gia thau va loai tu khoa
- Import tu khoa tu bo suu tap (Keyword Collection)
- Copy tu khoa sang bo suu tap khac
- Xuat danh sach tu khoa ra file Excel

**Yeu cau:** Tai khoan tra phi (Premium) - giao dien duoc boc boi `wrap-require-paid`.

---

## Giao dien

### Trang danh sach chien dich

**Duong dan:** `Shopee > Seller > Ads` (`/shopee/seller/ads`)

Hien thi bang danh sach cac chien dich quang cao voi cac cot:

| Cot | Mo ta |
|-----|-------|
| **#** | So thu tu |
| **Loai** (Type) | Loai chien dich: Keyword (tim kiem), Shop (cua hang) |
| **Ten** (Name) | Ten chien dich - click de xem chi tiet |
| **Tu khoa** (Keyword) | So luong tu khoa trong chien dich |
| **Trang thai** (State) | Trang thai: Tat ca, Dang chay, Tam dung |
| **Ngay bat dau** (Start) | Thoi gian bat dau chien dich |
| **Chi tieu ngay** (Daily Expense) | So tien da chi trong ngay |
| **Han muc ngay** (Daily Quota) | Gioi han chi tieu moi ngay |
| **Tong chi tieu** (Total Expense) | Tong so tien da chi |

### Trang chi tiet chien dich

**Duong dan:** `/shopee/seller/ads/:id`

Khi click vao ten chien dich tu danh sach, chuyen sang trang chi tiet de quan ly tu khoa cua chien dich do.

Giao dien gom 3 khu vuc chinh:

1. **Thanh cong cu** - Cac nut chuc nang: Import tu khoa, Xuat Excel, Copy tu khoa
2. **Form them tu khoa** - Them tu khoa don le hoac hang loat
3. **Bang tu khoa** - Danh sach tu khoa hien tai va trang thai

### Mau sac hang trong bang tu khoa

| Mau | Y nghia |
|-----|---------|
| Vang (`ads-warning-row`) | Tu khoa moi chua duoc tao tren Shopee |
| Xanh duong (`ads-info-row`) | Tu khoa da thay doi chua cap nhat |
| Xanh la (`ads-success-row`) | Tu khoa moi da cap nhat thanh cong |

---

## Cac tinh nang

### Xem danh sach chien dich

He thong goi API Shopee Seller (`/api/marketing/v3/pas/homepage/`) de lay danh sach chien dich trong 12 thang gan nhat, sap xep theo hieu suat (performance).

**Tham so truy van:**
- `limit`: So chien dich moi trang (mac dinh: 10)
- `page`: Trang hien tai
- `state`: Loc trang thai (`all`, `ongoing`, `paused`)
- `type`: Loc loai (`keyword`, `shop`)
- `search`: Tim kiem theo ten

### Quan ly tu khoa (Keyword Management)

#### Them tu khoa don le

Nhap tu khoa va gia thau vao form, nhan **"Them"** de them vao danh sach. Tu khoa se duoc danh dau la "moi" (mau vang) cho den khi duoc tao tren Shopee.

#### Them tu khoa hang loat

Nhap nhieu tu khoa vao o textarea (moi dong mot tu khoa), nhan **"Them hang loat"**. Ho tro dinh dang: `tu_khoa` hoac `tu_khoa|gia`.

#### Cap nhat tu khoa

Voi moi tu khoa trong bang, co the chinh sua:

| Truong | Mo ta |
|--------|-------|
| **Keyword** | Ten tu khoa (chi doc) |
| **Loai** (Type) | `exact` (chinh xac) hoac `extend` (mo rong) |
| **Gia cu** (Price Old) | Gia thau hien tai tren Shopee |
| **Gia moi** (Price Change) | Gia thau muon thay doi |

- Nut **"Cap nhat"**: Xuat hien khi tu khoa da ton tai va co thay doi - gui API cap nhat len Shopee
- Nut **"Them"**: Xuat hien khi tu khoa chua ton tai tren Shopee - gui API tao moi

#### Import tu khoa tu bo suu tap

1. Nhan **"Import tu kho"** de mo popup
2. Chon bo suu tap tu khoa (Keyword Collection)
3. Chon tung tu khoa hoac **"Chon tat ca"** / **"Bo chon"**
4. Nhan **"Import"** de them vao bang tu khoa

Tu khoa khong hoat dong (inactive) se hien thi gach ngang.

#### Copy tu khoa sang bo suu tap

1. Chon cac tu khoa trong bang (checkbox)
2. Nhan **"Copy sang kho"** de mo popup
3. Chon bo suu tap dich
4. Nhan **"Copy"** de sao chep tu khoa

#### Xuat tu khoa ra Excel

Nhan **"Xuat Excel"** de tai file Excel chua danh sach tu khoa voi cac cot: Tu khoa, Gia, Loai, Trang thai.

### Content Script - Nut tich hop tren Shopee Seller Center

Khi nguoi ban truy cap trang chi tiet quang cao tren Shopee Seller Center (URL co dang `marketing/pas/.../[id]?from`), extension se tu dong them nut **"Mo trong AutoShopee"** (mau tim) ben canh cac nut mac dinh cua Shopee. Khi click, nut nay mo trang chi tiet chien dich trong AutoShopee Kit.

---

## Cau truc du lieu

### Campaign (Chien dich quang cao)

```
- campaignid: ID chien dich
- name: Ten chien dich
- status: Trang thai (number)
- state: Trang thai hien thi (all / ongoing / paused)
- type: Loai chien dich (keyword / shop / boost_ads / search)
- start_time: Thoi gian bat dau (Unix timestamp)
- end_time: Thoi gian ket thuc (Unix timestamp)
- daily_quota: Han muc chi tieu ngay
- daily_expense: Chi tieu trong ngay
- total_expense: Tong chi tieu
- total_quota: Tong han muc
```

### ShopeeAdsCampaignKeyword (Tu khoa quang cao)

```
- keyword: Tu khoa
- price: Gia thau (string)
- match_type: Loai khop (number) - chuyen doi thanh exact/extend
- status: Trang thai (0: tat, 1: bat)
- algorithm: Thuat toan (mac dinh: kwrcmdv3)
```

### AdsKeywordItem (Tu khoa trong giao dien)

```
- index: So thu tu
- id: ID ngan (short hash tu keyword)
- keyword: Tu khoa
- type: Loai khop (exact / extend)
- algorithm: Thuat toan
- price: Gia thau moi
- priceOld: Gia thau cu
- isActive: Dang hoat dong
- isNew: Tu khoa moi (chua tao tren Shopee)
- isCreated: Da tao tren Shopee
- isUpdated: Da cap nhat
- isChange: Co thay doi chua luu
- loading: Dang xu ly
```

### Report (Bao cao hieu suat)

Moi chien dich co bao cao gom cac chi so (moi chi so gom `value` va `ratio`):

| Chi so | Mo ta |
|--------|-------|
| impression | Luot hien thi |
| click | Luot click |
| ctr | Ti le click (Click-Through Rate) |
| cost | Chi phi |
| cpc | Chi phi moi click (Cost Per Click) |
| order | Don hang |
| order_amount | Gia tri don hang |
| cr | Ti le chuyen doi (Conversion Rate) |
| cir | Ti le chi phi / doanh thu |
| direct_gmv / broad_gmv | Doanh thu truc tiep / gian tiep |
| direct_roi / broad_roi | ROI truc tiep / gian tiep |
| reach | Luot tiep can |
| unique_visitors | Khach truy cap duy nhat |
| page_views | Luot xem trang |

---

## Luu y quan trong

1. **Yeu cau Premium:** Tinh nang Quang cao Shopee chi khoi dong cho tai khoan tra phi.
2. **API Shopee Seller:** He thong su dung API noi bo cua Shopee Seller Center (`/api/marketing/v3/pas/`), nen can dang nhap Shopee Seller Center truoc khi su dung.
3. **Loai tu khoa:** Co 2 loai khop - `exact` (chinh xac, chi hien khi nguoi mua tim dung tu khoa) va `extend` (mo rong, hien voi cac tu khoa lien quan).
4. **Gia thau:** Gia thau anh huong den thu hang quang cao. Gia cao hon = vi tri tot hon nhung chi phi lon hon.
5. **Tu khoa trung lap:** He thong kiem tra trung lap truoc khi them. Tu khoa da ton tai se hien thong bao loi.
6. **Content Script:** Nut tich hop tren Shopee Seller Center hien dang duoc vo hieu hoa trong code (`if (false)`), co the duoc bat lai khi can.
7. **Keyword Collection:** Tu khoa co the duoc luu vao cac bo suu tap (collection) de tai su dung cho nhieu chien dich khac nhau, giup tiet kiem thoi gian quan ly.
8. **Xuat Excel:** File Excel duoc xuat voi ten dang `ads-keyword-[campaign_id]`, chua day du thong tin tu khoa de luu tru va phan tich.
