Requierements. The eKaay Engine needs a webspace with PHP and mySQL. The webspace has to be public, i.e. it has to be reachable by http://www.my-ekaay-engine.com, likewise the portal server http://www.my-portal-server.com. The two servers - and so their URLs - may be identical. The following php packages are expected to be installed: curl, gd, hash, mcrypt, mysqli, und openssl.
The standard procedure of the eKaay integration is the following:
SDK. Please unzip the file ekaay.zip which you got from eKaay. Put the this directory ekaay/ (''SDK'') into the webserver, preferably below the root. The drawing on the right shows the directory structure.
Basic settings. Do this next:
Stand-Alone Version. Now on the test website http(s)://www.my-ekaay-engine.com/ekaay/test/ one should already see the a 2D-code, with a small green dot blinking. If you don't see the 2D code on the test webpage or the green dot is not blinking, something is wrong.
Possible reasons. If the database is not connected then there should be corresponding messages shown on the screen within the iframes. By calling the script ''https://www.my-ekaay-engine.com/ekaay/test/checkenv/'' (is available as link ''checkenv'' on the test webpage) one can check whether all necessary PHP packages are activated.
Testing. When the 2D codes are shown and the dots are blinking, please test eKaay - now running already on your server: Activate eKaay on your smartphone by scanning the activation 2D code with your eKaay app. Afterwards log in to the test portal by scanning the login 2D code with your eKaay app. Everything should work like here: http://www.ekaay.com/dev/ekaay/test/
Current Status. After Step 1 is completed, ekaay already runs on your server. Unfortunately, it works just for the test portal (''test'') which was delivered as a part of the eKaay SDK package. eKaay has now to be ''married'' to the portal server. This will be done during Steps 2 and 3.
Instructions/Plugins. Before you continue, please check on page Integration, whether your software system appears in the list over there. If there are Instructions or even a Plugin for your software system then please follow the Instructions over there, and ignore the following steps 2 and 3.
Portal Server. On the website Preparation Portal-Server you find the specifications (L-1) und (L-2) for the login script and the html snippet - both have to be provided by the implementation team at the portal server.
eKaay-Engine. At the ekaay-Engine site the following settings for the call of the login script at the portal server have to be made within the file ekaay/settings.php, the explanations you find below.
define('OS_CALL_SCRIPT','http://www.my-portal-server.com/login.php?q=node'); define('OS_POST_PARNAME_USERNAME','user'); define('OS_POST_PARNAME_PASSWORD','passwd'); define('OS_POST_EXTRA_PARNAME1','ekaay'); define('OS_POST_EXTRA_VALUE1','1');
Login-Script URL. OS_CALL_SCRIPT determines the URL of the login script at the portal server. Fixed GET parameters may be added, see example ''q=node''.
Username und Token.Via OS_POST_PARNAME_USERNAME and OS_POST_PARNAME_PASSWORD the expected parameter names for Username and Token, resp., are determined.
Extra-Parameter. Via OS_POST_EXTRA_PARNAME1 and OS_POST_EXTRA_VALUE1 another pair of parameter name and parameter value can be send to the portal server login script. Up to 6 pairs of that kind can be determined (up to OS_POST_EXTRA_PARNAME6/OS_POST_EXTRA_VALUE6).
Page-ID. It is possible via URL parameters 'pageidname' und 'pageidvalue' to provide a pair parameter name/ parameter value within the call of the iframe. The pair is send as another parameter to the portal server login login script. This is useful in case the portal server provide its login webpage with changing page IDs. The call of the iframe looks this way (example from Drupal):
<iframe frameborder='0' src='https://www.my-ekaay-engine.com/ekaay/ekaaycore/proxy/www/? pageidname=form_build_id &pageidvalue=form-j3pm-uSN9hl4S8gVQtSh2Ei35J7oMICW6qlWD7ZGrm4' style='margin:5px;width:275px;height:325px'> </iframe>In this example the following parameter
Method. POST is the default methode for the parameters for the login script. Via '' define('OS_CALL_METHOD', 'GET');'' you can send all parameters via GET. Please don't forget to add a finishing ?, resp. &, to the string OS_CALL_SCRIPT.
Testing. When on both sides (portal server, eKaay engine) the above changes have been made, please check on the test page http://www.my-ekaay-engine.com/ekaay/demo/ whether everything works: activate eKaay on your cell phone with an existing user name of the portal server (2D-code on the right), and then try the login (2D-code on the left). Do you get into this user account at the portal server?
Zwischenstand. After Step 2 is completed one can active ekaay at the portal server and then log into the portal server via eKaay. But this works for any existing user account - this is of course not the way how it should work, and this is changed within Step 3.
Problem. Until now anyone can activate ekaay for any username at the portal server. But of course eKaay should be activated only for usernames existing at the portal server, and moreover, only the respective user should be able to do this.
Solution. The problem will be solved the following way. The activation iframe is only shown to a user when he is logged into his portal server account. Moreover, a so-called ''reverse token'' will be randomly created by the portal server the moment the iframe html code is created, and the username and the reverse token will be parameters for the iframe call. When the eKaay engine then starts to produce the content of the activation iframe it will first ask the portal server via URL call whether this pair username/reverse token is valid. Only if the answer of the portal server is positiv, the activation will proceed and the 2D code will be shown. The method of the reverse token is the same as the token method during the login, just in reverse direction, see drawing on the right for a comparison (click to enlarge).
Portal-Server. First, the changes (A-1) bis (A-4) for the ACTIVATION interface have to be made at the portal server site, see page Preparation Portal-Server.
eKaay Engine. On the ekaay engine side only the following settings have to be made.
define('OS_CHECK_REV_TOKEN', true); define('OS_CHECK_REVERSE_TOKEN_SCRIPT_URL', 'http://www.my-portal-server.com/ekaayCheckReverseToken.php?');With OS_CHECK_REV_TOKEN set to true the check of the reverse token is activated. Setting it to true lets the warning message within the activation iframe disappear. OS_CHECK_REVERSE_TOKEN_SCRIPT_URL determines the URL of the check script at the portal server. Please add the ?, resp. an &, at the end, see example above.
Testing. When the changes (A-1) to (A-4) at the portal server and the settings at the eKaay engine have been made, please check if it works. First check: if within the right iframe on the test page http://www.my-ekaay-engine.com/ekaay/demo/ still a 2D code can be seen then something went wrong. On the other hand, when you log into a user account at the portal server then it should be to execute a activation or reactivation of eKaay for this user. After you activated eKaay, check if the login via eKaay works.
Necessity. Step 3 should not be left out. If this is not done, all portal accounts are open for everybody.
Current Status. After Step 3 is done eKaay runs in its base version on the portal.
More Settings. Many more ways of adjusting the eKaay engine can be found in the file with the default settings ekaay/ekaaycore/server/system/config/settings_default.php.
A list of all constants defining the behaviour of eKaay can be found here.
The default settings are overwritten by define() commands in ekaay/settings.php. Please do not edit within ekaay/ekaaycore/server/system/config/settings_default.php because after an SDK update all changes there are gone.
Language. Via ''define('OS_LANG', 'en');'' and ''define('OS_LANG', 'de');'' you can set the language to English or to German, resp.
Texts. Changes of the default texts can be done in ekaay/settings.php. The names of the constants can be found in ekaay/ekaaycore/server/system/config/texts_en_default.php. Here are some text default definitions:
//login iframe: define('TEXT_HOME_ekaay_login', 'eKaay Login (<a href="http://www.ekaay.com?lang=en" target="_top">Info)'); // main subpage activation iframe define('TEXT_REGISTER_welcome_left', 'Welcome user <b>'); define('TEXT_REGISTER_welcome_user_name', true); // show username define('TEXT_REGISTER_welcome_right', '</b> to the eKaay activation page! (<a href="http://www.ekaay.com?lang=en" target="_top">Info)'); // page activation iframe containing 2D Code define('TEXT_REGISTER_online_act', 'In order to activate eKaay (<a href="http://www.ekaay.com?lang=en" target="_top">Info) please scan the 2D-code with the eKaay App. Your password will stay valid.');The examples show that it is possible to include formatting commands and even links into the text definition.
Styles. Changes of html styles can be made in ekaay/settings.php. The names and the default values of the style constants can be found in ekaay/ekaaycore/server/system/config/styles_default.php. The most important ones and the default values are the following.
//login iframe: define('STYLE_HOME_body', 'background-color:white;color:#00A;margin:5px;'); define('STYLE_HOME_tbl_login', 'background-color:#F0F0FF;width:180px;min-height:250px; border:1px solid black;align:center;margin:3px;padding:3px;font-size:80%;'); // activation iframe: define('STYLE_REGISTER_body', 'background-color:white;color:#00A;margin:5px;'); define('STYLE_REGISTER_main_div', 'background-color:#F0F0FF;width:425px;min-height:204px; border:1px solid black;margin:10px;padding:10px;font-size:85%;'); // the blinking dot - turn it off via display:none define('STYLE_HOME_polling', 'padding:3px;display:inline;'); define('STYLE_REGISTER_polling', 'padding:3px;color:#F0F0FF;display:inline;');
QR-Code. The color, the background color, and the size of the QR code can be defined in ekaay/settings.php, likewise the logo shown on the QR code.
define('STYLE_HOME_color_qr_code_r', '8'); //color qr code define('STYLE_HOME_color_qr_code_g', '114'); define('STYLE_HOME_color_qr_code_b', '192'); define('STYLE_HOME_bgcolor_qr_code_r', '246'); //background color qr code define('STYLE_HOME_bgcolor_qr_code_g', '246'); define('STYLE_HOME_bgcolor_qr_code_b', '242'); define('STYLE_HOME_size_qr_code', '111'); // size qr code define('STYLE_HOME_size_qr_code_rsa', '195'); //size offline login qr code define('STYLE_REGISTER_size_qr_code', '198'); //size activation qr code define('STYLE_HOME_show_portal_logo_on_qr_code', true);
Logo. The logo ekaay/logo.png appears as an icon on the ''Account List'' on the user's cell phone. Replace logo.png by your quadratic size png logo, for example your favicon. Optimal size is ca. 80x80 pixel - please not much larger because then it will take too much time to download it to the cell phone. Via ''define('STYLE_HOME_show_portal_logo_on_qr_code', true);'' the same logo appears on the QR code.
Webserver. If the portal has an Apache webserver, all access rules are given by existing .htaccess files. If a different webserver ist working the following access rules have to be set for the respective directories (and - implicitly - their recursive sub-directories):
|ekaay/||deny from all|
|ekaay/ekaaycore/proxy/www/||allow from all|
|ekaay/ekaaycore/proxy/www/config||deny from all|
|ekaay/ekaaycore/server/wwwsrv/_srv||allow from all|
Tests. Wenn all settings have been done, it's time for final testing.
Transfer Live System. When everything is tested and works the software can be transfered from the test system to the live system (copy+paste+adjust).
Please do not edit within the ekaaycore/ directory. Otherwise, after an update these changes are lost.
eKaay commits itself to the upward compabilität of the SDK.
In other words: once you have sucessfully implemented eKaay the ekaay system will run forever because changes of the versions
of the mobile apps will always be able to handle the requiered behaviour of your server SDK version.
Notice: Future changes of the PHP version running your eKaay engine webspace may cause problems.