title: Discovery

# Discovery Module

Version 0.10.0

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.

OpenRPC

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

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

Table of Contents

• Overview

• OpenRPC

• Usage

• Methods

  • clearContentAccess
  • contentAccess
  • entitlements
  • entityInfo
  • launch
  • listen
  • once
  • policy
  • purchasedContent
  • signIn
  • signOut
  • watched
  • watchNext

• Events

  • Additional Events

• Schemas

  • DiscoveryPolicy
  • EntityInfo
  • WayToWatch
  • ContentRating
  • ContentIdentifiers
  • FederatedRequest
  • FederatedResponse
  • EntityInfoFederatedRequest
  • EntityInfoParameters
  • EntityInfoFederatedResponse
  • EntityInfoResult
  • PurchasedContentFederatedRequest
  • PurchasedContentParameters
  • PurchasedContentFederatedResponse
  • PurchasedContentResult
  • Availability
  • ContentAccessIdentifiers
  • TuneChannels

Usage

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

import { Discovery } from '@firebolt-js/sdk'

Methods

clearContentAccess

Clear both availabilities and entitlements from the subscriber. This is equivalent of calling Discovery.contentAccess({ availabilities: [], entitlements: []}). This is typically called when the user signs out of an account.

function clearContentAccess(): Promise<void>

Promise resolution:

void

Examples

Clear subscriber's availabilities and entitlements

JavaScript:

import { Discovery } from '@firebolt-js/sdk'

Discovery.clearContentAccess()
    .then(result => {
        console.log(result)
    })

Value of result:

null

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "discovery.clearContentAccess",
  "params": {}
}

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

contentAccess

Inform the platform of what content the user can access either by discovering it or consuming it. Availabilities determine which content is discoverable to a user, while entitlements determine if the user can currently consume that content. Content can be available but not entitled, this means that user can see the content but when they try to open it they must gain an entitlement either through purchase or subscription upgrade. In case the access changed off-device, this API should be called any time the app comes to the foreground to refresh the access. This API should also be called any time the availabilities or entitlements change within the app for any reason. Typical reasons may include the user signing into an account or upgrading a subscription. Less common cases can cause availabilities to change, such as moving to a new service location. When availabilities or entitlements are removed from the subscriber (such as when the user signs out), then an empty array should be given. To clear both, use the Discovery.clearContentAccess convenience API.

function contentAccess(ids: ContentAccessIdentifiers): Promise<void>

Parameters:

Promise resolution:

void

Examples

Update subscriber's availabilities

JavaScript:

import { Discovery } from '@firebolt-js/sdk'

Discovery.contentAccess({
                          "availabilities": [
                            {
                              "type": "channel-lineup",
                              "id": "partner.com/availability/123",
                              "startTime": "2021-04-23T18:25:43.511Z",
                              "endTime": "2021-04-23T18:25:43.511Z"
                            },
                            {
                              "type": "channel-lineup",
                              "id": "partner.com/availability/456",
                              "startTime": "2021-04-23T18:25:43.511Z",
                              "endTime": "2021-04-23T18:25:43.511Z"
                            }
                          ]
                        })
    .then(result => {
        console.log(result)
    })

Value of result:

null

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "discovery.contentAccess",
  "params": {
    "ids": {
      "availabilities": [
        {
          "type": "channel-lineup",
          "id": "partner.com/availability/123",
          "startTime": "2021-04-23T18:25:43.511Z",
          "endTime": "2021-04-23T18:25:43.511Z"
        },
        {
          "type": "channel-lineup",
          "id": "partner.com/availability/456",
          "startTime": "2021-04-23T18:25:43.511Z",
          "endTime": "2021-04-23T18:25:43.511Z"
        }
      ]
    }
  }
}

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

import { Discovery } from '@firebolt-js/sdk'

Discovery.contentAccess({
                          "availabilities": [
                            {
                              "type": "channel-lineup",
                              "id": "partner.com/availability/123",
                              "startTime": "2021-04-23T18:25:43.511Z",
                              "endTime": "2021-04-23T18:25:43.511Z"
                            },
                            {
                              "type": "channel-lineup",
                              "id": "partner.com/availability/456",
                              "startTime": "2021-04-23T18:25:43.511Z",
                              "endTime": "2021-04-23T18:25:43.511Z"
                            }
                          ],
                          "entitlements": [
                            {
                              "entitlementId": "123",
                              "startTime": "2025-01-01T00:00:00.000Z",
                              "endTime": "2025-01-01T00:00:00.000Z"
                            }
                          ]
                        })
    .then(result => {
        console.log(result)
    })

null

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "discovery.contentAccess",
  "params": {
    "ids": {
      "availabilities": [
        {
          "type": "channel-lineup",
          "id": "partner.com/availability/123",
          "startTime": "2021-04-23T18:25:43.511Z",
          "endTime": "2021-04-23T18:25:43.511Z"
        },
        {
          "type": "channel-lineup",
          "id": "partner.com/availability/456",
          "startTime": "2021-04-23T18:25:43.511Z",
          "endTime": "2021-04-23T18:25:43.511Z"
        }
      ],
      "entitlements": [
        {
          "entitlementId": "123",
          "startTime": "2025-01-01T00:00:00.000Z",
          "endTime": "2025-01-01T00:00:00.000Z"
        }
      ]
    }
  }
}

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

import { Discovery } from '@firebolt-js/sdk'

Discovery.contentAccess({
                          "entitlements": [
                            {
                              "entitlementId": "123",
                              "startTime": "2025-01-01T00:00:00.000Z",
                              "endTime": "2025-01-01T00:00:00.000Z"
                            }
                          ]
                        })
    .then(result => {
        console.log(result)
    })

null

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "discovery.contentAccess",
  "params": {
    "ids": {
      "entitlements": [
        {
          "entitlementId": "123",
          "startTime": "2025-01-01T00:00:00.000Z",
          "endTime": "2025-01-01T00:00:00.000Z"
        }
      ]
    }
  }
}

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

import { Discovery } from '@firebolt-js/sdk'

Discovery.contentAccess({"entitlements":[]})
    .then(result => {
        console.log(result)
    })

null

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "discovery.contentAccess",
  "params": {
    "ids": {
      "entitlements": []
    }
  }
}

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

import { Discovery } from '@firebolt-js/sdk'

Discovery.contentAccess({"availabilities":[]})
    .then(result => {
        console.log(result)
    })

null

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "discovery.contentAccess",
  "params": {
    "ids": {
      "availabilities": []
    }
  }
}

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

entitlements

This API is deprecated since version 0.10.0. Use Discovery.contentAccess() instead.

Inform the platform of the users latest entitlements w/in this app.

function entitlements(entitlements: Entitlement[]): Promise<boolean>

Parameters:

Promise resolution:

Examples

Update user's entitlements

JavaScript:

import { Discovery } from '@firebolt-js/sdk'

Discovery.entitlements([
                         {
                           "entitlementId": "partner.com/entitlement/123",
                           "startTime": "2021-04-23T18:25:43.511Z",
                           "endTime": "2021-04-23T18:25:43.511Z"
                         },
                         {
                           "entitlementId": "partner.com/entitlement/456",
                           "startTime": "2021-04-23T18:25:43.511Z",
                           "endTime": "2021-04-23T18:25:43.511Z"
                         }
                       ])
    .then(success => {
        console.log(success)
    })

Value of success:

true

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "discovery.entitlements",
  "params": {
    "entitlements": [
      {
        "entitlementId": "partner.com/entitlement/123",
        "startTime": "2021-04-23T18:25:43.511Z",
        "endTime": "2021-04-23T18:25:43.511Z"
      },
      {
        "entitlementId": "partner.com/entitlement/456",
        "startTime": "2021-04-23T18:25:43.511Z",
        "endTime": "2021-04-23T18:25:43.511Z"
      }
    ]
  }
}

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

entityInfo

Provide information about a program entity and its available watchable assets, such as entitlement status and price, via either a push or pull call flow. Includes information about the program entity and its relevant associated entities, such as extras, previews, and, in the case of TV series, seasons and episodes.

See the EntityInfo and WayToWatch data structures below for more information.

The app only needs to implement Pull support for entityInfo at this time.

To allow the platform to pull data, use entityInfo(callback):

function entityInfo(callback: (parameters: EntityInfoParameters) => Promise<EntityInfoResult>): Promise<boolean>

Parameters:

Promise resolution:

Callback parameters:

Callback promise resolution:

Examples

Send entity info for a movie to the platform. (Pull)

JavaScript:

Discovery.entityInfo(function(parameters) {
  return Promise.resolve({
  "correlationId": null,
  "result": {
    "expires": "2025-01-01T00:00:00.000Z",
    "entity": {
      "identifiers": {
        "entityId": "345"
      },
      "entityType": "program",
      "programType": "movie",
      "title": "Cool Runnings",
      "synopsis": "Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Pulvinar sapien et ligula ullamcorper malesuada proin libero nunc.",
      "releaseDate": "1993-01-01T00:00:00.000Z",
      "contentRatings": [
        {
          "scheme": "US-Movie",
          "rating": "PG"
        },
        {
          "scheme": "CA-Movie",
          "rating": "G"
        }
      ],
      "waysToWatch": [
        {
          "identifiers": {
            "assetId": "123"
          },
          "expires": "2025-01-01T00:00:00.000Z",
          "entitled": true,
          "entitledExpires": "2025-01-01T00:00:00.000Z",
          "offeringType": "buy",
          "price": 2.99,
          "videoQuality": [
            "UHD"
          ],
          "audioProfile": [
            "dolbyAtmos"
          ],
          "audioLanguages": [
            "en"
          ],
          "closedCaptions": [
            "en"
          ],
          "subtitles": [
            "es"
          ],
          "audioDescriptions": [
            "en"
          ]
        }
      ]
    }
  }
})
}).then(success => {
  console.log(success)
})

Value of success

true

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "discovery.entityInfo",
  "params": {
    "correlationId": "xyz",
    "result": {}
  }
}

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

Discovery.entityInfo(function(parameters) {
  return Promise.resolve({
  "correlationId": null,
  "result": {
    "expires": "2025-01-01T00:00:00.000Z",
    "entity": {
      "identifiers": {
        "entityId": "345"
      },
      "entityType": "program",
      "programType": "movie",
      "title": "Cool Runnings",
      "synopsis": "Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Pulvinar sapien et ligula ullamcorper malesuada proin libero nunc.",
      "releaseDate": "1993-01-01T00:00:00.000Z",
      "contentRatings": [
        {
          "scheme": "US-Movie",
          "rating": "PG"
        },
        {
          "scheme": "CA-Movie",
          "rating": "G"
        }
      ],
      "waysToWatch": [
        {
          "identifiers": {
            "assetId": "123"
          },
          "expires": "2025-01-01T00:00:00.000Z",
          "entitled": true,
          "entitledExpires": "2025-01-01T00:00:00.000Z",
          "offeringType": "buy",
          "price": 2.99,
          "videoQuality": [
            "UHD"
          ],
          "audioProfile": [
            "dolbyAtmos"
          ],
          "audioLanguages": [
            "en"
          ],
          "closedCaptions": [
            "en"
          ],
          "subtitles": [
            "es"
          ],
          "audioDescriptions": [
            "en"
          ]
        }
      ]
    },
    "related": [
      {
        "identifiers": {
          "entityId": "345"
        },
        "entityType": "program",
        "programType": "preview",
        "title": "Cool Runnings Trailer",
        "waysToWatch": [
          {
            "identifiers": {
              "assetId": "123111",
              "entityId": "345"
            },
            "entitled": true,
            "videoQuality": [
              "HD"
            ],
            "audioProfile": [
              "dolbyAtmos"
            ],
            "audioLanguages": [
              "en"
            ],
            "closedCaptions": [
              "en"
            ]
          }
        ]
      }
    ]
  }
})
}).then(success => {
  console.log(success)
})

true

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "discovery.entityInfo",
  "params": {
    "correlationId": "xyz",
    "result": {}
  }
}

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

Discovery.entityInfo(function(parameters) {
  return Promise.resolve({
  "correlationId": null,
  "result": {
    "expires": "2025-01-01T00:00:00.000Z",
    "entity": {
      "identifiers": {
        "entityId": "98765"
      },
      "entityType": "program",
      "programType": "series",
      "title": "Perfect Strangers",
      "synopsis": "Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Pulvinar sapien et ligula ullamcorper malesuada proin libero nunc.",
      "releaseDate": "1986-01-01T00:00:00.000Z",
      "contentRatings": [
        {
          "scheme": "US-TV",
          "rating": "TV-PG"
        }
      ]
    },
    "related": [
      {
        "identifiers": {
          "entityId": "111",
          "seriesId": "98765"
        },
        "entityType": "program",
        "programType": "season",
        "seasonNumber": 1,
        "title": "Perfect Strangers Season 3",
        "contentRatings": [
          {
            "scheme": "US-TV",
            "rating": "TV-PG"
          }
        ],
        "waysToWatch": [
          {
            "identifiers": {
              "assetId": "556",
              "entityId": "111",
              "seriesId": "98765"
            },
            "entitled": true,
            "offeringType": "free",
            "videoQuality": [
              "SD"
            ],
            "audioProfile": [
              "stereo"
            ],
            "audioLanguages": [
              "en"
            ],
            "closedCaptions": [
              "en"
            ]
          }
        ]
      },
      {
        "identifiers": {
          "entityId": "111",
          "seriesId": "98765"
        },
        "entityType": "program",
        "programType": "episode",
        "seasonNumber": 1,
        "episodeNumber": 1,
        "title": "Knock Knock, Who's There?",
        "synopsis": "Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Pulvinar sapien et ligula ullamcorper malesuada proin libero nunc.",
        "releaseDate": "1986-03-25T00:00:00.000Z",
        "contentRatings": [
          {
            "scheme": "US-TV",
            "rating": "TV-PG"
          }
        ],
        "waysToWatch": [
          {
            "identifiers": {
              "assetId": "556",
              "entityId": "111",
              "seriesId": "98765"
            },
            "entitled": true,
            "offeringType": "free",
            "videoQuality": [
              "SD"
            ],
            "audioProfile": [
              "stereo"
            ],
            "audioLanguages": [
              "en"
            ],
            "closedCaptions": [
              "en"
            ]
          }
        ]
      },
      {
        "identifiers": {
          "entityId": "112",
          "seriesId": "98765"
        },
        "entityType": "program",
        "programType": "episode",
        "seasonNumber": 1,
        "episodeNumber": 2,
        "title": "Picture This",
        "synopsis": "Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Pulvinar sapien et ligula ullamcorper malesuada proin libero nunc.",
        "releaseDate": "1986-04-01T00:00:00.000Z",
        "contentRatings": [
          {
            "scheme": "US-TV",
            "rating": "TV-PG"
          }
        ],
        "waysToWatch": [
          {
            "identifiers": {
              "assetId": "557",
              "entityId": "112",
              "seriesId": "98765"
            },
            "entitled": true,
            "offeringType": "free",
            "videoQuality": [
              "SD"
            ],
            "audioProfile": [
              "stereo"
            ],
            "audioLanguages": [
              "en"
            ],
            "closedCaptions": [
              "en"
            ]
          }
        ]
      }
    ]
  }
})
}).then(success => {
  console.log(success)
})

true

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "discovery.entityInfo",
  "params": {
    "correlationId": "xyz",
    "result": {}
  }
}

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

To push data to the platform, e.g. during app launch, use entityInfo(correlationId: string, result: EntityInfoResult):

function entityInfo(correlationId: string, result: EntityInfoResult): Promise<boolean>

Parameters:

Promise resolution:

boolean

Examples

Send entity info for a movie to the platform.

JavaScript:

import { Discovery } from ''

Discovery.entityInfo(null,
                     {
                       "expires": "2025-01-01T00:00:00.000Z",
                       "entity": {
                         "identifiers": {
                           "entityId": "345"
                         },
                         "entityType": "program",
                         "programType": "movie",
                         "title": "Cool Runnings",
                         "synopsis": "Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Pulvinar sapien et ligula ullamcorper malesuada proin libero nunc.",
                         "releaseDate": "1993-01-01T00:00:00.000Z",
                         "contentRatings": [
                           {
                             "scheme": "US-Movie",
                             "rating": "PG"
                           },
                           {
                             "scheme": "CA-Movie",
                             "rating": "G"
                           }
                         ],
                         "waysToWatch": [
                           {
                             "identifiers": {
                               "assetId": "123"
                             },
                             "expires": "2025-01-01T00:00:00.000Z",
                             "entitled": true,
                             "entitledExpires": "2025-01-01T00:00:00.000Z",
                             "offeringType": "buy",
                             "price": 2.99,
                             "videoQuality": [
                               "UHD"
                             ],
                             "audioProfile": [
                               "dolbyAtmos"
                             ],
                             "audioLanguages": [
                               "en"
                             ],
                             "closedCaptions": [
                               "en"
                             ],
                             "subtitles": [
                               "es"
                             ],
                             "audioDescriptions": [
                               "en"
                             ]
                           }
                         ]
                       }
                     })

Value of success

true

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "discovery.entityInfo",
  "params": {
    "correlationId": null,
    "result": {
      "expires": "2025-01-01T00:00:00.000Z",
      "entity": {
        "identifiers": {
          "entityId": "345"
        },
        "entityType": "program",
        "programType": "movie",
        "title": "Cool Runnings",
        "synopsis": "Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Pulvinar sapien et ligula ullamcorper malesuada proin libero nunc.",
        "releaseDate": "1993-01-01T00:00:00.000Z",
        "contentRatings": [
          {
            "scheme": "US-Movie",
            "rating": "PG"
          },
          {
            "scheme": "CA-Movie",
            "rating": "G"
          }
        ],
        "waysToWatch": [
          {
            "identifiers": {
              "assetId": "123"
            },
            "expires": "2025-01-01T00:00:00.000Z",
            "entitled": true,
            "entitledExpires": "2025-01-01T00:00:00.000Z",
            "offeringType": "buy",
            "price": 2.99,
            "videoQuality": [
              "UHD"
            ],
            "audioProfile": [
              "dolbyAtmos"
            ],
            "audioLanguages": [
              "en"
            ],
            "closedCaptions": [
              "en"
            ],
            "subtitles": [
              "es"
            ],
            "audioDescriptions": [
              "en"
            ]
          }
        ]
      }
    }
  }
}

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

import { Discovery } from ''

Discovery.entityInfo(null,
                     {
                       "expires": "2025-01-01T00:00:00.000Z",
                       "entity": {
                         "identifiers": {
                           "entityId": "345"
                         },
                         "entityType": "program",
                         "programType": "movie",
                         "title": "Cool Runnings",
                         "synopsis": "Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Pulvinar sapien et ligula ullamcorper malesuada proin libero nunc.",
                         "releaseDate": "1993-01-01T00:00:00.000Z",
                         "contentRatings": [
                           {
                             "scheme": "US-Movie",
                             "rating": "PG"
                           },
                           {
                             "scheme": "CA-Movie",
                             "rating": "G"
                           }
                         ],
                         "waysToWatch": [
                           {
                             "identifiers": {
                               "assetId": "123"
                             },
                             "expires": "2025-01-01T00:00:00.000Z",
                             "entitled": true,
                             "entitledExpires": "2025-01-01T00:00:00.000Z",
                             "offeringType": "buy",
                             "price": 2.99,
                             "videoQuality": [
                               "UHD"
                             ],
                             "audioProfile": [
                               "dolbyAtmos"
                             ],
                             "audioLanguages": [
                               "en"
                             ],
                             "closedCaptions": [
                               "en"
                             ],
                             "subtitles": [
                               "es"
                             ],
                             "audioDescriptions": [
                               "en"
                             ]
                           }
                         ]
                       },
                       "related": [
                         {
                           "identifiers": {
                             "entityId": "345"
                           },
                           "entityType": "program",
                           "programType": "preview",
                           "title": "Cool Runnings Trailer",
                           "waysToWatch": [
                             {
                               "identifiers": {
                                 "assetId": "123111",
                                 "entityId": "345"
                               },
                               "entitled": true,
                               "videoQuality": [
                                 "HD"
                               ],
                               "audioProfile": [
                                 "dolbyAtmos"
                               ],
                               "audioLanguages": [
                                 "en"
                               ],
                               "closedCaptions": [
                                 "en"
                               ]
                             }
                           ]
                         }
                       ]
                     })

true

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "discovery.entityInfo",
  "params": {
    "correlationId": null,
    "result": {
      "expires": "2025-01-01T00:00:00.000Z",
      "entity": {
        "identifiers": {
          "entityId": "345"
        },
        "entityType": "program",
        "programType": "movie",
        "title": "Cool Runnings",
        "synopsis": "Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Pulvinar sapien et ligula ullamcorper malesuada proin libero nunc.",
        "releaseDate": "1993-01-01T00:00:00.000Z",
        "contentRatings": [
          {
            "scheme": "US-Movie",
            "rating": "PG"
          },
          {
            "scheme": "CA-Movie",
            "rating": "G"
          }
        ],
        "waysToWatch": [
          {
            "identifiers": {
              "assetId": "123"
            },
            "expires": "2025-01-01T00:00:00.000Z",
            "entitled": true,
            "entitledExpires": "2025-01-01T00:00:00.000Z",
            "offeringType": "buy",
            "price": 2.99,
            "videoQuality": [
              "UHD"
            ],
            "audioProfile": [
              "dolbyAtmos"
            ],
            "audioLanguages": [
              "en"
            ],
            "closedCaptions": [
              "en"
            ],
            "subtitles": [
              "es"
            ],
            "audioDescriptions": [
              "en"
            ]
          }
        ]
      },
      "related": [
        {
          "identifiers": {
            "entityId": "345"
          },
          "entityType": "program",
          "programType": "preview",
          "title": "Cool Runnings Trailer",
          "waysToWatch": [
            {
              "identifiers": {
                "assetId": "123111",
                "entityId": "345"
              },
              "entitled": true,
              "videoQuality": [
                "HD"
              ],
              "audioProfile": [
                "dolbyAtmos"
              ],
              "audioLanguages": [
                "en"
              ],
              "closedCaptions": [
                "en"
              ]
            }
          ]
        }
      ]
    }
  }
}

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

import { Discovery } from ''

Discovery.entityInfo(null,
                     {
                       "expires": "2025-01-01T00:00:00.000Z",
                       "entity": {
                         "identifiers": {
                           "entityId": "98765"
                         },
                         "entityType": "program",
                         "programType": "series",
                         "title": "Perfect Strangers",
                         "synopsis": "Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Pulvinar sapien et ligula ullamcorper malesuada proin libero nunc.",
                         "releaseDate": "1986-01-01T00:00:00.000Z",
                         "contentRatings": [
                           {
                             "scheme": "US-TV",
                             "rating": "TV-PG"
                           }
                         ]
                       },
                       "related": [
                         {
                           "identifiers": {
                             "entityId": "111",
                             "seriesId": "98765"
                           },
                           "entityType": "program",
                           "programType": "season",
                           "seasonNumber": 1,
                           "title": "Perfect Strangers Season 3",
                           "contentRatings": [
                             {
                               "scheme": "US-TV",
                               "rating": "TV-PG"
                             }
                           ],
                           "waysToWatch": [
                             {
                               "identifiers": {
                                 "assetId": "556",
                                 "entityId": "111",
                                 "seriesId": "98765"
                               },
                               "entitled": true,
                               "offeringType": "free",
                               "videoQuality": [
                                 "SD"
                               ],
                               "audioProfile": [
                                 "stereo"
                               ],
                               "audioLanguages": [
                                 "en"
                               ],
                               "closedCaptions": [
                                 "en"
                               ]
                             }
                           ]
                         },
                         {
                           "identifiers": {
                             "entityId": "111",
                             "seriesId": "98765"
                           },
                           "entityType": "program",
                           "programType": "episode",
                           "seasonNumber": 1,
                           "episodeNumber": 1,
                           "title": "Knock Knock, Who's There?",
                           "synopsis": "Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Pulvinar sapien et ligula ullamcorper malesuada proin libero nunc.",
                           "releaseDate": "1986-03-25T00:00:00.000Z",
                           "contentRatings": [
                             {
                               "scheme": "US-TV",
                               "rating": "TV-PG"
                             }
                           ],
                           "waysToWatch": [
                             {
                               "identifiers": {
                                 "assetId": "556",
                                 "entityId": "111",
                                 "seriesId": "98765"
                               },
                               "entitled": true,
                               "offeringType": "free",
                               "videoQuality": [
                                 "SD"
                               ],
                               "audioProfile": [
                                 "stereo"
                               ],
                               "audioLanguages": [
                                 "en"
                               ],
                               "closedCaptions": [
                                 "en"
                               ]
                             }
                           ]
                         },
                         {
                           "identifiers": {
                             "entityId": "112",
                             "seriesId": "98765"
                           },
                           "entityType": "program",
                           "programType": "episode",
                           "seasonNumber": 1,
                           "episodeNumber": 2,
                           "title": "Picture This",
                           "synopsis": "Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Pulvinar sapien et ligula ullamcorper malesuada proin libero nunc.",
                           "releaseDate": "1986-04-01T00:00:00.000Z",
                           "contentRatings": [
                             {
                               "scheme": "US-TV",
                               "rating": "TV-PG"
                             }
                           ],
                           "waysToWatch": [
                             {
                               "identifiers": {
                                 "assetId": "557",
                                 "entityId": "112",
                                 "seriesId": "98765"
                               },
                               "entitled": true,
                               "offeringType": "free",
                               "videoQuality": [
                                 "SD"
                               ],
                               "audioProfile": [
                                 "stereo"
                               ],
                               "audioLanguages": [
                                 "en"
                               ],
                               "closedCaptions": [
                                 "en"
                               ]
                             }
                           ]
                         }
                       ]
                     })

true

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "discovery.entityInfo",
  "params": {
    "correlationId": null,
    "result": {
      "expires": "2025-01-01T00:00:00.000Z",
      "entity": {
        "identifiers": {
          "entityId": "98765"
        },
        "entityType": "program",
        "programType": "series",
        "title": "Perfect Strangers",
        "synopsis": "Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Pulvinar sapien et ligula ullamcorper malesuada proin libero nunc.",
        "releaseDate": "1986-01-01T00:00:00.000Z",
        "contentRatings": [
          {
            "scheme": "US-TV",
            "rating": "TV-PG"
          }
        ]
      },
      "related": [
        {
          "identifiers": {
            "entityId": "111",
            "seriesId": "98765"
          },
          "entityType": "program",
          "programType": "season",
          "seasonNumber": 1,
          "title": "Perfect Strangers Season 3",
          "contentRatings": [
            {
              "scheme": "US-TV",
              "rating": "TV-PG"
            }
          ],
          "waysToWatch": [
            {
              "identifiers": {
                "assetId": "556",
                "entityId": "111",
                "seriesId": "98765"
              },
              "entitled": true,
              "offeringType": "free",
              "videoQuality": [
                "SD"
              ],
              "audioProfile": [
                "stereo"
              ],
              "audioLanguages": [
                "en"
              ],
              "closedCaptions": [
                "en"
              ]
            }
          ]
        },
        {
          "identifiers": {
            "entityId": "111",
            "seriesId": "98765"
          },
          "entityType": "program",
          "programType": "episode",
          "seasonNumber": 1,
          "episodeNumber": 1,
          "title": "Knock Knock, Who's There?",
          "synopsis": "Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Pulvinar sapien et ligula ullamcorper malesuada proin libero nunc.",
          "releaseDate": "1986-03-25T00:00:00.000Z",
          "contentRatings": [
            {
              "scheme": "US-TV",
              "rating": "TV-PG"
            }
          ],
          "waysToWatch": [
            {
              "identifiers": {
                "assetId": "556",
                "entityId": "111",
                "seriesId": "98765"
              },
              "entitled": true,
              "offeringType": "free",
              "videoQuality": [
                "SD"
              ],
              "audioProfile": [
                "stereo"
              ],
              "audioLanguages": [
                "en"
              ],
              "closedCaptions": [
                "en"
              ]
            }
          ]
        },
        {
          "identifiers": {
            "entityId": "112",
            "seriesId": "98765"
          },
          "entityType": "program",
          "programType": "episode",
          "seasonNumber": 1,
          "episodeNumber": 2,
          "title": "Picture This",
          "synopsis": "Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Pulvinar sapien et ligula ullamcorper malesuada proin libero nunc.",
          "releaseDate": "1986-04-01T00:00:00.000Z",
          "contentRatings": [
            {
              "scheme": "US-TV",
              "rating": "TV-PG"
            }
          ],
          "waysToWatch": [
            {
              "identifiers": {
                "assetId": "557",
                "entityId": "112",
                "seriesId": "98765"
              },
              "entitled": true,
              "offeringType": "free",
              "videoQuality": [
                "SD"
              ],
              "audioProfile": [
                "stereo"
              ],
              "audioLanguages": [
                "en"
              ],
              "closedCaptions": [
                "en"
              ]
            }
          ]
        }
      ]
    }
  }
}

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

launch

Launch or foreground the specified app, and optionally instructs it to navigate to the specified user action

function launch(appId: string, intent?: NavigationIntent): Promise<boolean>

Parameters:

Promise resolution:

Examples

Launch the 'Foo' app to it's home screen.

JavaScript:

import { Discovery } from '@firebolt-js/sdk'

Discovery.launch("foo", {"action":"home","context":{"source":"voice"}})
    .then(success => {
        console.log(success)
    })

Value of success:

true

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "discovery.launch",
  "params": {
    "appId": "foo",
    "intent": {
      "action": "home",
      "context": {
        "source": "voice"
      }
    }
  }
}

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

import { Discovery } from '@firebolt-js/sdk'

Discovery.launch("foo",
                 {
                   "action": "entity",
                   "data": {
                     "entityType": "program",
                     "programType": "movie",
                     "entityId": "example-movie-id"
                   },
                   "context": {
                     "source": "voice"
                   }
                 })
    .then(success => {
        console.log(success)
    })

true

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "discovery.launch",
  "params": {
    "appId": "foo",
    "intent": {
      "action": "entity",
      "data": {
        "entityType": "program",
        "programType": "movie",
        "entityId": "example-movie-id"
      },
      "context": {
        "source": "voice"
      }
    }
  }
}

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

import { Discovery } from '@firebolt-js/sdk'

Discovery.launch("foo",
                 {
                   "action": "playback",
                   "data": {
                     "entityType": "program",
                     "programType": "movie",
                     "entityId": "example-movie-id"
                   },
                   "context": {
                     "source": "voice"
                   }
                 })
    .then(success => {
        console.log(success)
    })

true

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "discovery.launch",
  "params": {
    "appId": "foo",
    "intent": {
      "action": "playback",
      "data": {
        "entityType": "program",
        "programType": "movie",
        "entityId": "example-movie-id"
      },
      "context": {
        "source": "voice"
      }
    }
  }
}

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

import { Discovery } from '@firebolt-js/sdk'

Discovery.launch("urn:firebolt:apps:main",
                 {
                   "action": "entity",
                   "data": {
                     "entityType": "program",
                     "programType": "movie",
                     "entityId": "example-movie-id"
                   },
                   "context": {
                     "source": "voice"
                   }
                 })
    .then(success => {
        console.log(success)
    })

true

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "discovery.launch",
  "params": {
    "appId": "urn:firebolt:apps:main",
    "intent": {
      "action": "entity",
      "data": {
        "entityType": "program",
        "programType": "movie",
        "entityId": "example-movie-id"
      },
      "context": {
        "source": "voice"
      }
    }
  }
}

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

import { Discovery } from '@firebolt-js/sdk'

Discovery.launch("urn:firebolt:apps:main",
                 {
                   "action": "section",
                   "data": {
                     "sectionName": "company:foo"
                   },
                   "context": {
                     "source": "voice"
                   }
                 })
    .then(success => {
        console.log(success)
    })

true

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "discovery.launch",
  "params": {
    "appId": "urn:firebolt:apps:main",
    "intent": {
      "action": "section",
      "data": {
        "sectionName": "company:foo"
      },
      "context": {
        "source": "voice"
      }
    }
  }
}

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

import { Discovery } from '@firebolt-js/sdk'

Discovery.launch("urn:firebolt:apps:main", {"action":"home","context":{"source":"voice"}})
    .then(success => {
        console.log(success)
    })

true

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "discovery.launch",
  "params": {
    "appId": "urn:firebolt:apps:main",
    "intent": {
      "action": "home",
      "context": {
        "source": "voice"
      }
    }
  }
}

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

import { Discovery } from '@firebolt-js/sdk'

Discovery.launch("urn:firebolt:apps:main", {"action":"search","context":{"source":"voice"}})
    .then(success => {
        console.log(success)
    })

true

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "discovery.launch",
  "params": {
    "appId": "urn:firebolt:apps:main",
    "intent": {
      "action": "search",
      "context": {
        "source": "voice"
      }
    }
  }
}

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

import { Discovery } from '@firebolt-js/sdk'

Discovery.launch("urn:firebolt:apps:main",
                 {
                   "action": "section",
                   "data": {
                     "sectionName": "settings"
                   },
                   "context": {
                     "source": "voice"
                   }
                 })
    .then(success => {
        console.log(success)
    })

true

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "discovery.launch",
  "params": {
    "appId": "urn:firebolt:apps:main",
    "intent": {
      "action": "section",
      "data": {
        "sectionName": "settings"
      },
      "context": {
        "source": "voice"
      }
    }
  }
}

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

import { Discovery } from '@firebolt-js/sdk'

Discovery.launch("urn:firebolt:apps:main",
                 {
                   "action": "section",
                   "data": {
                     "sectionName": "guide"
                   },
                   "context": {
                     "source": "voice"
                   }
                 })
    .then(success => {
        console.log(success)
    })

true

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "discovery.launch",
  "params": {
    "appId": "urn:firebolt:apps:main",
    "intent": {
      "action": "section",
      "data": {
        "sectionName": "guide"
      },
      "context": {
        "source": "voice"
      }
    }
  }
}

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

import { Discovery } from '@firebolt-js/sdk'

Discovery.launch("urn:firebolt:apps:main",
                 {
                   "action": "section",
                   "data": {
                     "sectionName": "app:foo"
                   },
                   "context": {
                     "source": "voice"
                   }
                 })
    .then(success => {
        console.log(success)
    })

true

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "discovery.launch",
  "params": {
    "appId": "urn:firebolt:apps:main",
    "intent": {
      "action": "section",
      "data": {
        "sectionName": "app:foo"
      },
      "context": {
        "source": "voice"
      }
    }
  }
}

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

listen

Listen for events from this module.

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

Discovery.listen(event: string, (data: any) => void): Promise<number>

Parameters:

Promise resolution:

Callback parameters:

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

Discovery.listen((event: string, data: any) => void): Promise<number>

Parameters:

Callback parameters:

Promise resolution:

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:

Discovery.once(event: string, (data: any) => void): Promise<number>

Parameters:

Promise resolution:

Callback parameters:

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

Discovery.once((event: string, data: any) => void): Promise<number>

Parameters:

Callback parameters:

Promise resolution:

See Listening for events for more information and examples.

policy

get the discovery policy

To get the value of policy call the method like this:

function policy(): Promise<DiscoveryPolicy>

Promise resolution:

Examples

Getting the discovery policy

JavaScript:

import { Discovery } from '@firebolt-js/sdk'

Discovery.policy()
    .then(policy => {
        console.log(policy)
    })

Value of policy:

{
  "enableRecommendations": true,
  "shareWatchHistory": true,
  "rememberWatchedPrograms": true
}

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "discovery.policy",
  "params": {}
}

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "enableRecommendations": true,
    "shareWatchHistory": true,
    "rememberWatchedPrograms": true
  }
}

To set the value of policy call the method like this:

function policy(): Promise<ListenResponse | DiscoveryPolicy>

Parameters:

Promise resolution:

Examples

Getting the discovery policy

JavaScript:

import { Discovery } from '@firebolt-js/sdk'

Discovery.policy(true)

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "discovery.policy",
  "params": {}
}

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "enableRecommendations": true,
    "shareWatchHistory": true,
    "rememberWatchedPrograms": true
  }
}

To subscribe to notifications when the value changes, call the method like this:

function policy (subscriber: () => void): Promise<listenerId>

Parameters:

Promise resolution:

Callback parameters:

Examples

JavaScript:

import { Discovery } from '@firebolt-js/sdk'

Discovery.policy((value) => {
  // property value was changed
  console.log(value)
}).then(listenerId => {
  // you can clear this listener w/ Discovery.clear(listenerId)
})

value of value:

{
  "jsonrpc": "2.0",
  "id": "1",
  "result": {
    "listening": "true"
  }
}

purchasedContent

Return content purchased by the user, such as rentals and electronic sell through purchases.

The app should return the user's 100 most recent purchases in entries. The total count of purchases must be provided in count. If count is greater than the total number of entries, the UI may provide a link into the app to see the complete purchase list.

The EntityInfo object returned is not required to have waysToWatch populated, but it is recommended that it do so in case the UI wants to surface additional information on the purchases screen.

The app should implement both Push and Pull methods for purchasedContent.

The app should actively push purchasedContent when:

• The app becomes Active.
• When the state of the purchasedContent set has changed.
• The app goes into Inactive or Background state, if there is a chance a change event has been missed.

To allow the platform to pull data, use purchasedContent(callback):

function purchasedContent(callback: (parameters: PurchasedContentParameters) => Promise<PurchasedContentResult>): Promise<boolean>

Parameters:

Promise resolution:

Callback parameters:

Callback promise resolution:

Examples

Inform the platform of the user's purchased content (Pull)

JavaScript:

Discovery.purchasedContent(function(parameters) {
  return Promise.resolve({
  "correlationId": null,
  "result": {
    "totalCount": 10,
    "expires": "2025-01-01T00:00:00.000Z",
    "entries": [
      {
        "identifiers": {
          "entityId": "345"
        },
        "entityType": "program",
        "programType": "movie",
        "title": "Cool Runnings",
        "synopsis": "Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Pulvinar sapien et ligula ullamcorper malesuada proin libero nunc.",
        "releaseDate": "1993-01-01T00:00:00.000Z",
        "contentRatings": [
          {
            "scheme": "US-Movie",
            "rating": "PG"
          },
          {
            "scheme": "CA-Movie",
            "rating": "G"
          }
        ],
        "waysToWatch": [
          {
            "identifiers": {
              "assetId": "123"
            },
            "expires": "2025-01-01T00:00:00.000Z",
            "entitled": true,
            "entitledExpires": "2025-01-01T00:00:00.000Z",
            "offeringType": "buy",
            "price": 2.99,
            "videoQuality": [
              "UHD"
            ],
            "audioProfile": [
              "dolbyAtmos"
            ],
            "audioLanguages": [
              "en"
            ],
            "closedCaptions": [
              "en"
            ],
            "subtitles": [
              "es"
            ],
            "audioDescriptions": [
              "en"
            ]
          }
        ]
      }
    ]
  }
})
}).then(success => {
  console.log(success)
})

Value of success

true

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "discovery.purchasedContent",
  "params": {
    "correlationId": "xyz",
    "result": {}
  }
}

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

To push data to the platform, e.g. during app launch, use purchasedContent(correlationId: string, result: PurchasedContentResult):

function purchasedContent(correlationId: string, result: PurchasedContentResult): Promise<boolean>

Parameters:

Promise resolution:

boolean

Examples

Inform the platform of the user's purchased content

JavaScript:

import { Discovery } from ''

Discovery.purchasedContent(null,
                           {
                             "totalCount": 10,
                             "expires": "2025-01-01T00:00:00.000Z",
                             "entries": [
                               {
                                 "identifiers": {
                                   "entityId": "345"
                                 },
                                 "entityType": "program",
                                 "programType": "movie",
                                 "title": "Cool Runnings",
                                 "synopsis": "Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Pulvinar sapien et ligula ullamcorper malesuada proin libero nunc.",
                                 "releaseDate": "1993-01-01T00:00:00.000Z",
                                 "contentRatings": [
                                   {
                                     "scheme": "US-Movie",
                                     "rating": "PG"
                                   },
                                   {
                                     "scheme": "CA-Movie",
                                     "rating": "G"
                                   }
                                 ],
                                 "waysToWatch": [
                                   {
                                     "identifiers": {
                                       "assetId": "123"
                                     },
                                     "expires": "2025-01-01T00:00:00.000Z",
                                     "entitled": true,
                                     "entitledExpires": "2025-01-01T00:00:00.000Z",
                                     "offeringType": "buy",
                                     "price": 2.99,
                                     "videoQuality": [
                                       "UHD"
                                     ],
                                     "audioProfile": [
                                       "dolbyAtmos"
                                     ],
                                     "audioLanguages": [
                                       "en"
                                     ],
                                     "closedCaptions": [
                                       "en"
                                     ],
                                     "subtitles": [
                                       "es"
                                     ],
                                     "audioDescriptions": [
                                       "en"
                                     ]
                                   }
                                 ]
                               }
                             ]
                           })

Value of success

true

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "discovery.purchasedContent",
  "params": {
    "correlationId": null,
    "result": {
      "totalCount": 10,
      "expires": "2025-01-01T00:00:00.000Z",
      "entries": [
        {
          "identifiers": {
            "entityId": "345"
          },
          "entityType": "program",
          "programType": "movie",
          "title": "Cool Runnings",
          "synopsis": "Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Pulvinar sapien et ligula ullamcorper malesuada proin libero nunc.",
          "releaseDate": "1993-01-01T00:00:00.000Z",
          "contentRatings": [
            {
              "scheme": "US-Movie",
              "rating": "PG"
            },
            {
              "scheme": "CA-Movie",
              "rating": "G"
            }
          ],
          "waysToWatch": [
            {
              "identifiers": {
                "assetId": "123"
              },
              "expires": "2025-01-01T00:00:00.000Z",
              "entitled": true,
              "entitledExpires": "2025-01-01T00:00:00.000Z",
              "offeringType": "buy",
              "price": 2.99,
              "videoQuality": [
                "UHD"
              ],
              "audioProfile": [
                "dolbyAtmos"
              ],
              "audioLanguages": [
                "en"
              ],
              "closedCaptions": [
                "en"
              ],
              "subtitles": [
                "es"
              ],
              "audioDescriptions": [
                "en"
              ]
            }
          ]
        }
      ]
    }
  }
}

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

signIn

Inform the platform that your user is signed in, for increased visiblity in search & discovery. Sign-in state is used separately from what content can be access through entitlements and availabilities. Sign-in state may be used when deciding whether to choose this app to handle a user intent. For instance, if the user tries to launch something generic like playing music from an artist, only a signed-in app will be chosen. If the user wants to tune to a channel, only a signed-in app will be chosen to handle that intent. While signIn can optionally include entitlements as those typically change at signIn time, it is recommended to make a separate call to Discovery.contentAccess for entitlements. signIn is not only for when a user explicitly enters login credentials. If an app does not require any credentials from the user to consume content, such as in a free app, then the app should call signIn immediately on launch.

function signIn(entitlements?: Entitlement[]): Promise<boolean>

Parameters:

Promise resolution:

Examples

Send signIn metric

JavaScript:

import { Discovery } from '@firebolt-js/sdk'

Discovery.signIn(null)
    .then(success => {
        console.log(success)
    })

Value of success:

true

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "discovery.signIn",
  "params": {}
}

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

import { Discovery } from '@firebolt-js/sdk'

Discovery.signIn([
                   {
                     "entitlementId": "123",
                     "startTime": "2025-01-01T00:00:00.000Z",
                     "endTime": "2025-01-01T00:00:00.000Z"
                   }
                 ])
    .then(success => {
        console.log(success)
    })

true

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "discovery.signIn",
  "params": {
    "entitlements": [
      {
        "entitlementId": "123",
        "startTime": "2025-01-01T00:00:00.000Z",
        "endTime": "2025-01-01T00:00:00.000Z"
      }
    ]
  }
}

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

signOut

Inform the platform that your user has signed out. See Discovery.signIn for more details on how the sign-in state is used.signOut will NOT clear entitlements, the app should make a separate call to Discovery.clearContentAccess. Apps should also call signOut when a login token has expired and the user is now in a signed-out state.

function signOut(): Promise<boolean>

Promise resolution:

Examples

Send signOut notification

JavaScript:

import { Discovery } from '@firebolt-js/sdk'

Discovery.signOut()
    .then(success => {
        console.log(success)
    })

Value of success:

true

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "discovery.signOut",
  "params": {}
}

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

watched

Notify the platform that content was partially or completely watched

function watched(entityId: string, progress?: number, completed?: boolean, watchedOn?: string): Promise<boolean>

Parameters:

Promise resolution:

Examples

Notifying the platform of watched content

JavaScript:

import { Discovery } from '@firebolt-js/sdk'

Discovery.watched("partner.com/entity/123", 0.95, true, "2021-04-23T18:25:43.511Z")
    .then(success => {
        console.log(success)
    })

Value of success:

true

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "discovery.watched",
  "params": {
    "entityId": "partner.com/entity/123",
    "progress": 0.95,
    "completed": true,
    "watchedOn": "2021-04-23T18:25:43.511Z"
  }
}

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

watchNext

Suggest a call-to-action for this app on the platform home screen

function watchNext(title?: LocalizedString, identifiers?: ContentIdentifiers, expires?: string, images?: object): Promise<boolean>

Parameters:

Promise resolution:

Examples

Suggest a watch-next tile for the home screen

JavaScript:

import { Discovery } from '@firebolt-js/sdk'

Discovery.watchNext("A Cool Show",
                    {
                      "entityId": "partner.com/entity/123"
                    },
                    "2021-04-23T18:25:43.511Z",
                    {
                      "3x4": {
                        "en-US": "https://i.ytimg.com/vi/4r7wHMg5Yjg/maxresdefault.jpg",
                        "es": "https://i.ytimg.com/vi/4r7wHMg5Yjg/maxresdefault.jpg"
                      },
                      "16x9": {
                        "en": "https://i.ytimg.com/vi/4r7wHMg5Yjg/maxresdefault.jpg"
                      }
                    })
    .then(success => {
        console.log(success)
    })

Value of success:

true

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "discovery.watchNext",
  "params": {
    "title": "A Cool Show",
    "identifiers": {
      "entityId": "partner.com/entity/123"
    },
    "expires": "2021-04-23T18:25:43.511Z",
    "images": {
      "3x4": {
        "en-US": "https://i.ytimg.com/vi/4r7wHMg5Yjg/maxresdefault.jpg",
        "es": "https://i.ytimg.com/vi/4r7wHMg5Yjg/maxresdefault.jpg"
      },
      "16x9": {
        "en": "https://i.ytimg.com/vi/4r7wHMg5Yjg/maxresdefault.jpg"
      }
    }
  }
}

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

Events

navigateTo

listen to navigateTo events

See also: listen(), once(), clear().

Event value:

Examples

Listening for navigateTo events:

JavaScript:

import { Discovery } from '@firebolt-js/sdk'

Discovery.listen('navigateTo', value => {
  console.log(value)
})

Value of value

{
  "action": "search",
  "data": {
    "query": "a cool show"
  },
  "context": {
    "campaign": "unknown",
    "source": "voice"
  }
}

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "discovery.onNavigateTo",
  "params": {
    "listen": true
  }
}

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "action": "search",
    "data": {
      "query": "a cool show"
    },
    "context": {
      "campaign": "unknown",
      "source": "voice"
    }
  }
}

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.

Schemas

DiscoveryPolicy

type DiscoveryPolicy = {
  enableRecommendations: boolean    // Whether or not to the user has enabled history-based recommendations
  shareWatchHistory: boolean        // Whether or not the user has enabled app watch history data to be shared with the platform
  rememberWatchedPrograms: boolean  // Whether or not the user has enabled watch history
}

EntityInfo

An EntityInfo object represents an "entity" on the platform. Currently, only entities of type program are supported. programType must be supplied to identify the program type.

Additionally, EntityInfo objects must specify a properly formed
ContentIdentifiers object, entityType, and title. The app should provide
the synopsis property for a good user experience if the contentmetadata is not available another way

The ContentIdentifiers must be sufficient for navigating the user to the
appropriate entity or detail screen via a detail intent or deep link.
EntityInfo objects must provide at least one WayToWatch object when returned as
part of an entityInfo method and a streamable asset is available to the user.
It is optional for the purchasedContent method, but recommended because the UI
may use those data.

type EntityInfo = {
  identifiers: ContentIdentifiers   // The ContentIdentifiers object is how the app identifies an entity or asset to
  title: string                     // Title of the entity.
  entityType: "program"
  programType: ProgramType          // In the case of a program `entityType`, specifies the program type.
  synopsis?: string                 // Short description of the entity.
  seasonNumber?: number             // For TV seasons, the season number. For TV episodes, the season that the episode belongs to.
  episodeNumber?: number            // For TV episodes, the episode number.
  releaseDate?: string              // The date that the program or entity was released or first aired.
  contentRatings?: ContentRating[]  // A list of ContentRating objects, describing the entity's ratings in various rating schemes.
  waysToWatch?: WayToWatch[]        // An array of ways a user is might watch this entity, regardless of entitlements.
}

See also:

• ProgramType

WayToWatch

A WayToWatch describes a way to watch a video program. It may describe a single
streamable asset or a set of streamable assets. For example, an app provider may
describe HD, SD, and UHD assets as individual WayToWatch objects or rolled into
a single WayToWatch.

If the WayToWatch represents a single streamable asset, the provided
ContentIdentifiers must be sufficient to play back the specific asset when sent
via a playback intent or deep link. If the WayToWatch represents multiple
streamable assets, the provided ContentIdentifiers must be sufficient to
playback one of the assets represented with no user action. In this scenario,
the app SHOULD choose the best asset for the user based on their device and
settings. The ContentIdentifiers MUST also be sufficient for navigating the user
to the appropriate entity or detail screen via an entity intent.

The app should set the entitled property to indicate if the user can watch, or
not watch, the asset without making a purchase. If the entitlement is known to
expire at a certain time (e.g., a rental), the app should also provide the
entitledExpires property. If the entitlement is not expired, the UI will use
the entitled property to display watchable assets to the user, adjust how
assets are presented to the user, and how intents into the app are generated.
For example, the Aggregated Experience could render a "Watch" button for an
entitled asset versus a "Subscribe" button for an non-entitled asset.

The app should set the offeringType to define how the content may be
authorized. The UI will use this to adjust how content is presented to the user.

A single WayToWatch cannot represent streamable assets available via multiple
purchase paths. If, for example, an asset has both Buy, Rent and Subscription
availability, the three different entitlement paths MUST be represented as
multiple WayToWatch objects.

price should be populated for WayToWatch objects with buy or rent
offeringType. If the WayToWatch represents a set of assets with various price
points, the price provided must be the lowest available price.

type WayToWatch = {
  identifiers: ContentIdentifiers       // The ContentIdentifiers object is how the app identifies an entity or asset to
  expires?: string                      // Time when the WayToWatch is no longer available.
  entitled?: boolean                    // Specify if the user is entitled to watch the entity.
  entitledExpires?: string              // Time when the entity is no longer entitled.
  offeringType?: OfferingType           // The offering type of the WayToWatch.
  hasAds?: boolean                      // True if the streamable asset contains ads.
  price?: number                        // For "buy" and "rent" WayToWatch, the price to buy or rent in the user's preferred currency.
  videoQuality?: 'SD' | 'HD' | 'UHD'[]  // List of the video qualities available via the WayToWatch.
  audioProfile?: AudioProfile[]         // List of the audio types available via the WayToWatch.
  audioLanguages?: string[]             // List of audio track languages available on the WayToWatch. The first is considered the primary language. Languages are expressed as ISO 639 1/2 codes.
  closedCaptions?: string[]             // List of languages for which closed captions are available on the WayToWatch. Languages are expressed as ISO 639 1/2 codes.
  subtitles?: string[]                  // List of languages for which subtitles are available on the WayToWatch. Languages are expressed as ISO 639 1/2 codes.
  audioDescriptions?: string[]          // List of languages for which audio descriptions (DVS) are available on the WayToWatch. Languages are expressed as ISO 639 1/2 codes.
}

See also:

• OfferingType
• AudioProfile

ContentRating

A ContentRating represents an age or content based of an entity. Supported rating schemes and associated types are below.

United States

US-Movie (MPAA):

Ratings: NR, G, PG, PG13, R, NC17

Advisories: AT, BN, SL, SS, N, V

US-TV (Vchip):

Ratings: TVY, TVY7, TVG, TVPG, TV14, TVMA

Advisories: FV, D, L, S, V

Canada

CA-Movie (OFRB):

Ratings: G, PG, 14A, 18A, R, E

CA-TV (AGVOT)

Ratings: E, C, C8, G, PG, 14+, 18+

Advisories: C, C8, G, PG, 14+, 18+

CA-Movie-Fr (Canadian French language movies):

Ratings: G, 8+, 13+, 16+, 18+

CA-TV-Fr (Canadian French language TV):

Ratings: G, 8+, 13+, 16+, 18+

type ContentRating = {
  scheme: 'CA-Movie' | 'CA-TV' | 'CA-Movie-Fr' | 'CA-TV-Fr' | 'US-Movie' | 'US-TV'  // The rating scheme.
  rating: string                                                                    // The content rating.
  advisories?: string[]                                                             // Optional list of subratings or content advisories.
}

ContentIdentifiers

The ContentIdentifiers object is how the app identifies an entity or asset to
the Firebolt platform. These ids are used to look up metadata and deep link into
the app.

Apps do not need to provide all ids. They only need to provide the minimum
required to target a playable stream or an entity detail screen via a deep link.
If an id isn't needed to get to those pages, it doesn't need to be included.

type ContentIdentifiers = {
  assetId?: string           // Identifies a particular playable asset. For example, the HD version of a particular movie separate from the UHD version.
  entityId?: string          // Identifies an entity, such as a Movie, TV Series or TV Episode.
  seasonId?: string          // The TV Season for a TV Episode.
  seriesId?: string          // The TV Series for a TV Episode or TV Season.
  appContentData?: string    // App-specific content identifiers.
}

FederatedRequest

type FederatedRequest = {
  correlationId: string
}

FederatedResponse

type FederatedResponse = {
  correlationId: string
}

EntityInfoFederatedRequest

type EntityInfoFederatedRequest = {
  correlationId: string
  parameters: EntityInfoParameters
}

EntityInfoParameters

type EntityInfoParameters = {
  entityId: string
  assetId?: string
}

EntityInfoFederatedResponse

type EntityInfoFederatedResponse = {
  correlationId: string
  result: EntityInfoResult            // The result for an `entityInfo()` push or pull.
}

EntityInfoResult

The result for an entityInfo() push or pull.

type EntityInfoResult = {
  expires: string
  entity: EntityInfo       // An EntityInfo object represents an "entity" on the platform. Currently, only entities of type `program` are supported. `programType` must be supplied to identify the program type.
  related?: EntityInfo[]
}

PurchasedContentFederatedRequest

type PurchasedContentFederatedRequest = {
  correlationId: string
  parameters: PurchasedContentParameters
}

PurchasedContentParameters

type PurchasedContentParameters = {
  limit: number
  offeringType?: OfferingType        // The offering type of the WayToWatch.
  programType?: ProgramType          // In the case of a program `entityType`, specifies the program type.
}

See also:

• OfferingType
• ProgramType

PurchasedContentFederatedResponse

type PurchasedContentFederatedResponse = {
  correlationId: string
  result: PurchasedContentResult
}

PurchasedContentResult

type PurchasedContentResult = {
  expires: string
  totalCount: number
  entries: EntityInfo[]
}

Availability

type Availability = {
  type: 'channel-lineup' | 'program-lineup'
  id: string
  catalogId?: string
  startTime?: string
  endTime?: string
}

ContentAccessIdentifiers

type ContentAccessIdentifiers = {
  availabilities?: Availability[]  // A list of identifiers that represent what content is discoverable for the subscriber. Excluding availabilities will cause no change to the availabilities that are stored for this subscriber. Providing an empty array will clear the subscriber's availabilities
  entitlements?: Entitlement[]     // A list of identifiers that represent what content is consumable for the subscriber. Excluding entitlements will cause no change to the entitlements that are stored for this subscriber. Providing an empty array will clear the subscriber's entitlements
}

See also:

• Entitlement

TuneChannels

An enumeration of xrn values for the TuneIntent that have special meaning.

type TuneChannels = 'xrn:firebolt:channel:any'