This document provides some basic guidance on how to customize the Unifi Controller v5.6+ Hot Spot Portal feature. Existing documentation seems to be scarce in this technician's opinion.
This readme is the culmination of some exploration in customizing the portal for business use. Please note, all examples use the installed location of the Unifi v5 Controller software on the Unifi CloudKey.
Some issues have been encountered after upgrading the Unifi Controller to newer releases specifically with the Hot Spot Portal customizations on Unifi Controller versions greater than 5.10 relating to the use of these instructions. You may not have a choice but to upgrade your included default template to the latest version and re-modify your portal files.
The portal actually runs on a different port from the controller or the cloudkey, specifically TCP 8843.
To view the portal without using the guest network, you must use a hostname that is pointed at your cloudkey's IP e.g. https://your.cloudkey.url:8843/guest/s/default/#
Depending on your Unifi Controller version, you may no longer have access to the default site portion of the URL (this has been observed as a feature removed in the latest betas of the controller). I have not had opportunity to test and verify this myself though.
Hotspot Override templates can become out of date! Always make a backup copy of any changes you make to version control or a system elsewhere!
By default, the files required to enable customization are not readily available or accessible to the end-user. To enable them, you must go into the Unifi Controller software (e.g. https://yourunificontrolleraddress.com:8443 ) and from there go to Settings (Gears Symbol at left navigation), Guest Control (from the left hand navigation bar).
Under "Portal Customization", ensure that the radio button beside AngularJS is selected and that the checkbox beside "Override Default Template" is checked.
Under "Portal Customization", ensure that the radio button beside AngularJS is selected and that the checkbox beside "Override templates with custom changes" is checked.
If the checkbox under portal customization related to the templates becomes unchecked after a controller upgrade, check it again and see if you are prompted to upgrade your override template.
The files to modify are located within the /usr/lib/unifi/data/sites/default/app-unifi-hotspot-portal/ directory on the Unifi CloudKey. For those who are using another Linux-based platform to host the controller, the path should be <unifi_install>/data/sites/default/app-unifi-hotspot-portal.
To modify specific forms such as the Free Trial form when gathering some customer information which is shared with the credit card payment form, the file is located at /usr/lib/unifi/data/sites/default/app-unifi-hotspot-portal/views/payment.html (this is symlinked to /srv/unifi/data/sites/default/app-unifi-hotspot-portal/views/payment.html.
The built-in templates have a lot of options available for you to build your modifications upon the existing framework of options.
A good example is the above mentioned form. The form box that begins on (if still using the default file) Line 66 of payment.html is always enabled IF you are accepting payment OR have a free trial option enabled AND you have configured the free trial option override to gather any type of contact info from the customer.
The default header isn't very versatile when the free trial option is enabled. So the below code customizes the header based on whether you hit the page paying OR if you are using a free trial option.
The below code replaces line 66 entirely in /srv/unifi/data/sites/default/app-unifi-hotspot-portal/views/payment.html with several lines that make for a more "friendly" appearance.
<h4 class="unifiPortalBox__header"><span ng-if="paymentCtrl.isFreePackage()">Enter your Email Address For Complimentary Internet</span><span ng-if="paymentCtrl.isPayablePackage()">{{'PAYMENT_HEADER_BILLING_ADDRESS' | translate}}</span></h4>
<div ng-if="paymentCtrl.isFreePackage()" class="unifiPortalFormGroup row">
<div class="col--xs12 noPaddingRight">
<label class="unifiPortalLabel--primary unifiPortalLabel--boxAlign unifiPortalLabel--responsive ng-scope">{{'PAYMENT_FREE_WIFI_MESSAGE' | translate}}</br></br>{{'PAYMENT_FREE_WIFI_ACCEPT' | translate}}</span></label>
</div>
</div>The final part of this effort is to modify the english locale portal.json file, the below 4 lines replace lines 15 and 16 in /srv/unifi/data/sites/default/app-unifi-hotspot-portal/locales/en/portal.json.
"PAYMENT_HEADER_CC_INFO": "Please enter your Credit Card Info",
"PAYMENT_HEADER_BILLING_ADDRESS": "Credit Card Billing Address",
"PAYMENT_FREE_WIFI_MESSAGE": "We ask that you provide a valid email address so that we can keep track of who is using our free wifi service. We respect your privacy and promise that we will never send you any unsolicited email, or share/sell your email address to any third parties.",
"PAYMENT_FREE_WIFI_ACCEPT": "By entering your email address you are simply agreeing to allow us to track that you have used our complimentary WiFi service.",The ng-if statements in the above example check a function to see if a specific selection was made at the previous screen. So paymentCtrl.isFreePackage() will be enabled if the customer has selected a free trial. In that situation, we want to set the header in the form to say "Free Trial" and we encapsulate it in a span so that if the ng-if check is not true, it will hide the contents of the span-including our header text. For presenting a different header when a customer is paying we check the function paymentCtrl.isPayablePackage() and if that is true, the form will present the header for that.. Keep in mind-there are many examples of the available functions in the built-in HTML templates. It is simply a matter of searching through them to find one that fits your needs. Also note, that functions in one html template may not exist in the others-it is best to go by what is in the template you're seeking to modify.
You can take this a step further and using the built-in localizations to provide your custom text and then have the form query that for the appropriate text. An example is {{'PAYMENT_HEADER_CC_INFO' | translate}} which queries /usr/lib/unifi/data/sites/default/app-unifi-hotspot-portal/locales/<lang>/ for the appropriate text which is stored for the language you have set.
The file /usr/lib/unifi/data/sites/default/app-unifi-hotspot-portal/locales/en/portal.json contains text substitutions if you've selected English as your language on the portal. An example of a customization is "PAYMENT_HEADER_CC_INFO": "Input Your Credit Card Info", which is the default header for line 66 of payment.html.
So instead of swapping in plain text in the above example, we could modify the /usr/lib/unifi/data/sites/default/app-unifi-hotspot-portal/locales/en/portal.json text for that variable instead and then add another for our free trial header. Then, if you're setting up a portal that will be used by people speaking different languages, you can modify the appropriate language (with the option of adding your own-but that is outside the scope of this document)to serve up your next text and variable as well.
The CSS included is all minified-so it is a bit of a pain to work with. It is located at /usr/lib/unifi/data/sites/default/app-unifi-hotspot-portal/css/app.css if you would like to take a look and modify to fit your needs.
Slightly off-topic, is it possible to modify the hotspot manager? I'm not a coder nor am I familiar with github. I have a strong background in html so I can understand the concepts. I see several people have created their own but I wanted to see how easy it was to modify what was already there. Thanks.