Metadata-Version: 2.4
Name: csgoogleanalytics
Version: 2.14.0
Summary: Google Analyticseko gure webguneko datuak hileka edo asteka jasotzeko tresna
Author-email: Jatsu Argarate <jargarate@codesyntax.com>
Project-URL: Homepage, https://gitlab.com/codesyntax/csgoogleanalytics
Project-URL: Source, https://gitlab.com/codesyntax/csgoogleanalytics
Project-URL: Issues, https://gitlab.com/codesyntax/csgoogleanalytics/-/issues
Keywords: tokikom,google analytics,django
Classifier: Environment :: Web Environment
Classifier: Framework :: Django
Classifier: Framework :: Django :: 5.2
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.12
Requires-Python: >=3.12
Description-Content-Type: text/markdown
Requires-Dist: google-analytics-data==0.23.3
Requires-Dist: django-object-actions>=4.1.0

[![pipeline status](https://gitlab.com/codesyntax/csgoogleanalytics/badges/main/pipeline.svg)](https://gitlab.com/codesyntax/csgoogleanalytics/-/commits/main)
[![coverage report](https://gitlab.com/codesyntax/csgoogleanalytics/badges/main/coverage.svg)](https://gitlab.com/codesyntax/csgoogleanalytics/-/commits/main)
[![PyPI](https://img.shields.io/pypi/v/csgoogleanalytics.svg)](https://pypi.org/project/csgoogleanalytics/)
![Python 3.12](https://img.shields.io/badge/python-3.12-blue)
![Django 5.2](https://img.shields.io/badge/django-5.2-0C4B33)

# cs-google-analytics

[Tokikom](https://tokikom.eus) hedabide-sarearentzako Google Analytics 4 datuak biltzeko Django
aplikazioa. Webgune bakoitzeko orrien bisita-kopuruak (pageviews) Google Analytics Data APIaren
bidez ekarri, tokian bertan gorde eta Django adminetik kudeatzeko balio du.

Aplikazioak multisite proiektuak onartzen ditu: gune bakoitzak bere Analytics property-a eta
kredentzialak izan ditzake. Gainera, orri historikoen estatistikak gordetzeko `Page` eta
`PageStats` modeloak eskaintzen ditu.

## Ezaugarriak

- **Google Analytics 4**: `google-analytics-data` bezero ofiziala erabiltzen du, ez du GA3
  (Universal Analytics) API zaharra erabiltzen.
- **Multisite**: `django.contrib.sites` bidez gune bakoitzeko `AnalyticsProfile` bat; profilik
  gabeko guneek ez dute gainerakoen eguneraketa blokeatzen.
- **Admin integrazioa**: "Update URLs" ekintzak analytika-datuak unean bertan eguneratzen ditu.
- **URL balidatzailea**: konfigura daitekeen funtzio batek path bakoitza eduki-objektu batekin
  lotu dezake, eta emaitza `is_valid`, izenburua, argazkia eta `ContentType`/object id gisa gorde.
- **Estatistika historikoak**: `Page` eta `PageStats` modeloek epeka (egun, aste, hilabete, urte)
  bildutako bisitak gordetzen dituzte.
- **Kudeaketa-komandoak**: analytika osoa edo eguneko pageviews-ak eskuz eguneratzeko.

## Baldintzak

- Python 3.12 edo berriagoa.
- Django 5.2 (Tokikom-ek onartzen duen bertsioa).
- Google Cloud-eko service account bat, Analytics Data API gaituta eta GA4 property-ra irakurtzeko
  baimenarekin.
- `requirements.txt` fitxategiko dependentziak: `google-analytics-data` eta
  `django-object-actions`. Django proiektu ostalariak hornitzen du.

## Instalazioa

```bash
pip install -e .
```

Proiektu ostalariaren `settings.py`-n aplikazioa eta bere admin-dependentzia gehitu:

```python
INSTALLED_APPS = [
    # ...
    "django_object_actions",
    "csgoogleanalytics",
]
```

Ez da URLrik gehitu behar: aplikazioak ez du bista publikorik, Django adminaren bidez eta
kudeaketa-komandoen bidez erabiltzen da.

Ondoren, migrazioak exekutatu:

```bash
python manage.py migrate
```

## Konfigurazioa

| Aldagaia | Lehenetsitako balioa | Azalpena |
| --- | --- | --- |
| `SECRET_ROOT` | — | Service account fitxategia bilatzeko direktorioa. Fitxategia `$SECRET_ROOT/secrets/csgoogleanalytics_secrets.json` izango da. |
| `CSGOOGLEANALYTICS_URL_VALIDATOR` | `csgoogleanalytics.validators.default_validator` | Path bat edukira lotzen duen funtzioaren bide puntuduna. |
| `SITE_ID` | `1` | Django sites framework-eko gune aktiboa. |

### Google Analytics kredentzialak

1. Google Cloud-en proiektu bat sortu eta **Analytics Data API** gaitu.
2. **Service account** bat sortu eta JSON gakoa deskargatu.
3. GA4 property-an service accountaren posta-elektronikoari irakurtzeko baimena eman.
4. JSON fitxategia `$SECRET_ROOT/secrets/csgoogleanalytics_secrets.json` gisa gorde.
5. Admin-ean `AnalyticsProfile` bat sortu: `tracking_code` eremuan GA4 property-aren zenbakia
   (adibidez `123456789`) eta `site` eremuan dagokion gunea.

### URL balidatzailea

Validatzaileak path bat jasotzen du eta bost elementuko tupla itzuli behar du:

```python
(is_valid, title, photo_src, content_type, object_id)
```

- `is_valid` (`bool`): path-a eduki-objektu batera lotzen den.
- `title` (`str`): admin-ean erakutsiko den izenburua.
- `photo_src` (`str`): argazkiaren URLa (hutsik egon daiteke).
- `content_type` (`int`): Django `ContentType`-aren pk-a.
- `object_id` (`int`): eduki-objektuaren pk-a.

Adibidea:

```python
def validator(path):
    try:
        albistea = Albistea.objects.get(permalink=path)
    except Albistea.DoesNotExist:
        return (False, path, "", None, None)
    return (
        True,
        albistea.izena,
        albistea.argazkia.url if albistea.argazkia else "",
        ContentType.objects.get_for_model(albistea).pk,
        albistea.pk,
    )
```

```python
CSGOOGLEANALYTICS_URL_VALIDATOR = "nire_proiektua.analytics.validator"
```

Validatzaileak salbuespena sortzen badu, errenkada `is_valid=False` eta balio lehenetsiekin
gordetzen da; eguneraketak ez du eteten.

## Datu-eredua

| Eredua | Azalpena |
| --- | --- |
| `Analytics` | Uneko bisita-kopurua path bakoitzeko: izenburua, pageviews, baliozkotasuna, argazkia eta eduki-erlazioa. |
| `AnalyticsProfile` | Gune bakoitzaren GA4 property kodea (`tracking_code`) eta `Site` erlazioa. |
| `AllowedPattern` | Historian erabilitako path-patroien zerrenda eta baliozkotasuna. |
| `Page` | Orri historiko bat: path-a, eduki-erlazioa eta data-zatiak (egun, aste, hilabete, urte). |
| `PageStats` | `Page` baten bisitak epe jakin baterako (`PERIOD_CHOICES_FULL`: 1d, 2d, 1w... 20y). |

`Page` erregistroak kanpoko proiektuek sortzen dituzte (adibidez, argitaratze-prozesuan); aplikazio
honek `PageStats`-eko pageviews-ak eguneratzen ditu.

## Kudeaketa-komandoak

| Komandoa | Azalpena |
| --- | --- |
| `update_analytics` | Gune guztien `Analytics` errenkadak berritu: atzoko eta gaurko pageviews-ak GA4tik ekarri eta URL balidatzailea aplikatu. |
| `update_pages --hasi 20240101 --bukatu 20240131` | Egun-tarte bateko `PageStats` datuak eguneratu. `--bukatu` ez bada ematen, `--hasi` egun bakarra hartzen da. |

Adibideak:

```bash
python manage.py update_analytics
python manage.py update_pages --hasi 20240101 --bukatu 20240131
```

`update_pages` komandoak 10 patheko multzotan egiten ditu GA4 eskaerak eta bi segundo itxaroten ditu
egun bakoitzaren artean APIaren kuotak errespetatzeko.

## Garapena

### Adarrak eta merge requestak

`main` adar nagusia babestuta dago: ezin da zuzenean push egin, eta aldaketak **merge request (MR)**
bidez sartzen dira beti.

1. `main` eguneratu eta lan-adar bat sortu:

   ```bash
   git switch main
   git pull
   git switch -c feat/nire-aldaketa
   ```

2. Aldaketak egin eta commit esanguratsuak sortu, conventional commits erabiliz:

   ```bash
   git commit -m "feat: admin ekintza berria gehitu"
   ```

3. Adarra bultzatu eta MRa ireki (`main` helmuga):

   ```bash
   git push -u origin feat/nire-aldaketa
   ```

Adarren izenak:

| Aurrizkia | Erabilera |
| --- | --- |
| `feat/` | Ezaugarri berria. |
| `fix/` | Akatsen konponketa. |
| `docs/` | Dokumentazioa. |
| `chore/` | Mantentze-lanak, dependentziak, konfigurazioa. |

> `main` adarreko babes-araua GitLab-en konfiguratzen da (Settings → Repository → Protected
> branches): MR bidezko mergea derrigorrezkoa, eta Maintainer taldeak bakarrik du push baimena.
> `master` adarra `main`-era aldatuta dago: GitLab-en default branch `main` da eta `master`
> ezabatuta dago.

### Menpekotasunak

Menpekotasunen iturri bakarra `requirements.txt` da: `pyproject.toml`-ek fitxategi hori irakurtzen
du `[tool.setuptools.dynamic]` atalaren bidez, eta ez ditu bertsioak bikoizten.
[Renovate](https://docs.renovatebot.com/) bidez eguneratzen dira: `renovate.json` fitxategiak
`pep621` eta `pip_requirements` kudeatzaileak gaitzen ditu, eta Tokikom-en Renovate preset
partekatua erabiltzen du Django bertsio nagusiak sinkronizatuta edukitzeko.

### Testak

Testak tox bidez exekutatzen dira. Ingurune bakarra dago: Python 3.12 eta Django 5.2.

```bash
tox -e py12-dj52
```

`tox` eta `tox-uv` instalatuta ez badaude:

```bash
pip install --user tox tox-uv
```

- `tox.ini`: ingurunearen definizioa eta pytest komandoa.
- `test-requirements.txt`: test-soilikako dependentziak. Django proiektu ostalariak kudeatzen
  duenez, hemen pinatzen da proba-ingurunea erreproduzigarria izan dadin.
- `tests/settings.py`: probetarako Django konfigurazio minimoa (sqlite memorian).
- `pytest.ini`: pytest-en konfigurazioa.
- `tests/`: probak.
- `.coveragerc`: estalduraren konfigurazioa. Gutxieneko estaldura %90ean dago (`fail_under`);
  hortik behera jaitsiz gero, testak huts egiten du.

Testak `--no-migrations`-ekin exekutatzen dira (taulak modeloetatik zuzenean sortzen dira);
migrazioak `tox -e migration_check` ingurunean egiaztatzen dira. Migrazioak estalduratik kanpo
daude.

### CIa

GitLab CI pipelineak MR bakoitzean eta `main` adarrean exekutatzen ditu:

- `black --check --diff .`: formateoa.
- `ruff check .`: lint fase 1 (`F`, `E4`, `E7`, `E9`, `I`).
- `tox -e py12-dj52`: testak, estaldura eta JUnit txostenekin.
- `tox -e migration_check`: migrazioak aplikagarri direla eta modeloen eta migrazioen artean
  desadostasunik ez dagoela egiaztatzen du.
- `semantic_release` (eskuz, `main` adarrean): bertsioa, changelog-a, commit-a, etiketa eta
  GitLab release-a sortzen ditu.
- `publish` (etiketetan automatikoa): paketea eraiki eta PyPIra igotzen du Trusted Publishing bidez.

Artifacts: `coverage.xml` (Cobertura), `htmlcov/`, `junit.xml` eta
`gl-code-quality-report.json` (Code Quality). Estalduraren konfigurazioa `.coveragerc`
fitxategian dago: migrazioak kanpoan uzten ditu.

Lint tresnak `lint-requirements.txt`-n daude pinatuta.

### Bertsioak

Bertsioak [semantic-release](https://semantic-release.gitbook.io/) bidez kudeatzen dira,
conventional commits-etatik abiatuta. Release bat argitaratzeko:

1. Aldaketak `main`-era eraman MR bidez (`feat:`, `fix:`, `feat!:`... erabiliz).
2. `main` adarreko pipelinean `semantic_release` joba **eskuz** abiarazi:
   - Bertsio berria kalkulatzen du (SemVer: `feat` → minor, `fix` → patch, breaking → major).
   - `pyproject.toml` eta `CHANGELOG.md` eguneratzen ditu, commit-a eta etiketa sortzen ditu.
   - GitLab release-a sortzen du.
3. Etiketak automatikoki `publish` joba abiarazten du: `sdist` eta `wheel` sortu eta PyPIra
   igotzen ditu.

> Etiketek hiru osagai izan behar dituzte (`X.Y.Z`): `semantic-release`-k erabiltzen duen
> node-semverrek ez ditu `2.13` moduko etiketa laburrak onartzen. Horregatik `2.13.0` etiketa
> `2.13` zaharraren alias gisa sortu da, eta etorkizuneko releaseek `2.14.0` moduko etiketak
> sortuko dituzte automatikoki.

Beharrezko CI/CD aldagaia:

- `GITLAB_TOKEN`: `api` eta `write_repository` scopeak eta Maintainer rola.

PyPIra igotzeko ez da API tokenik erabiltzen: **Trusted Publishing** erabiltzen da. PyPI-n behin
konfiguratu behar da:

1. PyPI → `csgoogleanalytics` → Publishing → Add a new publisher → **GitLab**.
2. GitLab namespace: `codesyntax`; project: `csgoogleanalytics`; top-level CI/CD pipeline file:
   `.gitlab-ci.yml`; environment: `pypi`.
3. Gorde.

`publish` jobak `id_tokens` bidez `PYPI_ID_TOKEN` lortzen du (`aud: pypi`) eta `twine`-k PyPI-rekin
trukatzen du; token iraunkorrik ez da gorde behar.

Bertsioa `pyproject.toml`-n (`[project].version`) eta `CHANGELOG.md` fitxategian eguneratzen dira
automatikoki; ez da eskuz aldatu behar.

### Egitura

```
csgoogleanalytics/
├── management/commands/    # update_analytics eta update_pages komandoak
├── migrations/             # datu-basearen migrazioak
├── templates/csgoogleanalytics/  # adminaren hautapen-txantiloia
├── admin.py                # Django adminaren konfigurazioa
├── models.py               # datu-ereduak
├── utils.py                # GA4 bezeroa eta estatistiken laguntzaileak
└── validators.py           # URL balidatzaile lehenetsia
```

Erroko fitxategiak: `pyproject.toml` (paketearen metadatuak eta dependentziak), `requirements.txt`
(dependentzia berdinak pip-entzat), `test-requirements.txt` (test-soilikako dependentziak),
`publish-requirements.txt` (build eta twine), `lint-requirements.txt` (black eta ruff), `tox.ini`
(test ingurunea), `pytest.ini` (pytest konfigurazioa), `.coveragerc` (estalduraren konfigurazioa),
`ruff.toml` (lint konfigurazioa), `.releaserc.json` (semantic-release konfigurazioa),
`CHANGELOG.md`, `.gitlab-ci.yml` (CI pipelinea), `tests/` (probak) eta `renovate.json`
(menpekotasunen eguneraketa automatikoa).

## Egileak

Codesyntax-ek garatua Tokikom-entzat.
