cituro Bewertungen in die eigene Website integrieren

Bewertungen können helfen, neue Kunden zu überzeugen einen Termin bei Ihnen zu buchen. Dazu können Sie die wertvollen cituro Bewertungen Ihrer Kunden nun sehr flexibel auf Ihrer Website integrieren. Wir zeigen Ihnen anhand eines einfachen Beispiels, wie das mit Hilfe unserer cituro REST-API funktioniert.

Ziel: Es sollen eine Zusammenfassung aller Bewertungen und die neusten 10 cituro Bewertungen auf der eigenen Website dargestellt werden.

Ergebnis:

See the Pen
PoZBRoQ by cituro (@cituro)
on CodePen.

1. Vorbereitung

HTML

In unserem einfachen Beispiel wollen wir die Bewertungen innerhalb eines HTML DIV Elements darstellen, das an jeder beliebigen Stelle einer Website platziert werden kann.

<div id=“container“>
<div id=“rating-summary“></div>
<div id=“rating-container“></div>
</div>

Dieses einfache HTML enthält noch keine Daten. Diese werden im weiteren Verlauf mit Hilfe von Javascript und der cituro REST API geladen und innerhalb der oben abgebildeten HTML Elemente angezeigt.

Javascript

Die in 2. und 3. folgenden Javascript Codes müssen in der Reihenfolge nach unserem HTML Code ausgeführt werden. Dazu gibt es zwei Möglichkeiten:

Code wird innerhalb eines Script Tags nach dem Container DIV Element platziert
Code wird im HEAD der Seite platziert. Achtung: Unbedingt darauf achten, dass der Code asynchron ausgeführt wird. Idealerweise sollte deshalb ein Onload Eventlistener verwendet werden, um die Ausführung des Javascript Codes zu starten.

window.addEventListener("load",function(){
	//Hier wird der Javascript Code ergänzt
});

Account Nummer

Um die Daten von der cituro REST API abfragen zu können, wird die ACCOUNT-NUMMER des gewünschten cituro Accounts benötigt. Diese finden Sie in Ihrem cituro Manager unter dem Menüpunkt „Vertrag“. Um die Daten des Accounts abzufragen, muss die entsprechende Account Nummer in den Javascripts ersetzt werden.

2. Darstellung der Zusammenfassung aller Bewertungen

Im ersten Schritt soll die Zusammenfassung aller Bewertungen ermittelt und angezeigt werden. Zunächst wird dazu das Element mit der ID „rating-summary“ aus 1. ermittelt. Im Anschluss werden die relevanten Daten mit Hilfe unserer REST-API ermittelt und innerhalb des DIV Elements dargestellt. Den Text und die Darstellung können Sie selbstverständlich individuell anpassen.

//Suchen des Elements, das die Zusammenfassung beinhalten soll
var ratingSummary = document.getElementById("rating-summary");

//Laden der Zusammenfassung mittels API Call und Darstellung
fetch("https://app.cituro.com/api/ratings/ACCOUNT-NUMMER/summary")
	.then(response => response.json())
  .then(jsonData => 
	{
		if(jsonData.success){
			var avg = Number(jsonData.data.average);
			var roundedAvg = avg.toFixed(1);
			var text = roundedAvg + " Sterne aus " + jsonData.data.count + " Bewertungen";
			ratingSummary.innerHTML = text;
		}
		else{
		//Fehlerbehandlung
		}
	}
);

3. Darstellung der einzelnen Bewertungen

Im zweiten Schritt sollen die neusten 10 Bewertungen ermittelt und dargestellt werden. Es sollen sowohl der Name des Kunden, als auch die vergebenen Sterne angezeigt werden. Zunächst wird dazu das DIV-Element mit der ID „rating-container“ aus 1. ermittelt. Im Anschluss werden die Bewertungen mit Hilfe unserer REST-API abgefragt und innerhalb des DIV-Elements dargestellt. Den Text und die Darstellung können Sie selbstverständlich individuell gestalten.

//Suchen des Elements, das die Zusammenfassung beinhalten soll
var ratingContainer = document.getElementById("rating-container");

//Laden der Bewertungen mittels API Call und Darstellung
fetch("https://app.cituro.com/api/ratings/ACCOUNT-NUMMER?limit=10&sort=-createdAt") //Die letzten 10 Bewertungen
	.then(response => response.json())
	.then(jsonData => 
	{
		if(jsonData.success){
			for (var rating of jsonData.data){
				var value = rating.rating; //Wert 1-5
				var customerName = rating.customerName; //Name des Kunden bspw.: Max M.
				var comment = rating.comment; //optionaler Kommentar
				var anonymous = rating.anonymous; //Anonyme Bewertung
				var createdAt = rating.createdAt; //Erstellungzeitpunkt bspw.: 2020-01-01T10:00:00
				
				var ratingElement = document.createElement("div");
        ratingElement.className="rating";
				var customerLabel = document.createElement("span");
        customerLabel.className='rating-customer';
				
				if(anonymous || !customerName){
					customerLabel.innerHTML="Anonym";
				}
				else{
					customerLabel.innerHTML=customerName;
				}
				
				var total = "";
				
				for (i = 0; i < value; i++) {
				  total = total + "★";
				} 
				
				var ratingLabel = document.createElement("span");
        ratingLabel.className="rating-stars";
								
				ratingLabel.innerHTML=total;
				
				customerLabel.appendChild(ratingLabel);
				ratingElement.appendChild(customerLabel);
				ratingContainer.appendChild(ratingElement);
				
				if(comment){
					var commentLabel = document.createElement("div");
          commentLabel.className="rating-comment";
					commentLabel.innerHTML=comment;
					ratingElement.appendChild(commentLabel);
				}				
			}
		}
		else{
		//Fehlerbehandlung
		}
	}
); 

4. Styling

Um das Ergebnis optisch aufzubereiten, können wir nun mit etwas CSS nachhelfen:

.container{
  width: 75%;
  max-width:500px;
  margin: auto;
  padding:20px;
  background:rgba(0,0,0,0.05);
  border-radius:5px;
  box-shadow:5px 5px 10px 3px rgba(0,0,0,0.5);
}

#rating-summary{
  font-weight:bold;
  margin-bottom:20px;
  font-size:1.25em;
}

.rating + .rating{
  margin-top:20px;
}

.rating-customer{
  font-weight:bold;
}

.rating-stars{
  margin-left:10px;
  color:gold;
  font-size:1.25em;
  text-shadow:1px 1px 0px #000;
}

.rating-comment{
  font-style:italic;
}

5. Erweiterungen

Sie können das gezeigte Beispiel beliebig um weitere Funktionen wie Pagination, Sortierung oder Filterung erweitern. Unsere REST API bietet Ihnen dazu alles was notwendig ist:

//Sortierung nach Erstellungsdatum (Neuste zuerst)
https://app.cituro.com/api/ratings/ACCOUNT-NUMMER?sort=-createdAt

//Sortierung nach Bewertungen (höchste zuerst)
https://app.cituro.com/api/ratings/ACCOUNT-NUMMER?sort=-rating

//Filter nach 5 Sternen
https://app.cituro.com/api/ratings/ACCOUNT-NUMMER?filter[rating]=5

//Filter nach 4 oder mehr Sternen
https://app.cituro.com/api/ratings/ACCOUNT-NUMMER?filter[rating]=gte:4

//Pagination: Elemente 100-200. Die Response enthält jeweils ein count Attribut.
//So lange limit >=count könnten weitere Ergebnisse vorhanden sein
https://app.cituro.com/api/ratings/ACCOUNT-NUMMER?limit=100&offset=100

//Pagination: Elemente 200-300
https://app.cituro.com/api/ratings/ACCOUNT-NUMMER?limit=100&offset=200