=== PYH Ads ===
Contributors: planyourhost
Tags: ads, advertising, adsense, ad manager, analytics
Requires at least: 6.3
Tested up to: 7.1
Requires PHP: 7.4
Stable tag: 1.0.0
License: GPLv2 or later
License URI: https://www.gnu.org/licenses/gpl-2.0.html

Self-hosted ad manager: image, video, HTML and AdSense ads with targeting, placements, scheduling and privacy-friendly built-in analytics.

== Description ==

**PYH Ads** lets you create, target, display and measure advertisements from your WordPress dashboard, with no separate ad platform and no external service.

It is built around three connected systems:

1. **Ad management**: what should be displayed?
2. **Targeting and placement**: where and when should it be displayed?
3. **Analytics**: how is it performing?

= Ad types =

* **Image ads**: pick from the Media Library, add a destination URL and alt text, optionally open in a new tab
* **Video ads**: self-hosted files or supported oEmbed URLs (such as YouTube), poster image, autoplay / mute / loop
* **Custom HTML ads**: basic HTML such as text, links, images and inline styles (sanitised; scripts, iframes and forms are removed)
* **Google AdSense**: enter your publisher ID and ad slot ID; the plugin builds the ad unit for you

= Ad management =

* Create, edit, duplicate, pause / activate, archive and delete ads
* Search, filter and sort by status, type, impressions, clicks, CTR or date
* Statuses: Draft, Active, Paused, Scheduled, Expired and Archived
* Start and end date/time, priority, and optional maximum impressions or clicks
* Preview at desktop, tablet and mobile widths (sandboxed)

= Targeting =

* Entire website, homepage, search results and all archives
* All content of a post type, a specific page / post / custom post type item, a specific category, tag or term, or anything in a taxonomy
* Exclusions always win, for example: show on all posts except the "Web Design" category

= Placements =

Header, below header, homepage hero, before content, after the first paragraph, middle of content, before the final paragraph, after content, sidebar and footer. You can also place an ad manually with the `[pyh_ads id="123"]` shortcode, the **PYH Ad** block, the **PYH Ads** widget, or template tags.

= Rotation =

When several ads compete for one placement, choose highest priority, weighted random, even rotation, random, or best CTR.

= Analytics =

* Impressions, clicks and CTR overall, per ad, per placement and per device type
* Dashboard and charts with Today, Yesterday, Last 7 days, Last 30 days, This month, Previous month and custom date ranges
* CSV export of ads, daily analytics and campaign performance
* Data is stored as small daily totals, with an automatic retention setting

= Performance and privacy =

* One small, batched request per page view; works with page caching and CDNs
* Front-end CSS and JavaScript load only on pages where an ad is actually shown
* No cookies, no IP addresses, no user agents and no personal data are stored
* Optional "Do Not Track" support, and a switch to turn tracking off completely
* Nothing is loaded from a CDN or third-party server by the plugin

= For developers =

* `pyh_ads_display( 123 );` prints a specific ad
* `do_action( 'pyh_ads_placement', 'header' );` prints whichever ad wins a placement
* Filters: `pyh_ads_capability`, `pyh_ads_ad_html`, `pyh_ads_allowed_html`, `pyh_ads_custom_placements`

== Installation ==

1. Upload the `pyh-ads` folder to `/wp-content/plugins/`, or install the plugin from **Plugins → Add New**.
2. Activate the plugin.
3. Go to **PYH Ads → Add New**, create an ad, choose its placements and set its status to Active.

== Frequently Asked Questions ==

= Can I paste JavaScript or my own ad-network code? =

No. Custom HTML ads are sanitised with `wp_kses()`: scripts, iframes and forms are removed when you save and when the ad is displayed. For Google AdSense, enter your publisher ID and ad slot ID and the plugin creates the ad unit. Managing ads requires the `manage_options` capability, which you can change with the `pyh_ads_capability` filter.

= Does it work with caching plugins? =

Yes. Ads are rendered on the server and tracked by a small script that reports to a REST endpoint, so cached pages are still counted. With full-page caching, which ad wins a placement is decided when the page is cached.

= Can AdSense clicks be tracked? =

No. AdSense renders inside a cross-origin iframe, so browsers do not let the page see clicks. Impressions are tracked; use your AdSense reports for clicks. The same applies to embedded YouTube and Vimeo players.

= Why does the header placement not show in my theme? =

Header and homepage hero use the standard `wp_body_open` hook. If your theme does not call `wp_body_open()`, use the shortcode or `do_action( 'pyh_ads_placement', 'header' )` in your template.

= How do I show an ad in a theme template? =

Use `<?php pyh_ads_display( 123 ); ?>` for a specific ad, or `<?php do_action( 'pyh_ads_placement', 'sidebar' ); ?>` for whichever ad wins that placement.

= Do targeting rules apply to shortcodes and blocks? =

No. Targeting applies to automatic placements. An ad inserted with a shortcode, block or widget-by-ID appears where you put it, as long as it is active and within its schedule.

= How do I remove all data? =

Use **PYH Ads → Tools → Delete All PYH Ads Data**, or tick "Delete all ads, analytics and settings when the plugin is deleted" under **PYH Ads → Settings**. Data is kept by default when you delete the plugin.

== External services ==

PYH Ads itself does not send any data to external services. Two optional features involve third parties:

**Google AdSense** (only if you create an AdSense ad)
* What: when an AdSense ad is displayed, your visitor's browser loads Google's AdSense library (`pagead2.googlesyndication.com`) using your publisher ID.
* When: only on pages where an AdSense ad is shown.
* Data sent: whatever Google's AdSense script collects from the visitor's browser, such as IP address and cookies, under Google's terms. You are responsible for any visitor consent your region requires.
* Terms of Service: https://policies.google.com/terms
* Privacy Policy: https://policies.google.com/privacy

**Video oEmbed** (only if you use an embed URL such as YouTube)
* What: embedded by WordPress core's oEmbed feature, which contacts the video provider (for example YouTube) to build the embed.
* Terms and privacy: those of the provider you choose.

== Privacy ==

PYH Ads does not set cookies and does not store IP addresses, user agents, names, email addresses or any other personal data. It stores only daily totals of impressions and clicks per ad, placement and device type (mobile, tablet or desktop, derived from screen width). Google AdSense, if you use it, may set its own cookies; that is governed by Google (see External services).

== Screenshots ==

1. Dashboard with totals, charts and top-performing ads.
2. All Ads list with status, placements, impressions, clicks and CTR.
3. Ad editor with type, placements, targeting rules, schedule and device preview.
4. Settings for rotation, in-content placements, tracking and privacy.
5. Placements overview with per-placement performance and manual placement options.
6. Analytics with impressions, clicks and CTR charts plus placement, device and campaign breakdowns.
7. Tools for CSV export, clearing analytics data and deleting all plugin data.

== Changelog ==

= 1.0.0 =
* Initial release.

== Upgrade Notice ==

= 1.0.0 =
Initial release.
