WiFi Portal Widget Application Guidelines

WiFi Portal Overview

The 1TO1.LINK generates dynamic WiFi Portals for end users in a local space. Spaces already curate physical experiences for customers, and the 1TO1.LINK is an extension of this into the digital realm.

We handle all the hard bits related to the local network and make it easy for 3rd parties to leverage the Instant Context of users and deliver enriched experiences engaging with mini apps in the WiFi Portal.

Next sections provide information that will help you to build a useful microservice that can be embedded as a widget application into the local space's WiFi portal.  

Widget Presentation Guidelines

WiFi Portal Widget

  • The WiFi Portal has a responsive design. Widgets should be developed to fit within the following layouts and observe the maximum dimensions.
  • Ordering of the widgets within the WiFi Portal is determined based on a combination of the user's role, the space owner discretion, and what users find hot.
  • Styling should be proposed that blends with the existing online branding of the local space and optimised for the widget's dimensions. If your application is successful, the local space will provide feedback and may supply additional branding guidelines.
  • Content formats and media types can be utilised within your microservice.  All content must conform to local copyright laws, distribution or redistribution laws, is age restricted (suitable for the audience that may be accessing it) and consideration should be given to suitability for the local space. 
  • Note: internet activity of WiFi network connections, including the WiFi Portal are subject to the local space's network security policies. This may result in content being blocked and is tested as part of the review of your submitted application.

Widget Technical Guidelines

In order for the WiFi Portal to operate optimally for end users and the space owner, the following guidelines should be observed:

Acceptable integration approaches

  • Building the whole DOM of your widget in JavaScript and placing it on the target page (more flexible)
  • Embed with iFrame (easier)

Namespace 

  • Widgets must use namespace separation so as to not cause variable and function conflicts. For example, don’t name your widget Class “AppWidget”, a best practice alternative is to call it “com.mycompany.AppWidget”. This also includes protecting your global variables to reduce “leakage” outside of your Classes.

Public Properties and Methods 

  • Only properties and methods that are internal should be kept private. All other properties need to be public.

Cross-platform compatibility 

  • Clearly document which platforms the widget was tested on. If you haven’t been testing your widgets cross-platform then you need to be. If you only designed your widget for a specific browser, that’s okay as long as it’s documented. At a minimum, truly cross-platform widgets will have been tested on the latest production versions of Firefox, Chrome, iPad/iPhone (Safari), Android (native) and IE.

Minimum performance

  • loading times: 3 seconds

Auto-resize 

  • Widgets must auto-resize to their container. The sheer popularity of smartphones and tablets is driving this requirement. For example, when a phone is turned on its side, a widget should automatically fill the new dimensions of the container. If your widget doesn’t auto-resize it will significant limit it’s marketability for mobile devices.

JavaScript rules

  • No overriding anything: Do not override built in object prototypes or functions. If you do, you risk breaking the target page’s functionality
  • No loading 3rd party scripts: Do not load libraries or other scripts unless you’re sure it will not create global variables that can conflict with the target page’s code, or you risk breaking the target page.
  • Handle your errors correctly: Be sure to be very careful and handle errors propery, as any error in your widget code can break the target page. Make sure you check for things you don’t normally check too, like errors with DOM functions which usually succeed.
  • When listening for events, always use addEvent and addEventListener: Never override any events (eg. el.onclick), as a handler may already exist for it and you risk breaking the target page

CSS style rules

  • You must always inline the styles you use: All styles of HTML elements you create must be inlined, because the customer’s website may have its own CSS styling for them.
  • Never trust the styles: The target page may have completely weird and wonky styles. If you’re at all unsure, inline even the most basic styles for your widget’s DOM nodes.
  • Never add any CSS rules: Adding any rules (eg. something that isn’t inlined in the style attribute) can easily break the target page
  • Any external URL links within the WiFi Portal widget that cannot be accommodated within the widget container must open a new browser window. 
  • URL links opening a new URL page within the same browser window are not permitted.
  • The local space may provide content based on an affiliate program. You have the opportunity to participate in the revenue sharing of the affiliate program. All you have to do is ensure that you utilise the links that are provided
  • If you are providing content with affiliate programs, you need to make sure that this is explained in your Application gallery page so that the user is aware. 

Data use transparency

  • Data privacy and protection is extremely important within the 1TO1.LINK, it's local spaces and audience end users. 
  • An attribution link is presented in the footer of the widget container pointing to your 1TO1.LINK application gallery page. On this page please explain the details of the API operations you are using and how you use the data. You must also provide a link to your website that includes a way that the end user can contact you regarding inquiries about how your microservice works or the data you store about them, in the case of any personally identifiable data.
  • Your Cookies: if you are using cookies, you should mention this to us in your application submission. The end user should also have a way to contact you to request additional information. 

API calls

  • There is a free tier for 1TO1.LINK APIs with a testing quota that is specified for each local space. 
  • A local space that operates the WiFi network may also choose to charge for API access to all or to only certain types of data. 
  • Therefore, a balance is needed between grabbing all the data to serve pages quickly or grabbing what is needed, when it is needed. The former will load pages quickly but has a higher technical cost, the latter may result in slower loading but is more efficient for data processing.

 

Useful references:

http://www.andygup.net/10-best-practices-for-developing-javascript-widgets/

https://codeutopia.net/blog/2012/05/26/best-practices-for-building-embeddable-widgets/