Note (11 Aug 2015): this page has obsolete content and has been replaced with the Developer documentation at


With the latest updates (1.2) to Keyman for Android and Keyman for iPhone and iPad, you can now install custom keyboards onto your favourite mobile devices.

This post will go through the steps required to make your custom keyboard available for distribution to Android or iOS devices.

Prerequisites for this tutorial are a keyboard .js file and font .ttf file (if your keyboard requires a custom font). You can learn how to build a keyboard with Keyman Developer here.

Step 1) Create the keyboard JSON file

The keyboard JSON file provides the meta data for a keyboard, such as what devices it is available on, the name and version of the keyboard, and what font to use with it. The keyboard.json format is based on the Keyman Engine for Web Cloud Services API:

      "options": {
      "keyboard": {
        "name":"Tamil Keyboard",
        "font": {

The above JSON file shows the format for an example Tamil99 keyboard. It is important to note that the keyboard id must match the keyboard id from the keyboard's .js file.

[Update 15 May 2014] What is the keyboard id in the keyboard's .js file?  This is built from the KI member variable in the .js file, and reflects a type-safe name based on the original filename of the keyboard source file.  A type-safe name contains only a-z, 0-9 and underscore.  The compiler will translate the original file name to lower case, and replace any invalid characters with underscores, in both the KI variable and the output .js filename.  Finally, the KI variable is prefixed with "Keyboard_".  This should not be included in the id.  For example, in the keyboard above, the KI variable is defined as follows:


And thus the id should be just "ekwtamil99uni". [End Update]

Here is the list of the objects inside of the JSON file and an explanation of each:

  • "options"
    • device: (The target device for your keyboard)
    • keyboardBaseUri: (The base URI for your keyboard file)
    • fontBaseUri: (If you are including a font file with your keyboard, this is the base URI for the font)
  • "keyboard"
    • id: (ID of the keyboard. It must always match the internal name of the keyboard in the keyboard .js file)
    • name: (Name of the keyboard)
    • filename: (Name of the keyboard .js file. Is appended to the keyboardBaseUri)
    • font:
      • family: (Font family that Keyman will provide for this font)
      • filename: (Array of downloadable filenames for this font. Is appended to the fontBaseUri)
    • version: (The version of the keyboard. If left off, will default to 1.0)
    • lastModified: (The date the keyboard file was last updated)
    • languages:
      • id: (3 letter ISO 639-3 code)
      • name: (Language name)

For a full explanation of the structure of the JSON file, please read the Keyman Engine for Web Cloud Services API documentation.

Step 2) Upload the keyboard files

Once the keyboard.json file is created, you will need to upload all resources to a public facing website. For this example, there are 3 files being uploaded:

  1. ekwtamil99uni.js (the keyboard .js file)
  2. aava1.ttf (the font file)
  3. tamil.json (the keyboard JSON file created in step 1)

Step 3) Create a link to the JSON file

Once all the files have been uploaded, you will need to provide a link to the keyboard.json file for your iOS or Android device to read. This can either be a link on a web page, or a link in an email. For this tutorial, I have created a very simple .html web page with a link to the tamil.json file:

        <a href="keyman://localhost/open?url=" >Custom Keyboard URL</a>

The link must be in the following format:


This tells Keyman on this device (localhost) to open (open) with the preferred language and keyboard. The keyboard will be installed if not already on the user's device.

The only required parameter is url, which specifies the source keyboard description JSON file for the keyboard.

The optional parameter direct tells Keyman to not use the Keyman Cloud to download the file.  Keyman will normally download the keyboard via Keyman Cloud, in order to permit caching, compression, and prevent overloading a target server. If you are hosting a keyboard file on an intranet or private website, you can specify direct=true to tell Keyman to download the keyboard directly.

Upload the web page to your public facing website. Once done, you can download the keyboard onto your mobile device by following these steps:

You can read the full documentation on keyboard distribution here.

2 thoughts on “Creating Custom Keyboards for Keyman for Android and Keyman for iPhone and iPad”

Ray · May 7, 2014 at 1:20 am

Thanks for the hard work on Keyman in general and this article as well. I have an existing keyboard and I followed the article to the point where I can install my custom keyboard fine (no install failed message, anymore), but it doesn’t display the font on the on-screen keyboard nor does pushing button does anything.

This leads me to think that my JS file is bad. The link above does not talk about the JS file but rather stopped with the KMN file. I first tried to use the code in the “code” tab under “Touch Layout” but that didn’t work.

Next I looked up the output for
and I grabbed one of the JS files in the browser and I saw the format is more like that generated by “Compile to Web”.

So my JS file now looks like:

KeymanWeb.KR(new Keyboard_shan());function Keyboard_shan(){this.KI=”Keyboard_shan”;this.KN=”Shan_tzerngkoang”;this.KV={F:’ 1em “Padauk”‘………

My JSON file is here:

Any suggestions on why it is not working would be appreciated!


Tano Fotang · May 14, 2014 at 4:29 pm

“id: (ID of the keyboard. It must always match the internal name of the keyboard in the keyboard .js file)”

What is the id if the js file starts as follows:
KeymanWeb.KR(new Keyboard_xx());function Keyboard_xx(){this.KI=”Keyboard_xx”;this.KN=”Mykeyb”;…

Is it “Keyboard_xx”, “Mykeyb” or “xx”?

Leave a Reply

Your email address will not be published. Required fields are marked *

Related Posts

Developing Keyboards

Introducing the Keyman Open Source Keyboard Repository

We have many hundreds of keyboard layouts online at that cover well over a thousand  languages. These keyboard layouts work on Windows, the web, iPhones, iPads and Android phones and tablets. However, most of Read more…


New video: type in Amharic in any app on your iPhone (or iPad)

This video shows you how you can use Keyman Pro to type in Amharic in any app on your iPhone or iPad. If you have any questions or suggestions, send us an email, or ask Read more…


Using Keyman Engine for Android to create a system keyboard

In part 1 of this series, we looked at the steps involved in creating a basic Android app which included a Keyman in-app keyboard. In this post, we’ll work with the second sample included in Read more…