@firebolt-js/manage-sdk
Version:
The Firebolt Manage JS SDK
450 lines (314 loc) • 11.5 kB
Markdown
title: Discovery
# Discovery Module
Version Discovery 1.5.0
## Table of Contents
- [Table of Contents](#table-of-contents)
- [Usage](#usage)
- [Overview](#overview)
- [Localization](#localization)
- [Methods](#methods)
- [listen](#listen)
- [once](#once)
- [Events](#events)
- [signIn](#signin)
- [signOut](#signout)
- [Private Events](#private-events)<details ontoggle="document.getElementById('private-events-details').open=this.open"><summary>Show</summary>
- [signOut](#signout-1)
</details>
- [Types](#types)
## Usage
To use the Discovery module, you can import it into your project from the Firebolt SDK:
```javascript
import { Discovery } from '@firebolt-js/manage-sdk'
```
## Overview
Your App likely wants to integrate with the Platform's discovery capabilities. For example to add a "Watch Next" tile that links to your app from the platform's home screen.
Getting access to this information requires to connect to lower level APIs made available by the platform. Since implementations differ between operators and platforms, the Firebolt SDK offers a Discovery module, that exposes a generic, agnostic interface to the developer.
Under the hood, an underlaying transport layer will then take care of calling the right APIs for the actual platform implementation that your App is running on.
The Discovery plugin is used to _send_ information to the Platform.
### Localization
Apps should provide all user-facing strings in the device's language, as specified by the Firebolt `Localization.language` property.
Apps should provide prices in the same currency presented in the app. If multiple currencies are supported in the app, the app should provide prices in the user's current default currency.
## Methods
### listen
To listen to a specific event pass the event name as the first parameter:
```typescript
listen(event: string, callback: (data: any) => void): Promise<number>
```
Parameters:
| Param | Type | Required | Summary |
| ---------- | ---------- | -------- | ------------------------------------------------------ |
| `event` | `string` | Yes | The event to listen for, see [Events](#events). |
| _callback_ | `function` | Yes | A function that will be invoked when the event occurs. |
Promise resolution:
| Type | Description |
| -------- | ------------------------------------------------------------------------------------------------- |
| `number` | Listener ID to clear the callback method and stop receiving the event, e.g. `Discovery.clear(id)` |
Callback parameters:
| Param | Type | Required | Summary |
| ------ | ----- | -------- | ------------------------------------------------------------------------------ |
| `data` | `any` | Yes | The event data, which depends on which event is firing, see [Events](#events). |
To listen to all events from this module pass only a callback, without specifying an event name:
```typescript
listen(callback: (event: string, data: any) => void): Promise<number>
```
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](#events). |
Callback parameters:
| Param | Type | Required | Summary |
| ------- | -------- | -------- | ------------------------------------------------------------------------------ |
| `event` | `string` | Yes | The event that has occured listen for, see [Events](#events). |
| `data` | `any` | Yes | The event data, which depends on which event is firing, see [Events](#events). |
Promise resolution:
| Type | Description |
| -------- | ------------------------------------------------------------------------------------------------- |
| `number` | Listener ID to clear the callback method and stop receiving the event, e.g. `Discovery.clear(id)` |
See [Listening for events](../../docs/listening-for-events/) for more information and examples.
### once
To listen to a single instance of a specific event pass the event name as the first parameter:
```typescript
once(event: string, callback: (data: any) => void): Promise<number>
```
The `once` method will only pass the next instance of this event, and then dicard the listener you provided.
Parameters:
| Param | Type | Required | Summary |
| ---------- | ---------- | -------- | ------------------------------------------------------ |
| `event` | `string` | Yes | The event to listen for, see [Events](#events). |
| _callback_ | `function` | Yes | A function that will be invoked when the event occurs. |
Promise resolution:
| Type | Description |
| -------- | ------------------------------------------------------------------------------------------------- |
| `number` | Listener ID to clear the callback method and stop receiving the event, e.g. `Discovery.clear(id)` |
Callback parameters:
| Param | Type | Required | Summary |
| ------ | ----- | -------- | ------------------------------------------------------------------------------ |
| `data` | `any` | Yes | The event data, which depends on which event is firing, see [Events](#events). |
To listen to the next instance only of any events from this module pass only a callback, without specifying an event name:
```typescript
once(callback: (event: string, data: any) => void): Promise<number>
```
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](#events). |
Callback parameters:
| Param | Type | Required | Summary |
| ------- | -------- | -------- | ------------------------------------------------------------------------------ |
| `event` | `string` | Yes | The event that has occured listen for, see [Events](#events). |
| `data` | `any` | Yes | The event data, which depends on which event is firing, see [Events](#events). |
Promise resolution:
| Type | Description |
| -------- | ------------------------------------------------------------------------------------------------- |
| `number` | Listener ID to clear the callback method and stop receiving the event, e.g. `Discovery.clear(id)` |
See [Listening for events](../../docs/listening-for-events/) for more information and examples.
## Events
### signIn
```typescript
function listen('signIn', () => void): Promise<number>
```
See also: [listen()](#listen), [once()](#listen), [clear()](#listen).
Event value:
Capabilities:
| Role | Capability |
| ------- | ------------------------------------------------ |
| manages | xrn:firebolt:capability:discovery:sign-in-status |
#### Examples
Default Example
JavaScript:
```javascript
import { Discovery } from '@firebolt-js/manage-sdk'
Discovery.listen('signIn', (event) => {
console.log(event)
})
```
Value of `event`:
```javascript
{
"appId": "firecert"
}
```
<details>
<summary>JSON-RPC:</summary>
Request:
```json
{
"jsonrpc": "2.0",
"id": 1,
"method": "Discovery.onSignIn",
"params": {
"listen": true
}
}
```
Response:
```json
{
"jsonrpc": "2.0",
"id": 1,
"result": {
"appId": "firecert"
}
}
```
</details>
### signOut
```typescript
function listen('signOut', () => void): Promise<number>
```
See also: [listen()](#listen), [once()](#listen), [clear()](#listen).
Event value:
Capabilities:
| Role | Capability |
| ------- | ------------------------------------------------ |
| manages | xrn:firebolt:capability:discovery:sign-in-status |
#### Examples
Default Example
JavaScript:
```javascript
import { Discovery } from '@firebolt-js/manage-sdk'
Discovery.listen('signOut', (event) => {
console.log(event)
})
```
Value of `event`:
```javascript
{
"appId": "firecert"
}
```
<details>
<summary>JSON-RPC:</summary>
Request:
```json
{
"jsonrpc": "2.0",
"id": 1,
"method": "Discovery.onSignOut",
"params": {
"listen": true
}
}
```
Response:
```json
{
"jsonrpc": "2.0",
"id": 1,
"result": {
"appId": "firecert"
}
}
```
</details>
## Private Events
<details id="private-events-details">
<summary>View</summary>
### signIn
```typescript
function listen('signIn', () => void): Promise<number>
```
See also: [listen()](#listen), [once()](#listen), [clear()](#listen).
Event value:
Capabilities:
| Role | Capability |
| ------- | ------------------------------------------------ |
| manages | xrn:firebolt:capability:discovery:sign-in-status |
#### Examples
Default Example
JavaScript:
```javascript
import { Discovery } from '@firebolt-js/manage-sdk'
Discovery.listen('signIn', (event) => {
console.log(event)
})
```
Value of `event`:
```javascript
{
"appId": "firecert"
}
```
<details>
<summary>JSON-RPC:</summary>
Request:
```json
{
"jsonrpc": "2.0",
"id": 1,
"method": "Discovery.onSignIn",
"params": {
"listen": true
}
}
```
Response:
```json
{
"jsonrpc": "2.0",
"id": 1,
"result": {
"appId": "firecert"
}
}
```
</details>
### signOut
```typescript
function listen('signOut', () => void): Promise<number>
```
See also: [listen()](#listen), [once()](#listen), [clear()](#listen).
Event value:
Capabilities:
| Role | Capability |
| ------- | ------------------------------------------------ |
| manages | xrn:firebolt:capability:discovery:sign-in-status |
#### Examples
Default Example
JavaScript:
```javascript
import { Discovery } from '@firebolt-js/manage-sdk'
Discovery.listen('signOut', (event) => {
console.log(event)
})
```
Value of `event`:
```javascript
{
"appId": "firecert"
}
```
<details>
<summary>JSON-RPC:</summary>
Request:
```json
{
"jsonrpc": "2.0",
"id": 1,
"method": "Discovery.onSignOut",
"params": {
"listen": true
}
}
```
Response:
```json
{
"jsonrpc": "2.0",
"id": 1,
"result": {
"appId": "firecert"
}
}
```
</details>
</details>
## Types