README

Lightweight & extensible OpenAds for Laravel, suitable for internal ads, marketplaces, CMS, or monetization platforms. All metrics (CTR, relevance, landing score) and click/view costs are automatically calculated based on ad performance.

✨ Key Features

🔍 Search Ads (keyword-based)
🖼️ Image & 🎥 Video Ads (URL / local / CDN)
🎯 Campaign → Ad Group → Ads → Keywords → Assets
⏰ Display based on time (start_time & end_time, default 24 hours)
🌍 Target locations: country / city (multi, default all)
📱 Target devices: android / ios / desktop (multi, default all)
🏆 Auction & ranking (bid × quality score)
📊 Automatic impression & click tracking
💰 Click cost = bid, view cost = bid × 20% (configurable)
🔄 CTR, relevance, landing score & campaign balance calculated automatically

📦 Installation

composer require lazyexe/openads

Or Manual / Local Development

"require": {
	"lazyexe/openads": "*"
},
"repositories": [
	{
		"type": "path",
		"url": "OpenAds"
	}
],

Publish config & migrations:

php artisan vendor:publish --tag=ads-config
php artisan vendor:publish --tag=ads-migrations
php artisan migrate

🚀 Usage

Routes

<?php

use Illuminate\Support\Facades\Route;
use App\Http\Controllers\HomeController;
use App\Http\Controllers\AdsClickController;

Route::get('/', [HomeController::class, 'index']);
Route::get('/ads/click/{adId}', [AdsClickController::class, 'click'])->name('ads.click');

HomeController

<?php

namespace App\Http\Controllers;

use Illuminate\Http\Request;
use OpenAds\Facades\Ads;

class HomeController extends Controller
{
    public function index(Request $request)
    {
        $query = $request->get('q', '');

        $adsCollection = $query ? Ads::search($query)->limit(3) : collect();

        return view('index', [
            'ads' => $adsCollection,
            'query' => $query,
        ]);
    }
}

AdsClickController

<?php

namespace App\Http\Controllers;

use Illuminate\Http\Request;
use OpenAds\Facades\Ads;

class AdsClickController extends Controller
{
    public function click(Request $request, int $adId)
    {
        $url = Ads::logClick($adId);
        if (!$url) {
            abort(404, 'Ads not found or insufficient budget.');
        }
        return redirect()->away($url);
    }
}

index.blade

@if($ads->all())
    @foreach($ads->all() as $ad)
        <div>
            <div>Sponsored</div>
            <h4>{{ $ad->title }}</h4>
            @if(!empty($ad->assets))
                @php $asset = $ad->assets[0]; @endphp
                @if($asset->type === 'image')
                    <img src="{{ $asset->source }}" alt="">
                @elseif($asset->type === 'video')
                    <video controls width="300">
                        <source src="{{ $asset->source }}">
                    </video>
                @endif
            @endif
            <p>
                <a href="{{ route('ads.click', $ad->id) }}" target="_blank">
                    {{ $ad->url }}
                </a>
            </p>
        </div>
    @endforeach
@else
    <p>No ads available.</p>
@endif

🔧 API Reference

Method	Description	Return
`Ads::search(string $query)`	Retrieve ads by keyword query, automatically logs impressions & charges views	`AdCollection`
`AdCollection->all()`	Get all ads	`array` of `AdDTO`
`AdCollection->limit(int $n)`	Get top n ads by score	`AdCollection`
`Ads::logClick(int $adId)`	Log click & charge campaign according to bid	`string	null` (landing URL)

⚙️ Configuration

config/ads.php

return [
    'default_platform' => 'search',
    'view_cost_percent' => 0.2, // view cost = bid * 20%
];

💡 Notes

Ads only display if campaign & ad group are active, budget > 0, and within date range (start_date & end_date).
CTR, relevance, and landing score are calculated automatically from impressions & clicks when a query runs.
All costs and performance updates occur immediately at query time, keeping data dynamic and accurate.

🗄️ Database Structure

Main Tables

Table	Purpose
`ads_campaigns`	Store campaigns & budgets
`ads_ad_groups`	Group keywords & ads
`ads_ads`	Ad unit (text / image / video)
`ads_keywords`	Keyword targeting
`ads_assets`	Ad assets (image / video)
`ads_impressions`	Ad impression log
`ads_clicks`	Ad click log

Campaign

Field	Description
`name`	Campaign name
`daily_budget`	Daily budget
`status`	active / paused
`start_date`	Campaign start date
`end_date`	Campaign end date
`start_time`	Start time (nullable = runs 24 hours)
`end_time`	End time (nullable = runs 24 hours)
`target_locations`	JSON: target countries/cities, null = all locations
`target_devices`	JSON: target devices (android/ios/desktop), null = all devices

Ad Group

Field	Description
`campaign_id`	Related campaign
`name`	Ad group name
`default_bid`	Default bid
`status`	active / paused

Field	Description
`ad_group_id`	Related ad group
`title`	Ad title
`url`	Landing page URL
`bid`	Bid price
`ctr`	Click-through rate
`relevance`	Relevance score
`landing_score`	Landing score
`status`	active / paused

ℹ️ Ads can be text-only or include image / video assets.

Keywords

Field	Description
`ad_group_id`	Related ad group
`keyword`	Target keyword
`match_type`	exact / phrase / broad
`negative`	Exclude keyword

Assets (Image / Video)

Field	Description
`ad_id`	Related ad
`type`	image / video
`source`	URL or local path
`is_primary`	Primary asset

Source can be:

CDN / external URL
Local upload (storage/ads/...)
S3 / object storage

lazyexe / openads

Maintainers

Details