Description
# XPlay Ads Plugin — Documentation
**Version:** 1.0.0
**Requires:** WordPress 5.8+, PHP 7.4+
**Compatible with:** XPlay Theme
—
## Table of Contents
1. [Installation](#installation)
2. [Initial Setup](#initial-setup)
3. [Stripe Setup](#stripe-setup)
4. [PayPal Setup](#paypal-setup)
5. [Ad Slots](#ad-slots)
6. [Shortcodes & Template Tags](#shortcodes–template-tags)
7. [Admin Dashboard](#admin-dashboard)
8. [Advertiser Flow](#advertiser-flow)
9. [User Dashboard](#user-dashboard)
10. [Ad Expiration](#ad-expiration)
11. [Security](#security)
12. [Database Schema](#database-schema)
13. [Troubleshooting](#troubleshooting)
—
## Installation
1. Download `xplay-ads.zip`.
2. In your WordPress admin, go to **Plugins → Add New → Upload Plugin**.
3. Upload the zip file and click **Install Now**.
4. Click **Activate Plugin**.
The plugin will automatically:
– Create three database tables (`xplay_ad_slots`, `xplay_ads`, `xplay_ad_payments`)
– Insert four default ad slots (Header, Sidebar Top, Sidebar Bottom, Footer)
– Schedule an hourly cron job to expire ads
—
## Initial Setup
After activation:
1. Go to **XPlay Ads → Settings**.
2. Enter your Stripe and/or PayPal credentials (see sections below).
3. Create two WordPress pages:
– **”Submit Ad”** — place the shortcode `[xplay_ad_form]` in the content
– **”Advertiser Dashboard”** — place the shortcode `[xplay_ad_dashboard]` in the content
4. In Settings → Pages, select those two pages from the dropdowns and save.
5. Add ad slots to your theme (see [Shortcodes](#shortcodes–template-tags)).
—
## Stripe Setup
1. Log into [dashboard.stripe.com](https://dashboard.stripe.com).
2. Go to **Developers → API Keys**.
3. Copy **Publishable key** → paste into **XPlay Ads → Settings → Stripe Publishable Key**.
4. Copy **Secret key** → paste into **Stripe Secret Key**.
5. Go to **Developers → Webhooks → Add endpoint**.
6. Set the endpoint URL to:
“`
https://yoursite.com/wp-admin/admin-ajax.php?action=xplay_stripe_webhook
“`
7. Select the event: `checkout.session.completed`.
8. Copy the **Signing secret** → paste into **Stripe Webhook Secret**.
> **Testing:** Use Stripe test keys (start with `pk_test_` / `sk_test_`) and test card `4242 4242 4242 4242`.
—
## PayPal Setup
1. Log into [developer.paypal.com](https://developer.paypal.com).
2. Go to **My Apps & Credentials → Create App**.
3. Copy **Client ID** and **Secret** into Settings.
4. Check **Sandbox Mode** while testing; uncheck for live.
> **Testing:** Use sandbox credentials and PayPal sandbox buyer accounts from the developer dashboard.
—
## Ad Slots
Default slots created on activation:
| Name | Slug | Size | Price |
|—————-|—————-|————|———|
| Header Banner | `header` | 728×90 | $49.99 |
| Sidebar Top | `sidebar-top` | 300×250 | $29.99 |
| Sidebar Bottom | `sidebar-bottom`| 300×250 | $24.99 |
| Footer Banner | `footer` | 728×90 | $39.99 |
### Creating a new slot
1. Go to **XPlay Ads → Ad Slots → Add New Slot**.
2. Fill in: Name, Slug (auto-generated), Description, Width, Height, Price.
3. Click **Create Slot**.
The slug is what you use in shortcodes and template tags.
—
## Shortcodes & Template Tags
### Display an ad slot
**Shortcode** (in pages, posts, widgets):
“`
[xplay_ad slot=”header”]
[xplay_ad slot=”sidebar-top”]
[xplay_ad slot=”footer”]
“`
**PHP template tag** (in theme files):
“`php
“`
If no ad is active in the slot, a styled **”Advertise Here”** placeholder is shown, linking to the submission page.
### Submission form
“`
[xplay_ad_form]
“`
Displays the full multi-step form (fill → preview → pay). Requires the user to be logged in.
### Advertiser dashboard
“`
[xplay_ad_dashboard]
“`
Shows the logged-in user’s ads, stats, payment history, and renew options.
—
## Admin Dashboard
### XPlay Ads → All Ads
View all ads across all advertisers. For each ad you can see:
– Advertiser name and email
– Which slot the ad is in
– Banner thumbnail
– Status (active / pending_payment / rejected / expired)
– Active dates (start → end)
– Impression and click counts
– Payment amount and method
You can manually change an ad’s status using the dropdown.
### XPlay Ads → Ad Slots
Create, edit, and delete ad slots. The “Available” column shows whether a slot currently has an active advertiser.
### XPlay Ads → Payments
Full payment history across all advertisers, including transaction IDs from Stripe/PayPal.
### XPlay Ads → Settings
Configure Stripe keys, PayPal credentials, sandbox mode, and page assignments.
—
## Advertiser Flow
The complete advertiser journey:
“`
1. Visit the Submit Ad page (must be logged in)
↓
2. Fill in: Name, Email, Target URL, Slot, Duration, Upload Banner
↓
3. Click “Preview My Ad →”
→ Banner is uploaded and saved as “pending_payment”
→ Ad is NOT visible publicly yet
↓
4. Preview shown in slot dimensions
→ Review banner appearance
↓
5. Choose payment: Stripe or PayPal
→ Redirected to hosted checkout
↓
6. Payment confirmed
→ Ad status becomes “active”
→ Start/end dates are set
→ Confirmation email sent to advertiser
→ Ad is now live on the site
↓
7. Ad expires automatically on end date
→ Status becomes “expired”
→ Slot becomes available for new advertisers
“`
—
## User Dashboard
The `[xplay_ad_dashboard]` shortcode shows logged-in users:
– **Active Ads** — banner preview, slot name, status badge, date range
– **Stats** — impressions, clicks, and CTR (click-through rate)
– **Renew button** — on expired ads; triggers a new payment flow
– **Payment History** — date, amount, method, status for all past payments
—
## Ad Expiration
Ads expire automatically based on the duration chosen at submission (7, 14, 30, 60, or 90 days).
– An hourly WP-Cron job (`xplay_ads_check_expiration`) checks for ads where `end_date < today`. – Expired ads have their status set to `expired`. – The slot immediately becomes available for a new advertiser. > If WP-Cron is disabled on your host, you may need to set up a real cron job:
> “`
> */60 * * * * wget -q -O /dev/null “https://yoursite.com/wp-cron.php?doing_wp_cron”
> “`
—
## Security
The plugin implements the following security measures:
| Measure | Implementation |
|—|—|
| Nonce verification | All forms and AJAX handlers use `wp_nonce_field` / `check_ajax_referer` |
| Capability checks | All admin actions require `manage_options` capability |
| Input sanitization | All inputs sanitized with appropriate WP functions (`sanitize_text_field`, `sanitize_email`, `esc_url_raw`, `absint`) |
| Output escaping | All output uses `esc_html`, `esc_attr`, `esc_url` |
| File type validation | Banner uploads restricted to JPEG/PNG/GIF/WebP by MIME type |
| File size limit | Banners capped at 2 MB |
| Payment verification | Ads only activate after confirmed payment response from Stripe/PayPal API |
| Ownership checks | Users can only renew their own ads (`user_id` check) |
—
## Database Schema
### `wp_xplay_ad_slots`
| Column | Type | Notes |
|—|—|—|
| id | BIGINT | Primary key |
| name | VARCHAR(100) | Display name |
| slug | VARCHAR(100) | Used in shortcodes |
| description | TEXT | Optional |
| width | INT | Pixels |
| height | INT | Pixels |
| price | DECIMAL(10,2) | Per period |
| status | VARCHAR(20) | `active` / `deleted` |
### `wp_xplay_ads`
| Column | Type | Notes |
|—|—|—|
| id | BIGINT | Primary key |
| user_id | BIGINT | WP user ID |
| slot_id | BIGINT | FK → ad_slots |
| advertiser_name | VARCHAR(150) | |
| advertiser_email | VARCHAR(200) | |
| banner_url | VARCHAR(500) | Uploaded image URL |
| target_url | VARCHAR(500) | Click destination |
| duration_days | INT | 7/14/30/60/90 |
| start_date | DATE | Set on payment |
| end_date | DATE | start + duration |
| status | VARCHAR(30) | `pending_payment` / `active` / `expired` / `rejected` |
| payment_method | VARCHAR(20) | `stripe` / `paypal` |
| payment_id | VARCHAR(200) | Transaction/session ID |
| payment_amount | DECIMAL(10,2) | Amount paid |
| impressions | BIGINT | Counter |
| clicks | BIGINT | Counter |
### `wp_xplay_ad_payments`
| Column | Type | Notes |
|—|—|—|
| id | BIGINT | Primary key |
| ad_id | BIGINT | FK → ads |
| user_id | BIGINT | WP user ID |
| amount | DECIMAL(10,2) | |
| currency | VARCHAR(10) | Default: USD |
| payment_method | VARCHAR(20) | `stripe` / `paypal` |
| transaction_id | VARCHAR(200) | From gateway |
| status | VARCHAR(30) | `completed` / `pending` |
—
## Troubleshooting
**Ads not going live after payment**
– Check your Stripe webhook is configured and the signing secret matches Settings.
– For PayPal, ensure your app credentials are correct and Sandbox mode matches your keys.
– Check the WordPress error log for any PHP errors.
**PayPal redirect not working**
– Ensure pretty permalinks are enabled (Settings → Permalinks → save).
– The return URL uses `home_url(‘/’)` — make sure your home URL is correct.
**Cron not running / ads not expiring**
– Many shared hosts disable WP-Cron. Set up a real server cron as described in [Ad Expiration](#ad-expiration).
**Upload errors**
– Check that `wp-content/uploads/` is writable (`chmod 755` or `775`).
– Confirm your PHP `upload_max_filesize` and `post_max_size` are at least 2 MB.
**”Slot is currently taken” on a slot that looks empty**
– An ad may be in `pending_payment` status (submitted but not yet paid). Admins can reject or delete it from **XPlay Ads → All Ads**.
—
*For support, contact your site administrator or the plugin developer.*
