Docs

Overview

Interface

Each Pokki app has four interface elements that users may interact with;

  1. Icon – an icon located in the Pokki area of the user's taskbar. Clicking on this icon opens and closes your app.
  2. App window – a window which is displayed when the user clicks on your app’s icon. This is the primary interaction point for your application. You define both the size and the content of this window.
  3. Badge – a small badge displayed over the top-right corner of your app’s icon. Inside the badge is a number which you may set and clear through a JavaScript API.
  4. Context menu – displayed when a user right-clicks on your app’s icon. Using our JavaScript API you can dynamically add context items and listen for a callback.

The figure below shows the interface elements.

pokki interface

Architecture

Basics

Each Pokki app is a collection of files stored in a single directory:

  • Manifest file (manifest.json) that contains metadata about your app
  • HTML window page file
  • (Optional) HTML background page file
  • Any files included by the HTML pages (e.g. images, JavaScript, CSS, etc.)
  • 19x19, 29x29, 42x42, 256x256 versions of the app's icon in PNG format
  • Any directory structures used to hold the files

The core components of an app are the two web pages:

  1. Window page – an HTML file used to define the app window contents and handle user interaction.
  2. Background page – an optional HTML file which is always running without an interface, used to determine when an app's badge should be updated.

Each page is loaded by Pokki and can use most of the APIs available in modern web browsers, such as JavaScript APIs, HTML5 and emerging APIs, and WebKit APIs. In addition, Pokki exposes a set of JavaScript APIs through the Pokki namespace object, enabling you to do things such as set a badge on your app's icon, or respond to a user clicking on your app's icon in the taskbar. Both the window page and background page can access the Pokki API.

While each page runs independently and does not share DOM or JavaScript contexts, they may communicate with each other using a remote procedure call (RPC) method in the Pokki API or share data using their unified local storage. This allows for a reduction in duplicate data transfer and processing between pages.

The figure below illustrates a Pokki app’s architecture and interactions.

pokki architecture

Sanboxed

All Pokki apps run in a sandboxed architecture – very similar to the one employed by Google Chrome and Chromium:

  1. http://www.chromium.org/developers/design-documents/sandbox

The sandbox is built on the notion of very limited privilege processes. It leverages the OS-provided security to allow code execution that cannot make persistent changes to the computer or access information that is confidential. The architecture and exact assurances that the sandbox provides are dependent on the operating system for which Pokki supports.

Pokki apps are sandboxed from each other, from the parent Pokki engine, and from Windows. This means a Pokki app:

  • Can't access files or data on the user's computer
  • Can't access another app's local storage
  • Is isolated, so if it crashes it does not affect Pokki or Windows

Packaging and Delivery System

We have built a centralized and secure delivery system for Pokki apps. Whenever you publish your app it is reviewed by the Pokki team before it can be distributed. Upon approval your app is packaged and signed on the server, scrambling any sensitive data you defined in your manifest (such as an API key), and can now be distributed and installed by a user.

Our system ensures the apps installed on a user’s computer have been approved by the Pokki team.

  • All apps (whether a new app or an update) are reviewed by the Pokki team before they can be installed by a user
  • When a user initiates the install of a Pokki app, Pokki communicates with the Pokki server using HTTPS and SHA-1 hashing to ensure:
    • Which app to install
    • The location of the app package to download
    • Post download verification of the package
    • Verification of the app once it's unpacked and ready to be installed

You can think of this as a signing and verification system.

In addition, Pokki does an integrity check at startup and every subsequent 24 hours. If Pokki itself or an app is found to have been tampered with since installation, it is disabled and the user is prompted to repair Pokki. The repair process securely downloads and installs the latest version of the affected components.

Auto-Update

Pokki automatically checks for updates of the engine and its installed apps at startup and every subsequent 24 hours. If a new version of either is found, it is silently downloaded and updated seamlessly the next time Pokki starts. This means users of your app are automatically upgraded to the latest published version.

Users are notified of the update after it has occurred. In the case of an app being updated, the user is presented with a Pokki notification dialog telling them which app was updated. If the user clicks on this dialog they are taken to the Pokki website and presented with the change log for this app.

Technology

Pokki is built on the following technologies:

  • Chromium for app sandboxing
  • WebKit for layout and rendering
  • V8 for JavaScript engine

We believe these open source technologies are at the forefront of web technologies and emerging standards. We strive to keep up to date with these technologies as they advance ensuring the latest features and functionality are available to Pokki developers while maintaining stability and security.

You may wish to detect what versions of Chromium and WebKit Pokki includes. You can do this by querying the current user agent just as you would a browser. For example:

var ua = window.navigator.userAgent;

Standard JavaScript APIs

These are the same core JavaScript and Document Object Model (DOM) APIs that you can use in ordinary web apps.

HTML5 and other emerging APIs

  • Audio element (codecs: Vorbis, WebM)
  • Video element (codecs: Theora, WebM)
  • Canvas
  • WebGL
  • Full-screen
  • Web Storage
  • Web SQL Database
  • Web Workers
  • Web Sockets

WebKit

WebKit provides CSS extensions, including animation, transitions and both 2D and 3D transforms. Leveraging these features in your app’s user interface is the best way to achieve fantastic cross operating system and device performance.

Pokki JavaScript API and Events

Pokki provides a set of JavaScript APIs that the window and background pages can utilize. The methods are accessed through the global pokki namespace in JavaScript. In addition to providing an API, Pokki also fires events that the window and background pages can listen for. These events include things the user opening and closing the window, selecting an item from the context menu, etc.

Please see the API Reference for a detailed description of each method and event.

Web App Compatibility

While a Pokki app is very similar to a traditional web app, there are some differences. Most notably, it’s not running in a traditional browser. We have done a lot to make this utterly seamless for your existing web app but it’s important to understand these differences.

Not Really a Browser

A Pokki app is not really a browser, and as such links should open in a user’s actual browser. The Pokki JavaScript object provides a method for opening a URL in a user’s default browser. This is obviously something web apps do not account for, and as such Pokki catches window.location changes and window.open calls and fires an event that you can listen for in your app. Read more about Opening the web browser.

Cross-origin XHR Works

You can make XHR requests to any domain using the standard XMLHttpRequest object (or any library that implements it). This includes XHR calls from within web workers

Web Sheets for Secure Login

To provide a secure login method for users, the Pokki API exposes Web sheets. Web sheets are embedded browsers that are solely intended to facilitate secure login. This is the preferred login method for all cases where it is possible.

Implications from the file protocol

Because a Pokki app is running locally (not on a domain), the window and background pages cannot read or write cookies, and as such we recommend using local storage for client storage. That said if you load an iframe or web sheet, cookies work as expected and are in-fact shared across all external resources loaded by your app.

Another gotcha related to the file protocol are JavaScript libraries that load resources using the shorthand protocol like “//somedomain.com/asset.js”. This negates a developer form having to determine if a page is running on http or https, however when run from the file protocol these references do not work as they are turned into “file:///somedomain.com/asset.js”.

Disabled APIs

To provide a cohesive user experience, there are several traditional web user-interface APIS that are disabled:

  • window.alert()
  • window.confirm()
  • window.prompt()