Erfordert: Charitable Pro 1.8.16+
Charitable Ambassadors 3.0.0+

Wenn Sarah ihren Einladungslink teilt und Marcus sich anmeldet, um Spenden zu sammeln, möchten Sie, dass Sarah die Anerkennung erhält. Die Zuordnung sorgt dafür, dass dies automatisch geschieht – ohne dass Sarah jemandem einen Code senden muss, ohne dass Marcus sich daran erinnern muss, sie zu erwähnen, und ohne dass Sie eine Tabelle führen müssen, wer wen rekrutiert hat.

Diese Seite erklärt, wie Charitable Ambassadors diese Verbindung herstellt – zuerst in einfacher Sprache, dann mit den vollständigen technischen Details für Entwickler am Ende.

Die Kurzfassung

Wenn jemand auf einen Einladungslink klickt, wird ein winziges Datenelement (ein „Cookie“) in seinem Browser gespeichert. Es teilt Ihrer Website im Grunde mit: „Diese Person kam von Sarah.“

Das Cookie bleibt bis zu 30 Tage lang unauffällig bestehen. Wenn die Person während dieses Zeitraums einen Spendenaufruf einreicht – sei es direkt nach dem Klicken auf den Link oder drei Wochen später von einer anderen Seite Ihrer Website aus –, liest das System das Cookie, erkennt, dass die Person von Sarah kam, und schreibt Sarah die Rekrutierung gut.

Das ist die ganze Idee. Der Rest dieser Seite sind nur die Details.

Die Reise, Schritt für Schritt

1. Sarah shares her link    >    2. Marcus clicks    >    3. Cookie stored
                                                                ↓
6. You approve, Sarah gets credit  ←  5. Marcus submits  ←  4. Marcus browses your site

1. Sarah teilt ihren Link

Von ihrer Seite „Meine Kampagnen“ kopiert Sarah ihre persönliche Einladungs-URL und teilt sie, wie sie möchte – per E-Mail, Textnachricht, soziale Medien, persönlich. Ihre URL sieht ungefähr so aus:

https://yoursite.com/?charitable-invite=jA4HZIx2AhBnouMN

Der Teil ?charitable-invite=… am Ende ist ein eindeutiger Token, der *sie* speziell identifiziert (und, wenn sie einen Rekrutierungsbutton pro Kampagne verwendet hat, die spezifische Sache, für die sie rekrutiert).

2. Marcus klickt

Marcus' Browser ruft diese URL ab. Bevor WordPress etwas rendert, fängt der URL-Handler von Ambassadors die Anfrage ab, sucht den Token und bestätigt, dass er zu einem echten, aktiven Einladenden (Sarah) gehört.

3. Das Cookie wird gespeichert

Das System hinterlässt ein kleines Cookie im Browser von Marcus:

Eigenschaft	Wert
Name	charitable_invite_token
Was ist drin	Sarahs Token (derselbe String wie in der URL)
Wie lange es hält	30 Tage
Wo es sichtbar ist	Nur auf Ihrer Website, nicht auf anderen Websites

Dieses Cookie ist die Spur. So erinnert sich Ihre Website daran, dass Marcus von Sarah kam, selbst wenn er den Tab schließt und später von einer völlig anderen Seite zurückkehrt.

Nachdem das Cookie gesetzt wurde, leitet das System Marcus auf Ihre Einladungs-Landingpage weiter – die Seite, die Sie unter Charitable > Ambassadors > Invitations > Landing Page konfiguriert haben. Die URL-Leiste aktualisiert sich, sodass der Parameter ?charitable-invite=… nicht mehr sichtbar ist (er muss es nicht sein – das Cookie ist jetzt da).

4. Marcus durchsucht Ihre Website

Hier wird die Zuordnung wirkungsvoll. Marcus könnte seinen Spendenaufruf sofort einreichen, oder er könnte:

• Zuerst Ihre „Über uns“-Seite lesen
• Die Kampagne im Detail prüfen
• Die Website als Lesezeichen speichern und morgen wiederkommen
• Eine Woche vergessen, sich dann plötzlich erinnern und Ihre Website erneut suchen

Jeder davon funktioniert immer noch, solange er innerhalb von 30 Tagen und im selben Browser stattfindet. Der Cookie wartet.

5. Marcus reicht seine Spendenaktion ein

Schließlich klickt Marcus auf „Spendenaktion starten“ (oder auf eine andere Schaltfläche, die zu Ihrem Einreichungsformular führt), füllt es aus und reicht es ein. In diesem Moment speichert WordPress seine neue Spendenaktion als Entwurf, und der Zuordnungs-Handler von Ambassadors wird ausgeführt:

1. Er liest den charitable_invite_token Cookie aus Marcus' Browser.
2. Er sucht nach dem Token, um den Einladenden (Sarah) zu finden.
3. Er versieht die neue Spendenaktion mit zwei Metadaten: „eingeladen von Benutzer-ID = Sarah“ und „über Token = T123“.
4. Er erhöht den claim_count von Sarahs Token um 1.

Diese Markierung ist das, was jedes „Rekrutierungs“-Feature in Charitable Ambassadors antreibt.

6. Sie genehmigen, Sarah erhält die Gutschrift

Wenn Sie Marcus' Spendenaktion genehmigen (sie in „veröffentlicht“ überführen – oder wenn Sie die automatische Genehmigung verwenden, wird sie sofort veröffentlicht), passieren drei Dinge aufgrund dieser Markierung:

• Marcus' Spendenaktion wird in Sarahs Ansicht „Ihre Rekruten“ auf ihrer Seite „Meine Kampagnen“ angezeigt.
• Marcus' Rekrut zählt für das Rekrutierungs-Widget auf Ihrem Übersichts-Dashboard.
• Sarah erhält eine gratulierende E-Mail („Die Spendenaktion Ihres Rekruten wurde genehmigt!“) – wenn Sie die Einstellung „E-Mail an Einladenden bei Genehmigung“ aktiviert haben.

Last-Click vs. First-Click – Was passiert, wenn jemand auf mehrere Links klickt?

Stellen Sie sich vor, Marcus hat Ihre Website zweimal besucht:

• Tag 1: klickt auf Sarahs Einladungslink, liest Ihre Website, meldet sich nicht an.
• Tag 15: sieht James' Einladungslink in einem Facebook-Post, klickt darauf und meldet sich noch am selben Tag an.

Wer erhält die Gutschrift – Sarah oder James?

Die Standardantwort ist Last-Click: James erhält die Gutschrift, da sein Link Marcus von „Browsen“ zu „Spendenaktion“ konvertiert hat. Dies ist das Standardmodell in Empfehlungssystemen und die gängigste Wahl für Peer-to-Peer-Programme.

Einige Organisationen bevorzugen jedoch die First-Click-Attribution: Sarah erhält die Gutschrift, weil sie diejenige war, die Marcus in Ihre Sache eingeführt hat. Auch wenn James' Anstoß der Abschluss war, hat Sarah die schwierigere Arbeit geleistet, jemanden, der mit Ihrer Sache nicht vertraut war, in Ihre Umlaufbahn zu bringen.

Der Wechsel zu First-Click ist eine einzige Codezeile (siehe Entwicklerreferenz unten). Der Kompromiss ist rein philosophisch – es gibt keine richtige Antwort.

Randfälle, die es wert sind, darüber Bescheid zu wissen

Einige Situationen kommen regelmäßig vor. Hier ist, was das System in jedem Fall tut:

Situation	Was passiert
Sarah klickt auf ihren eigenen Link und versucht, sich anzumelden	Selbst-Rekrutierungs-Schutz. Die Landingpage zeigt eine spezielle Variante „Sie können sich nicht selbst rekrutieren“. Selbst wenn Sarah irgendwie zum Einreichungsformular gelangt, überspringt der Zuordnungsschritt sie und protokolliert den Versuch.
Sarahs Konto wird zwischen dem Klick und der Genehmigung gelöscht	Marcus' Spendenaktion hat immer noch die Rekrutierungs-Stempel-Meta, sodass das Übersichts-Widget ihn immer noch als Rekruten zählt – aber der Einladende wird als „(gelöschter Benutzer)“ angezeigt und die Glückwunsch-E-Mail wird nicht gesendet.
Sarah widerruft ihren Token, während Marcus mitten in der Anmeldung ist	Die Zuordnung wird stillschweigend übersprungen. Marcus’ Spendenaktion wird normal erstellt; sie wird nur ohne Werbergutschrift erstellt.
Marcus’ 30-Tage-Cookie läuft ab, bevor er sich bewirbt	Die Einreichung ist nicht zugeordnet. Wenn Marcus erneut auf Sarahs Link klickt, bevor er sich bewirbt, wird der Cookie erneuert und die Zuordnung funktioniert.
Marcus klickt auf seinem Handy auf den Link, meldet sich aber auf seinem Laptop an	Der Cookie ist pro Gerät. Ohne Browser-Synchronisierung (z. B. Chrome-Synchronisierung) wird die Laptop-Anmeldung nicht zugeordnet.
Zwei Klicks auf denselben Link, derselbe Browser	Der view_count des Tokens erhöht sich um 1; die Ablaufzeit des Cookies wird auf 30 Tage ab dem letzten Klick zurückgesetzt. Sonst ändert sich nichts.
Ein Caching-Plugin liefert die Landingpage aus dem Cache	Das System gibt beim Weiterleitungsschritt keine Cache-Header aus und weist das Cache-Framework von Pro an, die Landingpage zu überspringen. Wenn Ihr Caching-Plugin sie trotzdem zwischenspeichert, wird der Cookie möglicherweise nicht gesetzt – Sie sehen eine Selbstüberprüfungsbenachrichtigung auf der Admin-Registerkarte „Einladungen“.

Wo die Zuordnung in Ihrem Admin angezeigt wird

Sobald ein Rekrut zugeordnet wurde, sehen Sie ihn an diesen Stellen:

• Übersicht > Rekrutierungs-Widget – zählt zu Gesamt / Genehmigt / Ausstehend / Abgelehnt und zum Zeitreiendiagramm der Rekrutierung.
• Übersicht > Top-Rekrutierer-Widget – Ihre Rangliste, wer die meisten Rekruten bringt.
• Meine Kampagnen > Ihre Rekruten (Frontend, für den Werber) – Sarah sieht Marcus in ihrer Liste.
• Einladungen > Top-Rekrutierer CSV-Export – exportiert die vollständige Rangliste für den aktiven Zeitraum.
• Einladungen > CSV-Export der letzten Aktivitäten – chronologisches Protokoll jedes Rekrutenereignisses.

Wo man nachsehen kann, wenn etwas schiefgelaufen zu sein scheint

Wenn ein Rekrut nicht dort angezeigt wird, wo Sie ihn erwarten, überprüfen Sie Wohltätigkeits-Tools > Protokoll. Jedes Zuordnungsereignis schreibt dort einen Eintrag:

Protokollcode	Was es bedeutet
invite_clicked	Ein gültiger Einladungslink wurde angeklickt. Bestätigt, dass der Klick Ihre Website erreicht hat.
invite_claimed	Eine Einreichung wurde erfolgreich einem Werber zugeordnet.
self_recruit_skipped	Ein Werber hat versucht, sich selbst zu rekrutieren. Zuordnung übersprungen.
attribution_skipped_revoked_token	Der Token wurde zwischen Klick und Einreichung widerrufen.
inviter_deleted_at_approval	Genehmigungs-E-Mail übersprungen, da der Benutzer des Werbers nicht mehr existiert.

Filtern Sie das Protokoll nach source: ambassadors_invites, um nur einladungsbezogene Einträge anzuzeigen.

---

Entwicklerreferenz

Der Rest dieser Seite ist für Entwickler, die das Attributionssystem anpassen.

Der Cookie

Name:      charitable_invite_token
Value:     The 16-character base62 token string
Lifetime:  30 days (filterable via charitable_ambassadors_invite_cookie_lifetime)
Path:      /
SameSite:  Lax
Secure:    true when is_ssl(), otherwise false
HttpOnly:  false (intentional - may be read by frontend analytics)

Der Cookie wird direkt mit WP’s setcookie() gesetzt, nicht über JS, sodass er beim nächsten Aufruf verfügbar ist.

Der URL-Handler

Charitable_Ambassadors_Invites::handle_invite_url() ist mit Priorität 1 an init gebunden. Er:

1. Kehrt frühzeitig zurück, wenn $_GET['charitable-invite'] leer ist.
2. Kehrt frühzeitig zurück, wenn is_admin() (Admin-Anfragen lösen keine Attribution aus).
3. Sucht den Token über Charitable_Ambassadors_Invites_Tokens::lookup_by_token().
4. Kehrt frühzeitig zurück, wenn der Token fehlt, widerrufen wurde oder zu einem gelöschten Benutzer gehört.
5. Setzt den Cookie über setcookie().
6. Ruft Charitable_Ambassadors_Invites_Tokens::increment_view( $token_id ) auf.
7. Sendet charitable_nocache_headers() (Pro 1.8.15.2+) oder nocache_headers() (WP Core Fallback).
8. Ermittelt die Landingpage über charitable_ambassadors_get_invites_setting( 'landing_page_id' ) und erstellt eine Weiterleitungs-URL, wobei charitable-invite entfernt wird.
9. wp_safe_redirect( $landing_url, 302 ) + exit.

Der 302-Statuscode ist beabsichtigt, damit Caching-Layer die Weiterleitung selbst nicht zwischenspeichern – nur die Zielseite, die dynamisch durch charitable_is_dynamic_page ist.

Der Attribution-Handler

Charitable_Ambassadors_Invites::on_campaign_submission_save() ist an die charitable_campaign_submission_save-Aktion von Pro gebunden. Signatur:

do_action( 'charitable_campaign_submission_save', $data, $campaign_id, $user_id, $form );

Der Handler ist signatur-adaptiv, da das Verifizierungssystem ihn mit einer älteren 2-Argument-Form ( $fundraiser_id, $user_id ) aufruft; in der Produktion erhält er immer die 4-Argument-Form. Der Handler:

1. Ermittelt den Cookie-Wert ($_COOKIE['charitable_invite_token']).
2. Kehrt frühzeitig zurück, wenn kein Cookie vorhanden ist.
3. Sucht den Token; kehrt bei fehlendem Token oder widerrufenem Status frühzeitig zurück.
4. Self-Recruit-Schutz: Kehrt frühzeitig zurück, wenn $token_row->inviter_user_id === (int) $user_id, protokolliert self_recruit_skipped.
5. Writes the two attribution meta keys:

   update_post_meta( $campaign_id, '_charitable_ambassadors_invited_by_user_id', (int) $token_row->inviter_user_id );
   update_post_meta( $campaign_id, '_charitable_ambassadors_invited_via_token_id', (int) $token_row->token_id );
   

6. Ruft Charitable_Ambassadors_Invites_Tokens::increment_claim( $token_id ) auf.
7. Löst do_action( 'charitable_ambassadors_invite_claimed', $token_row, $campaign_id, $inviter_user_id ) aus.
8. Protokolliert invite_claimed unter Charitable Tools > Protokoll.

Die beiden Post-Meta-Schlüssel

Dies sind die Quellangaben für alles nachgelagerte:

Meta-Schlüssel	Typ	Verwendet von
_charitable_ambassadors_invited_by_user_id	int (WP Benutzer-ID)	Rekrutierungs-Widget, Ansicht „Ihre Rekruten“, E-Mail-Gate für Einladende bei Genehmigung.
_charitable_ambassadors_invited_via_token_id	int (token_id PK)	Token-Level-Analysen. Ermöglicht es Ihnen, einen Rekruten zu einer bestimmten, geskripteten URL zurückzuverfolgen.

Diese werden vom Plugin niemals entfernt – selbst wenn der Einladende gelöscht wird, bleiben die Metadaten bestehen (Sie sehen „(gelöschter Benutzer)“ bei „Top Recruiters“). Um die Zuordnung für einen bestimmten Rekruten zu löschen, löschen Sie die post_meta-Einträge direkt:

delete_post_meta( $campaign_id, '_charitable_ambassadors_invited_by_user_id' );
delete_post_meta( $campaign_id, '_charitable_ambassadors_invited_via_token_id' );

Wechsel des Zuordnungsmodus

Fügen Sie dies zu den functions.php Ihres Themes oder einem sitespezifischen Plugin hinzu:

add_filter( 'charitable_ambassadors_invite_attribution_mode', function () {
    return 'first_click'; // default is 'last_click'
} );

Unter first_click aktualisiert der URL-Handler immer noch den Cookie bei jedem Klick (sodass die Aufrufzahlen pro Einladendem korrekt sind), setzt aber den Cookie-Wert nur, wenn kein vorhandener Cookie vorhanden ist. Sobald ein Cookie gesetzt ist, aktualisieren nachfolgende Klicks dessen Ablaufdatum, aber nicht seinen Wert.

Unter last_click (Standard) setzt jeder Klick einen neuen Cookie-Wert und ersetzt jeden vorherigen Einladenden.

Filter

Filter	Standard	Zweck
charitable_ambassadors_invite_attribution_mode	'last_click'	Wechseln Sie zu 'first_click'.
charitable_ambassadors_invite_cookie_lifetime	30 * DAY_IN_SECONDS	Cookie-Lebensdauer in Sekunden.
charitable_ambassadors_invite_cookie_samesite	'Lax'	SameSite-Cookie-Attribut. Verwenden Sie 'Strict', wenn Ihre Einladungs-URLs nur von Links auf Ihrer eigenen Domain angeklickt werden.
charitable_ambassadors_invite_self_recruit_allowed	false	Setzen Sie true, um die Selbst-Rekrutierungs-Sperre zu deaktivieren. Nicht empfohlen.

Aktionen

Aktion	Argumente	Wird ausgelöst, wenn
charitable_ambassadors_invite_url_resolved	$token_row, $request	Nachdem der URL-Handler den Token validiert hat, bevor der Cookie gesetzt wird. Verwenden Sie dies, um den Vorgang abzubrechen (z. B. bestimmte Tokens sperren).
charitable_ambassadors_invite_clicked	$token_row, $request	Nachdem der Cookie gesetzt wurde.
charitable_ambassadors_invite_claimed	$token_row, $fundraiser_id, $inviter_user_id	Erfolgreiche Zuordnung.
charitable_ambassadors_invite_self_recruit_skipped	$token_row, $fundraiser_id	Selbstwerbe-Schutz hat die Zuordnung blockiert.
charitable_ambassadors_invite_attribution_skipped	$token_row, $reason, $fundraiser_id	Catch-all für jedes Ergebnis der Zuordnung, das kein Erfolg war. $reason ist einer von 'revoked_token', 'self_recruit', 'no_cookie', 'deleted_inviter'.

Protokollierung

Jedes Zuordnungsereignis wird über charitable_log() in Charitable Tools > Log protokolliert:

charitable_log( $code, $context, [
    'type'    => 'addon',
    'source'  => 'ambassadors_invites',
    'level'   => 'info', // or 'warning' for skip cases
    'user_id' => get_current_user_id(),
] );

Log-Codes (das $code-Argument):

Code	Stufe	Wann
invite_clicked	Info	URL-Handler hat ein gültiges Token aufgelöst.
invite_claimed	Info	Einreichung erfolgreich zugeordnet.
self_recruit_skipped	Warnung	Selbstwerbe-Schutz ausgelöst.
attribution_skipped_revoked_token	Warnung	Token wurde zwischen Klick und Einreichung widerrufen.
inviter_deleted_at_approval	Warnung	Genehmigungs-E-Mail übersprungen, da der Benutzer des Einladenden nicht mehr existiert.
unconfigured_landing_page_admin_view	Info	Administrator hat den Tab „Einladungen“ angezeigt, während keine Landingpage konfiguriert war.

Caching

Die Landingpage ist dynamisch (pro Benutzer, pro Token). Der URL-Handler gibt bei jedem Einladungsklick No-Cache-Header aus, und der Filter charitable_is_dynamic_page von Pro 1.8.15.2 ist so eingestellt, dass Caching-Plugins die Landingpage komplett überspringen:

add_filter( 'charitable_is_dynamic_page', function ( $is_dynamic, $post_id ) {
    if ( charitable_ambassadors_is_invite_landing_page( $post_id ) ) {
        return true;
    }
    return $is_dynamic;
}, 10, 2 );

Wenn Sie eine Pro-Version älter als 1.8.15.2 verwenden (kein charitable_is_dynamic_page-Filter), deckt der Fallback-Aufruf nocache_headers() den Weiterleitungsschritt ab, hilft aber nicht, wenn ein Caching-Plugin die Landingpage direkt zwischenspeichert. Die Selbstprüfung der Einladungen warnt Sie in diesem Zustand.

Die Token-Tabelle

Siehe Wie Einladungsdaten gespeichert werden für das vollständige Schema. Die für die Zuordnung relevantesten Spalten:

Spalte	Typ	Zweck
token_id	BIGINT PK	Die Ganzzahl, die auf der Spendenaktion des Rekruten als _charitable_ambassadors_invited_via_token_id gestempelt ist.
token	VARCHAR(32)	Der String, der in der URL und im Cookie erscheint.
inviter_user_id	BIGINT	Die WP-Benutzer-ID des Einladenden.
campaign_id	BIGINT NULL	Wenn NICHT NULL, wird die Einreichung des Rekruten automatisch an diese übergeordnete Kampagne angehängt.
Status	VARCHAR(20)	'aktiv' oder 'widerrufen'. Widerrufene Token überspringen die Zuordnung.
beanspruch_zaehler	INT	Erhöht sich bei jeder erfolgreichen Zuordnung um 1.

Verwandt

• Einladungen – das übergeordnete Feature-Dokument.
• Wie Einladungsdaten gespeichert werden – der Lebenszyklus der benutzerdefinierten Tabelle.
• Hooks & Filter in Ambassadors – die vollständige Filter- und Aktionsreferenz.