Distributing Custom Keyboards for Keyman Mobile Apps

Overview

Welcome! In this tutorial you will learn how to distribute a custom keyboard (built with Keyman Developer) to the suite of Keyman mobile applications -- Keyman for Android and Keyman for iPhone and iPad.

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",
      "source":"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 keyboards .js file.

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

JSON format

Schema for JSON file: keyboard_json.json

options key

An object with the following members:

device key

The target device for your keyboard, one of: "windows", "macosx", "iphone", "ipad", "androidphone", "androidtablet", "mobile", "desktop", "tablet", "any". Optional.

keyboardBaseUri key

The base URI for your keyboard file. Required.

fontBaseUri key

If you are including a font file with your keyboard, this is the base URI for the font. Optional.

keyboard key

An object with the following members:

id key

ID of the keyboard. It must always match the internal name of the keyboard in the keyboard .js file. Required.

name key

Name of the keyboard. Optional but recommended.

filename key

Name of the keyboard .js file. Is appended to the keyboardBaseUri.

rtl key

Set to true if your keyboard is a right-to-left keyboard. Optional.

font key

An object with the following members. Optional.

family key

Font family that Keyman will provide for this font.

source key

String or Array of Strings of downloadable filenames for this font. Each string is appended to the fontBaseUri.

size key

CSS size of the font, defaults to 1em. Optional.

oskFont key

An object with the following members, used for the On Screen Keyboard. If not provided, uses font. Optional.

family key

Font family that Keyman will provide for this font

source key

String or Array of Strings of downloadable filenames for this font. Each string is appended to the fontBaseUri.

size key

CSS size of the font, defaults to 1em. Optional.

version key

The version of the keyboard. Required (note: previous version of spec said Optional, but in practice has always been required.)

lastModified key

The date the keyboard file was last updated, in ISO format, YYYY-MM-DDTHH:mm:ss.nnn+ZZ:ZZ)

languages key

An array of objects with the following members:

id key

3 letter ISO 639-3 code

name key

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.

Note: the keyman:// protocol is deprecated in mobile apps for Keyman 10.0 and will be removed in Keyman 11.0

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.

Note: the direct parameter is deprecated in mobile apps for Keyman 10.0 and will be removed in Keyman 11.0

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 to your iPhone or iPad
• Installing custom keyboards to your Android device