# Sponzar Connect — WordPress Plugin User Manual

> **Plugin Folder:** `/wp-content/plugins/sponzar-connect`  
> **Tested WordPress Versions:** 5.6 to 6.5+  
> **Requires PHP:** 7.4 or higher  
> **License:** GPLv2 or later  
> **Download Package:** [`https://sponzar.africa/downloads/sponzar-connect.zip`](https://sponzar.africa/downloads/sponzar-connect.zip)

---

## 1. Overview & Master Feature Matrix

**Sponzar Connect** turns any WordPress site into a fully monetized creator hub powered by Sponzar's enterprise Platform Kernel. Creators can publish paywalled videos, micro-dramas, audio albums, podcasts, sell event tickets, collect tips, offer subscription memberships, book appointments, and hire verified event vendors—all through standard WordPress shortcodes with zero custom coding.

### 1.1 Complete Feature Matrix

| # | Feature / Capability | WordPress Shortcode | Underlying Endpoint | Visual Output |
|---|---|---|---|---|
| **1** | **Content Feed & Paywall** | `[sponzar_content]` | `GET /api/v1/content` | Responsive card grid with 16:9 media, locked frosted glass overlay, & ZAR buy buttons. |
| **2** | **Series & Micro-Dramas** | `[sponzar_series]` | `GET /api/v1/series` | Cinema poster grid (2:3 aspect ratio) with episode badges & Season Pass pricing. |
| **3** | **Series Detail & Episode Player** | `[sponzar_series_detail id="..."]` | `GET /api/v1/series/{id}` | Full series hero banner, synopsis, Season Pass button, & interactive episode playlist. |
| **4** | **Audio & Music Albums** | `[sponzar_content type="audio"]` | `GET /api/v1/content?type=audio` | Audio track cards with inline streaming controls and paywalled track unlocks. |
| **5** | **Creator Directory** | `[sponzar_creators]` | `GET /api/v1/creators` | Creator profile cards with avatar, verified badge, bio, and subscription tiers. |
| **6** | **Tiered Subscriptions** | `[sponzar_subscribe]` | `POST /api/v1/subscriptions/subscribe` | Tiered membership box displaying monthly ZAR rates, perks list, and 1-click checkout. |
| **7** | **Direct Tip Jar** | `[sponzar_tip]` | `POST /api/v1/tips/send` | Preset ZAR quick-buttons (R20, R50, R100, R250), custom amount input, and support message. |
| **8** | **EventOS Tickets & Passes** | `[sponzar_events]`, `[sponzar_tickets]` | `GET /api/v1/events`, `POST /purchase` | Date badge, venue location, capacity indicator, tier selection, & instant QR issuance. |
| **9** | **Digital & Physical Shop** | `[sponzar_shop]` | `GET /api/v1/shop/products` | E-commerce product grid for digital downloads, merchandise, and presets. |
| **10** | **Creator Appointments** | `[sponzar_booking]` | `GET /api/v1/bookings/services` | 1-on-1 mentorship and booking service list with calendar appointment modals. |
| **11** | **EventOS Vendor Marketplace** | `[sponzar_vendors]` | `GET /api/v1/vendors`, `POST /hire` | Verified supplier directory (Sound, Staging, Catering) with Escrow hire contracts. |
| **12** | **Universal SDK Container** | `[sponzar_embed type="..."]` | Web Components SDK | Polymorphic loader rendering any Sponzar Web Component dynamically. |

---

## 2. Installation & Quickstart (Under 3 Minutes)

### 2.1 Installing the Plugin

#### Option A: Direct Download (Recommended)
1. Download the production zip archive:  
   👉 **[`https://sponzar.africa/downloads/sponzar-connect.zip`](https://sponzar.africa/downloads/sponzar-connect.zip)**
2. In your WordPress Dashboard, navigate to **Plugins → Add New**.
3. Click **Upload Plugin** at the top of the page.
4. Select `sponzar-connect.zip` and click **Install Now**.
5. Once uploaded, click **Activate Plugin**.

#### Option B: Via FTP / cPanel
1. Unzip `sponzar-connect.zip` on your computer.
2. Upload the `sponzar-connect` directory to `/wp-content/plugins/` on your server.
3. In WordPress Admin, open **Plugins → Installed Plugins** and click **Activate**.

---

### 2.2 Connecting to Your Sponzar Account

1. Log in to your **Sponzar Workspace** (`https://sponzar.africa/panel/user/developer-api`).
2. Go to **Developer → API Keys** and click **Generate New API Key**.
3. Select the required permissions (or `*` for full access) and copy your secret key (`sk_live_...`).
4. In your WordPress Admin sidebar, navigate to **Settings → Sponzar**.
5. Fill in the following fields:
   * **API Base URL**: `https://sponzar.africa` (default).
   * **API Key**: Paste your `sk_live_...` key.
   * **Embed Token**: (Optional) Paste your public embed token if using Web Component mode.
   * **Cache Duration**: Set transient cache in minutes (Default: `15`).
6. Click **Save Changes**.
7. Click the **Test Connection** button. You will see a green banner:  
   `✓ Connection Successful! Connected to Sponzar as: [Your Creator Name]`.

---

## 3. How It Looks & Works: Content Shortcodes Deep-Dive

### 3.1 Content Posts Grid — `[sponzar_content]`

Renders your published feed of videos, photos, and audio files in an adaptive card layout.

```text
[sponzar_content type="video" access="all" per_page="6" columns="3"]
```

#### Visual Wireframe & Layout:
```
┌─────────────────────────────────┐  ┌─────────────────────────────────┐  ┌─────────────────────────────────┐
│ [VIDEO]                         │  │ [VIDEO]                         │  │ [VIDEO]                         │
│ ┌─────────────────────────────┐ │  │ ┌─────────────────────────────┐ │  │ ┌─────────────────────────────┐ │
│ │                             │ │  │ │      [  🔒 LOCKED  ]        │ │  │ │                             │ │
│ │       Video Thumbnail       │ │  │ │                             │ │  │ │       Video Thumbnail       │ │
│ └─────────────────────────────┘ │  │ └─────────────────────────────┘ │  │ └─────────────────────────────┘ │
│ Ep. 01: The Johannesburg Beat   │  │ Ep. 02: Backstage Confidential  │  │ Ep. 03: The Finale              │
│ Exclusive studio breakdown...   │  │ Premium subscribers only...     │  │ Full rehearsal set...           │
│                                 │  │                                 │  │                                 │
│ [Avatar] Sipho Ndlovu • Oct 14  │  │ [Avatar] Sipho Ndlovu • Oct 15  │  │ [Avatar] Sipho Ndlovu • Oct 16  │
│ ▶ Watch Free                    │  │ 🔓 Unlock for R35.00            │  │ ▶ Watch Free                    │
└─────────────────────────────────┘  └─────────────────────────────────┘  └─────────────────────────────────┘
```

#### States & Micro-Interactions:
* **Free / Unlocked Posts:**
  - High-resolution poster with clear 16:9 aspect ratio.
  - Media type badge in top-left corner (`Video`, `Audio`, `Image`).
  - Creator avatar pill and publication date.
  - Clicking launches the media player immediately in-page.
* **Locked / Monetized Posts:**
  - Frosted dark glass overlay (`rgba(0,0,0,0.65)` backdrop blur) with a centered `🔒` lock badge.
  - High-visibility action button: `🔓 Unlock for R[Price]`.
  - Clicking launches the native in-page checkout modal.
* **Attributes Reference:**
  | Parameter | Default | Allowed Values | Description |
  |---|---|---|---|
  | `type` | `all` | `all`, `image`, `video`, `audio`, `file` | Filter content by media type |
  | `access` | `all` | `all`, `free`, `paid` | Filter by access level |
  | `per_page` | `10` | `1` to `50` | Number of cards to display |
  | `columns` | `3` | `1`, `2`, `3`, `4`, `5`, `6` | Column layout grid |
  | `creator_id` | *(empty)* | Integer ID | Show content from a specific creator |

---

### 3.2 Series Catalog Grid — `[sponzar_series]`

Displays catalogs of episodic productions (micro-dramas, TV shows, music albums, podcasts).

```text
[sponzar_series type="micro_drama" per_page="8" columns="4"]
```

#### Visual Appearance:
* **Cinema Poster Ratio:** Cards use a vertical `2:3` aspect ratio matching cinema and streaming platforms.
* **Type Pill:** Distinct badges for `🎬 Micro-Drama`, `📺 TV Series`, `🎵 Music Album`, and `🎙️ Podcast`.
* **Episode Counter:** Frosted pill in top-right displaying episode count (e.g., `12 episodes`).
* **Pass Price:** Displays Season Pass pricing in South African Rand (e.g., `Pass: R120.00`).
* **Attributes Reference:**
  | Parameter | Default | Allowed Values | Description |
  |---|---|---|---|
  | `type` | `all` | `all`, `micro_drama`, `tv_series`, `music_album`, `podcast` | Filter by series type |
  | `per_page` | `10` | `1` to `50` | Items per page |
  | `columns` | `3` | `1`, `2`, `3`, `4` | Column layout |
  | `creator_id` | *(empty)* | Integer ID | Filter by creator ID |

---

### 3.3 Single Series & Episode Player — `[sponzar_series_detail]`

Renders a complete, dedicated streaming page for a single series.

```text
[sponzar_series_detail id="101"]
```

#### Visual Wireframe:
```
┌────────────────────────────────────────────────────────────────────────────────────────┐
│  ┌──────────────┐   [🎬 Micro-Drama]                                                   │
│  │              │   BLOOD & REVENGE (SEASON 1)                                         │
│  │    POSTER    │   A high-stakes thriller set in Cape Town's underground.              │
│  │    (2:3)     │                                                                      │
│  │              │   By Sipho Ndlovu  •  10 Episodes  •  Season Pass: R95.00            │
│  └──────────────┘   [ 🎬 Buy Season Pass — R95.00 ]                                    │
├────────────────────────────────────────────────────────────────────────────────────────┤
│  EPISODES                                                                              │
│                                                                                        │
│  [1] [Thumb]  Episode 1: The Heist (14 mins)                        [ ▶ Play ]         │
│  [2] [Thumb]  Episode 2: The Ambush (16 mins)                       [ 🔓 R15.00 ]      │
│  [3] [Thumb]  Episode 3: The Confession (18 mins)                    [ 🔓 R15.00 ]      │
└────────────────────────────────────────────────────────────────────────────────────────┘
```

#### Behavior & Unlocking:
* **Hero Section:** Shows high-res cover art, series genre, creator byline, episode total, and a primary **Buy Season Pass** button.
* **Episode Playlist Table:**
  - Free / Unlocked episodes display a green `▶ Play` badge.
  - Locked individual episodes display an instant unlock button: `🔓 R15.00`.
  - Purchasing either an individual episode or the Season Pass immediately unlocks the content without page navigation.

---

### 3.4 The In-Page Checkout Modal Experience

When any visitor clicks an `Unlock`, `Buy Ticket`, `Subscribe`, or `Hire` button, Sponzar Connect handles the entire financial transaction via an in-page, mobile-optimized SSL modal:

```
User clicks "🔓 Unlock for R35.00"
               │
               ▼
┌────────────────────────────────────────────────────────┐
│  SPONZAR CONNECT — SECURE CHECKOUT                     │
│                                                        │
│  💳 Unlock Content                                     │
│  "Ep. 02: Backstage Confidential"                      │
│                                                        │
│  Amount: R35.00                                        │
│  Charged to your Sponzar Wallet or Instant EFT (Ozow)  │
│                                                        │
│  [  ✓ Confirm Unlock  ]       [ Cancel ]               │
└────────────────────────────────────────────────────────┘
               │
               ▼ (Instant AJAX charge via Platform Kernel)
┌────────────────────────────────────────────────────────┐
│  ✓ Payment Successful!                                 │
│  Unlocking content in 1.5s...                          │
└────────────────────────────────────────────────────────┘
               │
               ▼
Card automatically switches from Locked ➔ Unlocked with inline player!
```

* **Zero Page Redirection:** Visitors stay on your WordPress site.
* **Account Linking:** If the visitor is not logged in, a clean modal prompts them to enter their Sponzar User ID to link their wallet balance.
* **Compensating Rollbacks:** If wallet funds are insufficient, users are presented with direct Instant EFT (Ozow) payment options.

---

### 3.5 Creator Directory — `[sponzar_creators]`

Renders a verified creator discovery grid.

```text
[sponzar_creators category="music" per_page="12" columns="4"]
```

* Displays creator avatar, full name, `@username`, and official verification checkmark (`✓`).
* Shows creator profession/category and lowest active subscription tier (e.g., `From R50/mo`).
* Action button links to the creator's full profile or opens their subscription card.

---

### 3.6 Fan Subscriptions — `[sponzar_subscribe]`

Embeds a creator subscription membership tier box.

```text
[sponzar_subscribe creator_id="12" theme="dark" mode="native"]
```

* **Tier Cards:** Displays Bronze, Silver, and Gold membership tiers with recurring monthly ZAR pricing.
* **Perks Checklist:** Bulleted list of subscriber benefits (exclusive videos, early access, Discord role).
* **1-Click Subscribe:** Debits the supporter's wallet monthly with automated renewal.

---

### 3.7 Direct Tip Jar — `[sponzar_tip]`

Embeds an interactive tip jar for direct creator appreciation.

```text
[sponzar_tip creator_id="12" theme="dark"]
```

* **Preset Quick-Buttons:** `R20`, `R50`, `R100`, `R250`.
* **Custom Amount:** Numeric input allowing fans to enter any amount.
* **Message Field:** Supporter can leave an encouraging note shown in the creator's earnings ledger.

---

### 3.8 EventOS Tickets & Passes — `[sponzar_events]` & `[sponzar_tickets]`

Embeds upcoming live events, festivals, and conferences with real-time ticket inventory.

```text
[sponzar_events per_page="6" columns="3"]
[sponzar_tickets event_id="7"]
```

* **Event Card:** Features date badge (`📅 28 OCT 2026`), venue location pin, and remaining capacity indicator.
* **Ticket Tiers:** Displays General Admission, VIP, and Early Bird tiers with prices in ZAR.
* **Instant QR Issuance:** Upon purchase confirmation, the ticket QR code is instantly displayed on-screen, emailed to the attendee, and added to their EventOS Attendee Wallet.

---

### 3.9 Digital Storefront — `[sponzar_shop]`

Renders creator digital products (e-books, sample packs, presets, digital art) and physical merchandise.

```text
[sponzar_shop per_page="8" columns="4"]
```

* Displays product thumbnail, title, stock status, and ZAR price.
* Includes instant **Buy Now** button with automatic secure download link delivery.

---

### 3.10 Creator Appointments & Bookings — `[sponzar_booking]`

Displays bookable creator services for consultations, 1-on-1 coaching, or studio sessions.

```text
[sponzar_booking creator_id="12"]
```

* Shows service title, duration (e.g., `45 mins`), format (Online Video Call / In-Person), and price.
* Clicking **Book Session** opens an interactive date/time slot picker.

---

### 3.11 EventOS Vendor Marketplace — `[sponzar_vendors]`

Enables event organizers to showcase or hire verified event suppliers directly from WordPress.

```text
[sponzar_vendors category="Sound & Audio" columns="3"]
```

* Displays vendor business name, verification badge, category, review rating (`⭐ 4.9`), and starting quote.
* Clicking **Hire Vendor** opens an escrow milestone dialog powered by Sponzar's `EscrowOrchestrator`.

---

### 3.12 Universal Embed SDK Loader — `[sponzar_embed]`

A polymorphic shortcode that loads the Sponzar Access Layer™ SDK and embeds any Web Component directly into WordPress pages.

```text
[sponzar_embed type="events" theme="dark"]
[sponzar_embed type="series" id="101" theme="dark"]
[sponzar_embed type="vendors" category="Security"]
```

---

## 4. Design System & Styling Customization

Sponzar Connect includes an isolated, high-performance CSS stylesheet (`assets/css/sponzar-frontend.css`). It automatically inherits your WordPress theme's primary typography while providing responsive grids and dark mode support.

### 4.1 CSS Custom Properties (Variables)
You can override Sponzar styles by adding these variables to your WordPress Customizer (`Appearance → Customize → Additional CSS`):

```css
:root {
    --sponzar-primary: #6366f1;        /* Primary button and highlight color */
    --sponzar-primary-hover: #4f46e5;  /* Button hover state */
    --sponzar-radius: 14px;            /* Card border radius */
    --sponzar-bg-card: #ffffff;        /* Card background color */
    --sponzar-text: #1e293b;           /* Card title text */
    --sponzar-text-muted: #64748b;     /* Subtitle and description text */
    --sponzar-border: #e2e8f0;         /* Card border color */
}
```

### 4.2 Automatic Dark Mode
Sponzar Connect natively supports OS and browser dark mode preferences. When a visitor's system is set to dark mode, cards automatically switch to dark surfaces:
```css
@media (prefers-color-scheme: dark) {
    --sponzar-bg-card: #1e293b;
    --sponzar-bg-page: #0f172a;
    --sponzar-text: #e2e8f0;
    --sponzar-text-muted: #94a3b8;
    --sponzar-border: #334155;
}
```

### 4.3 Responsive Breakpoints
* **Desktop (>1024px):** Respects requested column count (`columns="3"` or `columns="4"`).
* **Tablet (768px - 1024px):** Automatically condenses to 2 or 3 columns.
* **Mobile (<480px):** Automatically collapses to a full-width 1-column card stack.

---

## 5. Performance & Transient Caching

To guarantee instant page loads and protect your WordPress server from rate limits:
* **15-Minute Transient Cache:** Sponzar Connect caches API responses in the WordPress database for 15 minutes by default.
* **Instant Manual Flush:** If you publish a new post or change pricing on Sponzar, navigate to **Settings → Sponzar** in WordPress Admin and click **Clear Cache Now**.
* **Zero Script Bloat:** The frontend CSS is under `16 KB` and loads only on pages where Sponzar shortcodes are present.

---

## 6. Live Testing Playground & Additional Documentation

* **Interactive SDK Playground:** Test all components, themes, and checkout events live at:  
  👉 [`https://sponzar.africa/sdk/demo.html`](file:///home/sponzar.africa/public_html/public/sdk/demo.html)
* **API Developer Guide:** Full REST specifications in [docs/api_developer_guide.md](file:///home/sponzar.africa/public_html/docs/api_developer_guide.md)
* **Embed SDK Manual:** Web Components reference in [docs/embed_sdk_manual.md](file:///home/sponzar.africa/public_html/docs/embed_sdk_manual.md)
* **Vendor Operations Guide:** Escrow and marketplace workflows in [docs/vendor_operations_guide.md](file:///home/sponzar.africa/public_html/docs/vendor_operations_guide.md)
* **EventOS User Manual:** Ticketing and attendee management in [docs/event_os_user_manual.md](file:///home/sponzar.africa/public_html/docs/event_os_user_manual.md)

---

## 7. Frequently Asked Questions (FAQ)

**Q: Do my website visitors need a Sponzar account to buy locked content or tickets?**  
A: No. Visitors can complete checkouts as guests using Instant EFT (Ozow) or credit/debit card, or link their existing Sponzar wallet for 1-click purchases.

**Q: Where do the earnings from WordPress sales go?**  
A: All funds are credited directly to your Sponzar Creator Wallet in real time, following the platform's immutable financial ledger rules. You can withdraw funds to any South African bank account at any time.

**Q: Can I use Sponzar Connect with page builders like Elementor or Divi?**  
A: Yes! Simply drag a **Shortcode** widget into your layout and paste any Sponzar shortcode.