=== Sanil Ads Kit ===
Contributors: sonill
Tags: ads, ad manager, advertisement, banner ads, ad rotation
Requires at least: 6.0
Tested up to: 7.1
Requires PHP: 8.1
Stable tag: 1.0.1
License: GPLv2 or later
License URI: https://www.gnu.org/licenses/gpl-2.0.html

Manage, schedule, rotate, and track ads anywhere on your WordPress site — with placements, groups, shortcodes, analytics, and popup/skip ads.

== Description ==

**Sanil Ads Kit** is a lightweight, performance-focused WordPress ad management plugin. Create and display banners, image ads, custom HTML/JS ads, iframes, and Google AdSense — then control exactly where and when they appear using flexible placements, scheduling, and targeting conditions.

Whether you're running a personal blog, a content-heavy publication, or a client site, Sanil Ads Kit gives you full control over your advertising without slowing down your site.

Learn more at [sanil.app/sanil-ads-kit](https://sanil.app/sanil-ads-kit/). Step-by-step guides and tutorials are in the [documentation](https://sanil.app/help/sanil-ads-kit/).

### Key Features

**Ad Creation & Management**
*   Create image ads, custom HTML/JS/CSS ads, iframes, and Google AdSense units
*   Upload ad images directly from the WordPress Media Library
*   Set custom dimensions, margins, and alignment (left, center, right, float)
*   Control ad visibility per device — desktop, mobile, or both

**Ad Groups & Rotation**
*   Group multiple ads together for A/B testing or campaign rotation
*   Supports **sequential** and **random** rotation modes
*   Give each ad a priority: higher-priority ads come first in sequential rotation and are picked more often in random rotation
*   Control how many ads are visible per group at once
*   Horizontal or vertical group layout options

**Ad Placements**
*   Inject ads into specific positions across your site without touching theme files
*   Supports before content, after content, after the first paragraph, the site footer, popup and skip-ad overlays, and manual placement
*   Place manual placements with the `[amkit_ad_placement]` shortcode, the `amkit_ad_placement()` template function, or `do_action( 'amkit_ads_placement', 'placement-id' )`
*   Assign individual ads or entire groups to a placement
*   Duplicate and manage placements from a clean admin interface

**Scheduling**
*   Set an expiry date and time for any ad, and use WordPress's scheduled publishing for a start date
*   Ads automatically go live and expire on schedule — no manual intervention needed
*   Timezone-aware scheduling using your WordPress site timezone

**Targeting & Conditions**
*   Show or hide ads based on post type, specific pages, categories, tags, any public taxonomy, author, post format, page template, parent page, content age, archive type, and more
*   Add several conditions per ad: ads show when any "is" condition matches, and any matching "is not" condition hides them
*   Show an ad on desktop only, mobile only, or all devices
*   Fine-grained control without writing custom code

**Popup & Skip Ads**
*   Built-in popup ad overlay support
*   Skip ad countdown timer for interstitial-style ads

**Flexible Display Options**
*   **Shortcodes** — embed ads, groups and placements anywhere with `[amkit_ad]`, `[amkit_ad_group]` and `[amkit_ad_placement]`
*   **Gutenberg Block** — insert ads directly in the block editor
*   **Template Functions** — developer-friendly PHP functions for theme integration
*   **Placements** — automatic injection with zero code

**Analytics**
*   Track impressions, clicks, and click-through rate (CTR) for every ad
*   Views, Clicks and CTR columns right in the All Ads list, sortable so you can see your best performers at a glance
*   Per-ad report on the ad edit screen: daily chart, countries, pages, and peak click hours, for 7, 30 or 90 days or a custom date range
*   Country detection uses a bundled local database — no external service, and visitor IP addresses are never stored
*   Sends `ad_impression` and `ad_click` events to Google Analytics (gtag.js) or Google Tag Manager when either is already on your site

**Developer Friendly**
*   Clean namespace-based PHP architecture (PSR-4)
*   Hooks and filters for extensibility (for example `amkit_group_ads_query_args`, `amkit_server_side_device_filter` and `amkit_ad_rendered`)
*   No jQuery dependency in frontend output
*   Minimal CSS footprint — easy to style to match your theme

== Installation ==

1. Upload the `sanil-ads-kit` folder to `/wp-content/plugins/`.
2. Activate the plugin via the **Plugins** menu in WordPress.
3. Navigate to **Sanil Ads Kit** in the WordPress admin sidebar.
4. Create your first ad under **Sanil Ads Kit → All Ads → Add New**.
5. Optionally configure placements under **Sanil Ads Kit → Placements** to auto-inject ads sitewide.

== Frequently Asked Questions ==

= Does it support Google AdSense? =
Yes. Use the **AdSense** ad type to paste your AdSense code directly. Admins with the `unfiltered_html` capability can enter raw script tags.

= Can I rotate multiple ads in the same spot? =
Yes. Create an **Ad Group**, add your ads to it, choose sequential or random rotation, and assign the group to a placement or shortcode.

= How do I display an ad inside a post? =
Use the shortcode `[amkit_ad id="123"]` (or `[amkit_ad_group id="4"]` for a group) or insert a **Sanil Ads Kit** Gutenberg block in the post editor.

= Can I show ads only on certain pages? =
Yes. Each ad has a **Targeting** section where you can set conditions based on post type, specific pages, categories, tags, taxonomies, author, post format, page template, parent page, content age and archive type. The **Show On** field limits an ad to desktop or mobile visitors. Targeting by user role is not available.

= How do I add an ad to my theme template? =
Use the template function `<?php amkit_ad_group( 'your-group-slug' ); ?>` or `<?php amkit_ad_placement( 'placement-id' ); ?>` anywhere in your theme files.

= Will it slow down my site? =
No. The plugin is built for performance. On the front end it loads one small stylesheet (about 2 KB, under 1 KB compressed) and, only on pages that display an ad, a small analytics script (about 2 KB compressed). Neither needs jQuery; the popup/skip-ad stylesheet and script load only when you have created a popup or skip-ad placement. The heavier admin scripts load only on the plugin's own screens.

= How do I see how my ads are performing? =
The **All Ads** list shows all-time views, clicks and CTR for every ad, and you can sort by any of them. Open an ad to see its detailed report (daily chart, countries, pages and peak click hours) in the **Analytics** box.

= How are views and clicks counted? =
A view is counted when at least half of an ad is visible in the visitor's browser, at most once per ad per browser session. A click is counted each time a visitor clicks an ad's link. Counts are grouped by hour, ad, page and country.

= Does analytics work with page caching? =
Counting happens in the visitor's browser, so cached pages are still tracked. Page caches can serve a page after the security token embedded in it has expired (typically 12–24 hours); if you see tracking stop on heavily cached pages, shorten the cache lifetime.

= Does analytics store personal data? =
No IP addresses, cookies or user identifiers are stored. See the Privacy section below.

= Does it work with page builders like Elementor or Divi? =
Yes. You can use shortcodes in any page builder that supports shortcode widgets or text blocks.

= Is it compatible with caching plugins? =
Yes. Ads are output as plain HTML, so they work with caching plugins. Because targeting conditions and the desktop/mobile setting are evaluated when the page is built, a page cache will keep serving the version it first stored. If you use **Show On** (desktop/mobile) together with full-page caching, either vary the cache by device or return false from the `amkit_server_side_device_filter` filter so every ad is output and CSS hides the wrong one.

= Where can I find the documentation? =
Step-by-step guides, tutorials and troubleshooting articles are at [sanil.app/help/sanil-ads-kit](https://sanil.app/help/sanil-ads-kit/).

= Where can I report a bug or request a feature? =
Please open a thread in the [WordPress.org support forum](https://wordpress.org/support/plugin/sanil-ads-kit/) for this plugin. You can also reach out through [sanil.app/support](https://sanil.app/support/).

= How does clean uninstall work? =
Enable the "Action on uninstall" option in plugin settings, then delete the plugin from the WordPress Plugins screen. This permanently removes all ads, ad groups, placements, analytics data and plugin settings.
Cleanup only runs during WordPress uninstall flow. Manual folder deletion (FTP/file manager) does not trigger uninstall hooks.

== Third-Party Libraries ==

* Select2 4.1.0 (MIT License) — used for the targeting and placement selectors. Bundled as `assets/js/select2.min.js` and `assets/css/select2.min.css`. Unminified source: https://github.com/select2/select2/tree/4.1.0
* Chart.js 4.5.1 (MIT License) — used for the analytics charts. Bundled as `assets/js/chart.min.js`. Unminified source: https://github.com/chartjs/Chart.js/tree/v4.5.1
* MaxMind DB Reader for PHP 1.x (Apache-2.0 License) — reads the country database locally. Installed with Composer into `vendor/maxmind-db/reader`. Source: https://github.com/maxmind/MaxMind-DB-Reader-php
* DB-IP Lite Country database (CC BY 4.0) — IP geolocation by [DB-IP](https://db-ip.com). Bundled as `data/dbip-country-lite.mmdb`; lookups run locally on your server.

The admin stylesheet is compiled from the SCSS files in `assets/scss/`, which are included in the plugin.

== Privacy ==

Sanil Ads Kit does not send data to any third party and makes no external requests.

Analytics, when ads are displayed on your site:
* For each ad view or click, the plugin stores a counter in your own WordPress database (the `amkit_ads_stats` table): the ad, the page it appeared on, the hour, and the visitor's country.
* The country is looked up from the visitor's IP address using a database bundled with the plugin. The IP address itself is never stored or sent anywhere.
* No cookies are set. To avoid counting the same view twice, the visitor's browser remembers which ads it has already counted for the current session only (using `sessionStorage`).
* If Google Analytics (gtag.js) or Google Tag Manager is already installed on your site, the plugin also sends `ad_impression` and `ad_click` events to it. That is handled by your existing Google tag, so include it in your own privacy policy.

All analytics data is deleted when an ad is permanently deleted, and with the rest of the plugin's data when the plugin is deleted with "Action on uninstall" enabled.

== Screenshots ==

1. All Ads — views, clicks and CTR for every ad, sortable at a glance.
2. Groups — organize ads for rotation and A/B testing.
3. Ad editor — ad type, creative, click URL, priority and device.
4. Layout, margins and targeting conditions.
5. Per-ad analytics — daily chart, countries, pages and peak click hours.
6. Placements — set up automatic ad injection with no theme edits.
7. Popup placement — trigger delay, show frequency and close options.
8. Settings — choose who can manage ads, and cleanup preferences.
9. Ads inside a post — header leaderboard, after-first-paragraph promo and footer ads.
10. A popup ad on the front end.
11. A skip-ad interstitial with countdown.

== Changelog ==

= 1.0.1 =
* Updated the plugin homepage, documentation and tutorial links to the new Sanil Ads Kit pages on sanil.app.
* Added documentation and support links to the readme.

= 1.0.0 =
* Initial release.

== Upgrade Notice ==

= 1.0.1 =
* Updates the plugin homepage and documentation links. No functional changes.

= 1.0.0 =
* Initial release.
