=== wspieraj.org - Widget Dotacyjny ===
Contributors: wspierajorg
Donate link: https://wspieraj.org
Tags: donations, fundraising, nonprofit, payments, widget
Requires at least: 6.4
Tested up to: 7.1
Requires PHP: 7.4
Stable tag: 1.9.0
License: GPLv2 or later
License URI: https://www.gnu.org/licenses/gpl-2.0.html

Umieść na stronie fundacji formularz wpłaty, pojedynczą zbiórkę albo ścianę wszystkich aktywnych zbiórek — bez programisty.

== Description ==

Oficjalna wtyczka wspieraj.org — polskiej platformy widgetów donacyjnych dla fundacji i organizacji pożytku publicznego. Zero prowizji platformy od wpłaty; utrzymujemy się z dobrowolnych opłat darczyńców.

Wtyczka NIE jest portalem zbiórkowym. Zbiórka żyje na stronie Twojej organizacji — ruch, pozycjonowanie i wiarygodność budują Twoją domenę, a darczyńca nie ogląda po drodze zbiórek innych fundacji.

= Co dostajesz =

* **[wspieraj_form]** — prosty formularz wpłaty na cele statutowe organizacji. Zero konfiguracji poza połączeniem konta.
* **[wspieraj_campaign id="…"]** — jedna konkretna zbiórka: opis, zdjęcia, pasek postępu, wpłaty innych darczyńców i formularz.
* **[wspieraj_zbiorki]** — ściana kafelków ze wszystkimi aktywnymi zbiórkami. Kliknięcie kafelka otwiera zbiórkę, przycisk „wstecz" w przeglądarce wraca do listy, a każda zbiórka ma własny adres do wysłania znajomym.
* Znaczniki Open Graph — udostępniona zbiórka pokazuje na Facebooku i w komunikatorach własny tytuł, opis i zdjęcie, a nie nazwę strony.
* Widget dopasowuje wysokość do treści automatycznie — nie trzeba jej ustawiać ręcznie.

= Jak to działa =

1. Zakładasz konto na wspieraj.org (za darmo) i tworzysz zbiórki w panelu.
2. W panelu kopiujesz klucz połączenia (Ustawienia → Wtyczka WordPress) — czeka tam gotowy.
3. Wklejasz klucz w ustawieniach wtyczki na swojej stronie.
4. Wstawiasz wybrany shortcode we wpisie, na stronie albo w bloku Elementora.

Klucz połączenia nie jest hasłem — to identyfikator, który w razie potrzeby (np. przy zmianie wykonawcy strony) możesz w każdej chwili unieważnić w panelu wspieraj.org.

== External services ==

Ta wtyczka łączy się z infrastrukturą wspieraj.org (AMS SOFTWARE sp. z o.o.), żeby dostarczyć widget wpłat i dane zbiórek. Bez tego połączenia wtyczka nie ma żadnej funkcji — to jest jej jedyny cel.

= api.wspieraj.org — publiczne REST API =

Serwer WordPressa łączy się z `https://api.wspieraj.org` w następujących sytuacjach:

* przy zapisie klucza połączenia w ustawieniach wtyczki — żeby sprawdzić, czy klucz jest ważny, i pobrać nazwę Twojej organizacji;
* przy wyświetleniu strony ustawień wtyczki — żeby pokazać listę Twoich zbiórek z gotowymi shortcode'ami;
* raz na dobę, w tle — żeby dopisać adres Twojej strony do listy stron, na które po wpłacie odsyłamy darczyńców (wysyłany jest klucz połączenia i adres strony);
* przy wyświetleniu strony zawierającej shortcode `[wspieraj_zbiorki]` — żeby pobrać listę aktywnych zbiórek do wyrenderowania kafelków;
* przy wyświetleniu wpisu z shortcode'em `[wspieraj_campaign]` albo zbiórki otwartej ze ściany kafelków — żeby pobrać tytuł, opis i zdjęcie zbiórki do znaczników Open Graph. Zdjęcie w podglądzie linku wskazuje na `api.wspieraj.org` — pobiera je serwis, na którym udostępniono link (np. Facebook), nie przeglądarka odwiedzającego.

Wysyłany jest wyłącznie identyfikator zbiórki lub identyfikator/klucz Twojej organizacji oraz adres Twojej witryny (nagłówek `Origin`, żeby w panelu wspieraj.org było widać, skąd klucz jest używany). Żadne dane osobowe odwiedzających Twoją stronę nie są przekazywane. Odpowiedzi są zapamiętywane lokalnie na 2 minuty, żeby ograniczyć liczbę zapytań.

= app.wspieraj.org — sam widget wpłat =

Kiedy shortcode `[wspieraj_form]`, `[wspieraj_campaign]` lub otwarta zbiórka z `[wspieraj_zbiorki]` wyświetla się odwiedzającemu, jego PRZEGLĄDARKA (nie serwer WordPressa) ładuje bezpośrednio z `https://app.wspieraj.org`:

* ramkę (`<iframe>`) z formularzem wpłaty — to w niej odwiedzający wpisuje kwotę i dane do przelewu;
* skrypt `embed.js`, który dopasowuje wysokość tej ramki do treści.

Płatności obsługuje w tej ramce operator płatności Tpay, licencjonowana krajowa instytucja płatnicza — wspieraj.org nie przechowuje danych karty ani przelewu.

Dostawca usługi: **AMS SOFTWARE sp. z o.o.**, ul. Józefa Wajzera 19/22, 41-808 Zabrze, KRS 0001242326, NIP 6482836354.

* Regulamin: https://wspieraj.org/regulamin
* Polityka prywatności: https://wspieraj.org/polityka-prywatnosci
* Umowa powierzenia przetwarzania danych: https://wspieraj.org/umowa-powierzenia

== Installation ==

1. W panelu WordPressa: **Wtyczki → Dodaj nową**, wyszukaj „wspieraj.org" i kliknij **Zainstaluj**, a potem **Włącz**.
   (Instalacja ręczna: pobierz ZIP, **Wtyczki → Dodaj nową → Wyślij wtyczkę na serwer**.)
2. W menu po lewej pojawi się pozycja **wspieraj.org**. Wejdź w nią.
3. Wklej klucz połączenia z panelu wspieraj.org (Ustawienia → Wtyczka WordPress) i kliknij **Połącz**.
4. Wklej wybrany shortcode w treści wpisu lub strony:
   * `[wspieraj_form]` — prosty formularz,
   * `[wspieraj_campaign id="…"]` — konkretna zbiórka (identyfikator skopiujesz z tabeli na stronie ustawień),
   * `[wspieraj_zbiorki]` — ściana wszystkich aktywnych zbiórek.

== Frequently Asked Questions ==

= Czy wtyczka pobiera prowizję od wpłat? =

Nie. Platforma wspieraj.org nie pobiera prowizji od darowizny — utrzymuje się z dobrowolnych opłat, które darczyńca może (ale nie musi) dodać przy wpłacie.

= Widget pokazuje pusty obszar zamiast formularza. =

Sprawdź, czy wtyczka jest połączona (menu **wspieraj.org** w panelu). Bez połączonego klucza shortcode'y wyświetlają komunikat, a nie pusty widget — jeśli jest zupełnie pusto, sprawdź, czy inna wtyczka (np. przyspieszająca stronę) nie blokuje ramek `<iframe>` z obcych domen.

= Zbiórki nie ma na liście w [wspieraj_zbiorki] ani w tabeli w ustawieniach. =

Na liście pokazują się wyłącznie zbiórki **aktywne**. Szkice i zbiórki czekające na zatwierdzenie w panelu wspieraj.org celowo się nie pokazują — to zabezpieczenie przed publikacją treści, której jeszcze nikt nie zatwierdził.

= Zmieniłem/-am zbiórkę, ale strona pokazuje starą treść. =

Dane z API są zapamiętywane na stronie przez 2 minuty. Jeśli używasz dodatkowo wtyczki do buforowania strony (cache), wyczyść też jej pamięć podręczną.

= Udostępniona zbiórka na Facebooku pokazuje nazwę strony zamiast tytułu zbiórki. =

Bez wtyczki SEO oraz z Yoast SEO, Rank Math i SEOPress wtyczka sama podaje tytuł, opis, adres i zdjęcie otwartej zbiórki (przy wtyczce SEO przez jej filtry, więc na stronie zostaje jeden komplet znaczników). Facebook pamięta raz pobrany podgląd: po zmianie wklej adres w Sharing Debuggerze (https://developers.facebook.com/tools/debug/) i kliknij „Scrape Again”.

= Czy muszę mieć programistę, żeby wstawić widget? =

Nie. Wklejenie shortcode'u to ta sama czynność co wstawienie filmu z YouTube — działa w Gutenbergu, klasycznym edytorze i większości konstruktorów stron (np. Elementor, przez widżet/blok „Shortcode").

= Czy wtyczka nadąża za nowymi wersjami WordPressa? =

Tak. Sprawdzamy zgodność przy każdym głównym wydaniu WordPressa i aktualizujemy pole „Tested up to" po realnym teście — nie zgadujemy. Pole „Requires at least" pokazuje najniższą wersję, z którą wtyczka na pewno działa; „Tested up to" najwyższą, którą faktycznie sprawdziliśmy. Jeśli między wydaniami WordPressa minie więcej czasu, niż zwykle, a „Tested up to" zacznie odstawać, oznacza to tylko, że nie zdążyliśmy jeszcze przetestować — nie że wtyczka przestała działać.

== Screenshots ==

1. Strona ustawień wtyczki — status połączenia i lista zbiórek z gotowymi shortcode'ami.
2. Ściana zbiórek wyrenderowana shortcode'em [wspieraj_zbiorki].
3. Pojedyncza zbiórka: opis, pasek postępu i formularz wpłaty.

== Changelog ==

= 1.9.0 =
* Na kafelkach `[wspieraj_zbiorki]` pod tytułem pokazuje się krótki „Cel zbiórki”, jeśli fundacja go wpisała w panelu wspieraj.org.
* Ten sam cel trafia do opisu w podglądzie udostępnionej zbiórki (Facebook, Messenger, WhatsApp) — zamiast początku długiego opisu.

= 1.8.0 =
* Wtyczka sama zgłasza adres Twojej strony (raz na dobę, w tle). Dzięki temu po wpłacie możemy bezpiecznie odesłać darczyńcę z powrotem na Twoją stronę — bez ręcznego ustawiania czegokolwiek w panelu wspieraj.org.

= 1.7.1 =
* Poprawka bezpieczeństwa: przy SEOPress tytuł zbiórki w tytule strony nie był escapowany — wersji 1.7.0 nie instaluj, przejdź od razu na 1.7.1.

= 1.7.0 =
* Podgląd udostępnionej zbiórki działa także przy Rank Math i SEOPress (wcześniej tylko bez wtyczki SEO i przy Yoast SEO).
* Adres zdjęcia w podglądzie niesie wersję okładki w ścieżce zamiast w parametrze — Rank Math obcinał parametr, a po podmianie okładki Facebook mógł dostać stare zdjęcie.

= 1.6.0 =
* Większe, czytelniejsze kafelki zbiórek: tytuł, kwota i podpisy w rozmiarach jak na dużych serwisach zbiórkowych.
* Rozmiary niezależne od motywu: wcześniej motyw ustawiający mniejszy bazowy rozmiar czcionki (częste `html { font-size: 62.5% }`) pomniejszał kafelki o ponad jedną trzecią, a jego style nagłówków potrafiły nadpisać tytuł.

= 1.5.0 =
* Naprawiony podgląd udostępnionej zbiórki na Facebooku i w komunikatorach. Przy Yoast SEO karta pokazywała tytuł podstrony i nie miała zdjęcia — teraz wtyczka podaje Yoastowi tytuł, opis, adres i zdjęcie otwartej zbiórki. Bez wtyczki SEO znaczniki w ogóle się nie pojawiały od wersji 1.2.3 (czytelne adresy zbiórek) — to również naprawione.
* Zdjęcie w podglądzie jest w formacie JPG 1200×630 z podanymi wymiarami — tak, jak zaleca Facebook. Wcześniej był to plik WebP, który Facebook bywa pomija.
* Otwarta zbiórka ma własny adres kanoniczny i tytuł strony („Tytuł zbiórki – Nazwa strony").

= 1.4.0 =
* Kafelek zbiórki z ustawioną datą zakończenia pokazuje „X dni do końca" (w ostatnim dniu „Ostatni dzień", po terminie „Termin minął" — zbiórka dalej przyjmuje wpłaty). Zbiórka bez terminu nie pokazuje nic.

= 1.3.0 =
* Nowy wygląd ściany zbiórek [wspieraj_zbiorki]: większy tytuł zamiast zajawki opisu, kwota „X zł z Y zł", grubszy pasek postępu, liczba wpłat i procent zebranej kwoty. Przekroczony cel jest pokazywany wprost (np. „111%").
* Kafelek bez zdjęcia ma zaślepkę tej samej wysokości — rząd kafelków nie rozjeżdża się już, gdy któraś zbiórka nie ma zdjęcia.
* Pasek postępu bierze kolor z ustawień widgetu Twojej organizacji.
* Zbiórka na cele statutowe stoi na końcu listy, po zbiórkach celowych.
* Kwoty na liście odświeżają się co 2 minuty zamiast co 15 — darczyńca wracający z płatności szybciej widzi swoją wpłatę.

= 1.2.3 =
* Adresy zbiórek (ściana kafelków, tabela shortcode'ów) używają teraz czytelnego identyfikatora z tytułu (np. „po-miesiacach-walki") zamiast surowego UUID. Stare, już opublikowane adresy nadal działają — oba formaty są rozpoznawane.

= 1.2.2 =
* Naprawiona zbyt wąska ramka dla [wspieraj_campaign] i otwartej zbiórki z [wspieraj_zbiorki] — kontener miał sztywne 820px, mimo że widget w środku sam mieści się aż do 1024px. Na szerszych kolumnach treści zostawiało to pustą przestrzeń zamiast wykorzystać dostępne miejsce.

= 1.2.1 =
* Naprawiona sytuacja, w której strona ustawień pokazywała „niepołączono" mimo poprawnie wklejonego klucza — działo się tak, gdy pierwsze sprawdzenie klucza akurat trafiło na chwilową awarię. Strona teraz sama próbuje ponownie przy kolejnym wejściu, bez wklejania klucza od nowa.
* W panelu wspieraj.org klucz połączenia przeniósł się z „Kreatora widgetu" do „Ustawień" i jest teraz zawsze jeden, gotowy od razu — bez wybierania czy mnożenia kluczy.

= 1.2.0 =
* Nowy shortcode [wspieraj_zbiorki] — ściana kafelków ze wszystkimi aktywnymi zbiórkami, z otwieraniem pojedynczej zbiórki i powrotem do listy.
* Klucz połączenia z kontem, możliwy do unieważnienia w panelu wspieraj.org, zastępuje ręczne wpisywanie identyfikatora organizacji.
* Przebudowana strona ustawień: status połączenia, lista zbiórek z gotowymi shortcode'ami do skopiowania, instrukcja i rozwiązywanie problemów.

= 1.1.0 =
* Znaczniki Open Graph dla udostępnionej zbiórki (tytuł, opis, zdjęcie).
* Automatyczne dopasowanie wysokości widgetu do treści.
* Poprawki udostępniania: natywny arkusz systemowy, WhatsApp, kopiowanie linku, kod QR.

= 1.0.0 =
* Pierwsze wydanie: shortcode'y [wspieraj_form] i [wspieraj_campaign].

== Upgrade Notice ==

= 1.2.0 =
Nowość: shortcode [wspieraj_zbiorki] i klucz połączenia. Dotychczasowe shortcode'y i ręcznie wpisany identyfikator organizacji działają bez zmian.
