# Sponzar Access Layer™ — Embed SDK & Web Components User Manual

> **SDK File:** `https://sponzar.africa/sdk/sdk.js`  
> **Interactive Playground:** [`https://sponzar.africa/sdk/demo.html`](https://sponzar.africa/sdk/demo.html)  
> **Architecture:** Native HTML5 Web Components (Shadow DOM)  
> **Compatibility:** Any website (HTML, WordPress, React, Vue, Webflow, Squarespace, Wix, Shopify)

---

## 1. Overview & 5-Minute Quickstart

The **Sponzar Access Layer™ Embed SDK** turns any website into an interactive creator hub with one line of code. Through standard HTML5 Web Components, creators and publishers can embed paywalled videos, micro-dramas, audio albums, podcasts, live event ticket sales, tip jars, subscription memberships, bookable appointments, and verified event suppliers directly into external pages.

### 1.1 Complete Features & Web Components Matrix

| # | Feature / Capability | Web Component Tag | Primary Attributes | What It Displays |
|---|---|---|---|---|
| **1** | **Micro-Dramas & TV Series** | `<sponzar-series>` | `id`, `theme`, `primary-color` | Cinema cover, episode list, locked video frosted overlay, & Season Pass unlock. |
| **2** | **Music Albums & Audio** | `<sponzar-music>` | `id`, `theme`, `accent-color` | Album art, tracklist, audio player, & individual track purchase modals. |
| **3** | **Creator Subscriptions** | `<sponzar-subscribe>` | `creator-id`, `theme` | Multi-tier membership box with monthly ZAR pricing & instant subscribe action. |
| **4** | **Instant Tip Jar** | `<sponzar-tip>` | `creator`, `suggested`, `theme` | Rand preset buttons (R20, R50, R100), custom amount, & optional message. |
| **5** | **Event Tickets & Passes** | `<sponzar-events>` / `<sponzar-ticket>` | `event-id`, `theme` | Live date, venue, capacity badge, ticket tier checkout, & instant QR issuance. |
| **6** | **Digital Products Store** | `<sponzar-shop>` | `theme`, `category` | Product grid for digital downloads, sample packs, and merchandise. |
| **7** | **Creator Appointments** | `<sponzar-booking>` | `creator-id`, `theme` | 1-on-1 mentorship and booking service list with calendar appointment modals. |
| **8** | **Podcast Series & Audio** | `<sponzar-podcast>` | `id`, `theme` | Podcast episode list, show notes, audio waveform streaming, & bonus unlocks. |
| **9** | **EventOS Vendor Marketplace** | `<sponzar-vendors>` / `<sponzar-vendor>` | `category`, `id`, `theme` | Verified event vendors (Sound, Stage, Catering) with Escrow hire contracts. |
| **10** | **Universal App Container** | `<sponzar-app>` | `type`, `id`, `theme` | Polymorphic container that auto-delegates to any Sponzar component. |

---

### 1.2 5-Minute Setup Guide

#### Step 1: Include the SDK Script
Add this line to your website's `<head>` or before the closing `</body>` tag:
```html
<script src="https://sponzar.africa/sdk/sdk.js" data-token="YOUR_EMBED_TOKEN"></script>
```

#### Step 2: Add Any Component Tag
Paste custom tags anywhere inside your page body:
```html
<!-- Embed a Micro-Drama or TV Series with Paywall -->
<sponzar-series id="101" theme="dark"></sponzar-series>

<!-- Embed Event Tickets -->
<sponzar-ticket event="7" theme="dark"></sponzar-ticket>

<!-- Embed a Tip Jar -->
<sponzar-tip creator="alice" suggested="25,50,100" theme="dark"></sponzar-tip>
```

---

## 2. Visual Wireframes, Layouts & States

### 2.1 Video Series Player — `<sponzar-series>`

#### Visual Anatomy & Layout:
```
┌────────────────────────────────────────────────────────────────────────────────────────┐
│  ┌──────────────┐   [🎬 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 ]      │
└────────────────────────────────────────────────────────────────────────────────────────┘
```

#### States & Micro-Interactions:
* **Free Episode (`▶ Play`):** Clicking plays video immediately in an inline responsive HTML5 video player inside the component's Shadow DOM.
* **Locked Episode (`🔓 R15.00`):** Frosted dark overlay with a lock badge. Clicking opens the checkout modal. Upon successful payment, the episode transitions immediately to unlocked without reloading the page.
* **Season Pass Button:** Unlocks all current and future episodes of the series in one transaction.

---

### 2.2 EventOS Ticketing Box — `<sponzar-events>` & `<sponzar-ticket>`

```
┌────────────────────────────────────────────────────────────────────────────────────────┐
│  📅 28 OCT 2026   •   📍 Cape Town Stadium                                             │
│  AFRICAN CREATOR SUMMIT 2026                                                           │
│  The premier gathering of African digital creators, filmmakers, and technologists.    │
├────────────────────────────────────────────────────────────────────────────────────────┤
│  TICKET TIERS                                                                          │
│                                                                                        │
│  General Admission    Access to main stage & creator marketplace           R150.00     │
│                       [ Buy GA Ticket ]                                                │
│                                                                                        │
│  VIP Pass             Front row seating + Backstage networking lounge      R450.00     │
│                       [ Buy VIP Pass ]                                                 │
└────────────────────────────────────────────────────────────────────────────────────────┘
```

Upon purchase, an encrypted QR ticket code is rendered on-screen and added to the attendee's mobile wallet for on-site scanning.

---

### 2.3 EventOS Verified Vendor Marketplace — `<sponzar-vendors>` & `<sponzar-vendor>`

```
┌────────────────────────────────────────────────────────────────────────────────────────┐
│  [✓ Verified Supplier]                                              ⭐ 4.9 (42 Reviews)│
│  SOUNDCRAFT AUDIO & LIGHTING SOLUTIONS                                                 │
│  Category: Sound, Staging & Production                                                 │
│  Starting Rate: R5,000 / Day                                                           │
│                                                                                        │
│  Verified inventory: Line array systems, digital consoles, moving heads, power backup.  │
│                                                                                        │
│  [ 🤝 Hire via Sponzar Escrow ]                                                        │
└────────────────────────────────────────────────────────────────────────────────────────┘
```

Clicking **Hire via Sponzar Escrow** initiates an escrow milestone contract powered by Sponzar's `EscrowOrchestrator`, protecting both the event organizer and the supplier.

---

## 3. In-Page Modal Checkout & Custom DOM Events

### 3.1 Zero-Redirect Modal Experience
When an external visitor clicks any buy, subscribe, or hire button:
1. The SDK creates an SSL overlay modal (`sponzar-modal`) directly on top of the parent page.
2. The visitor can pay using their Sponzar Wallet or Instant EFT (Ozow).
3. Once completed, the modal displays a confirmation message and automatically updates the component state to unlocked.

### 3.2 Custom JavaScript DOM Events
The SDK emits native Custom Events on the `window` object so your site can trigger analytics, conversion pixels, or custom UI animations:

```javascript
// 1. Listen for Event Ticket Purchases
window.addEventListener('sponzar:ticket:purchased', (e) => {
  console.log('Ticket Purchased:', e.detail);
  // detail: { event_id: 7, ticket_id: "TCK_123", amount: 150.00, currency: "ZAR" }
  
  if (window.gtag) {
    gtag('event', 'purchase', {
      transaction_id: e.detail.ticket_id,
      value: e.detail.amount,
      currency: 'ZAR'
    });
  }
});

// 2. Listen for Tips Sent
window.addEventListener('sponzar:tip:sent', (e) => {
  console.log('Tip Received:', e.detail);
  // detail: { creator: "alice", amount: 50.00, message: "Great show!" }
});

// 3. Listen for Content Unlocked
window.addEventListener('sponzar:content:unlocked', (e) => {
  console.log('Content Unlocked:', e.detail);
  // detail: { series_id: 101, episode_id: 3, amount: 15.00 }
});

// 4. Listen for Subscriptions
window.addEventListener('sponzar:subscribed', (e) => {
  console.log('New Subscription:', e.detail);
  // detail: { creator_id: 12, tier: "Gold VIP", amount: 150.00 }
});
```

---

## 4. Shadow DOM Theme Engine & CSS Variables

Sponzar Web Components use **Shadow DOM** for total style encapsulation. Your website's stylesheet cannot break the component, and the component's styles cannot leak into your layout.

You can customize component colors, typography, and borders by declaring CSS variables on the component selector in your stylesheet:

```css
sponzar-series,
sponzar-events,
sponzar-tip,
sponzar-vendors {
  --sp-primary: #6366f1;           /* Buttons & primary accents */
  --sp-primary-hover: #4f46e5;     /* Hover state for buttons */
  --sp-accent: #00cec9;            /* Secondary highlights and badges */
  --sp-bg-card: #121226;           /* Card background */
  --sp-text: #ffffff;              /* Heading & title color */
  --sp-text-muted: #9595b2;        /* Body & description text */
  --sp-border: #24244a;            /* Card border color */
  --sp-radius: 14px;               /* Corner border radius */
  --sp-font: 'Inter', sans-serif;  /* Typography font family */
}
```

---

## 5. Framework Integration Guides

### 5.1 React / Next.js
```jsx
import Script from 'next/script';

export default function SeriesWatchPage() {
  return (
    <main className="container">
      <Script 
        src="https://sponzar.africa/sdk/sdk.js" 
        data-token="emb_live_your_token" 
        strategy="afterInteractive" 
      />
      <h1>Cape Town Underground</h1>
      <sponzar-series id="101" theme="dark" />
    </main>
  );
}
```

### 5.2 Webflow, Squarespace, Wix & Shopify
1. Add an **Embed HTML** or **Custom Code** element to your page.
2. Paste the SDK script tag:
   ```html
   <script src="https://sponzar.africa/sdk/sdk.js" data-token="emb_live_your_token"></script>
   ```
3. Place the component tag where you want it to appear:
   ```html
   <sponzar-events theme="dark"></sponzar-events>
   ```
4. Publish your site.

---

## 6. Interactive Playground & Additional Manuals

* **Interactive SDK Playground:** Experience and test all 10 components with live token switching and DOM telemetry at:  
  👉 [`https://sponzar.africa/sdk/demo.html`](file:///home/sponzar.africa/public_html/public/sdk/demo.html)
* **WordPress Plugin Manual:** [docs/wordpress_plugin_manual.md](file:///home/sponzar.africa/public_html/docs/wordpress_plugin_manual.md)
* **API Developer Guide:** [docs/api_developer_guide.md](file:///home/sponzar.africa/public_html/docs/api_developer_guide.md)
* **EventOS User Manual:** [docs/event_os_user_manual.md](file:///home/sponzar.africa/public_html/docs/event_os_user_manual.md)
* **Vendor Operations Guide:** [docs/vendor_operations_guide.md](file:///home/sponzar.africa/public_html/docs/vendor_operations_guide.md)