Integration von Twingle in CiviCRM

Einleitung

Twingle ist ein Zahlungsdienstleister, der es sehr einfach ermöglicht, moderne Spendenformulare mit diversen Zahlungsmöglichkeiten zu erstellen und auf Websites einzubetten. Außerdem unterstützt Twingle Spendenaktionen, bei denen Dritte in Form eigener Aktionen Spenden für eine Organisation sammeln können.

Twingle API

Twingle lässt sich über die Erweiterung Twingle API mit CiviCRM verbinden. Die Anbindung von Twingle an CiviCRM bringt einige Möglichkeiten mit sich:

  • Zuwendungen können automatisch in CiviCRM angelegt und
    • bestehenden oder neuen Kontakten zugeordnet werden
    • abhängig von der Zahlungsart als abgeschlossen oder offen deklariert werden
  • Es können SEPA-Mandate für einmalige und wiederkehrende Zahlungen angelegt werden
  • Kampagnen können für Zuwendungen, Kontakte, SEPA-Mandate und Mitgliedschaften gesetzt werden
  • Spender*innen können in Gruppen für Newsletter, Postsendungen und Zuwendungsbescheinigungen eingetragen werden
    • bei Newsletter-Gruppen mit optionalem Double-Opt-In
  • Mitgliedschaften können eingerichtet werden
  • Werte können in benutzerdefinierte Felder eingetragen werden

Voraussetzungen

Installation

  1. Neustes Twingle API Release in den Erweiterungsordner von CiviCRM herunterladen und entpacken
  2. Die Erweiterung in CiviCRM installieren (Administration → Systemeinstellungen → Erweiterungen)

Einrichtung

  1. Im TwingleMANAGER müssen unter Einstellungen → Allgemein → CRM: CiviCRM die URL (z.B. https://meine-domain.de/sites/all/modules/civicrm/extern/rest.php), ein API-Key und der Site-Key hinterlegt werden. (Hilfeseite von Twingle)
  2. Unter Administration→ Verwaltungskonsole → Twingle API Configuration → Configure extension settings kann optional die Verwendung von CiviSEPA aktiviert werden.
  3. Unter Administration→ Verwaltungskonsole → Twingle API Configuration können Profile für einzelne Projekte (Spendenformulare) erstellt werden. Hierzu benötigt man die Projekt-ID, die sich im TwingleMANAGER im jeweiligen Projekt unter Kontaktdaten & Einbindung → CRM: CiviCRM findet und nach dem Muster „tw6cb96c6b52b7c" aufgebaut ist. Kann einer eingehenden Zahlungen kein Profil zugeordnet werden, wird automatisch das Default-Profil verwendet.
  4. Aufgrund eines derzeit noch nicht behobenen Fehlers kann es dazu kommen, dass vorhandene Adressdaten von Kontakten mit einer Adresse überschrieben werden, die lediglich das Land enthält. Um dies zu verhindern, sollte ein XCM-Profil erstellt und in den Twingle-API-Profilen verwendet werden, in dem die Option „Change Primary Detail?" nicht aktiviert ist. Dies kann allerdings dazu führen, dass die Kontaktdaten einer Person nicht gespeichert werden, wenn diese einmal ohne und dann einmal mit der Angabe von Adressdaten spendet.

Nutzung

  • Die Eigenschaften der Twingle-Spendenformulare können imTwingleMANAGER eingestellt werden. Auch die Einbettungscodes finden sich dort.
  • Die Verarbeitung der Zahlungen als Zuwendungen in CiviCRM kann über die Profile der Twingle API Erweiterung konfiguriert werden. Tipp: Dasselbe Profil kann für mehrere Projekte verwendet werden, indem im Profil mehrere Projekt-IDs als kommagetrennte Liste eingetragen werden.
  • Weitere Felder können in Absprache mit dem Twingle-Support von Twingle mit übertragen werden. Die übertragenen Werte können in den Twigle-API-Profilen mit benutzerdefinierten Feldern in CiviCRM verknüpft werden. Beispielsweise könnte man um die zusätzliche Übermittlung der Event-ID von Spendenaktionen bitten und diese mit einem benutzerdefinierten Feld „Spendenaktions-ID" einer Zuwendung verknüpfen, um einzelne Zuwendungen mit Spendenaktionen zu assoziieren.

TwingleCampaign

Die Erweiterung Twingle Campaign erweitert die Möglichkeiten der Twingle-API-Erweiterung indem sie Twingle-Spendenformulare als Kampagnen in CiviCRM abbildet.

  • Spendenformulare können in CiviCRM angelegt und bearbeitet werden
  • Dasselbe Spendenformular kann für mehrere Unterkampagnen genutzt werden, wodurch Zuwendungen z.B. einzelnen Newslettern oder Social-Media-Posts zugeordnet werden können
  • Spendenaktionen von Dritten werden automatisch als Unterkampagnen in CiviCRM angelegt
    • Initiator*innen der Spendenaktionen werden bestehenden Kontakten zugeordnet oder neu erstellt
    • Initiator*innen können Soft-Credits für die von ihnen gesammelten Spenden erhalten
    • Für Initiator*innen können Fälle definiert und ausgelöst werden

Bei dieser Extension handelt es sich um ein Projekt aus der deutschen CiviCRM Community. Die Maintainer freuen sich über gemeldete Fehler, Anregungen und Hilfe bei der Weiterentwicklung.

Voraussetzungen

Installation

  • Neustes TwingleCampaignRelease in den Erweiterungsordner von CiviCRM herunterladen und entpacken
  • Die Erweiterung in CiviCRM installieren (Administration → Systemeinstellungen → Erweiterungen)
  • Im Erweiterungsmenü die angezeigten Datenbankupdates durchführen

_ Einrichtung _

  1. Ein neues XCM-Profil erstellen, das zum Zuordnen oder Anlegen von Initiator*innen von Spendenaktionen verwendet werden soll
  • Fill Fields: Vorname, Nachname
  • Fill Details: Email
  1. Das XCM-Profil in der Twingle Campaign Konfiguration auswählen
    (Administration→ Verwaltungskonsole → Twingle Campaign Konfiguration)
  2. Den Twingle-API-Schlüssel in der Twingle Campaign Konfiguration eintragen
  3. Optional: In der Twingle Campaign Konfiguration kann ein Default-Fall ausgewählt werden, der für die Initiator*innen von Spendenaktionen ausgelöst wird. Der Default-Fall wird von der Einstellung in den jeweiligen Kampagnen überschrieben.
  4. Optional: Den Synchronisationsintervall der Twingle-Projekte und Events unter Administration → Systemeinstellungen → Geplante Jobs → TwingleSync → Bearbeiten auf den gewünschten Wert einstellen (der Default ist „stündlich").

Nutzung

  • Im Kampagnenmanager können neue Spendenformulare angelegt werden, indem eine Kampagne mit dem Kampagnentyp „Twingle Project" angelegt wird. Dort lassen sich einige Attribute des Spendenformulars einstellen.
    • Änderungen die an einem Formular im TwingleMANAGER vorgenommen werden, brauche ggf. eine Weile um zu CiviCRM synchronisiert zu werden.
    • Die URL eines Spendenformulars kann gesetzt werden, damit auch Unterkampagnen zur Zuordnung von Spenden auf dasselbe Formular verweisen können.
    • Spendenformulare lassen sich mit allen ihren Werten klonen.
      Kampagne ansehen → Actions → Kampagne klonen
    • Bei Spendenformularen, die Spendenaktionen (Events) haben können, kann ein Fall ausgewählt werden, der für die Initiator*innen ausgelöst werden soll. Dieser überschreibt den in der Twingle Campaign Konfiguration ausgewählten Default-Fall.
  • Spendenaktionen lassen sich im Kampagnenmanager nicht anlegen, da diese nur über ein Spendenformular angelegt werden können. Sie erscheinen im Kampagnenmanager jedoch als Unterkampagnen vom Typ „Twingle Event".
  • Für jedes Spendenformular (Twingle Project) kann eine unbegrenzte Zahl von „Tracking"-Kampagnen (Twingle Campaign) angelegt werden, die die Zuordnung von Spenden beispielsweise zu Newslettern oder Social-Media-Posts ermöglichen. „Twingle Campaigns" müssen immer als Unterkampagne eines „Twingle Projects" angelegt werden (aber nicht unbedingt als direkte Unterkampagne).
  • Während in CiviCRM angelegte Spendenformulare zu Twingle synchronisiert werden und umgekehrt, werden gelöschte Formulare aus Sicherheitsgründen nicht auch automatisch auf der anderen Seite gelöscht. Um Spendenformulare zu löschen, müssen diese manuell sowohl in CiviCRM als auch im TwingleMANAGER gelöscht werden.

2 „Gefällt mir“

Danke für die gute Doku! Die Einbindung ist leichter als gedacht. Ich glaube es ist ein wenig Aufwand, sich in die dann neue Kampagnenstruktur einzuarbeiten. Aber man bekommt dadurch eine Möglichkeit, Spendenformulare online ziemlich einfach einzubetten und die Spenden auf die einzelnen Formulare einfach zu bewerten, zu gliedern und auszuwerten.

Ein Tipp für alle, die mit der Twingle-Terminologie (Project, Event) Probleme haben:

Die von der Twingle Campaign Erweiterung verwendeten Kampagnennamen sind ursprünglich der API-Dokumentation von Twingle entnommen. Natürlich lassen sich diese aber auch umbenennen (Administration → CiviCampaign → Kampagnentypen → bearbeiten), um sie etwas aussagekräftiger zu machen.

Default Kampagnenname Vorschlag zur Umbenennung
Twingle Project Twingle Spendenformular
Twingle Event Twingle Spendenaktion
Twingle Campaign Twingle Tracking-Link

Die Umbenennung hat keine Auswirkung auf die Funktionalität.

1 „Gefällt mir“

Wer die Twingle-Einbindung gerne auf einem Testsystem ausprobieren will, kann mit dieser Sammlung von API-Calls für Postman viele Interaktionen mit dem Twingle-Server simulieren.

1 „Gefällt mir“