Integration

Integration of the Handy UI is simple and comes with a number of configurable options.

Introduction

The Handy UI is packaged into a small button with a Handy-branded logo. It is designed to have minimum visual impact on the content of the website it is being integrated into. For the user, the Handy UI is meant to provide an indication that a video has a Handy-compatible script, as well as a common connection interface for users who visit several video partners.

The Handy UI is built on top of our SDK and includes methods for synchronizing your videos with the Handy. The SDK can be used to handle the synchronization logic ⁠— without the Handy UI ⁠— if you require a customized frontend for your application.

The Handy SDK binds to the video tag on your site, and uses the events of the HTML5 Video API to synchronize the video with the Handy.

Prerequisites

You can load the Handy UI SDK from a CDN:

<script src="https://unpkg.com/@ohdoki/handy-sdk"></script>

Alternatively, you can use NPM to install the latest release:

npm i @ohdoki/handy-sdk

Installation

Option 1 — With Handy user interface

Step 1 — Include the SDK

First, include the Handy UI SDK script on your site.

<head>
	<script src="https://unpkg.com/@ohdoki/handy-sdk"></script>
</head>

Step 2 — Attach the Handy UI button

Next, create an empty <div> tag in the location where you want to show The Handy button and give it an id of handy-ui.

<div id="handy-ui"></div>

By default, the SDK will look for a div with an id of handy-ui to bind to, but this is customizable in the configurations.

Initialize the SDK inside a script tag with const HANDY = Handy.init();.

<script>
  ...
	const HANDY = Handy.init();
  ...
</script>

You can also set a custom config by passing variables into the constructor, e.g. const HANDY = Handy({ syncCount: 30, outliers: 10 }). See the Configuration section below for details.

Attach the Handy UI to your page by calling following method:

HANDY.attachUUI();

You can pass a custom id as a string param here. For example, if you want the Handy UI to bind to a <div> with id my-custom-div:

HANDY.attachUUI("my-custom-div");

Step 3 — Bind the Handy SDK to the video element

Use the setVideoPlayer method in the SDK on your <video> element.

HANDY.setVideoPlayer(HTMLVideoElement);

Step 4 — Send script to Handy

We are now ready to send the script to the Handy with the setScript() method.

However, first we need to check if the user has connected their Handy to the Handy UI. If there is no Handy connected, then sending of the script will fail.

To make sure we succeed, we use the on() method to create a listener for the connect event:

handy.on('connect', () => {
  handy.setScript('https://playground.handyfeeling.com/assets/sync_video_2021.csv');
});

This way when the user connects, the SDK will wait until the Handy is connected before sending the script.

And that’s it! You should now see the Handy button and, when you click on it, you’ll see the connection screen. All the relevant connection and synchronization events will be handled automatically by the SDK.

Option 2 — Without Handy user interface

Step 1 — Include the SDK

First, include the Handy SDK script in the <head> of your site.

<head>
	<script src="https://unpkg.com/@ohdoki/handy-sdk"></script>
</head>

Step 2 — Initialize the SDK

Initialize the SDK inside a script tag with const HANDY = Handy.init();.

<script>
  ...
	const HANDY = Handy.init();
  ...
</script>

You can also set a custom config by passing variables into the constructor, e.g. const HANDY = Handy({ syncCount: 30, outliers: 10 }). See the Configuration section below for details.

Step 3 — Bind the Handy SDK to the video element

Use the setVideoPlayer method in the SDK on your <video> element.

HANDY.setVideoPlayer(HTMLVideoElement);

Step 4 — Create connection interface

Add an input field that allows the user to insert their connection key. Pass the value in the input field to the connect method. If the connect method returns a positive response, you should set the script URL in the callback with HANDY.setScript().

For example:

HANDY
  .connect(key)
  .then(result => {
    if (result !== Handy.ConnectResult.CONNECTED) {
      throw new Error(Handy.ConnectResult[result]);
    }
    holder.innerHTML = 'connected';
    return HANDY.setScript('https://sweettecheu.s3.eu-central-1.amazonaws.com/scripts/admin/dataset+(2)_fix_150420.csv');
  })
  .then(() => {
    holder.innerHTML = 'Script has been set';
  })
  .catch(error => {
     holder.innerHTML = error.message;
  });

Finally, add a disconnect button and handle the event with the disconnect() method.

Configuration

The Handy UI comes with a number of configuration options to simplify its fit into your website.

  • Dark mode
  • Compact mode
const HANDY = Handy({ theme: 'dark', compactMode: true })

See the SDK Reference for additional details.