# Menyambung PrestaWeb ke Google Analytics

Panduan ini membawa anda dari sifar sehingga `php artisan analytics:check` lulus,
supaya butang **Jana Laporan** di `/website-reports` boleh menarik data sebenar.

## Dua laman web Google yang berbeza

Ini punca kekeliruan yang paling biasa. Dua tapak berlainan terlibat:

| Tapak | URL | Untuk apa |
|---|---|---|
| **Google Cloud Console** | `console.cloud.google.com` | Service account, kunci JSON, mengaktifkan API |
| **Google Analytics** | `analytics.google.com` | Property, akses, ID property, data sebenar |

Service account **dicipta di Cloud**, kemudian **dibenarkan di Analytics**.
Ia tidak akan wujud dalam Google Analytics sehingga anda menampalnya di sana.

---

## Langkah 1 — Cloud: pastikan projek betul

Buka https://console.cloud.google.com dan pilih projek **`prestaweb-505706`**
pada dropdown di bahagian atas.

Semua langkah Cloud di bawah mesti dibuat dalam projek yang sama.

## Langkah 2 — Cloud: aktifkan Google Analytics Data API

1. Pergi ke **APIs & Services → Library**
   (https://console.cloud.google.com/apis/library)
2. Cari **"Google Analytics Data API"**
3. Klik **Enable**

> **Berhati-hati:** ada dua API berlainan dengan nama serupa.
> Anda perlukan **Data API** (untuk membaca laporan), bukan **Admin API**
> (untuk mengurus tetapan). Jika tersalah, panggilan API akan ditolak.

## Langkah 3 — Cloud: service account

Sudah siap. Akaun anda ialah:

```
prestaweb@prestaweb-505706.iam.gserviceaccount.com
```

Jika perlu melihatnya semula: **IAM & Admin → Service Accounts**
(https://console.cloud.google.com/iam-admin/serviceaccounts)

Ia **tidak perlu** sebarang peranan (role) IAM dalam Cloud. Kebenarannya
datang daripada Google Analytics pada Langkah 5.

## Langkah 4 — Cloud: muat turun kunci JSON

1. Klik pada service account tersebut
2. Tab **Keys**
3. **Add key → Create new key**
4. Pilih **JSON** → **Create**

Fail akan dimuat turun secara automatik. Namakannya semula dan letakkan di:

```
storage/app/google/ga4-service-account.json
```

Dari Windows File Explorer, folder itu ialah:

```
\\wsl.localhost\ubuntu\home\asyraf\project\web-audit\storage\app\google\
```

Kandungan fail bermula seperti ini — jika tidak, anda memuat turun jenis
kunci yang salah:

```json
{
  "type": "service_account",
  "project_id": "prestaweb-505706",
  "client_email": "prestaweb@prestaweb-505706.iam.gserviceaccount.com",
  ...
}
```

> Kunci ini ialah kelayakan (credential). Folder `storage/app/google/`
> sudah ditetapkan supaya kandungannya tidak masuk ke dalam Git.

## Langkah 5 — Analytics: beri akses kepada service account

Sekarang barulah tukar ke https://analytics.google.com

1. **Admin** (ikon gear, kiri bawah)
2. Pastikan **Property** di lajur tengah ialah property yang betul
3. **Property access management**
4. Butang **+** (kanan atas) → **Add users**
5. Tampal `prestaweb@prestaweb-505706.iam.gserviceaccount.com`
6. **Buang tanda** pada *Notify new users by email* — service account tiada peti masuk
7. Peranan: **Viewer**
8. **Add**

> Tambah pada peringkat **Property**, bukan **Account**. Akaun berfungsi juga,
> tetapi memberi akses lebih daripada yang diperlukan.

## Langkah 6 — Analytics: salin ID property

1. **Admin → Property details** (atau *Property Settings*)
2. Di kanan atas ada nombor, contohnya `483721904`
3. Masukkan ke dalam `.env`:

```bash
GA4_PROPERTY_ID=483721904
```

> **Ini bukan ID pengukuran `G-XXXXXXX`.** Yang `G-` itu dipasang pada halaman
> web untuk mengumpul data. Yang bernombor pula digunakan oleh API untuk
> membaca data. Menggunakan `G-` di sini adalah silap yang paling kerap berlaku.

## Langkah 7 — Sahkan

```bash
php artisan analytics:check
```

Jalankan selepas setiap langkah jika mahu — ia memberitahu dengan tepat di mana
anda tersekat. Apabila semuanya lulus, ia menyenaraikan hostname yang menghantar
data dan memadankannya dengan laman web berdaftar.

## Langkah 8 — Jana laporan

Selepas pemeriksaan lulus, buka `/website-reports`, pilih bulan, klik
**Jana Laporan**. Atau melalui terminal:

```bash
php artisan reports:websites --month=2026-07
```

---

## Jika tersekat

| Mesej | Maksud | Tindakan |
|---|---|---|
| `Fail kelayakan tidak dijumpai` | Kunci JSON belum ada di tempatnya | Langkah 4 |
| `Fail itu bukan kunci service account` | Anda memuat turun kunci API atau OAuth client | Langkah 4 — pilih jenis **JSON** pada service account |
| `GA4_PROPERTY_ID belum ditetapkan` | Tiada dalam `.env` | Langkah 6 |
| `GA4_PROPERTY_ID mesti nombor sahaja` | Anda memasukkan `G-XXXXXXX` | Langkah 6 — guna nombor dari Property details |
| `Panggilan API gagal` + `PERMISSION_DENIED` | Service account belum diberi akses | Langkah 5 |
| `Panggilan API gagal` + `API has not been used` | Data API belum diaktifkan | Langkah 2 |
| `Tiada hostname melaporkan trafik` | Kelayakan betul, tetapi kod penjejakan belum mengumpul data | Pasang kod `G-XXXXXXX` pada laman web |

## Nota

- **Kunci API tidak boleh digunakan.** GA4 Data API hanya menerima service
  account atau OAuth. Kunci `AIza...` akan sentiasa ditolak.
- **Satu property untuk semua laman web.** Sistem membezakan setiap laman web
  melalui `hostName`, jadi tiada apa-apa perlu disimpan pada setiap rekod laman web.
- **Laman tanpa data tetap mendapat laporan**, ditanda *"Tiada data analitik"* —
  bukan laporan penuh sifar. Ini membezakan antara "tiada pelawat" dengan
  "kod penjejakan belum dipasang".