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 7, 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")

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 275px 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.

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.

Clone this wiki locally