-
Notifications
You must be signed in to change notification settings - Fork 55
How to build a Hive app
Hive apps are static HTML, CSS and JavaScript running in an embedded browser inside the Hive window. You can use most features you'd expect from a standard modern web browser.
We recommend using the Hive Toolbelt for getting started quickly with everything you need to build Hive apps.
A Hive app needs to have:
- a
manifest.jsonfile at the root of the project tree - an
index.htmlfile, in the same place - an icon file
Additional assets like like scripts, stylesheets and images can be place anywhere inside the app directory. Remote resources may be loaded via xhr, <script> or <link> but for responsive user experience we recommend keeping all assets inside the bundle (e.g. bundle jquery.js with the app rather than loading it from a CDN).
Every Hive app is described by a manifest.json file, which may look like the following:
{
"id": "com.grabhive.awesomeapp",
"version": "1.0",
"name": "My Awesome App",
"author": "Me",
"contact": "[email protected]",
"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. Note that the id must be a valid hostname - it may contain only the ASCII letters 'a' through 'z' (in a case-insensitive manner), the digits '0' through '9', the hyphen ('-') and dots('.'). See http://en.wikipedia.org/wiki/Hostname#Restrictions_on_valid_host_names for more details.
- 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) - a very short description of what the app does - will be displayed on the list in the App Store app
- icon: string (required) - name of the file storing the icon to be shown on the "Apps" screen
-
category: string (required) - a single category selected from the list below (this will be used to group apps in the App Store, uncategorized apps will be put in the "Other" group):
-
Exchanges(apps interacting with exchanges like Bitstamp, Localbitcoins) -
Wallets(apps that allow users to use external wallets like Coinbase, Blockchain.info) -
Shopping(merchant integrations, stores accepting bitcoins) -
Fun(games, gambling) -
Donations(see also thecharityfield if you use this category) -
Utilities(e.g. statistics, charging mobile accounts with Bitcoin, and other tools that don't fit in any of the previous categories) -
Other(everything else)
-
- 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. Available values are
"allow","require"or"disable"(default is"allow") -
accessedHosts: array[string] (optional) - lists all hostnames that the app wants to access using
bitcoin.makeRequest - apiVersionMajor: int (required) - major API version required by the app (currently always 0, see below)
- apiVersionMinor: int (required) - minor API version required by the app (see below)
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.
To access user's data and prompt the user to send Bitcoin to a given address, use our JavaScript API.
Minor API versions will only add functionality. Normally only major API versions should ever cause incompatibilities. Therefore, Hive will launch apps if it can provide the exact major API version, and at least the minor API version.
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.
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.
To release a new version of the app
- pack the application into a zip archive
- rename it to
.hiveapp - upload it somewhere, e.g. to the "Releases" page in your GitHub repository
To load the app into Hive, user needs to
- download your bundled app files (with extension
.hiveapp) - double-click the bundle in Finder and confirm the action in Hive.
We have a central app registry where you can registry your app. With the next release of our app store, users will be able to browse and download apps listed in the registry (watch this ticket). For now users have to download and install it manually.
It is possible to try out your app using nothing but a browser, if you include the mock api in your app. When it comes to properly testing your app inside the actual Hive app, development is currently easier with Hive OSX, as it offers more debugging possibilities. But it's also possible to load your app for testing into Hive Android. See below for some tips regarding the different platforms.
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
It would be pretty inconvenient to rebuild the .hiveapp archive after every change - fortunately, you don't have to do that. App bundles are installed in Hive's Applications folder - ~/Library/Application Support/Hive/Applications for the main network, ~/Library/Application Support/HiveTest/Applications for testnet. If an app bundle 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 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.
Important: The name of the bundle file / directory / symlink needs to be the same as the id field in the manifest.
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".
The app store contains a hidden debug mode which allows you to switch from the default registry of Hive apps to a local registry for the purpose of installing a test version of your app. To reveal this mode, open the app store and click on the Hive logo in the upper left corner three times. Make sure you pause between clicks, to allow the website to register them. After the third click a text box titled "Alternative app registry" should reveal itself.
You can use the Hive Toolbelt to run a local registry which serves the app you are developing. After starting a registry and assuming a local IP of 192.168.0.1, you can browse to http://192.168.0.1:8888/index.json to check, that your app is listed properly. Then provide http://192.168.0.1:8888/ as a registry to the app store (make sure the trailing slash is included), to be able to download the app and run it inside Hive Android.