Software - Know-how

JS-API – Technische Implementation

Die Technische Implementation der JS-API setzt lediglich HTML-Kenntnisse voraus und ist damit auch für Hobby-Bastler geeignet. Prinzipiell unterstützt unsere JS-API hier zwei Modelle: Die Einbindung mit und die Einbindung ohne die blau direkt Markup Language, kurz blauML.

Die Einbindung ohne blauML

Zur Implementation eines Vergleichsrechners via JS-API ohne blauML laden Sie bitte als erstes unsere JS-API, indem Sie folgenden HTML-Code im <head>-Bereich Ihrer Website platzieren:

Der Pfad zur API ist in diesem Fall „https://www.maklerinfo.biz/js/api-1.0.js“. Beachten Sie bitte unbedingt unsere Hinweise zur Versionierung (siehe unten), da sich der Pfad ändern kann und wird. Setzen Sie anschließend, am besten genau dadrunter, Ihre Vermittler-Nummer. In diesem Beispiel wäre dies die „003542“.

Alternativ können Sie die Vermittler-Nummer übrigens auch gleich beim Instanziieren setzen. Aus den beiden obigen Code-Blöcken wird dann einer:

Platzieren Sie nun einen <div>-Container mit fester ID in Ihrer Website, in welchen später der iFrame mit dem Vergleichsrechner geladen werden soll. In diesem Beispiel ist die ID „rechner_hunde“.

Nun haben wir bereits die benötigte JS-API geladen sowie die Ziel-Position des Vergleichsrechners definiert. Was nun noch fehlt ist das eigentliche Laden des Vergleichsrechners. Dies geht über den folgenden Funktionsaufruf:

Achtung! Das Element, in welches der Vergleichsrechner eingefügt werden soll, muss zu diesem Zeitpunkt natürlich bereits existieren!

Zur Erklärung: „hunde“ steht in diesem Fall für die ID des Vergleichsrechners und gibt an, dass der „Hunde-Rechner“ geladen werden soll. „rechner_hunde“ definiert den <div>, in welchem der iFrame platziert werden soll. Eine vollständige Liste unserer Vergleichsrechner mit dazugehörigen IDs finden Sie übrigens in unserem Maklerportal unter „Service“ -> „Link-Liste“.

Die Einbindung mit blauML

Die Verwendung der blauML, kann die Einbindung aber noch weiter vereinfachen. Um blauML zu verwenden, geben Sie dies bitte beim Instanziieren an.

Ausserdem sollten Sie den Pfad zum XML-Namespace einfügen:

Anschliessend können Sie den von Ihnen gewünschten Rechner einfach in Ihrer Website einfügen, indem Sie folgenden HTML-Code an gewünschter Stelle platzieren:

Auch in diesem Fall ist „hunde“ wieder die Rechner-ID und gibt so an, welcher blau direkt Vergleichsrechner geladen werden soll.

Hinweise zur Versionierung

Unsere JS-API wird versioniert. Die Versionsnummer ist zweistellig und setzt sich aus Major.Minor zusammen. Bei nicht abwärtskompatiblen Updates wird die Minor hochgezählt. Die Major wird nur bei grundsätzlichen Weiterentwicklungen hochgezählt.

Die aktuelle Version beeinflusst den aktuellen Pfad zur JS-API wie folgt: https://www.maklerinfo.biz/js/api-Major.Minor.js

Wir halten die letzten 3 Versionen der JS-API vor. Beim vierten Update liefern wir folgerichtet die erste Version nicht mehr aus, usw. Damit Sie das nicht vor unlösbare Aufgaben stellt, informieren wir alle unsere Lizenznehmer der JS-API natürlich bei jedem versionsrelevantem Update per E-Mail inkl. Changelog.

Aus organisatorischer Sicht macht es bei der merhfachen Verwendung der JS-API daher durchaus Sinn auf eine zentrale Verwaltung der aktuell verwendeten Version, eventuell sogar der Einbindung, zu setzen.

Avatar-Foto
Hannes Heilenkötter ist Chief Technology Officer bei blau direkt.

13 Kommentare zu “JS-API – Technische Implementation”

  5. Zwei Fragen:

    Kann man das JS-API asynchron nachladen? Also z.B. erst nach „onload“ in den DOM einbauen?

    Kann man davon ausgehen, daß die blauML auch in späteren Versionen kompatibel ist, man also nur die aktuelle JS-Version hochzählen muß?

    Antworten

  6. Hallo Herr Freund,

    die JS-API kann auch asynchron nachgeladen werden.

    Wir versionieren die JS-API u.a. deshalb, damit wir keine lebenslange Abwärtskompatibilität sicherstellen müssen. Dies macht die Softwareentwicklung nämlich unnötig teuer. Aktuell ist es zwar nicht angedacht die blauML in späteren Versionen abzuschaffen oder zu verändern, ausschließen können wir es aber zum aktuellen Zeitpunkt trotzdem nicht. Kurz um: Es könnte sein, dass sich mit späteren Versionssprüngen auch der Code für die Einbindung, insbesondere in Bezug auf die Events, ändert.

    Aus organisatorischer Sicht macht es bei der mehrfachen Verwendung der JS-API daher durchaus Sinn auf eine zentrale Verwaltung der aktuell verwendeten Version sowie der Einbindung zu setzen.

    Mit freundlichen Grüßen

    Hannes Heilenkötter

    Antworten

  9. Hallo Herr Krist,

    Sie haben Recht. Eine Dokumentation zur Implementation des Kunden-Logins via JS-API existiert noch gar nicht. Ist aber natürlich möglich.

    Den erklärenden Blog-Artikel hierzu habe ich gerade geschrieben und für nächsten Freitag zur Veröffentlichung geplant.

    Antworten

  11. Hallo Ivo,

    die Abschluss-Seite des Vergleichsrechners enthält einen Div mit einer ID, aus welcher man die „kid“ des Vertrages auslesen kann. Die Zeile HTML sieht beispielsweise so aus:

    <div class="cbg" id="kid-123456">

    Die Nummer „123456“ steht hierbei für die sog. „kid“. Das ist bei uns die eindeutige ID des Vertrages, unter welcher der Vertrag in unserer Software geführt wird. Bei der Einbindung des Vergleichsrechners via AJAX-Tunnel könntest du die kid mit einem regulären Ausdruck auslesen und weiterverarbeiten.

    Die Alternative hierzu ist die Übergabe einer „externen Kennung“ an den Vergleichsrechner. Bei Vertrags-Abschluss kann unsere Software diese externe Kennung zum Vertrag mitspeichern und „durchschleifen“. Bei Exporten bspw. können wir dir diese Kennung zurückgeben und du kannst dann mergen. Wie das technisch genau funktioniert müsste ich allerdings auch erst nachschauen. Bei Interesse schreib mir am besten einfach eine kurze E-Mail.

    Antworten

  12. Hallo Herr Krist,

    die JS-API ist der nachfolger des AJAX-Tunnels. Beide Arten der Einbindung haben Vor- und Nachteile. Wenn Sie nicht vorhaben Datenströme des Vergleichsrechners auszulesen oder zu manipulieren empfehle ich die JS-API.

    Ein „Upgrade“ von AJAX-Tunnel auf JS-API ist übrigens jederzeit problemlos möglich – auch ohne doppelte Lizenzkosten. Wenden Sie sich diesbzgl. am besten direkt an unsere Maklerbetreuung. Die kennt hier die genaue Vorgehensweise.

    Antworten

Komentar verfassen

Die E-Mail-Adresse wird nicht veröffentlicht. Erforderliche Felder sind mit * markiert.