Extension Helper public beta

Terminology

  • Extension: A piece of software that can be installed on OWN3D to add functionality.
  • ext-types: A set of typescript definitions for the extension helper.
  • Extension Helper: A piece of software run within the extension iframe that provides a set of functions communicate with the supervisor.
  • Extension Supervisor: A piece of software acting as a bridge between the extension and the OWN3D platform.

How this helper works

The extension helper is a piece of software that runs within the extension iframe. It provides a set of functions to communicate with the extension supervisor. The supervisor is within the OWN3D platform and acts as a bridge between the extension and the platform.

Use the extension helper within your extension

  1. Install the package for typed definitions
yarn add own3d/ext-types
  1. Add the extension helper script to your extension

This script must be added as the first script before any other scripts to pass the review.

<script src="https://extension-files.ext-own3d.tv/latest/own3d-ext.js"></script>
  1. Use the extension helper
<script>
  console.log(`Running ${OWN3D.ext.version} on ${OWN3D.ext.environment}`)

  OWN3D.ext.onAuthorized((data) => {
    console.log('onAuthorized', data)
  })

  OWN3D.ext.onContext((context, changed) => {
    for (const key of changed) {
      console.log(`Context changed ${context[key]}`)
    }
  })

  OWN3D.ext.socket.on('remote-config', (data) => {
    console.log('Config changed', data)
  })
</script>

API

OWN3D.ext

OWN3D.ext.version

Returns the version of the extension helper.

OWN3D.ext.environment

Returns the environment of the extension helper. Possible values are production and development.

OWN3D.ext.onAuthorized(callback)

Registers a callback that is called when the extension is authorized.

Parameters
  • callback - A function that is called when the extension is authorized.

The callback receives an object with the following properties:

ParameterTypeDescription
client_idstringThe client id of the extension.
client_tokenstringJWT token that can be used for OWN3D API requests. Usage of Extension Client Tokens
channel_idobjectThe user id of the channel where the extension is installed.
user_idobjectThe user id of the user who interacts with the extension.
scopesobjectThe scopes of the user who interacts with the extension.
tokenobjectJWT token that should be used for any Extension Backend request.
Example
OWN3D.ext.onAuthorized((data) => {
    console.log('onAuthorized', data)
})

OWN3D.ext.onContext(callback)

Registers a callback that is called when the context is updated.

Parameters
  • callback - A function that is called when the context is updated.
Example
OWN3D.ext.onContext((context, changed) => {
    for (const key of changed) {
        console.log(`Context changed ${context[key]}`)
    }
})

OWN3D.ext.coins

The coins module provides a set of functions to exchange coins for products. Coins are a digital good that can be purchased by users. Products are a set of items that can be exchanged for coins.

Products

Products are defined in the Developer Console. Products have a sku, a name, a cost. The cost is defined in coins. The cost is the amount of coins that are required to exchange for the product.

PropertyTypeDescription
skustringThe sku of the product.
namestringThe name of the product.
costCostThe cost of the product.
cost.amountnumberThe amount of coins that are required to exchange for the product.
cost.typestringThe type of the cost. Can be coins.
environmentstringThe environment of the product. Can be production or sandbox.

Transactions

A transaction is a record of an exchange of coins for a product.

PropertyTypeDescription
idstringThe id of the transaction.
client_idstringThe id of the client.
user_idstringThe id of the user.
channel_idstringThe id of the channel.
subscriptionSubscriptionThe subscription that was exchanged for coins.
productProductThe product that was exchanged for coins.
product.skustringThe sku of the product.
product.namestringThe name of the product.
product.costCostThe cost of the product.
product.cost.amountnumberThe amount of coins that are required to exchange for the product.
product.cost.typestringThe type of the cost. Can be coins.
product.environmentstringThe environment of the product. Can be production or sandbox.
product.recurrencestringThe recurrence of the product. Can be one-time or weekly, monthly or yearly.
metadataMetadataThe key-value map of metadata that was sent with the transaction.
statusstringThe status of the transaction. Can be pending, completed, cancelled or failed.

OWN3D.ext.coins.getProducts()

Returns a list of products available for exchange.

Example
OWN3D.ext.coins.getProducts().then((products) => {
    console.log('Got products', products)
})

OWN3D.ext.coins.showCoinsBalance()

Shows the current coins balance.

Example
OWN3D.ext.coins.showCoinsBalance()

OWN3D.ext.coins.useCoins(sku, metadata)

Exchange coins for a product.

Parameters
  • sku - The sku of the product to exchange coins for.
  • metadata - The metadata to send with the transaction.
Example
OWN3D.ext.coins.useCoins('test', { foo: 'bar' })

OWN3D.ext.coins.onTransactionComplete(callback)

Registers a callback that is called when a transaction is completed.

Parameters
  • callback - A function that is called when a transaction is completed.
Example
OWN3D.ext.coins.onTransactionComplete((transaction) => {
    console.log('Transaction completed', transaction)
})

OWN3D.ext.coins.onTransactionCancelled(callback)

Registers a callback that is called when a transaction is cancelled.

Parameters
  • callback - A function that is called when a transaction is cancelled.
Example
OWN3D.ext.coins.onTransactionCancelled((transaction) => {
    console.log('Transaction cancelled', transaction)
})

OWN3D.ext.socket

The socket module is an event emitter. It provides a set of functions, so you can listen to events from our event bus.

OWN3D.ext.socket.on(event, callback)

Example
OWN3D.ext.socket.on('remote-config', (data) => {
  console.log('Config changed', data)
})

OWN3D.ext.ipc

The ipc module is an event emitter. It provides a set of functions, so you can send messages from the extension to the supervisor and vice versa.

IPC Channels

In extensions, processes communicate by passing messages through developer-defined "channels" with the ipc module. These channels are arbitrary (you can name them whatever you want, but we recommend using something that describes the channel's purpose) and bidirectional (you can use the same channel name for both sides).

Understanding context-isolated processes

The extension helper runs in a context-isolated process. This means that the extension helper is running in a separate process than the supervisor. The supervisor is running in the OWN3D platform. The extension helper and the supervisor communicate with each other via the ipc module.

  • Extensions cannot directly access the DOM of the OWN3D platform.
  • Extensions cannot access cookies or local storage of the OWN3D platform.
  • Extensions cannot access the user session of the OWN3D platform without the user's consent.

OWN3D.ext.ipc.send(channel, payload)

Sends a message to the supervisor.

Parameters
  • channel - The channel to send the message to.
  • payload - The payload to send.
Example
OWN3D.ext.ipc.send('test', { foo: 'bar' })

OWN3D.ext.ipc.on(channel, listener)

Registers a listener for a channel.

Parameters
  • channel - The channel to listen to.
  • listener - A function that is called when a message is received.
Example
OWN3D.ext.ipc.on('test', (payload) => {
    console.log('Got test message', payload)
})

OWN3D.ext.config public beta

WARNING

Do not store sensitive data in the Remote Config! The Remote Config is not encrypted and can be accessed by anyone who interacts with the extension.

The config namespace allows streamers and developers to store and retrieve data. To learn more about the Remote Config Service, see the Remote Config documentation.

OWN3D.ext.config.getSegments(): Promise<ConfigSegments> public beta

Get all segments.

Example
OWN3D.ext.config.getSegments().then((segments) => {
    console.log('Segments', segments)
})

OWN3D.ext.config.setSegment(segment, content): Promise<void> public beta

Set the value of a key.

Parameters
  • segment - The segment to set the value of.
  • content - The content to set (object).
Example
OWN3D.ext.config.setSegment('test', { foo: 'bar' })

OWN3D.ext.features closed beta

WARNING

The OWN3D.ext.features module is currently not supported in the public beta.

The feature-flag namespace provides information about the current global feature flags.

OWN3D.ext.features.isEnabled(feature: string) closed beta

Returns whether the current feature flag is enabled.

Parameters
  • feature - The feature to check.
Example
if (OWN3D.ext.features.isEnabled('feature-flag')) {
    console.log('Feature flag is enabled')
}

OWN3D.ext.features.getFeatures() closed beta

Returns a list of all available feature flags.

Example
console.log('Features', OWN3D.ext.features.getFeatures())
// Features [ 'feature-flag' ]