Keyboard Module

Version Keyboard 1.2.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
correlationId string true  
error object true  

Result:

Capabilities:

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

Examples

Example 1

JSON-RPC:

Request:

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "Keyboard.emailError",
  "params": {
    "correlationId": "123",
    "error": {
      "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:

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
correlationId string true  
result string true  

Result:

Capabilities:

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

Examples

Example

JSON-RPC:

Request:

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "Keyboard.emailResponse",
  "params": {
    "correlationId": "123",
    "result": "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
correlationId string true  
error object true  

Result:

Capabilities:

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

Examples

Example 1

JSON-RPC:

Request:

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "Keyboard.passwordError",
  "params": {
    "correlationId": "123",
    "error": {
      "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:

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
correlationId string true  
result string true  

Result:

Capabilities:

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

Examples

Example

JSON-RPC:

Request:

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "Keyboard.passwordResponse",
  "params": {
    "correlationId": "123",
    "result": "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
correlationId string true  
error object true  

Result:

Capabilities:

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

Examples

Example 1

JSON-RPC:

Request:

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "Keyboard.standardError",
  "params": {
    "correlationId": "123",
    "error": {
      "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:

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
correlationId string true  
result string true  

Result:

Capabilities:

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

Examples

Example

JSON-RPC:

Request:

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "Keyboard.standardResponse",
  "params": {
    "correlationId": "123",
    "result": "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.

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

Usage:

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

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 'username'
  }

  async password(parameters, session) {
    return 'password'
  }

  async email(parameters, session) {
    return '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": undefined,
    "parameters": {
      "message": "Enter your user name."
    }
  }
}

App initiated response to event

Request:

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

Response:

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

Asynchronous event to initiate password()

Event Response:

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

App initiated response to event

Request:

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

Response:

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

Asynchronous event to initiate email()

Event Response:

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

App initiated response to event

Request:

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

Response:

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

Types

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 // The request to start a keyboard session
}

See also:

KeyboardParameters