Meranie zobrazení a klikov

Zobrazenia a kliky zaznamenáte synchrónne alebo, pri tracking.buffered nastavenom na true, cez frontu. Obe cesty v jednej transakcii zapíšu riadok do advertisement_events a zvýšia denormalizované počítadlo — neúspešný zápis nezanechá ani jedno, takže opakovaný job nikdy nezapočíta dvakrát — a potom spustia udalosť:

use RoundlyConsulting\Advertisements\DataTransferObjects\ImpressionData;
use RoundlyConsulting\Advertisements\Facades\Advertisements;

Advertisements::for($ad)->track('sidebar')->impression();
Advertisements::for($ad)->track('sidebar')->click(new ImpressionData(
    ip: $request->ip(),
    userAgent: $request->userAgent(),
    referrer: $request->headers->get('referer'),
));
Advertisements::for($ad)->track()->impression(); // no placement

$ad->impressions(); // int  (impressions_count)
$ad->clicks();      // int  (clicks_count)
$ad->ctr();         // float 0.0–1.0
$ad->events;        // HasMany<AdvertisementEvent>

ctr() je podiel klikov a zobrazení (0.0–1.0), a kým nie sú žiadne zobrazenia, vracia 0.0. Umiestnenie je voliteľné a prijíma model, id alebo slug.

Čo track() odmietne

track() odmietne reklamu, ktorá práve nie je živá — koncept, naplánovanú, expirovanú či archivovanú reklamu (AdvertisementNotActive) — a track($placement) navyše odmietne umiestnenie, v ktorom reklama nebeží (AdvertisementNotInPlacement). Obe sú AdvertisementException, takže podvrhnutá či zastaraná URL zobrazenia alebo kliku nič nezapočíta; v controlleri presmerovania kliku zachyťte základnú triedu a reagujte podľa potreby:

use RoundlyConsulting\Advertisements\DataTransferObjects\ImpressionData;
use RoundlyConsulting\Advertisements\Exceptions\AdvertisementException;
use RoundlyConsulting\Advertisements\Facades\Advertisements;

try {
    Advertisements::for($ad)->track('sidebar')->click(new ImpressionData(ip: $request->ip()));
} catch (AdvertisementException) {
    // not credited: the ad is not live, or never ran in this placement
}

Kontext požiadavky

ImpressionData je voliteľné, rovnako ako každé jeho pole — ip, userAgent, referrer, occurredAt a meta. Zadaný kontext sa zlúči do meta udalosti; kľúče s hodnotou null sa vynechajú:

use Illuminate\Support\Collection;

// Inline mode returns the persisted AdvertisementEvent (buffered mode: null)
$event = Advertisements::for($ad)->track('sidebar')->click(new ImpressionData(
    ip: $request->ip(),
    occurredAt: now(),                                     // defaults to now
    meta: new Collection(['campaign' => 'autumn-launch']), // your own keys
));

$event->type;          // AdvertisementEventType::Click
$event->occurred_at;   // Carbon
$event->placement;     // ?Placement
$event->meta;          // Collection — ip, user_agent, referrer (when given) + your keys
$event->country_code;  // 'SK' when geo stamping resolved the IP, else null

Zápis cez frontu

Pri vysokej návštevnosti môžete zápis presunúť mimo požiadavky. So zapnutým bufferovaním vrátia impression() a click() null a RecordAdvertisementEventJob vykoná zápis tým istým jadrom na nakonfigurovanom spojení a fronte — synchrónny aj odložený zápis vedú k rovnakému výsledku. Kontrola živej reklamy aj umiestnenia prebehne už pri volaní track(), ešte pred zaradením jobu do fronty. Job nesie len id, nikdy celé modely; reklama zmazaná pred spustením jobu sa preskočí.

ADVERTISEMENTS_TRACKING_BUFFERED=true
ADVERTISEMENTS_TRACKING_CONNECTION=redis   # unset or blank = the default connection
ADVERTISEMENTS_TRACKING_QUEUE=tracking     # unset or blank = the default queue

php artisan queue:work redis --queue=tracking

Reporty podľa krajín

Keď je geo.stamp_events zapnuté a ImpressionData obsahuje IP adresu, zápis ju cez geolocation-for-laravel preloží na polohu a krajinu diváka uloží do indexovaného stĺpca country_code, región, mesto, zemepisnú šírku a dĺžku do meta:

use RoundlyConsulting\Advertisements\DataTransferObjects\ImpressionData;

Advertisements::for($ad)->track('sidebar')->impression(new ImpressionData(ip: $request->ip()));

$ad->impressionsByCountry(); // ['SK' => 1240, 'CZ' => 310]
$ad->clicksByCountry();      // ['SK' => 58]

Zlyhanie zistenia polohy zápis nikdy nepreruší: IP adresa, ktorú geolokácia neurčí, divák určený bez krajiny aj vyhľadanie, ktoré vyhodí výnimku (chýbajúca databáza MaxMind, rate limit, chyba vlastného poskytovateľa), uložia udalosť s country_code null a počítadlo aj tak zvýšia. Výnimku z vyhľadania dostane report() vášho exception handlera, takže nefunkčný poskytovateľ sa objaví v logoch a nezlyháva potichu. Funguje to aj pri zápise cez frontu.

Reakcia na meranie

Počúvajte ImpressionRecorded a ClickRecorded — každá sprístupňuje uložený AdvertisementEvent vo verejnej vlastnosti $event (pozri Udalosti).