Keyboard Module

Version Keyboard 1.0.0

Table of Contents

Usage

To use the Keyboard module, you can import it into your project from the Firebolt SDK:

import { Keyboard } from '@firebolt-js/manage-sdk'

Overview

Methods for prompting users to enter text with task-oriented UX

Methods

emailError

This is an private RPC method.

Internal API for Email Provider to send back error.

Parameters:

Param Type Required Description
error ProviderResponse true  

Result:

null

Capabilities:

Role Capability
provides xrn:firebolt:capability:input:keyboard

Examples

Example 1

JSON-RPC:

Request:

{
	"jsonrpc": "2.0",
	"id": 1,
	"method": "Keyboard.emailError",
	"params": {
		"error": {
			"correlationId": "123",
			"result": {
				"code": 1,
				"message": "Error"
			}
		}
	}
}

Response:

{
	"jsonrpc": "2.0",
	"id": 1,
	"result": null
}

emailFocus

This is an private RPC method.

Internal API for Email Provider to request focus for UX purposes.

Result:

null

Capabilities:

Role Capability
provides xrn:firebolt:capability:input:keyboard

Examples

Example

JSON-RPC:

Request:

{
	"jsonrpc": "2.0",
	"id": 1,
	"method": "Keyboard.emailFocus",
	"params": {}
}

Response:

{
	"jsonrpc": "2.0",
	"id": 1,
	"result": null
}

emailResponse

This is an private RPC method.

Internal API for Email Provider to send back response.

Parameters:

Param Type Required Description
response ProviderResponse true  

Result:

null

Capabilities:

Role Capability
provides xrn:firebolt:capability:input:keyboard

Examples

Example

JSON-RPC:

Request:

{
	"jsonrpc": "2.0",
	"id": 1,
	"method": "Keyboard.emailResponse",
	"params": {
		"response": {
			"correlationId": "123",
			"result": {
				"text": "email@address.com"
			}
		}
	}
}

Response:

{
	"jsonrpc": "2.0",
	"id": 1,
	"result": null
}

passwordError

This is an private RPC method.

Internal API for Password Provider to send back error.

Parameters:

Param Type Required Description
error ProviderResponse true  

Result:

null

Capabilities:

Role Capability
provides xrn:firebolt:capability:input:keyboard

Examples

Example 1

JSON-RPC:

Request:

{
	"jsonrpc": "2.0",
	"id": 1,
	"method": "Keyboard.passwordError",
	"params": {
		"error": {
			"correlationId": "123",
			"result": {
				"code": 1,
				"message": "Error"
			}
		}
	}
}

Response:

{
	"jsonrpc": "2.0",
	"id": 1,
	"result": null
}

passwordFocus

This is an private RPC method.

Internal API for Password Provider to request focus for UX purposes.

Result:

null

Capabilities:

Role Capability
provides xrn:firebolt:capability:input:keyboard

Examples

Example

JSON-RPC:

Request:

{
	"jsonrpc": "2.0",
	"id": 1,
	"method": "Keyboard.passwordFocus",
	"params": {}
}

Response:

{
	"jsonrpc": "2.0",
	"id": 1,
	"result": null
}

passwordResponse

This is an private RPC method.

Internal API for Password Provider to send back response.

Parameters:

Param Type Required Description
response ProviderResponse true  

Result:

null

Capabilities:

Role Capability
provides xrn:firebolt:capability:input:keyboard

Examples

Example

JSON-RPC:

Request:

{
	"jsonrpc": "2.0",
	"id": 1,
	"method": "Keyboard.passwordResponse",
	"params": {
		"response": {
			"correlationId": "123",
			"result": {
				"text": "password"
			}
		}
	}
}

Response:

{
	"jsonrpc": "2.0",
	"id": 1,
	"result": null
}

provide

To provide a specific capability to the platform. See Provider Interfaces for a list of interfaces available to provide in this module.

provide(capability: string, provider: any): void

Parameters:

Param Type Required Summary
capability string Yes The capability that is being provided.
provider any Yes An implementation of the required interface.

See Provider Interfaces for each capabilities interface definition.

standardError

This is an private RPC method.

Internal API for Standard Provider to send back error.

Parameters:

Param Type Required Description
error ProviderResponse true  

Result:

null

Capabilities:

Role Capability
provides xrn:firebolt:capability:input:keyboard

Examples

Example 1

JSON-RPC:

Request:

{
	"jsonrpc": "2.0",
	"id": 1,
	"method": "Keyboard.standardError",
	"params": {
		"error": {
			"correlationId": "123",
			"result": {
				"code": 1,
				"message": "Error"
			}
		}
	}
}

Response:

{
	"jsonrpc": "2.0",
	"id": 1,
	"result": null
}

standardFocus

This is an private RPC method.

Internal API for Standard Provider to request focus for UX purposes.

Result:

null

Capabilities:

Role Capability
provides xrn:firebolt:capability:input:keyboard

Examples

Example

JSON-RPC:

Request:

{
	"jsonrpc": "2.0",
	"id": 1,
	"method": "Keyboard.standardFocus",
	"params": {}
}

Response:

{
	"jsonrpc": "2.0",
	"id": 1,
	"result": null
}

standardResponse

This is an private RPC method.

Internal API for Standard Provider to send back response.

Parameters:

Param Type Required Description
response ProviderResponse true  

Result:

null

Capabilities:

Role Capability
provides xrn:firebolt:capability:input:keyboard

Examples

Example

JSON-RPC:

Request:

{
	"jsonrpc": "2.0",
	"id": 1,
	"method": "Keyboard.standardResponse",
	"params": {
		"response": {
			"correlationId": "123",
			"result": {
				"text": "username"
			}
		}
	}
}

Response:

{
	"jsonrpc": "2.0",
	"id": 1,
	"result": null
}

Events

onRequestEmail

This is an private RPC method.

Registers as a provider for when the user should be shown a keyboard optimized for email address entry.

Parameters:

Param Type Required Description
listen boolean true  

Result:

KeyboardProviderRequest

Capabilities:

Role Capability
provides xrn:firebolt:capability:input:keyboard

Examples

Default Example

JSON-RPC:

Request:

{
	"jsonrpc": "2.0",
	"id": 1,
	"method": "Keyboard.onRequestEmail",
	"params": {
		"listen": true
	}
}

Response:

{
	"jsonrpc": "2.0",
	"id": 1,
	"result": {
		"correlationId": "abc",
		"parameters": {
			"message": "Enter your user name."
		}
	}
}

onRequestPassword

This is an private RPC method.

Registers as a provider for when the user should be shown a password keyboard, with dots for each character entered.

Parameters:

Param Type Required Description
listen boolean true  

Result:

KeyboardProviderRequest

Capabilities:

Role Capability
provides xrn:firebolt:capability:input:keyboard

Examples

Default Example

JSON-RPC:

Request:

{
	"jsonrpc": "2.0",
	"id": 1,
	"method": "Keyboard.onRequestPassword",
	"params": {
		"listen": true
	}
}

Response:

{
	"jsonrpc": "2.0",
	"id": 1,
	"result": {
		"correlationId": "abc",
		"parameters": {
			"message": "Enter your user name."
		}
	}
}

onRequestStandard

This is an private RPC method.

Registers as a provider for when the user should be shown a standard keyboard.

Parameters:

Param Type Required Description
listen boolean true  

Result:

KeyboardProviderRequest

Capabilities:

Role Capability
provides xrn:firebolt:capability:input:keyboard

Examples

Default Example

JSON-RPC:

Request:

{
	"jsonrpc": "2.0",
	"id": 1,
	"method": "Keyboard.onRequestStandard",
	"params": {
		"listen": true
	}
}

Response:

{
	"jsonrpc": "2.0",
	"id": 1,
	"result": {
		"correlationId": "abc",
		"parameters": {
			"message": "Enter your user name."
		}
	}
}

Provider Interfaces

KeyboardInputProvider

The provider interface for the xrn:firebolt:capability:input:keyboard capability.

Usage:

Keyboard.provide('xrn:firebolt:capability:input:keyboard', provider: KeyboardInputProvider | object)

standard

Registers as a provider for when the user should be shown a standard keyboard.

function standard(parameters?: KeyboardParameters, session?: FocusableProviderSession): Promise<KeyboardResult>

Provider methods always have two arguments:

Param Type Required Summary
parameters KeyboardParameters false  
session FocusableProviderSession false  
Parameters Property Type Required Summary
message string true The message to display to the user so the user knows what they are entering 
type KeyboardParameters = {
  message: string            // The message to display to the user so the user knows what they are entering
}

Promise resolution:

Property Type Description
text string The text the user entered into the keyboard
canceled boolean Whether the user canceled entering text before they were finished typing on the keyboard

password

Registers as a provider for when the user should be shown a password keyboard, with dots for each character entered.

function password(parameters?: KeyboardParameters, session?: FocusableProviderSession): Promise<KeyboardResult>

Provider methods always have two arguments:

Param Type Required Summary
parameters KeyboardParameters false  
session FocusableProviderSession false  
Parameters Property Type Required Summary
message string true The message to display to the user so the user knows what they are entering 
type KeyboardParameters = {
  message: string            // The message to display to the user so the user knows what they are entering
}

Promise resolution:

Property Type Description
text string The text the user entered into the keyboard
canceled boolean Whether the user canceled entering text before they were finished typing on the keyboard

email

Registers as a provider for when the user should be shown a keyboard optimized for email address entry.

function email(parameters?: KeyboardParameters, session?: FocusableProviderSession): Promise<KeyboardResult>

Provider methods always have two arguments:

Param Type Required Summary
parameters KeyboardParameters false  
session FocusableProviderSession false  
Parameters Property Type Required Summary
message string true The message to display to the user so the user knows what they are entering 
type KeyboardParameters = {
  message: string            // The message to display to the user so the user knows what they are entering
}

Promise resolution:

Property Type Description
text string The text the user entered into the keyboard
canceled boolean Whether the user canceled entering text before they were finished typing on the keyboard

Examples

Register your app to provide the xrn:firebolt:capability:input:keyboard capability.

import { Keyboard } from '@firebolt-js/manage-sdk'

class MyKeyboardInputProvider {

    async standard(parameters, session) {
        return await Promise.resolve({
            "text": "username"
        })
    }

    async password(parameters, session) {
        return await Promise.resolve({
            "text": "password"
        })
    }

    async email(parameters, session) {
        return await Promise.resolve({
            "text": "email@address.com"
        })
    }

}

Keyboard.provide('xrn:firebolt:capability:input:keyboard', new MyKeyboardInputProvider())

<summary>JSON-RPC</summary>

Register to recieve each provider API

Request:


{
    "id": 1,
    "method": "Keyboard.onRequestStandard",
    "params": {
        "listen": true
    }
}

{
    "id": 2,
    "method": "Keyboard.onRequestPassword",
    "params": {
        "listen": true
    }
}

{
    "id": 3,
    "method": "Keyboard.onRequestEmail",
    "params": {
        "listen": true
    }
}

Response:


{
    "id": 1,
    "result": {
        "listening": true,
        "event": "Keyboard.onRequestStandard"
    }            
 
}

{
    "id": 2,
    "result": {
        "listening": true,
        "event": "Keyboard.onRequestPassword"
    }            
 
}

{
    "id": 3,
    "result": {
        "listening": true,
        "event": "Keyboard.onRequestEmail"
    }            
 
}

Asynchronous event to initiate standard()

Event Response:

{
    "id": 1,
    "result": {
        "correlationId": "abc",
        "parameters": {
            "message": "Enter your user name."
        }
    }
}

App initiated response to event

Request:

{
    "id": 4,
    "method": "Keyboard.standardResponse",
    "params": {
        "correlationId": "abc",
        "result": {
            "text": "username"
        }
    }
}

Response:

{
    "id": 4,
    "result": true
}

Asynchronous event to initiate password()

Event Response:

{
    "id": 2,
    "result": {
        "correlationId": "abc",
        "parameters": {
            "message": "Enter your user name."
        }
    }
}

App initiated response to event

Request:

{
    "id": 5,
    "method": "Keyboard.passwordResponse",
    "params": {
        "correlationId": "abc",
        "result": {
            "text": "password"
        }
    }
}

Response:

{
    "id": 5,
    "result": true
}

Asynchronous event to initiate email()

Event Response:

{
    "id": 3,
    "result": {
        "correlationId": "abc",
        "parameters": {
            "message": "Enter your user name."
        }
    }
}

App initiated response to event

Request:

{
    "id": 6,
    "method": "Keyboard.emailResponse",
    "params": {
        "correlationId": "abc",
        "result": {
            "text": "email@address.com"
        }
    }
}

Response:

{
    "id": 6,
    "result": true
}

Types

KeyboardResult

type KeyboardResult = {
  text: string           // The text the user entered into the keyboard
  canceled?: boolean     // Whether the user canceled entering text before they were finished typing on the keyboard
}

KeyboardParameters

type KeyboardParameters = {
  message: string            // The message to display to the user so the user knows what they are entering
}

KeyboardProviderRequest

type KeyboardProviderRequest = {
  correlationId: string           // An id to correlate the provider response with this request
  parameters: KeyboardParameters
}

See also:

KeyboardParameters