Widgets und API

Nutzung der Nachhaltigkeitsampel

Die WeGreen Nachhaltigkeitsampel kann in eigene Anwendungen und Portale integriert werden.

Für die Integration stehen zwei Schnittstellen zur Verfügung:

  • Die Javascript API erlaubt die Integration der Nachhaltigkeitsampel als Widget in webbasierte Angebote mit minimalem Aufwand. Hierbei sind keine Programmierkenntnisse nötig.
  • Die Webservice API erlaubt den direkten Zugriff auf die Datenbank von WeGreen und ist insbesondere für die Integration in Mobile Apps und Desktop Applikationen geeignet.

Javascript API, Version 1.4 (10.09.2012)

Die Integration der WeGreen Nachhaltigkeitsampel als Widget erfolgt in zwei einfachen Schritten:

Schritt 1: Initialisierung der API

Fügen Sie bitte zunächst das folgende JavaScript vor dem schließenden Body-Tag der Seite ein, auf der Sie die Nachhaltigkeitsampel einblenden wollen:

 <!-- (c) WeGreen UG -->
   <!-- Initialize WeGreen JavaScript API -->
   <div id="wg-root"></div>
   <script type="text/javascript">
     window.wgAsyncInit = function() {
       WG.init({appId: '$APP_ID',
         xwgml: true,
         locale: '$LOCALE'});
     };
     (function() {
       var e = document.createElement('script');
       e.async = true;
       e.src = document.location.protocol
         + '//api.wegreen.de/js/wgAPI.js';
       document.getElementById('wg-root').appendChild(e);
     }());
   </script>
 

Ersetzen Sie nach dem Einfügen die Zeichenkette $APP_ID durch Ihre Application ID und die Zeichenkette $LOCALE durch die gewünschte Sprachvariante. WeGreen unterstützt die Sprachvarianten de (Deutsch), fr (Französisch) und en (Englisch).

Hinweis: Die Initialisierung der JavaScript API von WeGreen erfolgt asynchron und verlangsamt nicht das Laden oder die Darstellung Ihrer Webseite.

Schritt 2: Platzierung des Ampel-Widgets

Danach gehen Sie zu der Nachhaltigkeitsampel, die sie in Ihre Seite einfügen wollen und Klicken auf "Einbetten". Fügen Sie den angezeigten Tag an der Stelle in Ihre Webseite ein, an der die Nachhaltigkeitsampel erscheinen soll. Fertig!

Hinweis: Das Widget aktualisiert sich selbstständig. Wenn sich z.B. die Bewertung des Unternehmens oder die Anzahl der interessierten Nutzer verändert, wird dies automatisch auf Ihrer Webseite dargestellt!

Ampel-Widget für Dynamische Webseiten

Wenn Sie die Nachhaltigkeitsampel in eine dynamische Webseite einfügen wollen, auf der je nach Aufruf unterschiedliche Unternehmen, Marken oder Produkte angezeigt werden, können Sie einen Tag einfügen, der automatisch die passende Nachhaltigkeitsampel findet. Fügen Sie dazu den folgenden Tag ein:

<div name="wg:badge" layout="$LAYOUT" $SELECTOR></div>

Zum Beispiel fügt der Tag <div name="wg:badge" slug="kik"></div> die Nachhaltigkeitsampel des Unternehmens Kik ein, wie nachfolgend dargestellt:

Die Nachhaltigkeitsampel von Kik wurde in diesem Beispiel durch den Selektor slug="kik" generiert. Es stehen Ihnen jedoch auch andere Selektoren zur Verfügung.

Darstellungsvarianten

Ersetzen Sie nach dem Einfügen die Zeichenkette $LAYOUT durch die gewünschte Darstellungsvariante des Widgets. Es stehen die Varianten standard und link zur Verfügung.

Hinweis: Beim Layout standard kann über den Parameter width die gewünschte Breite des Widgets festgelegt werden, bis zu einer minimalen Breite von 125 Pixeln. Das Layout passt sich automatisch an.

<div name="wg:badge" slug="kik" width="500"></div>

<div name="wg:badge" slug="kik" width="350"></div>

<div name="wg:badge" slug="kik" width="250"></div>

<div name="wg:badge" slug="kik" width="125"></div>

Selektoren

Ersetzen Sie die Zeichenkette $SELECTOR durch die gewünschte Adressierung des Unternehmens, der Marke oder des Produkts, zu welchem die passende Nachhaltigkeitsampel dargestellt werden soll.

Die nachfolgende Tabelle zeigt die möglichen Selektoren:

Name Funktionsweise Wert
slug Slug eines Objekts in WeGreen, vgl. Wikipedia. Der Slug eines Objekts ist ein Teil der URL der jeweiligen Nachhaltigkeitsampel im Portal wegreen.de. Beispielsweise ist die Nachhaltigkeitsampel des Unternehmens "Procter & Gamble" auf WeGreen unter der URL http://wegreen.de/de/nachhaltigkeit/profile/procter-gamble/v/overview abrufbar. Der Slug (Bestandteil der URL) lautet deshalb procter-gamble. Jeder Slug ist eindeutig auf wegreen.de. Achten Sie deshalb auf eine exakte Schreibweise. Eine Alternative zum slug Selektion ist der Selektor text Z.B "procter-gamble" für "Procter & Gamble"
text Selektion über einen bekannten Namen des Unternehmens, der Marke oder des Produkts Z.B. "BASF SE" oder "basf"
href Selektion über zugeordnete Homepage Vollständige URL der Homepage, z.B. "http://www.basf.com/index.html". Bei der Suche wird nur die Domain berücksichtigt.
fid Selektion über ID in der Freebase Datenbank Z.B. "/en/basf" für das Unternehmen BASF SE
special Selektion der nachhaltigsten (Wert "best"), am wenigsten nachhaltigen (Wert "worst") oder am meisten abgerufenen (Wert "popular"). Bei "best" und "worst" werden nur Unternehmen mit sehr hoher Konfidenz berücksichtigt, also vielen unabhängigen Quellen. Der zusätzliche Parameter "count" bestimmt die Anzahl der selektierten (Default und Maximum ist 10).

Hinweis: Es können auch mehrere Tags auf einer Seite eingefügt werden, z.B. wenn Sie auf einer Seite Nachhaltigkeitsampeln zu verschiedenen Unternehmen, Marken oder Produkten darstellen wollen.

Zufällige Ampel und Slideshow

Sie wollen auf Ihrer Homepage oder in Ihrem Blogbeitrag die Ampel eines zufällig aus einer Liste ausgewählten Unternehmens anzeigen? Kein Problem.

Jeder der Selektoren akzeptiert auch eine Semikolon-separierte Liste von Werten. In diesem Fall wird zufällig einer der Werte ausgewählt.

Zum Beispiel fügt der Tag

<div name="wg:badge" slug="apple;nokia;sonyericsson;samsung" nocache="true"></div>

die Nachhaltigkeitsampel eines der Unternehmen ein, zufällig ausgewählt:

Hinweis: Der Parameter nocache="true" deaktiviert den Cache, so dass die zufällige Auswahl bei jedem Seitenabruf erfolgt. Wird der Parameter nicht angegeben oder als Welt false übergeben, erfolgt die Auswahl einmal stündlich.

Alternativ können Sie das Widget so parametrieren, dass alle Ampeln in einer Slideshow nacheinander angezeigt werden.

Fügen Sie hierfür einfach den Parameter slideshow="true" ein.

<div name="wg:badge" slug="apple;nokia;sonyericsson;samsung;htc-1" slideshow="true"></div>

Hinweis: Darstellung als Slideshow wird nur beim Standard-Layout unterstützt. Der Parameter nocache="true" wird für Slideshows nicht benötigt.

Slideshows können mit dem Selektor "special" kombiniert werden!

<div name="wg:badge" special="popular" count="10" slideshow="true"></div>

<div name="wg:badge" special="best" count="10" slideshow="true"></div>

<div name="wg:badge" special="worst" count="10" slideshow="true"></div>

Weitere Features

Wir werden nach und nach weitere Features zu diesem Widget hinzufügen, z.B. die interaktive Vervollständigung der Eingabe des Nutzers. Sie müssen für die Nutzung dieser Features nach initialer Einbettung des Widgets nichts ändern, die Aktualisierung erfolgt automatisch.

Webservice API (Version 1.0, 3. April 2011)

Für nicht HTML-basierte Anwendungen steht eine wahlweise HTTP/JSON oder HTTP/XML basierte REST API als Webservice zur Verfügung.

Der Webservice kann zur Integration von WeGreen in Smartphone Apps, Adobe Flash basierte Web-Apps und Desktop Applikationen verwendet werden. Zum Beispiel verwendet Barcoo diese API zur Integration der WeGreen Nachhaltigkeitsampel in die eigenen Apps für iPhone, Android und Smartphones weiterer Hersteller.

Endpunkt

Endpunkt des Webservice ist die URL http://api.wegreen.de/services/{service}/{subject}.{format}?{parameters}

service bestimmt den zu nutzenden Service. Aktuell stehen search für die Suche und Anzeige von Nachhaltigkeitsampeln sowie tracking für den Aufruf des Echtzeit Webtrackings bei Einblendung einer Ampel zur Verfügung.

subject bestimmt das Subjekt des Service. Bei der Suche wird aktuell der Wert scoreable unterstützt um nach von WeGreen bewerteten Entitäten zu Suchen (Unternehmen, Marken, Produkte etc.). Beim Tracking wird das Subjekt pageview, d.h. übermittelt, also die Einblendung bzw. der Seitenabruf einer Ampel - worauf die Auwertung von Besuchen (Visits), Besuchern (Visitors) etc. basiert.

format kennzeichnet das gewüschte Responseformat eines Aufrufs. Für alle Services und Subjekte werden json sowie xml unterstützt, d.h. die Response erfolgt in der JavaScript Object Notation oder in XML Notation.

parameters enthät eine Liste von Parameter in die dem Service übermittelt werden. Konkret werden Parameter als Query String übermittelt. Die Parameter der Services sowie die jeweilige Struktur der Rückgabe/Response wird in den folgenden Abschnitten definiert. Vorweg ein Beispiel:

Der Aufruf von http://api.wegreen.de/services/search/scoreable.json?appId=XXX&appSecret=YYY&locale=de&slug=basf liefert als Response die für die Darstellung der WeGreen Nachhaltigkeitsampel des Unternehmens BASF notwendigen Daten. Die Werte der Parameter appID und appSecret sind vor Aufruf durch die individuellen Werte Ihrer Applikation zu ersetzen, wie im folgenden erläütert.

Generische Parameter eines Request

Folgende Parameter muss bei jedem Request unabhägig von Service, Subjekt und anderen Parametern übermittelt werden:

  • appID (erforderlich): Der Parameter kennzeichnet die individuelle ID Ihrer Applikation. Um ein appID zu erhalten, registrieren Sie sich als Nutzer bei WeGreen. Ihre Application ID wird im Bereich "Mein WeGreen" > "Für Entwickler" angezeigt.
  • . Die appID ist individuell aber nicht geheim.
  • appSecret (erforderlich): Der Parameter kennzeichnet ein "Geheimnis", das Ihnen auf Anfrage von unserem Support mitgeteilt wird un an Ihre Application ID gebunden ist. Das Application Secret ist geheim und darf von Ihnen nicht an Dritte weitergegeben werden.

Generischer Aufbau einer Response

Unabähängig vom aufgerufen Service, Subjekt, Format und Parameter enthät jede Response die folgenden Elemente:

  • code (immer enthalten): Kennzeichnet den Status der Response, ähnlich einem HTTP Response Code. OK kennzeichnet eine erfolgreiche Inanspruchnahme des jeweiligen Service. INVALID_REQUEST kennzeichnet einen ungültigen Request. Weitere Werte sind abhängig von Service und Subjekt, z.B. NOT_FOUND für eine Suche ohne Treffer.
  • message: Im Fall eines Fehlers (z.B. bei einem ungütigen Request, s.o.) enthält dieses Element eine menschenlesbare Beschreibung der Fehlerursache. Tritt kein Fehler auf ist das Element nicht in der Response enthalten.
  • version (immer enthalten): Kennzeichnet die Version der Response. Aktuell enthält dieses Element immer den Wert 1.0.

Suche nach bewerteten Unternehmen, Marken und Produkten

Der Service search mit Subjekt scoreable erlaubt die Suche nach bewerteten Unternehmen, Marken und Produkten und liefert die für die Darstellung der zugehörigen Nachhaltigkeitsampel notwendigen Daten.

Die Response und darin enthaltene Daten dürfen maximal für 24 Stunden von Ihrer Anwendung gecached (lokal gespeichert) werden.

Request

Für die Suche nach "Scoreables" ist bei jedem Request genau einer der folgenden Parameter anzugeben, welcher den gewünschten Treffer bestimmt:

  • text: Name des Unternehmens, der Marke oder des Produkts. Hierbei wird eine Prefix-Suche nach einem bekannten Namen durchgeführt, wobei der Wert des Parameters zuvor um Stopwörter und Operatoren wie "der", "die", "das", "and", "or" etc. bereinigt wird. Als Wert können Sie z.B. die Suchanfrage Ihres Endnutzers übermitteln oder einen Ihrer Applikation bekannten Namen des gesuchten Objekts.
  • href: URL einer Webseite des gesuchten Unternehmens, Marke oder Produkts. Bei der Suche wird die URL auf Ihre Domain reduziert und nach einer bekannten Domain des gesuchten Objekts gesucht.
  • fbid: Freebase ID des gewünschten Objekts. Sofern bekannt sind alle Unternehmen, Marken und Produkte in WeGreen mit Objekten der Freebase Datenbank verknüpft. Weitere Informationen zu Freebase inkl. dem Aufbau einer Freebase ID entnehmen Sie bitte www.freebase.com.
  • slug: Slug eines Objekts in WeGreen, vgl. Wikipedia. Der Slug eines Objekts ist ein Teil der URL der jeweiligen Nachhaltigkeitsampel im Portal wegreen.de. Beispielsweise ist die Nachhaltigkeitsampel des Unternehmens "Procter & Gamble" auf WeGreen unter der URL http://wegreen.de/de/nachhaltigkeit/profile/procter-gamble/v/overview abrufbar. Der Slug (Bestandteil der URL) lautet deshalb procter-gamble. Jeder Slug ist eindeutig auf wegreen.de. Achten Sie deshalb auf eine exakte Schreibweise. Eine Alternative zum slug Selektion ist der Selektor text.
  • id: ID eines Objekts in WeGreen.

Weitere Parameter

  • locale (optional): Der Parameter bestimmt die Landessprache der in der Response zurückgelieferten Daten. Unterstützt werden die Werte de (deutsch, Default), en (englisch) und fr französisch.

Response

  • locale (immer enthalten): Locale der Response, z.B. "de". Abhängig vom gleichnamigen Parameter des Request.
  • baseURL (immer enthalten): Basisurl f¨r in anderen Elementen der Response angegebene relative URLs/Pfade.

Sofern ein Objekt gefunden wurde, sind folgende Elemente enthalten. Elemente die nicht immer zurückgeliefert werden sind als solche gekennzeichnet:

  • scoreable.it: Transaktionscode. Ist beim nachfolgenden Aufruf des Tracking-Service zu übermitteln (s.u.).
  • scoreable.id: ID des gefundenen Objekts. Ist beim nachfolgenden Aufruf des Tracking-Service zu übermitteln (s.u.). Kann lokal gespeichert werden um bei zukünftigen Suchvorgängen einen ID-Lookup statt einer Suche per Name oder URL durchführen zu müssen.
  • scoreable.sid: Site-ID des gefundenen Objekts. Ist beim nachfolgenden Aufruf des Tracking-Service zu übermitteln (s.u.).
  • scoreable.fid: Freebase-ID des gefundenen Objekts (s.o.). Kann verwendet werden um weitere Daten zu dem Objekt aus Freebase nachzuladen. Kann lokal gespeichert werden um bei zukünftigen Suchvorgängen einen ID-Lookup statt einer Suche per Name oder URL durchführen zu müssen.
  • scoreable.lid: Legacy ID des gefundenen Objekts. Kann von herkölichen Anwendungen ignoriert werden.
  • scoreable.slug: Slug des gefundenen Objekts (s.o.). Kann verwendet werden um einen Hyperlink zu dem Objekt auf wegreen.de zu konstruieren. Kann lokal gespeichert werden um bei zukünftigen Suchvorgängen einen ID-Lookup statt einer Suche per Name oder URL durchführen zu müssen.
  • scoreable.url: Absolute URL des gefundenen Objekts (s.o.) auf wegreen.de. Die URL ist sowohl für Desktop als auch mobile Browser gültig (Auto-Detection).
  • scoreable.csrURL (optional): Absolute URL der vom Unternehmen selbst eingestellten Nachhaltigkeitsinformationen auf wegreen.de, sofern vorhanden.
  • scoreable.originalName (optional): Kurzname des gefundenen Objekts, für welches die Nachhaltigkeitsampel angefordert wurde.
  • scoreable.name: Kurzname des Objekts, dessen Nachhaltigkeitsampel zurückgegeben wurde. Der Name ist nicht immer gleich dem scoreable.originalName. Wird z.B. im Request als Parameter text=iphone übergeben, ist der Wert von scoreable.name gleich "Apple", der von scoreable.originalName gleich "iPhone".
  • scoreable.weightedColor (optional): "Farbe" der Nachhaltigkeitsampel des Objekts sofern vorhanden ("red", "yellow" oder "green").
  • scoreable.weightedScoreImagePath (optional): Pfad zum Signalbild der Nachhaltigkeitsampel sofern vorhanden.
  • scoreable.weightedScoreIconPath (optional): Pfad zum Signalicon der Nachhaltigkeitsampel sofern vorhanden.
  • scoreable.weightedScoreLastUpdate (optional): Datum der letzten Aktualisierung der Nachhaltigkeitsampel sofern vorhanden. Format abhängig von Locale.
  • scoreable.totalSourceCount (optional): Anzahl der unabhängigen Quellen welche in der Bewertung berücksichtigt wurden.
  • scoreable.overallUniqueVisitorsCount (optional): Anzahl der eindeutigen Besucher welche die Ampel gesehen haben (auf wegreen.de, im WeGreen Firefox Add-on oder in Partner-Apps).
  • scoreable.interestedVisitorsCount (optional): Anzahl der eindeutigen Besucher welche Details zur jeweiligen Ampel auf wegreen.de angefordert und gesehen haben. Nicht eingschlossen sind Besucher, welche die Ampel ausschliesslich innerhalb von Partner Apps gesehen habe. Grundlage der Aussage "interessiert das".
  • scoreable.profileType (optional): "unclaimed", "basic" oder "professional", je nachdem ob das Profil vom Unternehmen bisher nicht "geclaimed" wurde, geclaimed wurde bzw. Unternehmensangaben eingestellt wurden.
  • scoreable.profileTypeIconPath (optional): Pfad zum Icon welches den Profiltyp kennzeichnet.
  • scoreable.profileCompanyBannerPath (optional): Pfad zum vom Unternehmen eingestellten Banner welches auf die Unternehmensangaben verlinkt. Muss angezeigt werden, sofern vorhanden.

Tracking von Einblendungen der Nachhaltigkeitsampel

Der Service track mit Subjekt pageview ist zwingend umgehend während oder maximal 5 Minuten nach Einblendung einer Nachhaltigkeitsampel aufzurufen.

Anwendungen die den Suche-Service in Anspruch nehmen aber den Tracking-Service nicht vereinbarungsgemäß aufrufen, werden gesperrt.

Request

  • it (erforderlich): Transaktionscode. Der Wert ist der Response des zuvor durchgeführten Suchvorgangs (s.o.) zu entnehmen.
  • id (erforderlich): ID der Nachhaltigkeitsampel. Der Wert ist der Response des zuvor durchgeführten Suchvorgangs (s.o.) zu entnehmen.
  • sid (erforderlich): Site-ID der Nachhaltigkeitsampel. Der Wert ist der Response des zuvor durchgeführten Suchvorgangs (s.o.) zu entnehmen.
  • ip (erforderlich): IP Adresse des Endnutzers. Das letzte Oktet kann auf 0 gesetzt werden um aktuellen Empfehlungen beim Datenschutz zu genügen.
  • url (erforderlich): URL der Ihrer Seite, in welcher die Nachhaltigkeitsampel eingeblendet wurde. Wird die Ampel nicht auf einer Webseite eingeblendet, konstruieren Sie bitte eine virtuelle URL z.B. http://{myapp}.de/search?q={Suchanfrage des Endnutzers}
  • pageTitle (erforderlich): Seitentitel Ihrer Seite, in welcher die Nachhaltigkeitsampel eingblendet wurde.
  • localtime (erforderlich): Lokale Uhrzeit bei Einblendung der Nachhaltigkeitsampel. Format: HH:MM:SS
  • userAgent (erforderlich): User Agent des Browsers Ihres Nutzers. Falls nicht-Browser-basierte Anwendung übermitteln Sie bitte eine virtuelle Kennzeichnung, z.B. {myapp}.
  • browserLanguage (erforderlich): Landessprache des Browsers/der App Ihres Nutzers, z.B. "de-de" oder "en-us".

Response

Die Response eines Tracking-Aufrufs enthält keine über die generischen Elemente hinausgehende.

Support

Kontaktieren Sie bitte info@wegreen.de, falls Sie Fragen zur Webservice API haben oder Unterstützung bei der Integration benötigen.

Nutzungsbedingungen

Möchten Sie die WeGreen API nutzen, kontaktieren Sie uns bitte, um die Bedingungen zu erfahren. Nutzungsbestimmungen. Z.B. muss bei der Verwendung der Daten WeGreen als Urheber der Informationen erkennbar sein und das WeGreen Design bei Einblendung der Ampel eingehalten werden.


Application ID und Application Secret

Für die Nutzung der WeGreen APIs wird eine "Application ID", für die Webservice API zusätzlich ein "Application Secret" benötigt, das bei jedem Aufruf übermittelt werden muss. Application ID und Secret erlauben uns die Zugriffe auf den WeGreen Datenbestand zu kontrollieren und bei unsachgemäßer Nutzung zu sperren.

Jeder registrierte Nutzer von WeGreen hat automatisch eine persönliche Application ID und ein Application Secret. Um die persönliche Application ID und den Application Secret einsehen zu können, loggen Sie sich ein und klicken Sie hier.

Berechtigungsstatus bei REST basierten Webservice

Um den Zugriff auf den REST basierten Webservice freischalten zu lassen, wenden Sie sich bitte an den WeGreen Support. Der Berechtigungsstatus für die Nutzung der WeGreen APIs ist ebenfalls auf der Seite "Für Entwickler" einsehbar.