Geografické cielenie

Reklamy deklarujú cielenie hodnotovým objektom Targeting — povolené a zablokované krajiny a/alebo okruh okolo bodu. Pri servírovaní získate aktívne reklamy umiestnenia, ktoré zodpovedajú polohe diváka:

use RoundlyConsulting\Advertisements\Facades\Advertisements;
use RoundlyConsulting\Advertisements\ValueObjects\Targeting;
use RoundlyConsulting\Geolocation\DataTransferObjects\Coordinates;

$ad->targeting = new Targeting(
    countries: ['SK', 'CZ'],                 // allow list (empty = any)
    excludeCountries: ['RU'],                // deny list
    center: new Coordinates(48.1486, 17.1077),
    radiusKm: 50.0,
);
$ad->save();

// Resolve the viewer from the request IP (geolocation), or pass a Location / null:
$ads = Advertisements::targetedIn('sidebar', request())->get();

// Or the model scope directly:
Advertisement::query()->active()->forPlacement('sidebar')->targetedAt($location)->get();

targetedIn() preloží Request — alebo aktuálnu požiadavku, ak nič nezadáte — na polohu cez geolocation-for-laravel, prípadne prijme už zistenú Location. Vyhľadanie, ktoré vyhodí výnimku, sa nahlási a divák sa považuje za neznámeho, takže geolokácia servírovanie nikdy nezhodí. Pri vypnutom geo.targeting_enabled sa správa rovnako ako in().

Pravidlá zhody

• excludeCountries — zoznam zakázaných kódov ISO, kontroluje sa ako prvý.
• countries — zoznam povolených krajín; prázdny znamená akúkoľvek krajinu.
• center + radiusKm — divák musí byť do radiusKm od stredu (presný Haversinov vzorec). Platí len vtedy, keď sú nastavené obe hodnoty.
• Reklama sa zhoduje, keď divák spĺňa každé pravidlo, ktoré nastavuje: zoznamy povolených a zakázaných krajín kontrolujú krajinu diváka, okruh jeho súradnice.
• Reklama bez cielenia (null alebo prázdny new Targeting(), ktorý sa uloží ako žiadne cielenie) sa zobrazí každému divákovi, kým je geo.untargeted_match zapnuté.

Neznámi diváci a chýbajúce údaje

Divákom môže byť Location, samotné Coordinates, kód krajiny ISO, Request (poloha sa zistí z jeho IP) alebo null. Čo sa stane, keď o divákovi niečo nevieme, určuje geo.match_when_unknown:

Pri predvolenom nastavení teda divák známy len ako „US“ nikdy nedostane reklamu obmedzenú na 50 km okolo Bratislavy a samotné súradnice New Yorku nikdy nedostanú reklamu len pre SK.

Scope targetedAt()

Scope, na ktorom stojí targetedIn(), prijíma diváka v štyroch podobách:

use RoundlyConsulting\Geolocation\DataTransferObjects\Coordinates;

Advertisement::query()->active()->targetedAt($location)->get();   // Location — country lists + radius
Advertisement::query()->active()->targetedAt('SK')->get();        // country only — a radius rule can't be checked
Advertisement::query()->active()
    ->targetedAt(new Coordinates(48.1486, 17.1077))->get();       // coordinates only — a country list can't be checked
Advertisement::query()->active()->targetedAt(null)->get();        // unknown viewer — per geo.match_when_unknown

Cielenie sa vyhodnocuje presne v PHP nad kandidátmi, ktorých už zúžil okolitý dopyt — preto pred ním reťazte active() a forPlacement().

Čítanie a zrušenie cielenia

$targeting = $ad->targeting;         // ?Targeting
$targeting?->isEmpty();              // no country list and no radius (centre + radiusKm)
$targeting?->matches('SK');          // Location, Coordinates or a country code
$targeting?->matches('SK', true);    // a rule the viewer lacks the fact for counts as met
$targeting?->toArray();              // ['countries' => [...], 'exclude_countries' => [...], 'center' => [...], 'radius_km' => 50.0]

$ad->targeting = Targeting::fromArray([   // snake_case payload, e.g. from a form
    'countries' => ['sk', 'cz'],          // normalised to upper case
    'center' => ['latitude' => 48.1486, 'longitude' => 17.1077],
    'radius_km' => 25,
]);

$ad->targeting = null;                    // untargeted again
$ad->save();

Cast ukladá cielenie ako JSON a stred skopíruje do stĺpcov target_latitude a target_longitude. Cielenie zrušíte priradením null (alebo prázdneho Targeting); iná hodnota než Targeting alebo null vyhodí InvalidTargeting. Stred bez okruhu ani okruh bez stredu nie je pravidlo.