Einführung
Hier finden Sie alles was zur Einrichtung und Verbindung des SDK mit der ImmobilienScout24 API nötig ist. Beachten Sie bitten, dass für manche Aktionen spezielle Berechtigungen nötig sind. Infos dazu finden Sie hier.
Um die Funktionen nutzen zu können die über das Immocaster SDK zur Verfügung stehen, muss man sich über das SDK mit der ImmobilienScout24 API verbinden. Hierfür benötigen Sie als Zugangsdaten den oAuth-Key und oAuth-Secret, welche kostenlos auf der API-Dokumentation angefordert werden können. Für die Verbindung zur ImmobilienScout24 API über das SDK ist ein einfaches Script nötig, welches die Verbindung startet. Das SDK muss zuerst geladen und dann lediglich KEY und SECRET als Parameter in die Instanz ($oImmocaster) übergeben werden. Als erster Parameter wird der Namespace für das Objekt übergeben.
<?php
// SDK laden
require_once('Immocaster/Sdk.php');
// Verbinden
$sImmobilienScout24Key = 'KEY';
$sImmobilienScout24Secret = 'SECRET';
$oImmocaster = Immocaster_Sdk::getInstance('is24',$sImmobilienScout24Key,$sImmobilienScout24Secret);
?>Natürlich muss "Immocaster/Sdk.php" der richtige Pfad zur Datei "Sdk.php" sein. Nach erfolgreicher Verbindung kann man nun mit weiteren Anfragen an die API starten. Es muss darauf geachtet werden, welchen Key man angefordert hat. Standardmäßig versucht sich das Immocaster SDK mit der Sandbox zu verbinden. Sollten Key und Secret für den Live-Bestand von ImmobilienScout24 sein, muss man in den Live-Modus umschalten. Außerdem wird empfohlen mit cURL zu arbeiten, da es sonst teilweise zu Problemen auf manchen Servern kommen kann.
Standardmäßig nutzt das PHP SDK die Sandbox (Testsystem) mit dem http. Um https zu verwenden, kommentieren Sie folgende Funktion ein:
<?php
$oImmocaster->useHttps(true);
?>Zusätzlich müssen Sie (nächster Schritt) die Request URL auf 'sandbox' oder 'live' setzen, je nachdem welches System Sie ansprechen möchten.
Standardmäßig nutzt Immocaster die Sandbox von ImmobilienScout24, welche Testobjekte zur Verfügung stellt. Um mit echten Daten arbeiten zu können, benötigen Sie die Berechtigung für Ihren Key und Secret von ImmobilienScout24. Sofern die Berechtigung für die Arbeit mit Live-Daten besteht, muss folgender Code ergänzt werden um vom Sandbox-Modus in den Live-Modus zu wechseln:
<?php
$oImmocaster->setRequestUrl('live');
?>Mit diesem Code wird die Hauptdomain für Requests von der Sandbox-Domain (sandbox.immobilienscout24.de) auf die Live-Domain (rest.immobilienscout24.de) geändert. Es besteht ebenfalls die Möglichkeit zur Laufzeit des Scripts wieder von Live-Modus auf Sandbox-Modus zu schalten. Dazu muss einfach folgender Code ausgeführt werden:
<?php
$oImmocaster->setRequestUrl('sandbox');
?>Das SDK arbeitet standardmäßig mit der PHP-Funktion "file_get_contents". Da diese aus Sicherheitsgründen bei vielen Hostinganbietern deaktiviert ist, wird empfohlen das SDK mit cURL zu verwenden. Hierfür muss cURL natürlich auf dem Server oder dem Hostingpaket installiert und aktiv sein. Der Code um auf cURL umzuschalten lautet:
<?php
$oImmocaster->setReadingType('curl');
?>Häufig benötigt man JSON anstatt XML als Antwort von der API. Dadurch ist das Ergebnis zwar nicht mehr so übersichtlich zu lesen wie es bei strukturierten XML der Fall ist, aber schneller im Datenaustausch. Besonders bei der Arbeit mit JavaScript ist es hilfreich mit JSON zu arbeiten, da außerdem lästige Parsing-Vorgänge entfallen. Um von XML auf JSON umzuschalten, wird lediglich folgende zusätzliche Zeile im Code benötigt:
<?php
$oImmocaster->setContentResultType('json');
?>Um die Ergebnisse im Strict-Mode zu erhalten, kann mit folgender Zeile auf Strict umgeschaltet werden:
<?php
$oImmocaster->setStrictMode(true);
?>Um den Strict-Mode wieder zu deaktivieren, wird anstatt des "true" für den ersten Parameter "false" angegeben.
Für einige Abfragen wird eine lokale MySql-Datenbank benötigt. Innerhalb dieser selbst erstellten Datenbank wird ein AccessToken beim zertifizieren der Applikation gespeichert. Dieser wird benötigt um das 3-legged-oauth von ImmobilienScout24 zu nutzen und z. B. die Suche auf Maklerobjekte einzugrenzen. Folgender Code legt eine Tabelle in der Datenbank an in der später der AccessToken gespeichert wird:
<?php
$aDatabase = array(
'mysql',
'Host',
'Benutzer',
'Passwort',
'Datenbankname'
);
$oImmocaster->setDataStorage($aDatabase);
?>Innerhalb des Arrays müssen natürlich die Angaben für die Datenbank gemacht werden. Host, Benutzer, Passwort und Datenbankname müssen mit den Daten der MySql-Datenbank ersetzt werden. Die Datenbank muss natürlich vor dem Aufrufen dieser Funktion angelegt werden. Die Tabelle in der die Token gespeichert werden, wird über das Immocaster SDK automatisch angelegt. Somit muss kein Dump eingespielt werden. Soll ein anderer Name für die Tabelle verwendet werden als der Standardname "Immocaster_Storage", kann man der Funktion ein zusätzlichen Parameter mitgeben:
<?php
$aDatabase = array(
'mysql',
'Host',
'Benutzer',
'Passwort',
'Datenbankname'
);
$oImmocaster->setDataStorage(
$aDatabase,
'Immocaster',
'MeineTabelle',
true
);
?>Dieser Code würde eine Tabelle mit dem Namen "MeineTabelle" anlegen. Der zweite Parameter ist der Namespace für die Variablen, die bei der Nutzung des 3-legged-oauths in die Session geschrieben werden müssen.
Es ist darauf zu achten, dass Immocaster für die Zertifizierung der Applikation per Secret und Key eine Session benötigt. Diese erstellt Immocaster automatisch. Ist die Application bereits zertifiziert, kann das automatische Erstellen der Session deaktiviert werden. Hierfür steht ein vierter Parameter innerhalb der Funktion setDataStorage zur Verfügung. Dieser muss einfach auf false gesetzt werden. Das könnte z.B. so aussehen:
<?php
$aDatabase = array(
'mysql',
'Host',
'Benutzer',
'Passwort',
'Datenbankname'
);
$oImmocaster->setDataStorage(
$aDatabase,
null,
null,
false
);
?>Bitte benutzt beim Zertifizieren den Username des Maklers. Das muss nicht immer die Kundennummer sein, sondern kann von den Maklern frei vergeben werden.
Es ist dringend darauf zu achten, dass das Auslesen von eigenen Objekten über den Channel "Homepage" nicht mit dem Basiszugang von IS24 funktioniert. Hierzu informiert man sich bitte direkt bei ImmobilienScout24.
Vor dem zertifizieren einer Applikation muss eine Verbindung zu einer Datenbank hergestellt werden. Das Debugging (enableRequestDebug) muss ausgeschaltet sein! Anschließend kann folgender Code eingebunden und ausgeführt werden:
<?php
echo '<h2>Zertifizierung einer Applikation durch den Makler</h2><br/>Diese Funktion wurde auskommentiert!<br/><br/>';
$sCertifyURL = 'http://MEINE-AKTUELLE-URL.DE'; // Komplette URL inkl. Parameter auf der das Script eingebunden wird
if(isset($_GET['main_registration'])||isset($_GET['state']))
{
if(isset($_POST['user'])){ $sUser=$_POST['user']; }
if(isset($_GET['user'])){ $sUser=$_GET['user']; }
$aParameter = array('callback_url'=>$sCertifyURL.'?user='.$sUser,'verifyApplication'=>true);
// Benutzer neu zertifizieren
$returnAuthentication = $oImmocaster->getAccess($aParameter);
if ($returnAuthentication === true)
{
echo '<div id="appVerifyInfo">Zertifizierung in der MySQL Datenbank war erfolgreich.</div>';
}
elseif (is_array($returnAuthentication) && count($returnAuthentication) > 1)
{
echo '<div id="appVerifyInfo">Zertifizierung war erfolgreich. Hier finden Sie Access Token und Token Secret kommasepariert und url enkodiert.</div>';
echo '<div class="codebox"><textarea>'.implode(",", $returnAuthentication).'</textarea></div>';
}
else
{
echo '<div id="appVerifyInfo">Es ist etwas schief gelaufen. Troubleshooting: Benutzer ist bereits in der MySQL Datenbank zertifiziert oder es besteht keine Verbindung zur Datenbank.</div>';
}
}
echo '<form action="'.$sCertifyURL.'?main_registration=1" method="post"><div id="appVerifyButton"><strong>Hinweis: Unter IE9 kann es zu Problemen mit der Zertifizierung kommen.</strong><br />Benutzername: <input type="text" name="user" /><br /><em>Der Benutzername sollte nach Möglichkeit gesetzt werden. Standardmäßig wird ansonsten "me" genommen. Somit können aber nicht mehrere User parallel in der Datenbank abgelegt werden. Der gewählte Benutzernamen muss der gleiche wie im Formular auf der nächsten Seite sein, damit der Token richtig zugewiesen werden kann.</em><br /><input type="submit" value="Jetzt zertifizieren" /></div></form>';
echo '<p>Registrierte Nutzer in der Datenbank: ';
// Anzeige welche Nutzer bereits in der MySQL Datenbank registriert sind
print_r($oImmocaster->getAllApplicationUsers(array('string'=>true)));
?>Natürlich muss der Wert für "sCertifyURL" richtig gesetzt sein. Dies ist eine häufige Fehlerquelle, da oftmals nicht die komplette URL angegeben wird. Die URL muss 100% der URL entsprechen, auf dem der Code eingebunden wird. D. h. mit Unterverzeichnissen und Parametern (z.B.: https://www.meine-immocaster-url.de/ic/test/index.php?testen=yes&immocaster=1). Nach erfolgreicher Anmeldung wurde ein AccessToken generiert, der in nun in der Datenbank hinterlegt ist. Dieser Token wird für alle weiteren Anfragen an die API genutzt, bei denen eine Zertifizierung nötig ist. Ob die Zertifizierung erfolgreich war kann man in der Datenbank sehen. Hier sollte nun ein Eintrag sein, der mit "APPLICATION" im Feld "ic_desc" gekennzeichnet ist. Dieser Eintrag sollte nicht per Hand aus der Datenbank gelöscht werden, da die Zertifizierung sonst erneut durchgeführt werden muss. Wenn alles geklappt hat, kann der Code zum zertifizieren wieder entfernt werden.
Sollten Sie -wider Erwarten- die Token Schlüssel manuell in der Datenbank eintragen (wenn diese z.B. aus Sicherheitsgründen von uns gelöscht worden sind) stellen Sie sicher das die Token dort urlencodiert angelegt/ abgespeichert werden da es sonst zu Signierungsproblemen/ Fehler beim Datenabruf (ERROR MESSAGE: Invalid signature for signature method HMAC-SHA1) kommen kann.
Die Zertifizierung erlauft das zertifizieren mehrerer Nutzer. Deshalb sollte immer ein Nutzername mit angeben werden. Wir kein Nutzername angegeben, vergibt das SDK automatisch "me" als Nutzernamen. Das SDK hält zusätzlich eine Funktion bereit um zu prüfen, welche Nutzernamen bereits zertifiziert sind:
<?php
echo '<p>Registrierte Nutzer: ';
print_r($oImmocaster->getAllApplicationUsers(array('string'=>true)));Dabei wird kein Username benötigt, da dieser vorher für die Datenbank und Folgerequests benötigt wurde. Somit ist nun eine 1-Klick Authentifizierung möglich. Allerdings erhält man "nur" Access Token und Secret, welche für Folgerequests nicht benutzt werden.
- Mindestens SDK Version 1.1.66 benötigt
- Debuggung (enableRequestDebug) ausschalten.
- Schalter für Authentifizierung ohne MySQL Datenbank einschalten:
<?php
/**
* Authentifizierung mit oder ohne MySQL Eintrag durchspielen
* default,false: MySQL
* true: Session
*/
$oImmocaster->authenticateWithoutDB(true);- Authentifizierung ohne Eingabe von Username starten
- Auf ImmobilienScout24 SSO Seite einloggen ODER Login bestätigen
- Response mit Access Token und Token Secret in Codebox erhalten
dddd