Product Support

Keyboard Support

Developer Support

Contact and Search

Keyman.com Homepage

Header bottom

Keyman.com
Other versions
Version 9.0

On this page

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:

Keep me updated