Wie du ein Spendenbarometer selbst programmierst

Der folgende Artikel beschreibt die Schritte zur Erstellung eines Spendenbarometers für Spenden, die über den RaiseNow Manager registriert wurden.

Voraussetzungen

Um dein eigenes Spendenbarometer zu erstellen, müssen folgende Voraussetzungen erfüllt sein:

• Ein RaiseNow-Konto für manage.raisenow.com
• Die RaiseNow-Händler-Kennung (Merchant Identifier)
• Einen RaiseNow-API-User, um die RaiseNow-API abzufragen. Du kannst einen API User erstellen, indem diesem Knowledge Base Artikel folgst: Wie erstelle ich einen neuen User im RaiseNow Manager. Wichtig dabei ist, dass du die API-Berechtigungen und das Flag für einen API-User festlegst, da der User sonst abläuft. 

Anleitung zur Implementierung

Die vollständige Dokumentation ist auf GitHub zu finden.

Das Spendenbarometer besteht aus zwei Hauptkomponenten:

1. einer serverseitigen Komponente, die die RaiseNow-API abfragt.
2. der Frontend-Komponente, die die Spendenbetragsstatistik anzeigt.

1. Serverseitige Komponente

Um Spenden, die über RaiseNow für Ihre Organisation eingegangen sind, zusammenzutragen, kannst du die RaiseNow-Such-API von deiner serverseitigen Komponente aus abfragen. Sobald du die Spendendaten erhalten hast, kann die serverseitige Komponente eine API für dein Frontend bereitstellen.

Warum solltest du eine serverseitige Komponente zur Abfrage der Such-API verwenden? Die Such-API ist durch Berechtigungsnachweise geschützt. Wenn du die API vom Frontend aus abfragst, werden diese Berechtigungsnachweise der Öffentlichkeit zugänglich gemacht, so dass jeder sie verwenden und deine Daten bei RaiseNow abfragen und aktualisieren kann. Es liegt in deiner Verantwortung, diese Anmeldeinformationen geheim und sicher zu halten.

Autorisierung

Um auf die RaiseNow-API zuzugreifen, musst du die Anfrage per HTTP Basic Authentifizierung und deinen API-User Zugangsdaten authentifizieren.

Suchabfrage

Um die Daten über Ihre eingegangenen Spenden zu erhalten, können Sie die folgende API-Anfrage verwenden:

GET https://api.raisenow.com/epayment/api/<MERCHANT_IDENTIFIER>/transactions/search?<QUERY>'

wobei

• MERCHANT_IDENTIFIER ist deine RaiseNow Händler-Kennung
• QUERY ist die Suchanfrage in Form einer URL-kodierten Zeichenfolge in folgendem Format:
  • Ein Sortier-Auftrag, der beschreibt, wie die Spende sortiert werden soll. Wenn das Erstellungsdatum verwenden und absteigend sortiert wird, erhältst du die neueste Spende.
    
    • sort[0][field_name]=created
    • sort[0][order]=desc
  • Ein Filter-Teil, der die Transaktionen filtert. Im Folgenden werden alle erfolgreich durchgeführten Spenden in CHF ausgegeben.
    
    • filters[0][field_name]=last_status
    • filters[0][type]=term
    • filters[0][value]=final_success
    • filters[1][field_name]=test_mode
    • filters[1][type]=term
    • filters[1][value]=production
    • filters[2][field_name]=currency_identifier
    • filters[2][type]=term
    • filters[2][value]=chf
  • Ein Berechnungs- Teil (facets), der definiert, wie die Spenden verrechnet werden. Neben der Gesamtsumme der Spenden, die Ihrer Filterabfrage entsprechen, gibt diese Facette auch die Maximal-, Minimal-, Durchschnittswerte und die Standardabweichung an. Beachten Sie, dass der Name der Facette auch in der Antwort enthalten ist. Dies ist besonders nützlich, wenn mehrere Berechnungen definiert werden.
    
    • facets[0][field_name]=amount
    • facets[0][type]=stats
    • facets[0][name]=total_amount
  • Ein Abschnitt, der definiert, welche Art von Feldern von der Suchanfrage ausgegeben werden.
    
    • displayed_fields=epp_transaction_id,created,currency_identifier,amount,payment_method_identifier
  • Ein Abschnitt, der festlegt, wie viele Datensätze pro Seite zurückgegeben werden sollen.
    
    • records_per_page=5
  • Die vollständige Liste der Optionen findest du auch in den RaiseNow Developer Docs und weitere Beispiele für Abfragen in unserer Knowledge Base Transaction Search API.

Du erhälst dann eine Ausgabe, die wie folgt aussieht: 

{
  "result": {
    "transactions": [
      {
        "epp_transaction_id": "<TRANACTION_IDENTIFIER>",
        "created": "1642428270", 
        "currency_identifier": "<CURRENCY>",
        "amount": <AMOUNT_IN_CENTS>,
        "payment_method_identifier": "<PAYMENT_METHOD_IDENTIFIER>"
      },
      {
        "epp_transaction_id": "<TRANACTION_IDENTIFIER>",
        "created": "1640073719",
        "currency_identifier": "<CURRENCY>",
        "amount": <AMOUNT_IN_CENTS>,
        "payment_method_identifier": "<PAYMENT_METHOD_IDENTIFIER>"
      },
      {
        "epp_transaction_id": "<TRANACTION_IDENTIFIER>",
        "created": "1639470666",
        "currency_identifier": "<CURRENCY>",
        "amount": <AMOUNT_IN_CENTS>,
        "payment_method_identifier": "<PAYMENT_METHOD_IDENTIFIER>"
      },
      {
        "epp_transaction_id": "<TRANACTION_IDENTIFIER>",
        "created": "1639415198",
        "currency_identifier": "<CURRENCY>",
        "amount": <AMOUNT_IN_CENTS>,
        "payment_method_identifier": "<PAYMENT_METHOD_IDENTIFIER>"
      },
      {
        "epp_transaction_id": "<TRANACTION_IDENTIFIER>",
        "created": "1639412837",
        "currency_identifier": "<CURRENCY>",
        "amount": <AMOUNT_IN_CENTS>,
        "payment_method_identifier": "<PAYMENT_METHOD_IDENTIFIER>"
      }
    ],
    "sort": [
      {
        "fieldname": "created.raw",
        "order": "desc"
      }
    ],
    "additional_info": {
      "lang": "de",
      "search_time": "138.7160",
      "total_hits": 900,
      "page": 1,
      "total_pages": 180,
      "records_per_page": "5"
    },
    "filters": [
      {
        "field_name": "last_status",
        "type": "term",
        "value": "final_success",
        "filter_group": 0
      },
      {
        "field_name": "test_mode",
        "type": "term",
        "value": "production",
        "filter_group": 1
      },
      {
        "field_name": "currency_identifier",
        "type": "term",
        "value": "chf",
        "filter_group": 2
      }
    ],
    "facets": [
      {
        "name": "total_amount",
        "type": "stats",
        "stats": {
          "min": 1,
          "max": 5000,
          "mean": 120.93333333333,
          "count": 900,
          "total": 108840,
          "standard_deviation": 324.61111092095,
          "sum_of_squares": 107997520,
          "variance": 105372.37333333
        }
      }
    ]
  }
}

wobei

• transactions enthält bis zu records_per_page Transaktionen, die mit Ihrer Filterabfrage übereinstimmen. Die Variablen sind wie folgt definiert:
  • TRANACTION_IDENTIFIER ist die Kennung der Spende bei RaiseNow
  • CURRENCY ist die Währung, in der die Spende getätigt wurde, z.B.chf
  • AMOUNT_IN_CENTS ist der Spendenbetrag in Cents.
  • PAYMENT_METHOD_IDENTIFIER Kennung des Zahlungsmittels
• sort beschreibt, nach welchem Feld sortiert wurde
• additional_info gibt Ihnen einen Eindruck davon, wie viele Datensätze mit Ihrer Abfrage übereinstimmen
• filters beschreibt, welche Filter in der Abfrage angewendet wurden
• facets gibt Ihnen detaillierte Informationen

Normalerweise wird Ihre serverseitige Komponente nur die Summe (total) der (facets) ausgeben, um den gesammelten Gesamtbetrag anzuzeigen.

Example

Die vollständige Dokumentation ist auf GitHub zu finden.

Ein Beispiel für die serverseitige PHP-Komponente findest du in server/server.php.

Um diese auszuführen, kannst du folgenden Schritten folgen:

1. Installieren Sie die composer -Abhängigkeiten mit composer install.
2. Führe php server.phpaus.

2. Frontend Komponente

Sobald du die serverseitige Komponente fertiggestellt hast, kannst mit dem Code in client/index.htmldeinen Spenden-Barometer anzeigen.