Integrating Web Apps

The example portal is able to determine if any secondary web apps have been added to the boot image, and if they have been, add them to the main menu and be able to handle application switching. Please note that this is just ONE way of implementing multi-app switching and web app integration, and you are free to alter some of the mechanisms discussed here. Because of this flexibility, it is important to have read and understood the multi-app documentation and especially the web app integration page before diving into the code shown here.

Overall goal

It would be nice to write the example portal in such a way that we don't hard-code any details of secondary applications into the actual portal code. A more data-driven approach is to instead represent each web app with an IIP which installs everything necessary to display, launch and manage the web app. We can then very simply add and remove secondary apps from the boot image configuration file just by adding and removing the IIP.

An example IIP is provided in the SDK in <sdk_root>/products/kreatv-app-webgldemo_<KreaTV version>.iip. You can untar this IIP and examine the contents if you like. Add kreatv-app-webgldemo to your boot image config to include the IIP.

We will now take a closer look at some of the custom features that have been added to the secondary IIP to help it integrate with the portal.

Web App Icon

The portal will need to have an icon representing the web app, which will be added to the main menu. A simple 128x128 png file is used by the example portal, you can use whatever suits your menu system. The full contents of the example web app IIP is:

.
├── data
│   └── usr
│       ├── applications
│       │   └── webgldemo
│       │       └── properties_webgldemo.xml
│       └── local
│           └── portal
│               └── icons
│                   └── f1.png
├── iip_version
├── info.xml
└── install
    └── buildtime

Any files under the data directory will be added to the boot image's root disk (the Linux file system when the STB is in operation). The /usr/local/portal path is special, as it is automatically whitelisted, and any files you want to load into the browser need to be placed in there. The file can then be accessed by file:///usr/local/portal/icons/f1.png.

Life Cycle Management

Some web apps (such as the WebGLDemo provided) require large amounts of graphics resources and CPU power to run. It is not advisable to leave these running in the background all of the time. When switching to the app it can be started, and stopped again when the end-user leaves the app. This takes longer (especially the start) since the data for the application needs to be downloaded, but it does free up a lot of system resources for portal activity (such as an EPG).

Since the desired behaviour may be different from web app to web app (lightweight apps could be left running) we need a mechanism in the IIP which communicates this to the portal. The example portal creates a few custom properties in the properties_webgldemo.xml file, which the portal can access:

  <Property name="iconUrl">file:///usr/local/portal/icons/f1.png</Property>
  <Property name="stopOnHide">false</Property>
  <Property name="autoStart">true</Property>
  <Property name="exitKey">BrowserBack</Property>
  <Property name="menuKey">Menu</Property>

These properties are custom, in that they can be named arbitrarily and you are free to use them how you like within the portal code. The current secondary generic browser app is TECHNICAL PREVIEW, but when it is finalized it is likely that some (or all) of these lifecycle-related properties will be officially defined (and possibly automatically implemented) and shown on the application property file page.

The URL to the icon is specified with the custom iconUrl property. The stopOnHide boolean indicates that the application should be stopped when the user switches away from it (to the portal or another app, this requires restarting the application again at some point). Finally, the autoStart boolean is used to tell the portal to start this application immediately, during the portal start-up. If this is set, the portal starts the application and keeps it in STATE_HIDDEN, ready to immediately show it. This provides the fastest switching time, at the expense of memory.

The multi-app support page shows how the portal code can read the properties defined in an applications properties XML file.

Key handling

Portal handling Back and Menu

Two more custom properties are used to inform the portal about key presses while the secondary is visible. The exitKey tells the portal to subscribe to this keyIdentifier, and when it occurs, exit the secondary (stopping or hiding according to stopOnHide). The menuKey indicates which keyIdentifier is used to bring up the portal main menu over the secondary. Some web apps may work better if the MENU key is only consumed by the web app, bringing up some menu within it, which is why the behaviour here is specified for individual applications.

When the portal starts, and reads the application properties, it subscribes to these keyIdentifiers. When they occur, both the web app and the portal receive them.

Custom remote control key mapping

A custom keymapping feature is also provided, which allows you to override the DOM event generated from a remote control button, per-application. This is useful for example if you have a web app which was designed with keyboard navigation in mind, and you want to map those keyboard keys to remote control buttons in a more sensible way. The IIP includes a keymap XML file and refers to it with the KeyBindingMap property.

GfxMemory allocation

The Hello Racer example used in the WebGLDemo app requires a lot of graphics memory to be allocated. So adjust the memory_size argument to kreatv-option-graphics in the example.config if you run into display problems (you will see a lot of Cannot Create Surface type errors in the log). A value of 131072 works fine for this demo. You can use the Profiler Service to determine peak amounts of graphics memory usage to fine-tune your setup.