Erfordert: Charitable Pro 1.8.16+
Charitable Ambassadors 3.0.0+

Die Einladungsfunktion verwendet eine kleine benutzerdefinierte Datenbanktabelle, um die eindeutigen Tokens zu speichern, die die Einladungs-URLs Ihrer Botschafter antreiben. Diese Seite erklärt, wo sich diese Tabelle befindet, wann sie erstellt wird, was sie enthält und was passiert, wenn sie verloren geht.

Wenn Sie noch nie über die Datenbank Ihrer Website nachgedacht haben: Es handelt sich um eine kleine, gut verwaltete Tabelle, die das Plugin automatisch verwaltet. Der Rest dieser Seite ist für den Fall, dass etwas Ungewöhnliches passiert (ein Upgrade schiefgelaufen ist, ein Backup nicht sauber wiederhergestellt wurde, ein Administrator fragt „welche Daten speichert diese Funktion?“) und Sie die Details kennen müssen.

Die Kurzfassung

Frage	Antwort
Was wird gespeichert?	Eine Zeile pro Einladungs-Token. Jede Zeile enthält den Token-String, die Benutzer-ID des Einladenden, eine optionale Kampagnen-ID, ein Erstellungsdatum, ein Widerrufsdatum (falls widerrufen), eine Aufrufanzeige und eine Einlöseanzeige.
Wo wird es gespeichert?	In einer benutzerdefinierten Tabelle namens <wp_prefix>charitable_ambassadors_invite_tokens (z. B. wp_charitable_ambassadors_invite_tokens).
Wann wird die Tabelle erstellt?	Beim ersten Aktivieren von Einladungen auf der Admin-Seite. Bis dahin existiert die Tabelle nicht.
Werden persönliche Daten gespeichert?	Nein – nur die WordPress-Benutzer-ID des Einladenden. Keine Namen, keine E-Mails, keine IPs.

Wann die Tabelle erstellt wird

Bis Sie Einladungen aktivieren, existiert die benutzerdefinierte Tabelle nicht – die Funktion ist vollständig optional. Wenn Sie zum ersten Mal Einladungen aktivieren unter Charitable > Ambassadors > Invitations aktivieren, sehen Sie ein einmaliges Bestätigungsfenster, das erklärt, was passieren wird:

„Das Aktivieren von Einladungen erstellt eine neue Datenbanktabelle zum Speichern von Einladungs-Tokens. Die Tabelle ist klein und wird nur von der Einladungsfunktion verwendet. Fortfahren?“

Bestätigen Sie, und die Tabelle wird über den Standard-WordPress-Helfer dbDelta() erstellt (derselbe Mechanismus, den jedes Plugin zur sicheren Verwaltung benutzerdefinierter Tabellen verwendet). Das Schema wird idempotent neu erstellt – wenn die Tabelle bereits existiert, gibt dbDelta() nur die ALTER-Anweisungen aus, die es tatsächlich benötigt.

Eine Zeile wird auch in wp_options geschrieben:

charitable_ambassadors_invites_schema_version = '1.0'

So weiß das Plugin, auf welcher Schemaversion Ihre Tabelle ist, damit zukünftige Upgrades sauber migriert werden können.

Was sich in der Tabelle befindet

Die Tabelle hat acht Spalten – keine PII, keine Spendenbeträge, nichts, was der Einladende nicht bereits auf seiner eigenen Seite „Meine Kampagnen“ sieht:

Spalte	Was es speichert
id	Automatisch inkrementierender Primärschlüssel.
token	Der eindeutige String, der in der URL erscheint. 16 Zeichen, alphanumerisch.
user_id	Die WordPress-Benutzer-ID des Einladenden.
campaign_id	(Optional) Eine übergeordnete Kampagnen-ID, wenn das Token auf eine bestimmte Ursache beschränkt ist.
erstellt_am	Als der Token zum ersten Mal generiert wurde.
widerrufen_am	Wann der Token widerrufen wurde (null, wenn aktiv).
aufruf_zaehler	Wie oft jemand auf die URL dieses Tokens geklickt hat.
beanspruch_zaehler	Wie viele Rekruten sich erfolgreich über diesen Token angemeldet haben.

Das ist alles. Keine E-Mails, keine IPs, keine Browser-Fingerabdrücke. Der Einladende und der Empfänger sind beide geschützt.

Wie die Tabelle verwendet wird

Drei Dinge passieren im normalen Betrieb mit dieser Tabelle:

1. Token-Erstellung – Wenn ein berechtigter Botschafter My Campaigns mit aktivierten Einladungen zum ersten Mal besucht, wird eine Token-Zeile für ihn erstellt (und eine zusätzliche Zeile für jede übergeordnete Kampagne, die er besitzt).
2. Klick-Auflösung – Wenn jemand auf eine Einladungs-URL klickt, sucht der URL-Handler den Token, um den Einladenden zu finden.
3. Zähler – view_count wird bei jedem Klick erhöht; claim_count wird erhöht, wenn sich ein Rekrut erfolgreich zuordnet.

Das ist der gesamte Lebenszyklus. Es gibt keine Hintergrundverarbeitung, keine geplanten Aufträge, keine Synchronisierung mit externen Diensten.

Die vier Selbstprüfungszustände

Der Admin-Tab Einladungen verfügt über ein Selbstprüfungsbanner, das die seltenen Momente erfasst, in denen etwas nicht stimmt:

Sie sehen	Was falsch ist	Was zu tun ist
Rot: „Aktiviert, aber Datenbanktabelle fehlt“	Ein Plugin-Update, eine manuelle Datenbankbereinigung oder eine Wiederherstellung aus einem Backup hat die Tabelle gelöscht, während die Einstellung beibehalten wurde.	Klicken Sie auf Tabelle neu erstellen – das Schema wird an Ort und Stelle neu aufgebaut. Kein Datenverlust für neue Klicks; alte Tokens sind weg.
Gelb: „Schema veraltet“	Ein zukünftiges Upgrade hat ein neueres Schema eingeführt; Ihre Installation wurde noch nicht migriert.	Klicken Sie auf Upgrade ausführen. Die Migration ist sicher und idempotent.
Blau: „Deaktiviert, aber Daten vorhanden“	Sie haben die Funktion deaktiviert, aber die Tabelle ist noch vorhanden und enthält Token-Zeilen.	Entweder Wieder aktivieren (Daten werden wieder verwendet) oder Dauerhaft löschen und Tabelle entfernen (Daten sind für immer weg).
Blau: „Cache-Kompatibilität aus“	Ein Caching-Plugin kann Ihre Einladungs-Landingpage cachen, was die Zuordnung beeinträchtigen würde.	Aktivieren Sie Cache-Kompatibilität unter Charitable > Einstellungen > Erweitert > Diverses.

Die Selbstprüfung läuft bei jedem Besuch des Tabs „Einladungen“ und unter „Charitable Tools“ > „Site-Infos“. So erfahren Sie von Tabellenproblemen, bevor sie Ihre Kunden betreffen.

Deaktivieren der Funktion (Soft Disable)

Wenn Sie entscheiden, dass Einladungen nicht für Ihr Programm geeignet sind, deaktivieren Sie Einladungen oben im Admin-Tab:

• Der Schalter wird auf „Aus“ umgelegt.
• Der Shortcode wird auf der Landingpage nicht mehr gerendert (oder zeigt die Admin-Vorschau an, wenn ein Admin sie betrachtet).
• Die Rekrutierungskarte erscheint nicht mehr unter „Meine Kampagnen“.
• Der URL-Handler verarbeitet keine ?charitable-invite=...-Klicks mehr.
• Die Tabelle bleibt bestehen. Der Token-Verlauf wird gespeichert, sodass Sie ihn später wieder aktivieren können, ohne ihn zu verlieren.

Dies ist umkehrbar – aktivieren Sie es jederzeit wieder, und die vorhandenen Tokens funktionieren wieder.

Permanentes Löschen der Daten (Hard Uninstall)

Wenn Sie möchten, dass die Daten gelöscht werden – z. B. zur Einhaltung der DSGVO oder weil Sie sich entschieden haben, Einladungen definitiv nicht mehr zu verwenden – verwenden Sie Tabelle dauerhaft löschen und entfernen am Ende des Tabs „Einladungen“:

Der destruktive Ablauf ist absichtlich in mehrere Schritte unterteilt:

1. Klicken Sie auf Tabelle dauerhaft löschen und entfernen.
2. Ein Bestätigungsmodal fordert Sie auf, den Tabellennamen einzugeben (z. B. wp_charitable_ambassadors_invite_tokens), um zu bestätigen.
3. Senden. Die Tabelle wird gelöscht, die Option _schema_version wird entfernt, die Einstellung invites_enabled wird auf „aus“ gesetzt.
4. Die Aktion wird unter „Charitable Tools“ > „Protokoll“ mit der Benutzer-ID des Moderators protokolliert.

Dies ist eine Einbahnstraße. Wenn Sie Einladungen das nächste Mal aktivieren, wird eine neue Tabelle mit null Zeilen erstellt.

Was während eines Exports / Backups passiert

Die Tabelle ist eine normale MySQL-Tabelle in Ihrer WordPress-Datenbank. Jedes Tool, das WordPress-Datenbanken sichert (UpdraftPlus, BackupBuddy, mysqldump, die automatischen Backups Ihres Hosters), schließt sie automatisch ein. Wiederherstellungen funktionieren genauso – bringen Sie die Datenbank zurück, die Tabelle ist dabei.

Was während eines Exports persönlicher Daten passiert

Das WordPress-Tool zum Exportieren persönlicher Daten exportiert die Benutzerkontodaten des Benutzers. Die Tabelle „Einladungen“ speichert user_id-Referenzen, sodass die Einladungs-Tokens eines Benutzers in ihren Export persönlicher Daten einbezogen werden (Token-Strings + Ansichts-/Anspruchszählungen). Es sind keine PII über die Benutzer-ID hinaus in der Tabelle enthalten.

Tipps

• Bearbeiten Sie die Tabelle nicht manuell. Die Admin-Benutzeroberfläche des Plugins bietet alles, was Sie benötigen – einen Token widerrufen, einen Token neu generieren, Zählungen anzeigen. Das manuelle Bearbeiten von Zeilen beeinträchtigt die Integrität von claim_count.
• Wenn Sie ein Backup wiederherstellen, das diese Tabelle nicht enthält, wird die Selbstprüfung dies beim nächsten Besuch des Administrators feststellen und „Tabelle neu erstellen“ anbieten.
• Das Schema ist versioniert. Zukünftige Plugin-Updates können Spalten hinzufügen; das Upgrade ist sicher und idempotent.
• Kein SQL in diesem Dokument aus Designgründen. Schemas ändern sich; die Dokumente sollten sie nicht mitführen. Lesen Sie immer die Klasse Charitable_Ambassadors_Invites_Schema des Plugins für die kanonische Spaltenliste.

---

Entwicklerreferenz

Der Rest dieser Seite ist für Entwickler und DBAs.

Schema-Klasse

Charitable_Ambassadors_Invites_Schema::table_name();        // string - prefixed name
Charitable_Ambassadors_Invites_Schema::exists();            // bool   - does the table exist
Charitable_Ambassadors_Invites_Schema::is_current();        // bool   - exists + columns match + version current
Charitable_Ambassadors_Invites_Schema::schema_version();    // string - stored version (empty if no record)
Charitable_Ambassadors_Invites_Schema::create();            // creates via dbDelta + stamps version
Charitable_Ambassadors_Invites_Schema::upgrade();           // idempotent migration to current schema
Charitable_Ambassadors_Invites_Schema::drop();              // drops table + deletes schema-version option

Alle Methoden sind statisch und können sicher aus jedem Kontext aufgerufen werden (die Datei wird bedingungslos geladen, sodass die Selbstprüfung und die Site-Informationen den Status abfragen können, auch wenn Einladungen deaktiviert sind).

Optionsschlüssel

charitable_ambassadors_invites_schema_version       # current installed schema version
charitable_settings > ambassadors > invites_enabled # feature master switch

Tokens-Klasse

Für die programmatische Arbeit mit Zeilen in der Tabelle:

Charitable_Ambassadors_Invites_Tokens::get_or_create( $user_id, $campaign_id = 0 );
Charitable_Ambassadors_Invites_Tokens::lookup_by_token_string( $token_string );
Charitable_Ambassadors_Invites_Tokens::lookup_by_id( $token_id );
Charitable_Ambassadors_Invites_Tokens::increment_view( $token_id );
Charitable_Ambassadors_Invites_Tokens::increment_claim( $token_id );
Charitable_Ambassadors_Invites_Tokens::revoke( $token_id );
Charitable_Ambassadors_Invites_Tokens::build_invite_url( $token_string );

Filter

Filter	Standard	Zweck
charitable_ambassadors_invites_table_name	wp_charitable_ambassadors_invite_tokens	Überschreiben Sie den Tabellennamen (z. B. für Multisite-Tabellen). In der Produktion nicht empfohlen.
charitable_ambassadors_invitations_storage_docs_url	diese Seite	Überschreiben Sie die Dokumentations-URL, auf die die Selbstprüfungsbanner verlinken.

Aktionen

Aktion	Argumente	Wird ausgelöst, wenn
charitable_ambassadors_invites_schema_created	$table_name	Schema::create() hat die Tabelle tatsächlich erstellt (nicht nur aktualisiert).
charitable_ambassadors_invites_schema_upgraded	$from_version, $to_version	Schema::create() hat dbDelta ausgeführt und ALTERs angewendet.
charitable_ambassadors_invites_schema_dropped	$table_name	Schema::drop() hat die Tabelle entfernt.

Site-Info-Integration

Charitable Tools » Site Info hat einen Ambassadors-Block, der Folgendes anzeigt:

• Ob die Tabelle existiert.
• Die aktuelle Schemaversion.
• Die Gesamtzahl der Zeilen.
• Ob das Schema aktuell ist.

Siehe Site Info für das vollständige Layout.

Multisite

Jede Unterseite erhält ihre eigene Tabelle, da der Tabellenname über $wpdb->prefix präfixiert wird. Netzwerkaktiv bedeutet nicht, dass sich dies ändert – die Funktion wird pro Unterseite aktiviert.

Export personenbezogener Daten

Die Einladungen-Funktion registriert einen Exporter für personenbezogene Daten bei den WordPress-Datenschutzwerkzeugen. Wenn ein Nutzer seinen Export personenbezogener Daten anfordert, durchläuft der Exporter seine Token-Zeilen und schließt die Token-Zeichenfolgen, Daten, Aufrufzahlen und Anspruchszahlen in seinen Export ein.

Funktionen

Alle Admin-Operationen (neu erstellen, aktualisieren, löschen) erfordern manage_charitable_settings. Die destruktive Deinstallation erfordert zusätzlich die Eingabe des Tabellennamens zur Bestätigung.

Anpassungsbeispiele

Blende die Option zur destruktiven Deinstallation für eine bestimmte Benutzerrolle aus:

add_filter( 'user_has_cap', function ( $allcaps, $caps, $args ) {
    if ( ! empty( $caps ) && in_array( 'manage_charitable_settings', $caps, true ) ) {
        $user = get_userdata( $args[1] );
        if ( $user && in_array( 'finance_admin', (array) $user->roles, true ) ) {
            unset( $allcaps['manage_charitable_settings'] );
        }
    }
    return $allcaps;
}, 10, 3 );

Sende einen Webhook an dein Audit-System, wenn die destruktive Deinstallation ausgelöst wird:

add_action( 'charitable_ambassadors_invites_schema_dropped', function ( $table_name ) {
    wp_remote_post( 'https://audit.example.com/hook', [
        'body' => [
            'event'      => 'invites_table_dropped',
            'table_name' => $table_name,
            'user_id'    => get_current_user_id(),
            'site_url'   => site_url(),
            'timestamp'  => time(),
        ],
    ] );
} );

Richte die Self-Check-Banner auf deine internen Dokumente um:

add_filter( 'charitable_ambassadors_invitations_storage_docs_url', function () {
    return home_url( '/internal/charitable-invitations-runbook/' );
} );

Verwandt

• Einladungen – das übergeordnete Feature-Dokument.
• So funktioniert die Zuordnung – der Klick-zu-Gutschrift-Fluss.
• Seiteninformationen – der Diagnoseblock, der den Tabellenstatus anzeigt.
• Hooks & Filter in Ambassadors – vollständige Referenz.

---