Skip to main content
Version: 4.2.x

How-tos • XDK recipes

This document will show how to interact with connected devices using XDK capabilities. How to use this guide

  • Examples are organized from more simple to more complex
  • The examples may not include all the steps. i.e., If we are talking about how to play DRM content, the definition of the URL will be avoided, as it has previously defined.
  • We recommend using the vanilla application as a playground to experiment with XDK
  • If you miss some part of the documentation, ask for it on the #group-js slack group


​

How to add new device modules in your project​

How to install XDK​

Before you start to use XDK, you will need to install the required dependencies.

npm i @accedo/xdk-base-modules @accedo/xdk-config @accedo/xdk-core @accedo/xdk-domready @accedo/xdk-virtual-key

You will also need to install the required device packages.

npm i @accedo/xdk-device-workstation
npm i @accedo/xdk-device-playstation-msdk

How to configure XDK​

Before you start to use XDK, you will need to set it up.

Usually, we name the config file xdk.config.js as a convention.

The config file is required to include the targeted devices in our applications.

It also allows us to do a fine-tuning of the included device packages.

import workstation, { ID as WORKSTATION } from '@accedo/xdk-device-workstation';

const CONFIG = {
  devices: {
    packages: [workstation],
    details: {
      // overrides the default configurations
      [WORKSTATION]: {
        cookieName: 'app-name-cookie'
      }
    }
  },
  storages: {
    cookie: {
      name: 'global-cookie-name'
    }
  },
  media: {
    guessProtocolByUrl: (url, option) => {
      // your logic here
    }
  },
  logging: {
    // logging options
  }
};

Setup your XDK Application​

XDK and modern JS applications can require polyfills to support features that may not be available on some connected devices.

XDK Application should be transpiled for ES5 if you target multiple devices.

// usually this goes to a preflight.js file

// load of polyfills. You may add more polyfills like a smooth scroll or any other
import 'core-js';
import 'raf/polyfill';

// load of xdk config
import xdkConfigStore from '@accedo/xdk-config';
import config from './xdk.config';

// pre configure XDK
xdkConfigStore.load(config);

Load XDK library and get an XDK instance​

To load XDK, you will need to

  1. Load the configuration
  2. Init the library
  3. Use the instance
// usually this is done on a 'preflight' file
import './preflight'; // see Setup your XDK Application
import xdk, * as XDK from '@accedo/xdk-core';

await xdk.load(); // now xdk will contain an initialised xdk instance

How to configure a XDK device​

Under this section you will learn how to modify the device configuration thanks to the @accedo/xdk-config DeviceConfig helpers

How to capture the EXIT button on Samsung​

This was the default behaviour in the platform "@accedo/xdk-device-samsung-tizen" below to v4.2.4 We have corrected the behaviour and now is false by default. If you want to revert it you can set the register-exit-key platform specific parameter to true.

xdk.config.js
import tizen, {ID as TIZEN}  from '@accedo/xdk-device-samsung-tizen';

const CONFIG = {
  devices: {
    packages: [
      // ... other platforms
      tizen
      // ... more platforms
    ],
    details: {
      [TIZEN]: {
        ['register-exit-key']: true
      }
    }
  }
}

export default CONFIG;

How to extend/override your device keymap​

By default, XDK devices have their own TVKey dependency inside the System.js module logic.

In order to allow a basic extension/override of the keymaps we have added a new method setKeyMapping

For more info regarding the available standar keys please go to the @accedo/xdk-virtual-key vKey.js file.

xdk.config.js
import workstation, {ID as WORKSTATION}  from '@accedo/xdk-device-workstation' ;
import { vKey } from '@accedo/xdk-base-modules';

workstation
  .setKeyMapping({
          chars: {
            [81]: {id: 'device:kb-vkey:k',text: 'l'}
          },
          // more priority than the chars object
          // overrides the preset chars
          keys: {
            [81]: vKey.EXIT
          }
        })

How to add a new player​

By default, XDK devices provides the most native player available for the device, following the directions from the available documentation.

In some cases, you may need to use an HTML5 based player, like hls.js or shaka-player.

You can do it following the next snippet

xdk.config.js
import { shaka, hlsjs } from '@accedo/xdk-players-contrib'
import workstation, {ID as WORKSTATION}  from '@accedo/xdk-device-workstation' ;

const hlsConfig = {
  // here your custom hls.js configuration;
};

const shakaConfig = {
  // here your custom shaka configuration
};

export default {
  devices: {
    packages: [
      workstation
        .addPlayer(hls, hlsConfig)
        .addPlayer(shaka, shakaConfig)
    ]
  }
}

How to remove all device players​

Under some circustamces, you may need to override the device player configuration completely.

In order to do it, we provide the DeviceConfig.removeAllPlayers() method:

xdk.config.js
import workstation, {ID as WORKSTATION}  from '@accedo/xdk-device-workstation' ;

export default {
  devices: {
    packages: [
      workstation
        .removeAllPlayers() // now there are no players availables
        .addPlayer()        // but you can keep adding them as usual ;D
    ]
  }
}

How to add new storage to the device​

If you need to implement your own storage for an existing device, you can set it with the next snippet

xdk.config.js
import workstation, {ID as WORKSTATION}  from '@accedo/xdk-device-workstation' ;
import storageConfig from '../path/to/your/storage/config/file'

export default {
  devices: {
    packages: [
      workstation
        .addStorage(storageConfig)
    ]
  }
}

How to override the detection function of a device​

By default, xdk.load() iterates all the devices list trying to find a device that returns a true when it executes the detect function.

Under some circustances, the detection function may fail for a specific platform/device.

If you want or need to force the detection of one device, you can do it following the next code snippet

xdk.config.js
import workstation, {ID as WORKSTATION}  from '@accedo/xdk-device-workstation' ;
import detectionFn from '../path/to/your/detection/function/file'

export default {
  devices: {
    packages: [
      workstation
        .overrideDetection(detectionFn)
    ]
  }
}

You can also define a function with the detection defined on it

xdk.config.js
import workstation, {ID as WORKSTATION}  from '@accedo/xdk-device-workstation' ;
const failDetection = () => {
  return Promise.resolve({default: false});
}
export default {
  devices: {
    packages: [
      workstation
        .overrideDetection(failDetection)
    ]
  }
}

How to force the detection of a device​

By default, xdk.load() iterates all the devices list trying to find a device that returns a true when it executes the detect function.

Under some circustances, the detection function may fail for a specific platform/device.

If you want or need to force the detection of one device, you can do it following the next code snippet

xdk.config.js
import workstation, {ID as WORKSTATION}  from '@accedo/xdk-device-workstation' ;

export default {
  devices: {
    packages: [
      workstation
        .forceDetection(true)
    ]
  }
}

How to add an extension​

If you need to add a XDK extension, like the TTS, use the next snippet

xdk.config.js
import workstation, {ID as WORKSTATION}  from '@accedo/xdk-device-workstation' ;
import { tts }  from '@accedo/xdk-extensions-contrib'
const { html5: html5TtsConfig  } = tts;

export default {
  devices: {
    packages: [
      workstation
        .addExtension(html5TtsConfig)
    ]
  }
}

How to replace the network configuration​

Important, this only changes the configuration passed to the network module, not the network module itself.

xdk.config.js
import workstation, {ID as WORKSTATION}  from '@accedo/xdk-device-workstation' ;

const networkConfig = {
  polling: {
    interval: 15
  }
};

export default {
  devices: {
    packages: [
      workstation
        .replaceNetwork(networkConfig)
    ]
  }
}

How to replace the network module​

If you want to move from the platform default network module (in charge of notify when the device gets disconnected from internet, among other methods) you will need to:

  1. Create an application local XDK platform package folder
  2. Add at least the files described in the next code block
  3. Point your XDK config to the new local device with the desired configuration

For a more detailed example please visit the vanilla generator. Workstation is using this approach.

warning

Note: You should only do this if the current implementated Network model is not working as the new Network model will be added to the base one, ending in two working implementations with sepate internal Environment event trigger

The new folders should look like this

project/
  src/
    config/
      xdk.config.js           --> Target platform will point to the local files
    xdk-local-modules/
      xdk-platform-name/      --> Replacement for the official XDK platform module. Only overrides a minimal set of methods
        index.js              --> Default exports required to use this platform on the detection stage
        config.js             --> Overrides the XDK module config pointing to the local DevicePackage.js one
        DevicePackage.js      --> Overrides the XDK module DevicePackage pointing to the local Syste.js one
        System.js             --> Overrides the XDK module System init method to load the local Network.js file
        Network.js            --> Local replacement for Network. Can be your new implementation scrath or an extension using inheritance and overriding desired methods

Now you will need to point to the newly created configuration from your xdk.config.js​

How to detect the current device from the Application​

Usually, adding if/else/switch clauses based on the detected device is a bad practice. Report the use case and try to fix it on the device abstractions

If you need to detect what device has been loaded, you can retrieve the ID from the device config with the following recipe.

import {ID as WORKSTATION} from '@accedo/xdk-device-workstation';
import {ID as VIZIO} from '@accedo/xdk-device-vizio-contrib';

switch (xdk.platform) {
  case WORKSTATION: 
    // your logic for workstation
    break;
  case VIZIO: 
    // your logic for vizio
    break;
  default:
    // any other case
    break;
}

How to create a new device package platform abstraction​

Please follow the How to make a new XDK device package confluence guide.

Please check the platforms/xdk-device-dummy-package example implementation.

How to develop​

npm i
npm start
npm i
npm run start:vanilla

To speed up the development workflow, we have set up a script that does the following actions for you:

  1. Transpile all the XDK modules
  2. Watch for any change on the modules
  3. Launch a test app to verify all your changes.
    • The test app will reload if you change any XDK source file

After launching the application, you will be able to open it on any device and start to hack XDK4 by changing the configurations, adding more devices or applying a hotfix.

How to play content​

In this section, you will find how to play different kinds of content and access multiple video playback capabilities.

This includes how to play video or more complex flows like DRM, subtitles support, change the audio tracks or the default behaviour to guess the stream protocol.

How to check playback capabilities in the config​

In this section, you will find how to check the different playback capabilities.

First, you should look into the README.md file of the device package to check what is supposed to be supported.

Just open the device package defaultConfig.js or the project xdk.config.js files to check the device configuration.

Our device supports DRM, audio tracks, and subtitles in the following example.

defaultConfig[PLAYERS] = [{
  id: 'playstation-player',
  importer: () => import(`./player/UVPlayer.js`),
  extensions: [{
    type: 'drm',
    importer: () => import('./player/extension/PlayreadyDRMAgent.js'),
    config: {
      scheme: 'playready'
    }
  },
  {
    type: 'audio-track',
    importer: () => import('./player/extension/UVPlayerAudioStrategy.js')
  },
  {
    type: 'subtitle',
    importer: () =>
      import('./player/extension/UVPlayerSubtitlesStrategy.js'),
    config: {
      location: 'internal'
    }
  }
}];

How to play an MP4 file​

In this example, we have shown how to play a regular mp4 file.

const URL =
  '//d1knl4odus8cue.cloudfront.net/bbb/bbb_sunflower_1080p_60fps_normal.mp4';
const playObject = {}; // object with the playback options, like DRM, subtitles, etc
xdk.media.load(url, playObject);
xdk.media.play();

How to add needed attributes to HTML5 video player​

For those devices that use HTML5 players, you can pass extra attributes within the videoHtmlAttributes object. For example, this is useful for content with a cross-origin attribute.

const URL =
  '//d1knl4odus8cue.cloudfront.net/bbb/bbb_sunflower_1080p_60fps_normal.mp4';
const playObject = {
  // for those devices that use HTML5 player, you can pass extra attributes within this object
  videoHtmlAttributes: {
    crossorigin: 'anonymous'
  }
};
xdk.media.load(url, playObject);
xdk.media.play();

How to retrieve the video player object​

Under some scenarios, we need to access to the video player object to listen to custom events, use video analytics libraries or just because we want to debug whats going on.

Starting on XDK 4.1 we are able to retrieve the player object from the media, and from there manipulate that object, to set new listeners or retrieve the attached HTML5 player if any.

This approach is discouraged, but as the alternative is to attach the native APIs, we have implemented the method. 

// get the video html5 element from hls.js player
xdk.media?.getPlayerObject()?.media;
// get the video html5 element from shaka.js
xdk.media?.getPlayerObject()?.getMediaElement();
// for other examples check the player implementation

How to change video element DOM parent​

If you are using a HTML5 player, the video tag will be added to the body element by default. But you can add a parent node in order to attach the video tag to that DOM element.

For doing this, you will need to add parentNode as an option within the options object.


const customParentNode = document.createElement('div');

const playObject = {
  parentNode: customParentNode,
  drm: 'playready',
  [...]
};

xdk.media.load(url, playObject);
xdk.media.play();

Note: for those player based on HTML5 player, make sure that the player implementations calls the method ._preparePlayerObject; defined on HTML5player.js.

How to change the video aspect ratio​

Some times we need to change the video aspect ratio to meet the goals.

XDK Media.js exposes a method to do it

import xdk, {MediaConstants} from '@accedo/xdk-core';
const  {VIDEO_DISPLAY_MODE:{FIT, FILL, ZOOM, NONE}}  = MediaConstants;

xdk.media.setVideoDisplayMode(FIT|FILL|ZOOM|NONE);

How to Play DRM content​

In this example, you will see how to play a regular MP4 file.

const playObject = {
  drm: 'playready', // See the README.md file of each package to check the supported DRMs
  drmURL: 'https://content/url' // different DRMs could require different attributes
};
xdk.media.load(url, playObject);
xdk.media.play();

How to add auth for DRM or any other player requests​

Some players allow intercepting the player request. For those players, you can add a property to the options object to add a callback.

For example, Shaka player allows these interceptors. So if you are going to use Shaka in your project, you can use requestInterceptor to pass a function. Please, pay attention to the parameters; each player will use a different signature for these parameters.

const playObject = {
  drm: 'widevine', // See the README.md file of each package to check the supported DRMs
  drmURL: 'https://licenseserver/url' // different DRMs could require different attributes,
  requestInterceptor: (type, request) => {
    if (type === shaka.net.NetworkingEngine.RequestType.LICENSE) {
      request.headers.mySpecialHeader = token;
    }
  }

};
xdk.media.load(url, playObject);
xdk.media.play();

How to select a player to load​

Suppose you need to select a specific player for playing a particular type of content/DRM within a specific platform. In that case, you can use the player identifier from the list of prepared players (default config/project overridden config) by doing the following:

// TODO: add the platform/DRM condition
xdk.media.load(url, { ...playerOption, playerId: 'playerIdentifier' }); // TODO: change playerIdentifier with the specific id
xdk.media.play();

How to select the video audio tracks​

In this example, you will see how to set up and configure your XDK player to use audio tracks.

If you are not able to get the audio tracks working, please check the How to check playback capabilities in the config section

xdk.media.load(url, playObject);
xdk.media.play(); // you need to start the playback to gather the audio tracks
let audioTracks = await xdk.media.getAudioTracks(); // return an array of audio tracks
let audioId = audioTracks?.[0]?.id; // this is an example, you may check before the lang
xdk.media.setAudioTrack(audioId); // this will change the audio track

How to set the Stream protocol for the players​

XDK by default, tries to guess the streaming protocol by applyting some regexp on the stream URL.

We provide mechanisms to force a specific protocol or override the default guessing mechanism.

The priority order is the next

  • load options prococol
  • xdk.config.js media.guessProtocolByUrl user function
  • Media.js default defaultGuessProtocol

Examples

Setting the protocol option when loading the stream​

const url = '';
const opts = {
  protocol: 'progressive' // from constants.media.PROTOCOL
};
xdk.media.load(url, opts);

Using the xdk.config.js media.guessProtocolByURL​

// xdk.config.js
//...
media: {
  guessProtocolByURL: (url, opts) => {
    let protocol;
    // custom logic here
    return protocol; // from constants.media.PROTOCOL
  };
}

How to use internal Subtitles​

In this example, you will see how to set up and configure your XDK player to use internal subtitles.

If you are not able to get the subtitles working, please check the How to check the playback capabilities section

First, you will need to ensure that your device has an external subtitles strategy with config.location === external by reviewing the README.md file of the device package or checking the defaultConfig.js.

xdk.media.load(url, playObject);
xdk.media.play(); // you need to start the playback to gather the available subtitles tracks
let subtitles = await xdk.media.getSubtitles(); // return an array of subtitles
let id = subtitles[0].id; // this is an example, you may check before the lang
xdk.media.showSubtitle(id); // this will enable the subtitle

How to use external Subtitles​

In this example, you will see how to set up and configure your XDK player to use external subtitles.

If you are not able to get the subtitles working, please check the How to check the playback capabilities section

const playObject = {
  subtitle: [
    {
      // subtitle play array. must contain one subtitle object per subtitle track
      mimetype: 'webvtt',
      url: 'https://subtitle/url.vtt',
      language: 'en',
      label: 'english subtitle vtt'
    }
  ]
};
xdk.media.load(url, playObject);
xdk.media.play(); // you need to start the playback to gather the subtitle tracks
let subtitles = await xdk.media.getSubtitles(); // return an array of subtitles
let id = subtitles[0].id; // this is an example, you may check before the lang
xdk.media.showSubtitle(id); // this will enable the subtitle, a per device action may be requires (ie: Tizen onsubtitlechange event)

How to render subtitles on Samsung Tizen and Playstation 4 (or any other event dependant subtitle stratregy)​

Both Tizen and Playstation4 devices are event dependent on displaying subtitles, as the device will trigger an event that the app needs to listen to. XDK allows to simplify it for all the platforms by handling and raising a single event that the apps need to listen to: environment.MEDIA.SUBTITLE_UPDATE

Sample code:

import { Environment, getSubtitleRenderer } from '@accedo/xdk-core';
const environment = Environment.singleton();

const subtitleRenderer = getSubtitleRenderer({parentNode, className});
environment.addEventListener(environment.MEDIA.SUBTITLE_UPDATE, subtitleRenderer)

...
const onsubtitleChange = ({ duration, text }) => {
  // Your code here
}

How to use an external subtitle strategy​

You will need to create a player config and set it to the desired device

mport { PlayerConfig } from '@accedo/xdk-config';
import { vtt } from '@accedo/xdk-players-contrib';
const ID = 'html5adds'

const html5adds = new PlayerConfig({
  id: ID,
  importer: () => import(`@accedo/xdk-base-modules/esm/player/HTML5Player.js`),
  extensions: [
    vtt
  ]
});

export default html5adds;

On your xdk.config.js

import workstation from '@accedo/xdk-device-workstation';
import HTML5PlayerConfig from `local/module`;

export default {
  devices: {
    packages: [
      workstation
        .removeAllPlayers() // remove any player from the config
        .addPlayer(HTML5PlayerConfig)
    ]
  }
};

How to customise XDK​

We can extend XDK by creating local (to the project) modules and modifying the local configuration (xdk.config.js) to enable its load.

There are different typical uses cases for the extension, mainly of a specific abstract layer module of a device: network, player, audio strategy, subtituleStrategy, etc.

How to customise general configuration with local extension​

To be able to extend any specific abstraction layer with your module, the following steps are required:

  1. Create a local file that extends or directly implements from scratch the desired module.
  2. Create your local config file to override the specific module (Network, Player, Player extension, etc.)
  3. Update the xdk.config.js file to point to your local config for the desired platform in the details config section.

local config sample file

import config from '@accedo/xdk-config';

const {
  KEY: { PLAYERS }
} = config;

const extendedConfig = {
  [PLAYERS]: [
    {
      id: 'html5player',
      importer: () => import(`../ext/HTML5Player.js`)
    }
  ]
};

export default extendedConfig;

xdk.config.js sample file

xdk.config.js
import workstationConfig from './ext/workstationConfig';
[...]
details: {
  [WORKSTATION]: workstationConfig,
}

How to add a local audio​

If you want to add custom local audio, you must create a new AudioStrategy file. You can find an example of an AudioStrategy implemented in UVPlayerAudioStrategy.js from @accedo/xdk-device-playstation-msdk

With this module and its required methods in place, we are ready to override the specific platform configuration using the steps from the previous step with the following additional changes:

[...]
[...]

How to add local subtitles​

If you want to add a custom local subtitle, you must create a new SubtitleStrategy file. You can find an example of a SubtitleStrategy implemented in UVPlayerSubtitlesStrategy.js from @accedo/xdk-device-playstation-msdk

Once this file is created with all the required methods. You can override the specific platform using the steps from the previous step with the following additional changes:

import config from '@accedo/xdk-config';

const {
  KEY: { PLAYERS }
} = config;

const extendedConfig = {
  [PLAYERS]: [
    {
      id: 'html5player',
      importer: () => import(`{yourPackageNameRoute}`),
      extensions: [
        {
          type: 'subtitle',
          importer: () => import(`{pathToExtension}/{fileNameSubtitle}.js`),
          config: {
            location: 'external'
          }
        },
        {
          type: 'audio-track',
          importer: () => import(`{pathToExtension}/{fileNameAudio}.js`)
        }
      ]
    }
  ]
};

export default extendedConfig;

How to extend XDK Capabilities​

XDK includes a built-in mechanism to extend the XDK limits and capabilities throught the XDK extensions.

We provide some contrib extensions on the @accedo/xdk-extensions-modules-contrib, but you can use this mechanism to implement anything that should work cross device in a similar way.

If you want to play with an example go to vanilla app. We are loading and extension and using it on the app boot

In order to do it we recommend to follow the next folder and files estructure and steps:

/
  src/
    config/
      xdk-config.js       // needs to use the extension configuration
    xdk-local-modules/
      extensions/
        extension-type/
          interface.js    // shared interface
          platform/
            index.js      // device interface implementation of the extension
            config.js     // exposes the extension id and the config itself

Loading and using a XDK extension​

xdk.config.js

import myExtension from 'path/to/xdk-extensions/extension-type/platform/config';

const CONFIG = {
  devices: {
    packages: [
      // ...
    ],
    details: {
      workstation: { // id from the package configuration
       extensions: [
         myExtension
       ]

application code

// get the ID of the extension to avoid magic numbers
import { ID as EXTENSION_ID } from 'path/to/xdk-extensions/extension-type/platform/config';

// retrieve a instance of the extension using the ID
const myExtension = await xdk.extensionManager.getExtension(EXTENSION_ID);

// execute one of the methods
myExtension.method();

Using Text to Speech extensions • TTS​

The way to load the TTS extensions is the same than the described in the previous section.

Load the TTS modules on the desired devices xdk.config.js

import { tts } from '@accedo/xdk-extensions-contrib';

const { html5: html5TTS, vizio: vizioTTS, webos: WebOSTTS } = tts;

const CONFIG = {
  devices: {
    packages: [
      // ...
    ],
    details: {
      [WORKSTATION]: {
        extensions: [html5TTS]
      },
      [VIZIO]: {
        extensions: [vizioTTS]
      },
      [WEBOS]: {
        extensions: [webOSTTS]
      }
    }
  }
};

export default CONFIG;

application code

// get the ID of the extension to avoid magic numbers
import ID as TTS  from '@accedo/xdk-extensions-contrib/esm/tts/id';

// retrieve a instance of the extension using the ID
const tts = await xdk.extensionManager.getExtension(TTS);

// execute one of the methods
tts.speak('halo world!');

How to debug with source maps in a project​

If you are using XDK in an ongoing project and think there is a problem in one package, you will not see the source map files due to the dependency in the project had been installed in prod mode. So for enabling the source map, you will have to use npm link to the lib locally.

Imagine you want to debug the workstation package in your project.

  1. You have to fetch/clone the xdk repo locally. Install dependencies and run a dev build because the maps are created only for development.
git clone git@github.com:Accedo-Global-Solutions/xdk.git
cd xdk
npm i
npm run build:dev
  1. Then go to the package folder you need to debug. In this case, xdk-device-workstation and run npm link.
cd packages/xdk-device-workstation/
npm link
  1. Once the link is done, you need to go to your project folder and just do npm link @accedo/xdk-device-workstation The
cd myAwesomeProject
npm link @accedo/xdk-device-workstation

If everything has been done correctly, a log will appear showing the current alias npm has done for the package.

myAwesomeProjectPath/node_modules/@accedo/xdk-device-workstation -> /myUserPath/.nvm/versions/node/v14.15.0/lib/node_modules/@accedo/xdk-device-workstation -> /xdk/packages/xdk-device-workstation

Now, if you run your project, you will be able to see the source map files, and if you find a bug or need the package need some contributions, please do not hesitate to do it. How to contribute

You can check the steps in this video

How to work with storage​

How to select storage​

With XDK, you can get any specific storage type using the device StorageManager. The current list of supported storage includes:

  • local
  • session
  • cookie

A sample with local will be like:

import { device } from '@accedo/xdk-core';
...
const localStorage = await device.storageManager.getStorage('local|cookie|session');

You can also (and it is the recommended way) get the default one for the current device by not specifying any type.

import { device } from '@accedo/xdk-core';
...
const defaultStorage = await device.storageManager.getStorage();

By default, XDK 4.1 sets a default cookie name and throws a warning using the XDK logger: [Cookie] Default cookie name is being set. Please set a global or device cookie name.

In order to define a unique cookie name you can use a global approach or a platform one

xdk.config.js

export default {
  storages: {
    cookie: {
      name: 'global-cookie-name'
    }
  },
  devices: {
    // platforms configuration load
  },
  details: {
    ['platform']: {
      cookieName: 'platform-cookie-name'
    }
  }
};

How to use storage​

Once you have selected the desired storage, you can use any of the storage methods to persist data in your application:

  • get: to get a specific key.
  • set: to set the value of a specific key.
  • unset: to clear the value of a specific key.
  • clear: to clear the entire storage.

Sample usage:

import { device } from '@accedo/xdk-core';
...
const storage = await device.storageManager.getStorage('local');
...
storage.set('key', value);
storage.get('key');
storage.unset('key');
storage.clear();

How to extend storage​

XDK allows creating an extension of the storage both in the device-specific code (check UWP Storage for an example) This is done by creating the extension of any of the default Storage (or the Interface itself) in the device package and adding those into the storage section of the defaultConfig.js as:

  [STORAGES]: [
    {
      type: 'local',
      importer: () => import('./storage/Local.js')
    },
    {
      type: 'roaming',
      importer: () => import('./storage/Roaming.js')
    }
  ],

You can also create your storage or an extension of an existing one as described in the section How to extend general configuration with local extension

XDK logger​

How to use XDK logger​

XDK logger allows us to use a flexible library to send logs to multiple logging transports.

You can set the transport logging mechanism as an argument or the xdk.config.js file.

Logger transports should expose error, warn, log, info, and debug methods.

import {LOG_LEVELS} from '@accedo/xdk-log';

// xdk.config.js file
export default {
  devices: {
    // devices config
  }
  logging: {
    transport,                  // optional, xdk transport logger
    level: LOG_LEVELS.ALL,      // restrict the logs
    verbose: {
      TVKey: true,              // config for tvkey module
      ConnectionPoller: false   // config for connection poller
    }
  }
}
// module using the logger
import logger from '@accedo/xdk-log';

const logTag = 'label for your logs';
const transport = {};
const {
  error,
  logError, // this is an alias for error
  warn,
  info,
  debug
} = logger({ logTag, transport });

error('Error test');
debug('Debug test');

How to enable on-screen logs​

In your xdk.config.js device file, you should add a logging object, including the options you want.

Necessary to mention: the trigger option, assign a key to make visible/hide the logs component. If you cannot associate a key for your device for any reason, you can add the option visibleOnStart. Therefore, the logger component will be present from the beginning.

import transport from '@accedo/xdk-log-logger-onscreen';
import {LOG_LEVELS} from '@accedo/xdk-log';

export default {
  devices: {
    // devices config
  }
  logging: {
    transport,
    maxLine: 24,
    visibleOnStart: true, // Forces to shown the logs from the application boot
    trigger: 'KEY_1',     // Specifies the key that shown/hides the logs
    style: {
      top: '50vh',
      right: 0,
      width: '66.7vw',
      height: '50vh'
    },
    level: LOG_LEVELS.INFO, // Only showns Info < Log < Warn < Error logs
    verbose: {
      TVKey: true,
      ConnectionPoller: false
    }
  }
}

XDK Network​

Connection Poller​

If we need to check if our application is online or not, we should use the connection poller to get notified when we get connected or disconnected.

To enable it, we should modify the xdk.config.js file and then subscribe to

// xdk.config.js file
const network = {
  polling: {
    interval: 30                                         // be carefull with this
  }

  export default {
    devices: {
      packages: [
        // packages config here
      ],
      details: {
        workspace: {
          network
          // other config here
        }
      }
    }
  };

};
// code to listen to the network state change
import xdk, * as XDK from '@accedo/xdk-core';

const { environment } = XDK;

environment.addEventListener(
  environment.SYSTEM.NETWORK_STATUS_CHANGED,
  status => {
    // status is true if connected, false if disconnected
  }
);

XDK Events​

How to dispatch events​

Sometimes you will need to dispatch events

This may be also useful if you want to simulate internal events dispatch to simulate some XDK actions. i.e Unit testing depending on XDK events

Here is a quick recipe to showcase how events are dispatched

import { Environment } from '@accedo/xdk-core';

const sEnv = Environment.singleton();

const type = "system:key:down"; // to be listened
const payload = {id: "device:vkey:right"}; // expected payload for the event
sEnv.dispatchEvent(type, payload);

And a recipe to showcase how events are listened

import xdk from '@accedo/xdk-core';
const { environment } = xdk;
environment.addEventListener('system:key:down', (payload, type) => {
  // here your logic
})

How to stop event propagation​

If our application registers the same event more than once for different components, maybe you want to stop propagation.

Component 1

const keyHandler_a = ({ id }) => {
  const { BACK } = vKey;
  switch (id) {
    case BACK.id:
      // do some stuff;
    default:
      break;
  }
};

environment.addEventListener(environment.SYSTEM.KEYDOWN, keyHandler_a);
Component 2

const keyHandler_b = ({ id }, event) => {
  const { BACK } = vKey;
  switch (id) {
    case BACK.id:
      // for some cases we don't want to
      // the stuff defined in the other handler is executed
      event.stopImmediatePropagation();
    default:
      break;
  }
};

environment.addEventListener(environment.SYSTEM.KEYDOWN, keyHandler_b);

The last handler registered will be the first handler to be called, so if you want to stop propagation, stopImmediatePropagation must be called in the deepest component.

The callback for the events will receive two arguments now. The second one is the event argument. This object contains the type information and the stopPropagation function.

const event = {
  type: string
  stopImmediatePropagation: function
};