118 lines
8.2 KiB
Markdown
118 lines
8.2 KiB
Markdown
# StreamGoals Donate
|
||
|
||
PayPal donations for WordPress, built for streamers: multiple donation goals, optional "cover the fees",
|
||
and OBS overlays (goal bar, subathon timer, counter, donation alerts) that update live.
|
||
|
||
Requires WordPress 7.x, PHP 8.1+, and a **PayPal Business** account to take live payments (see below).
|
||
|
||
## Install
|
||
1. Download `streamgoals-donate.zip` from the latest [release](../../releases).
|
||
2. WordPress admin → Plugins → Add New → Upload Plugin → activate.
|
||
3. Open **StreamGoals** in the admin menu. The setup wizard walks you through the rest.
|
||
|
||
## Which PayPal account?
|
||
- **Testing:** nothing special. PayPal's Sandbox gives every developer account a sandbox business account
|
||
(the seller) and a sandbox personal account (the buyer).
|
||
- **Live payments:** PayPal's developer policy requires a **Business** account to go live. Upgrading a
|
||
Personal account is free, and a personal name is fine (no company needed).
|
||
- PayPal's User Agreement also expects accounts used mainly for business or donation-taking to be Business accounts;
|
||
a Personal account used that way risks limits or closure. Read PayPal's current terms before going live.
|
||
|
||
## Connect PayPal (about 5 minutes)
|
||
You need two values from PayPal: a **Client ID** and a **Secret**.
|
||
|
||
1. Go to <https://developer.paypal.com> and log in with your PayPal Business account.
|
||
2. Open **Apps & Credentials**. Use the **Sandbox** toggle for testing, **Live** for real money.
|
||
3. Click **Create App**, name it anything (e.g. "My Donations"), type **Merchant**.
|
||
4. Copy the **Client ID** and **Secret** into the StreamGoals wizard (Step 1).
|
||
5. Click **Test connection**. On success the plugin registers its webhook with PayPal automatically.
|
||
|
||
Start in **Sandbox**, make a test donation using a PayPal sandbox buyer account, then repeat the steps
|
||
with the Live credentials and switch the mode to Live in Settings.
|
||
|
||
### Behind Cloudflare?
|
||
Nothing to do: the plugin recognises Cloudflare automatically (by its published addresses) so each visitor is rate
|
||
limited separately. For another proxy, choose it in StreamGoals > Settings > Advanced; the panel there shows what your
|
||
server sees.
|
||
|
||
### Notes on fees and currency
|
||
- "Cover the processing fees" adds an estimate based on the rates in Settings (default: US domestic,
|
||
3.49% + $0.49). Your actual PayPal rate depends on your account, country and payment method.
|
||
- Cross-border and currency-conversion fees are **not** included in the estimate, so a covered donation
|
||
from another country can net slightly less than intended.
|
||
- One currency per site. PayPal converts for donors paying from another currency.
|
||
- Donations are not tax-deductible. Don't present them as such.
|
||
|
||
## Using it
|
||
- **Donation page:** add the shortcode `[streamgoals_donate]` to a page (or `[streamgoals_donate goal="ID"]` to pin one goal).
|
||
- **Goals:** StreamGoals → Goals. Create as many as you like; each can have its own rules.
|
||
- **Rules (time and counters):** per goal, e.g. "+60 seconds per $1" (subathon timer), "+1 per $10" (counter),
|
||
or a bonus event above a minimum amount. Amounts can be measured on the base donation or including fee cover.
|
||
- **Overlays:** StreamGoals → Overlays. Copy a widget URL into OBS as a **Browser Source** (suggested 800×200
|
||
for the goal bar; transparent background is built in). Keep the URL private; "Regenerate token" invalidates it.
|
||
- **Rewards (actions for set amounts):** StreamGoals > Rewards. Add things you do on stream for a set amount, for example
|
||
"$5: eat an every-flavor bean" or "$25: 25 pushups". Each reward is either *exactly this amount* or *every time the
|
||
donation adds up to this amount* (a $10 donation triggers a $5 reward twice). Rewards appear as buttons on the donation
|
||
form, as a **Rewards menu** overlay for OBS, and as a highlighted line in the donation alert. Triggered rewards land in a
|
||
**queue** on the Rewards screen so you can tick them off as you do them. Rewards count the donation amount, not the
|
||
optional fee cover, and must be at least your minimum donation.
|
||
- **Alerts with pictures, GIFs, videos and sounds:** StreamGoals > Alerts. Pick files from your WordPress Media Library
|
||
(PNG, JPEG, GIF, WebP, MP4, WebM for the picture/video; MP3, OGG, WAV for sound). Tie an alert to **a donation size**
|
||
("any donation of at least $5": the highest matching amount wins) or to **a reward** (a reward alert beats an amount
|
||
alert). Set the volume, how long a picture stays, and a message using `{name}`, `{amount}` and `{reward}`. In OBS media
|
||
plays automatically; in an ordinary browser tab click the page once before sound is allowed. Keep files small (videos
|
||
under about 25 MB). If a file is deleted the alert still shows, just without it.
|
||
- **Tiers (milestones):** on the Goals screen use **Tiers** to turn one goal into a ladder, for example $100 "Giveaway",
|
||
$250 "New microphone", $500 "24-hour stream". The goal bar shows the current tier and fills within it; unlocking a tier
|
||
shows a **TIER UNLOCKED** line in the alert and the bar moves on to the next one. The goal's final target is your highest
|
||
tier. The donation form shows "Next unlock: ... to go".
|
||
- **End at target:** tick "Close this goal to donations when the target is reached" on a goal. When the total reaches or
|
||
passes the target (for a tiered goal, the final tier) the goal closes and the donation page says so. Donations already
|
||
in checkout still go through. Use **Reopen** after raising the target.
|
||
- **Test:** "Send test donation" on the Overlays screen shows an alert without touching real totals.
|
||
|
||
## Privacy and moderation
|
||
- Donors choose a name or "Anonymous". For anonymous donors the **name is never stored**.
|
||
- Optional message approval queue and a streamer-controlled profanity filter (whole-word, your own word list).
|
||
|
||
## Not supported
|
||
- **Refunds and chargebacks are not tracked.** Refunds and chargebacks done in PayPal are NOT reflected in goal
|
||
totals, timers, counters or tiers. The donation keeps counting as if it had been paid.
|
||
|
||
## Transparent alerts
|
||
In StreamGoals > Alerts, tick **Frameless** on an alert to drop the dark box, border and glow so only your picture or
|
||
video shows. Transparency works with PNG, GIF and WebP pictures that have an alpha channel and with WebM (VP8/VP9)
|
||
videos made with alpha; MP4 (H.264) can never be transparent. To make a WebM with alpha:
|
||
`ffmpeg -i input.mov -c:v libvpx-vp9 -pix_fmt yuva420p -b:v 0 -crf 30 output.webm`. The name and bonus lines still
|
||
show under the media, outlined so they stay readable. The alert preview has a checkerboard/sample-scene backdrop.
|
||
|
||
## Overlays update themselves
|
||
An open OBS Browser Source never reloads on its own. Every overlay response now carries a build id (plugin version
|
||
plus a counter); when it differs from the one the page was loaded with, the overlay reloads itself once. Updating the
|
||
plugin does this automatically, and StreamGoals > Overlays > "Refresh all overlays now" does it on demand. Alert media
|
||
URLs also carry `?v=<file modified time>`, so replacing a file with the same name is picked up.
|
||
|
||
## Updates
|
||
New versions appear in WordPress automatically (Dashboard > Updates and the Plugins screen), checked against
|
||
this repository's releases. The repository is public, so no token is needed. (If you run a private fork, paste an
|
||
access token with read access to releases in StreamGoals > Settings > Advanced > Plugin updates.) You can switch
|
||
automatic updates on or off for this plugin on the Plugins screen, and use "Check for updates now" in
|
||
StreamGoals > Settings > Advanced to look straight away.
|
||
|
||
## Development
|
||
```
|
||
composer install
|
||
vendor/bin/phpunit
|
||
```
|
||
Architecture notes are in `docs/ARCHITECTURE.md`. Every push to `main` runs the tests and, if they pass,
|
||
publishes a versioned zip release via Gitea Actions.
|
||
|
||
## License
|
||
StreamGoals Donate is free software, released under the GNU General Public License, version 2 or (at your option)
|
||
any later version (GPL-2.0-or-later). See the `LICENSE` file for the full text.
|
||
|
||
## Uninstalling
|
||
Deleting the plugin from the Plugins screen always removes its scheduled task and cached data. Your donations, goals,
|
||
rules, rewards, alerts, tiers and settings are kept unless you first tick "Delete all data when the plugin is deleted"
|
||
in StreamGoals > Settings > Advanced (off by default; deleting cannot be undone).
|