Adding an app to the Bangle.js App Loader

If you have an app (eg by following the Bangle.js First App tutorial), you might want to add it to the Bangle.js App Loader so you or others can easily install it.

Note: To keep things simple for everyone, the BangleApps Git repository and all code in it are MIT Licensed. By contributing an app you're agreeing that the code in it will be MIT Licensed too, and you need to be sure you don't include any copyrighted code data or images that you don't have the right to distribute freely.

Forking

The first step is to 'Fork' the existing Bangle.js App Loader (make your own copy).

Enable GitHub Pages

Now, let's enable "GitHub Pages", which allows you to view and use your own copy of the repository.

Your site is ready to be published at https://your_user_name.github.io/BangleApps/.

Note: You can host the App Loader yourself, but it must be on an HTTPS server (not HTTP) for Web Bluetooth to work.

Adding your app

If you followed the Bangle.js First App tutorial you should now have an app with an ID of timer, so let's use that. We should create a new folder of the same name as your app's ID in the apps folder.

An example of what the folder might look like is in: https://github.com/espruino/BangleApps/tree/master/apps/_example_app

Experienced Git developers will know about cloning a repository to their local computer, but I'll assume you don't know/want to do that, so we'll do everything online.

E.showMessage("My\nSimple\nApp","My App")

Now we need to upload the icon in a form that Bangle.js understands

At this point you could add a ChangeLog file so others can see what changed if you release multiple versions of your app, but we're going to skip that for now.

Finally, it's time to add a description of your app. There's an example at https://github.com/espruino/BangleApps/blob/master/apps/_example_app/metadata.json

{ "id": "timer",
  "name": "My Timer App",
  "shortName":"My Timer",
  "icon": "app.png",
  "version":"0.01",
  "description": "This is a description of my awesome timer app",
  "tags": "",
  "storage": [
    {"name":"timer.app.js","url":"app.js"},
    {"name":"timer.img","url":"app-icon.js","evaluate":true}
  ]
}

There is more information about the format of this file on https://github.com/espruino/BangleApps/blob/master/README.md

Note: If you were working with a local copy of the GitHub repository you could run the bin/sanitycheck.js file which would give your app's description a quick check over to make sure everything looked ok (icons, code, etc).

Using your new App

Note: If the App Loader doesn't work, it's almost certainly because of an error in the metadata.json file that was changed earlier.

Documenting your App

While there's short field for a description, many apps may need slightly more documentation about how to use them.

To add this documentation in a way that can be found easily from the app loader, create a file called README.md (a markdown file) in your app's folder.

Then, in your app's metadata.json file, add:

  "readme":"README.md",

Now, when anyone sees your app in the App Loader, there'll be a link saying Read more.... When clicked, it'll bring up a window showing your documentation.

Making Changes

If you want to change your app you can simply edit the files in your repository. However if you are publicly submitting your app we'd suggest that you add a ChangeLog file so users can see what has changed.

0.01: New App!
0.02: Fixed thingybob
0.03: Added fancy text

After this, if a user clicks on the version number in the App Loader they'll be able to see the ChangeLog file

Submitting your App to the main App Loader website

Now you have a working app it's easy to submit it.

_While we will try to accept any apps you send us, we won't be able to accept any obviously broken or non-child-friendly apps. However your apps will still be available on https://your_user_name.github.io/BangleApps/ for anyone that wants to upload them_

You'll see the pull request as well as yellow test saying Some checks haven’t completed yet.

We run the bin/sanitycheck.js script on any submissions using Travis CI. This allows us to do a quick check that everything is ok. It won't detect bugs in your app but it will ensure that the App Loader stays working.

After a while it'll change to either a green All checks have passed or a red Checks failed. If checks fail then we're unlikely to be able to merge as-is, but you can click Show all Checks, Details and see what errors were found. If you correct these in your repository then the check status will update.

More Info

There are a more Bangle.js tutorials on making apps.

For a reference of the format of apps and the JSON, check out the Bangle.js App Loader's README file

This page is auto-generated from GitHub. If you see any mistakes or have suggestions, please let us know.