Software development kit¶
New in version 6.0: SDK for external mode
New in version 8.0: SDK for external and local mode
Current SDK Version: 18.0
Hint
- The SDK comes preinstalled on every IACBOX with the custom logon page/custom webserver.
- If a central installation (for many systems) is needed, the SDK can be installed on an external webserver.
The SDK provides a small PHP framework which abstracts all the tiny details away and lets you easily make customization and/or create new plugins and extensions.
Contents
The SDK written in PHP provides you with a sample login page and plugins for many different authentication methods. Starting with version 2 the SDK is also used for the local custom webserver.
Downloads¶
You will find the SDK for external use in the download section of our homepage or in the my.iacbox partner-portal.
Login-API operation modes¶
Ahead of any other decisions that have to be made, you have to be aware of two very different operation modes of the Login-API. You have to choose which one serves your needs:
1. External Mode: this is the normal mode of version 1.x. The Login-API SDK is hosted on an external webserver by yourself.
- Advantages:
- Allows to point any number of IACBOXes to this login page.
- One single place to make changes.
- Centralized data storage possible.
- Disadvantages:
- You have to host the SDK on an external webserver which has to be maintained and configured by yourself.
- Slower than local mode and consumes uplink bandwidth.
- Without any failover architecture this external server is a single point of failure.
2. Local Mode: Since version 8.0 an IACBOX comes equipped with a custom logon webserver with PHP 5.6 and the preinstalled SDK replacing the traditional loginpage. So this can also be used to just change the look of the login page like it wasn’t possible before.
- Advantages:
- The login page ist fast no matter how slow or unreliable your uplink is.
- The traffic to your login page is only local and does not utilize your upstream.
- Make easy and fast changes with the built-in code editor.
- Fewer redirects compared to the external mode, less complex plugins.
- Disadvantages
- If you are using multiple systems you have to make your changes on every IACBOX seperately.
- If you want to manage a central database with authentication data and having logs of logins the local mode still allows that but it is harder to achive
- Currently no local database available.
Login-API SDK architecture¶
Configuration¶
The configuration of the Login-API SDK is handeled in two different places. The main configration can be found in conf/main.config. Everything important regarding the Login-API is handeled there.
| Configuration key | Since | Default | ||
|---|---|---|---|---|
| profile-desc | 2.0 | [profilename] | ||
| Name of the profile | ||||
| company-name | 2.0 | |||
| Will be the title of the logon page | ||||
| company-name-legal | 2.0 | |||
| Shown on the end of the logon page | ||||
| logo | 2.0 | login_logo.png | ||
| Logo which should be used | ||||
| background-image | 17.0 | login_bg_full.jpg | ||
| Backgroundimages shown on the logon page | ||||
| show-welcome-header | 17.0 | true | ||
| Should the Headermessage be shown | ||||
| show-lang-select | 17.0 | true | ||
| Should the language selection be shown | ||||
| template | 17.0 | index_view.php | ||
| Determines which template will be the default tempalte | ||||
| plugins | 2.0 | |||
| Plugins which should be used for the logon. | ||||
| languages | 2.0 | en | ||
| Available languages for the logon page. Only needed for the external version | ||||
| fallback-language | 2.0 | en | ||
| Will be used if a language could not be found | ||||
| location-based | 2.0 | false | ||
| Enable location based configuration | ||||
| location-id-fields | 2.0 | iacbox | ||
| Fields to determine different locations | ||||
| base-url | 2.0 | https://hotspot.internet-for-guests.com | ||
| Should not be changed except you use another base-URL for the Surf-LAN | ||||
| webserver-url | 2.0 | |||
| Url of your Webserver used for plugins with callbacks from externel servers | ||||
| sender-name | 2.0 | |||
| Name of the sender (used in payment plugin only) | ||||
| sender-email | 2.0 | |||
| Email address which will be shown in email (used in payment plugin only) | ||||
| log-level | 2.0 | INFO | ||
| Determines the log level for the Login-API | ||||
| redirect-url | 2.0 | |||
| Redirect after the login | ||||
| show-terms | 2.1 | true | ||
| Show the terms of use (no checkbox) | ||||
| show-privacy-policy | 2.1 | true | ||
| Show the privacy policy (no checkbox) | ||||
| force-terms | 2.0 | true | ||
| Force to accept the terms of use | ||||
| force-privacy-policy | 2.1 | false | ||
| Force to accept the privacy policy | ||||
| encryption | 2.0 | |||
| Has to match the configuration in Module/Interfaces/Login-API on the IACBOX | ||||
| encryption-shared-secret | 2.0 | |||
| The shared secret can be found in Module/Interfaces/Login-API on the IACBOX | ||||
| use-browser-auto-settings | 2.0 | |||
| The Browser should use autocomplete, autocapitalization, spellcheck and autocorrect features | ||||
| custom-services | 2.0 | |||
| Register one or more custom services (separated by commas) | ||||
| test-template | 2.0 | |||
| Creates a fake session for testing purposes | ||||
| refresh-id-mapping | 2.0 | |||
| Refresh call to a certain page | ||||
| lgnapi-version | 2.0 | |||
| Version of the API / protocol | ||||
| use-rdbms | 2.0 | |||
| Loads the RdbmsConnector to hold and manage a connection to your database. | ||||
Attention
- Please note that the configuration use-rdbms can only be used with an external DB
- Create a secure connection to your DB! (e.g.: VPN)
The second part of the configurations are the plugin specific configurations. This files can be found in Iacbox/LoginApi/Plugin/[Plugin]/[plugin].conf. Which configurations have to be done depends on the plugins you have activated in conf/main.conf. For further informations which configurations are possible read the Plugin configuration documentation.
Existing plugins¶
| Pluginname | Since | Type | Usage |
|---|---|---|---|
| Ticket | 1.0 | AuthPlugin | loc, ext |
| Ticket/ Voucher Login | |||
| Pms | 1.1 | AuthPlugin | loc, ext |
| PMS Login | |||
| PwdOnly | 1.4 | AuthPlugin | loc, ext |
| Password only Login | |||
| Free | 2.0 | AuthPlugin | loc, ext |
| Free login coupled with Free Logon or Take online | |||
| Social | 2.0 | AuthPlugin | loc, ext |
| Social login (Facebook, Google+, Twitter) | |||
| Payment | 2.0 | AuthPlugin | loc, ext |
| Payment plugin (PayPal, Sofortüberweisung) | |||
| 2.0 | AuthPlugin | loc, ext | |
| Email Login coupled with Email Messaging Module | |||
| Sms | 17.0 | AuthPlugin | loc, ext |
| SMS Login coupled with SMS Messaging Module | |||
| Status | 2.0 | Others | loc, ext |
| Status information of the client | |||
| Ads | 2.0 | Others | loc, ext |
| Show advertisement before logon | |||
| Socialshare | 2.0 | Others | loc, ext | |
| Show sociale like/share buttons | |||
loc = available in local mode, ext = available in external mode
Styling¶
Template changes can be made on two different places. The structure of the main page can be changend in htdocs/index_view.php. It is also possible to creae your own page and include it in the htdocs/index.php. The main CSS file can be found in htdocs/css/style.css. We recommend to use the overlay file htdocs/css/style_overlay.css for changes to the CSS because the style.css will be updated regularly.
Some plugin specific CSS classes can be found in the corresponding CSS file Iacbox/LoginApi/Plugin/[Pluginname]/css/. If there is a need to change the template structure of a plugin this can be done in the file [pluginname](_local).php. Please note that if you create your own plugin you are not bound to the naming convention for templates we are using in the already existing plugins.
Translations¶
General translations are stored in conf/lang/[language].lang. Plugin specific translations can be found in Iacbox/LoginApi/Plugin/[Pluginname]/lang/. The LoginApi provides translations for all 23 languages of the normal logon page but not alle languages are fully translated.
Hint
- Since version 17 it is possible to add translations for the selection of gender and building mapping in the PMS configuration.
- The translation-keys need to be lowercase and seperated per “-” (dash)
- Example: building-mapping = 1:house-a; 2:house-b
Logging¶
System log¶
Externale Mode
As default the SDK logs to your syslog - depending on your Linux distribution this is /var/log/syslog or /var/log/messages. On newer systems
which use systemd you can see your logs with jounalctl -f. All messages start with LGNAPI which makes it simple to filter (adding | grep LGNAPI).
If you encounter any errors (especially white pages what means PHP had an fatal error) then you should look into your webserver log - for apache this is very
often /var/log/apache2/error.log or similar.
Local Mode
The SDK logs per default to the syslog of the IACBOX. All messages start with LGNAPI which makes it simple to filter. The System logs can be downloaded in the menu Reporting/System.
If you encounter any errors (especially white pages what means PHP had an fatal error) then you should look into the log of the Login-API webserver. This log can be accessed if you connect via FTP with the user sysop.
Database¶
If you want to log the messages in a database, which is available in both modes, there is already a custom service called DBLogger part of the SDK.
This is made for external Login-API but theoretically possible in local mode too when writing to an external database (But this is propably a
performance issue). Be sure to have this config lines in your main.config
1 2 3 4 5 6 | use-rdbms = true
db-type = <database type like pgsql or mysql>
db-host = <database host>
db-name = <database name>
db-user = <database user>
db-pwd = <database password>
|