Skip to content
This repository has been archived by the owner on Jan 3, 2019. It is now read-only.

How to build a Hive app

Jump to bottom
Jakub Suder edited this page Dec 14, 2013 · 32 revisions

Hive apps are made with HTML, CSS and JavaScript. They're basically just websites with JavaScript code, running in an embedded browser inside the Hive window. You can use most features you'd expect from a standard modern web browser.

If you need to check Hive version for some reason, the user agent string will include "Hive/hive_version_number" at the end, e.g. "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_8_5) AppleWebKit/536.30.1 (KHTML, like Gecko) Hive/0.9".

App structure

A Hive app needs to have:

  • a manifest.json file at the root of the project tree
  • an index.html file, in the same place
  • an icon file

It can also contain additional helper files like scripts, stylesheets and images, which you can place anywhere inside the app directory. You can also use JavaScript, <script> or <link> tags to load any remote resources, but it's recommended that you keep as much of the app as possible inside the bundle for faster loading (e.g. bundle a jquery.js inside the app instead of loading it from a CDN).

Manifest file

The manifest file includes various metadata about the application. It should contain a single JSON hash that looks like this:

{
  "id": "com.grabhive.awesomeapp",
  "version": "1.0",
  "name": "My Awesome App",
  "author": "Me",
  "contact": "me@google.com",
  "description": "Just run it and see",
  "icon": "icon.png"
}

List of fields that can be included in the JSON:

  • id: string (required) - a string that uniquely identifies the app; there can't be two apps with the same ID, so domain-style IDs like "com.company.product" are recommended
  • version: string (required) - current version of the app - in future we'll have some kind of auto-update feature in Hive that will check app repositories and download new versions if the current version is lower than the one in the repo
  • name: string (required) - this will be shown on the "Apps" screen below the icon, make sure it isn't too long
  • author: string (required) - your name
  • contact: string (required) - your email address
  • description: string (required) - currently unused, but we're planning to use it later; make it 1-2 sentences long
  • icon: string (required) - name of the file storing the icon to be shown on the "Apps" screen
  • homepage: string (optional) - currently unused, but if you set it we might use it later
  • charity: boolean (optional) - currently unused, but if you're creating an app that lets people donate Bitcoin to a charity, set this to true; this will tell us that we shouldn't deduct transaction fees from transactions made from this app in the future
  • tor: string (optional) - currently unused, but we plan to use this value in the future to determine if this app should use Tor connections; set this to "allow", "require" or "disable" (default is "allow")
  • accessedHosts: array[string] (optional) - lists all hostnames that the app wants to access using bitcoin.makeRequest

Index page

The index.html file is the entry point to your app. It should render the app's main view, load necessary scripts and stylesheets, and so on. Remember that the Hive window has proportions and dimensions similar to a mobile phone screen, so you should design this page like a mobile website. Don't assume any specific dimensions - be prepared for page width between approximately 300px and 500px and height from 400px to 800px or more.

The page is loaded at an HTTP URL - Hive uses internal virtual URLs, which are used to load files that are actually stored inside the app's bundle. Currently the addresses are of the form http://your_app_name.hiveapp/, but you should not rely on this as this might change in the future. If possible, you should rather extract the base hostname and URL from window.location.

JavaScript API

To access user's data and prompt the user to send Bitcoin to a given address, we should use our JavaScript API - check out our API specification.

Data storage

You might want to store various user data, configuration, application state etc. in a persistent storage in order to preserver user's context when they navigate away from the app. You can use standard browser cookies for that purpose - just remember to set a persistent cookie if necessary, i.e. with an expiration date, like this:

document.cookie = 'selectedTab=1; expires=' + date.toGMTString();

If you don't set an expiration date, a session cookie will be set, so it will disappear after Hive is restarted.

Another method of persisting data could be localStorage; unfortunately, at the moment it isn't persisted between sessions and is lost after a restart, so you should not rely on it.

External links

If you want a link to open a page in an external browser, just set a target="_blank" attribute on the link element, link you would normally do to make a link open in a new window.

Bundling the app

To load the app into Hive, user needs to download your app files bundled inside a zip archive with the extension changed to .hiveapp, and then double-click the bundle in Finder and confirm the action in Hive. When you're ready to release a new version of the app, pack the application inside an archive, rename it and upload it somewhere, e.g. to the "Releases" page in your GitHub repository. We're planning to have a central repository linking all apps to a single place (watch this ticket), but for now users will have to download and install it manually.

Development tips

Some things that might be useful during app development:

JS console / inspector

Current builds have a WebKitDeveloperExtras option set to true in the preferences (this is set in HIAppDelegate). This means that you can right click inside any app, choose "Inspect" and you get access to the standard WebKit developer console, where you can play with the API, check error messages etc. If the default setting is changed in the future, you can always override it with:

defaults write com.grabhive.Hive WebKitDeveloperExtras TRUE

Working on unpacked app files

It would be pretty inconvenient to rebuild the .hiveapp archive after every change - fortunately, you don't have to do that. If an app bundle in Hive's Applications folder (~/Library/Application Support/Hive/Applications) is replaced with a directory with extracted contents, the app will work exactly the same as if it was compressed. That way you can edit the app files, reload them inside Hive and see the new code in action immediately.

You can even add new apps to Hive's Applications list by copying an app directory to the Applications directory mentioned above and using the "Rebuild application list" tool (in top menu: Tools > Debugging Tools…) to rescan the directory.

Another option is to have the application files in a separate directory outside Hive's folder (e.g. in your "Projects" directory) and make a symlink to that directory from Hive/Applications (e.g. ln -s ~/Projects/hiveapp-coinbase coinbase) - that way you can work on the app in your own directory, and you won't have to worry that Hive might delete your code for some reason.

Note: in any case, the name of the bundle file / directory / symlink needs to be the same as the id field in the manifest.

Clone this wiki locally