Keyboard Module

Version 0.1.0-alpha.4

Overview

A module for registering an app that provides keyboard UI to Firebolt

OpenRPC

Firebolt APIs are maintained in the rdkcentral/firebolt-manage-sdk.git GitHub repository.

You can see this API in the keyboard.json OpenRPC JSON-Schema document.

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'

Methods

listen

Listen for events from this module.

To listen to a specific event pass the event name as the first parameter:

Keyboard.listen(event: string, (data: any) => void): Promise<bigint>

Parameters:

Param Type Required Summary
event string Yes The event to listen for, see Events.
callback function Yes A function that will be invoked when the event occurs.

Promise resolution:

Type Description
bigint Listener ID to clear the callback method and stop receiving the event, e.g. Keyboard.clear(id)

Callback parameters:

Param Type Required Summary
data any Yes The event data, which depends on which event is firing, see Events.

To listen to all events from this module pass only a callback, without specifying an event name:

Keyboard.listen((event: string, data: any) => void): Promise<bigint>

Parameters:

Param Type Required Summary
callback function Yes A function that will be invoked when the event occurs. The event data depends on which event is firing, see Events.

Callback parameters:

Param Type Required Summary
event string Yes The event that has occured listen for, see Events.
data any Yes The event data, which depends on which event is firing, see Events.

Promise resolution:

Type Description
bigint Listener ID to clear the callback method and stop receiving the event, e.g. Keyboard.clear(id)

See Listening for events for more information and examples.

once

Listen for only one occurance of an event from this module. The callback will be cleared after one event.

To listen to a specific event pass the event name as the first parameter:

Keyboard.once(event: string, (data: any) => void): Promise<bigint>

Parameters:

Param Type Required Summary
event string Yes The event to listen for, see Events.
callback function Yes A function that will be invoked when the event occurs.

Promise resolution:

Type Description
bigint Listener ID to clear the callback method and stop receiving the event, e.g. Keyboard.clear(id)

Callback parameters:

Param Type Required Summary
data any Yes The event data, which depends on which event is firing, see Events.

To listen to all events from this module pass only a callback, without specifying an event name:

Keyboard.once((event: string, data: any) => void): Promise<bigint>

Parameters:

Param Type Required Summary
callback function Yes A function that will be invoked when the event occurs. The event data depends on which event is firing, see Events.

Callback parameters:

Param Type Required Summary
event string Yes The event that has occured listen for, see Events.
data any Yes The event data, which depends on which event is firing, see Events.

Promise resolution:

Type Description
bigint Listener ID to clear the callback method and stop receiving the event, e.g. Keyboard.clear(id)

See Listening for events for more information and examples.

provide

Register to provide a capability from this module.

See Provider Interfaces, for more info.

function provide(provider: object | class): Promise<void>

Parameters:

Param Type Required Summary
provider `object class` true

Promise resolution:

void

Additional methods

The following methods are documented as part of a related set of method APIs.

For more information, follow the links under the “Documentation” column.

JavaScript RPC Parameters Documentation
NA standardFocus ()  
NA passwordFocus ()  
NA emailFocus ()  
NA standardResponse (response: ProviderResponse) KeyboardInputProvider
NA passwordResponse (response: ProviderResponse) KeyboardInputProvider
NA emailResponse (response: ProviderResponse) KeyboardInputProvider

Events

Additional events

The following events are documented as part of a related set of method APIs.

For more information, follow the links under the “Documentation” column.

JavaScript RPC Payload Documentation
NA onRequestStandard KeyboardProviderRequest  
NA onRequestPassword KeyboardProviderRequest  
NA onRequestEmail KeyboardProviderRequest  

Provider Interfaces

Providers are interfaces that your app can implement in order to provide certain capabilties back to the platform.

To register a provider, use the provide() method.

Every provider interface method has the following signature:

(parameters: object | void, session: ProviderSession) => {}

ProviderSession has the following interface:


interface ProviderSession {
    correlationId(): string        // Returns the correlation id of the current provider session
}


interface FocusableProviderSession extends ProviderSession {
    focus(): Promise<void>         // Requests that the provider app be moved into focus to prevent a user experience
}

KeyboardInputProvider

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

interface KeyboardInputProvider {
	standard(parameters?: KeyboardParameters, session?: FocusableProviderSession): Promise<KeyboardResult>
	password(parameters?: KeyboardParameters, session?: FocusableProviderSession): Promise<KeyboardResult>
	email(parameters?: KeyboardParameters, session?: FocusableProviderSession): Promise<KeyboardResult>
}

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:

Type Description
KeyboardResult  

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:

Type Description
KeyboardResult  

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:

Type Description
KeyboardResult  

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())
**JSON-RPC**

Register to recieve each provider API

Request:


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

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

{
    "id": 3,
    "method": "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": "standardResponse",
    "params": {
        "response": {
            "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": "passwordResponse",
    "params": {
        "response": {
            "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": "emailResponse",
    "params": {
        "response": {
            "correlationId": "abc",
            "result": {
                "text": "email@address.com"
            }
        }
    }
}

Response:

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

Schemas

KeyboardType

The type of keyboard to show to the user

type KeyboardType = 'standard' | 'email' | 'password'

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
}

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
}
 
Go To Top