Creating Custom Keyboards for Keyman for Android and Keyman for iPhone and iPad

Note (11 Aug 2015): this page has obsolete content and has been replaced with the Developer documentation at http://help.keyman.com/developer/9.0/guides/distribute/mobile-apps

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": {
        "device":"any",
        "keyboardBaseUri":"http://keyman.com/test/",
        "fontBaseUri":"http://keyman.com/test/"
      },
      "keyboard": {
        "id":"ekwtamil99uni",
        "name":"Tamil Keyboard",
        "filename":"ekwtamil99uni.js",
        "font": {
          "family":"Latha",
          "filename":"aava1.ttf"
        },
        "version":"1.1",
        "lastModified":"2014-04-17T14:07:00+11:00",
        "languages":[
          {
            "id":"tam",
            "name":"Tamil"
          }
        ]
      }
    }
  

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:

this.KI="Keyboard_ekwtamil99uni";

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:

    <html>
      <head>
      </head>
      <body>
        <a href="keyman://localhost/open?url=http://keyman.com/test/tamil.json" >Custom Keyboard URL</a>
      </body>
    </html>
  

The link must be in the following format:

keyman://localhost/open?url=url

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:

• Installing custom keyboards on your iOS device
• Installing custom keyboards on your Android device

You can read the full documentation on keyboard distribution here.