# Blue Billywig for WordPress — Administrator guide

This guide is for the WordPress site administrator who installs and configures the plugin. The editor-facing guide lives in [user-guide.md](./user-guide.md).

## Who this plugin is for

Any WordPress site that publishes videos hosted on the Blue Billywig Online Video Platform (OVP). It provides:

- A Gutenberg embed block and a `[blue_billywig]` shortcode.
- A Media Library browser backed by your BB publication (search, folders, bulk actions).
- A slide-in metadata drawer for in-place editing of clip title, description, tags, status, CPP, playout, publication date, and language.
- Upload from WordPress to BB over TUS (resumable, direct to S3 — never through the WP server).
- Captions upload, per-clip call-to-action editor (link + email-capture modes).
- Server-side block rendering with JSON-LD VideoObject schema.
- An XML video sitemap provider.
- oEmbed: paste a `https://<pub>.bbvms.com/p/.../c/<id>.html` URL in the editor and it auto-embeds.

## Requirements

- WordPress 6.9 or later.
- PHP 8.1 or later.
- A Blue Billywig publication and an API identity (ID + secret) with SAPI access.

## Installation

1. Download the release ZIP.
2. `Plugins → Add New → Upload Plugin`, select the ZIP, activate.
3. Go to `Blue Billywig → Settings` in the WP admin sidebar and enter:
   - **Publication** (sub-domain — the `X` in `X.bbvms.com`).
   - **API ID** and **API secret** — issued in the OVP admin under `Users → API keys`.
   - **Default playout** (normally `default`).
   - **Embed type** (`javascript` recommended; `iframe` only when your theme needs it).
4. Click **Test connection**. A green banner confirms the plugin can reach SAPI.

If the connection test fails, see [Troubleshooting](#troubleshooting).

## Capability model

| Capability          | Who gets it by default                   | What it grants                                |
|---------------------|------------------------------------------|-----------------------------------------------|
| `edit_posts`        | Contributor and above                    | Browse the BB library, insert embeds, inline-edit metadata, upload captions, create CTAs, run bulk status/folder/CPP changes. |
| `delete_posts`      | Author and above                         | Bulk-delete clips from the WP library view. Required in addition to `edit_posts` for the delete action. |
| `upload_files`      | Author and above                         | Start a TUS upload to BB. |
| `manage_options`    | Administrator                            | Change the plugin's own settings (credentials, default playout, embed type). |

The plugin follows the standard WordPress capability map — you can fine-tune it with any role-editor plugin (User Role Editor, Members, etc.) without touching this plugin's code.

## Content Security Policy

If your site runs with a strict CSP (e.g. via Wordfence, WP Content Security Policy, or a header set at the CDN), the plugin propagates the CSP nonce to every BB embed script it emits so player JS is not blocked. No configuration is required — the plugin reads the nonce from the `Content-Security-Policy` header WordPress emits and injects it into any `<script>` element produced by the block or shortcode.

Two scripts that BB bootstraps (Cast SDK, legacy vpaid playout) still cannot carry a nonce; if you enforce `strict-dynamic` without `'unsafe-inline'` those features are disabled. See the internal tickets #18522 and #18523 for the OVP-side work that will eventually remove that limitation.

## Form-capture CTA webhooks

Editors can configure a CTA as an email-capture soft gate. Submissions are:

1. Always saved in the visitor's `localStorage` under `bbtl_{clipId}` so the overlay doesn't re-gate the same visitor.
2. Optionally POSTed as JSON to a **submit endpoint URL** the editor enters in the CTA form.

No data is sent to BB or to Anthropic. If you enable this feature and want submissions collected somewhere, stand up an endpoint on your own site or platform (e.g. a WP REST route, a serverless function, a Zapier catch webhook) and give editors that URL. The payload shape is:

```json
{
  "email": "visitor@example.com",
  "clipId": "12345",
  "postUrl": "https://your-site.example/blog/post-slug",
  "submittedAt": "2026-04-15T09:12:34.567Z"
}
```

The endpoint must accept `application/json`, support CORS for your site, and respond with a 2xx status. On non-2xx the visitor sees a retry message and the soft-gate is **not** locked.

## Performance notes

- SAPI read operations (playout list, publication data, language list, folder tree, CPP list) are cached in WordPress transients for one hour (day for the language list). Saving settings busts these caches. If you need to force a refresh, run `wp transient delete bb_playout_list` (etc.) or disable transients on your environment.
- The frontend CTA form-overlay script is only enqueued on posts that contain a BB block or shortcode — it does not load site-wide.
- All embed scripts are loaded async; lazy-load kicks in via IntersectionObserver for embeds below the fold.

## Troubleshooting

**"Could not verify connection" on settings save.** The API credentials are wrong, or outbound HTTPS to `<publication>.bbvms.com` is blocked by your firewall. Open a terminal on the WP host and try `curl -I https://<publication>.bbvms.com/sapi/publication` — a 401/403 means networking works but auth is wrong; a timeout means networking is the problem.

**Embed renders a blank box.** Most often a CSP violation. Open the browser console; if you see `Refused to execute inline script because it violates the following Content Security Policy directive`, add the plugin's nonce injection path or widen the CSP. Second most common: the configured playout doesn't exist on the publication — edit the block and pick a valid playout from the dropdown.

**Upload stops at 99%.** The TUS upload to S3 succeeded but the finalize call to SAPI timed out. Refresh the Library tab; the clip should be present with status `uploaded`. If not, check `error_log` for `Blue Billywig TUS`.

**Captions list is empty but I uploaded a file.** Check `error_log` for `Blue Billywig SAPI error in SapiClient::postMultipart`. Usually this is a SAPI validation error on the language code — verify the language is in the publication's language list under `OVP → Languages`.

**CTA disappeared from a clip.** Check `error_log` for `Blue Billywig CTA`. Every save and delete is logged with clip id + timeline id. If someone edited the same clip in the interactive-video editor, the CTA plugin refuses to overwrite that timeline and logs a `foreign_timeline` error.

## Logs and support

The plugin writes to `error_log` with the `Blue Billywig` prefix. When opening a support ticket, grep the log and include the lines around the time of the issue.

For help, visit [support.bluebillywig.com](https://support.bluebillywig.com).