Hook Mobile Player App

Ooyala offers a flexible media player application designed specifically for the needs of
mobile platforms. The Hook media player enables publishers to deliver live, linear, and
premium VOD content not possible on current mobile web platforms without the significant
cost and lengthy time to market that is required to build custom video-centric apps.

With Hook, you don’t need to create and maintain a mobile player app that works across a
variety of Android devices. Hook does that for you. The Ooyala Hook mobile player app
supports all of the following features:

  1. Live/linear content
  2. ABR
  3. Closed Captions for VOD and Live
  4. Client-side Pre-roll, Mid-roll and Post-roll ad insertion
  5. Full Ooyala analytics
  6. Studio-approved DRM


For publishers, Hook:

  • Enables playback of premium content on Android devices without having to build an
  • Can build (mobile) HTML5 website as they normally would. Playback happens seamlessly in
    the Hook app.


With the Hook mobile app, consumers can take advantage of the following:

  • Download the app once per device.
  • After initial download, playback works across any Hook-enabled website.
  • Ooyala-powered publishers does not require additional downloads.
  • Go to or load your website with a player, it will look like a normal HTML5-based video

It’s easy to get started. You can enable Hook on a website with our basic setup and then
use the API to provide a more customized experience for your customers.

Where it Works

Hook supports the following embed types and devices.

Embed Types



Player V3

Android 2.3+ devices using an HTML5 player.

Certain exceptions can make a device incompatible with Hook. Exceptions
can include:

  • Devices with Android side-loaded such as the Nook or Kindle
    tablets. This can prevent Hook from working on a particular Android
    version (such as 3.X on these tablets).

  • Placing the player in an iframe. See the topic "iframe
    Restrictions" in later in this document.

Setting Up Hook

To get Hook to run on your website:

  1. Configure a movie to play using this player. Embed this movie as normal in a mobile
    phone accessible website.

    Note: This will only work if you have streams capable of
    playing on Android devices.

  2. Provide a Backlot username and website URL to your Ooyala Customer Success Manager
    for the required provider attribute. For more information, see the following
    1. Setting Provider Attributes
    2. Launching Hook from a Different Application.
  3. In your code, the embed script  has a URL in the form of: 
 <script src="http://player.ooyala.com/v3/player_id”> <script>

Playing Content With Hook

With Hook, users will see a website that loads the HTML5-based video player.  When the
user presses play, the website does one of the following:

  1. If the Hook app is installed, the app automatically opens and starts
  2. If the Hook app is not installed, the website opens a dialog box and prompts
    the user to install the app by providing the options listed in the following

If the user clicks...


Show me where to download,

the user will be taken to the Google Play store page.

Remind me later,

the dialog box will close and page will remain accessible to the

I already have it,

we assume the app was installed, but not detected, and we try to open the

Note: Users might click, “I have the app,” but actually do not. To deal with
this situation we strongly recommend having a “Download Hook here!” link,
that directs the user to

Customizing the Hook App Experience

You can create some custom behavior for the Hook app to perform when the user clicks the
“Play” button on an Android device. The website developer can perform any action on the
click of the Play button. However, you must keep in mind the following guideline:

Do NOT create your “on play” customization by listening to Player

If you decide to customize the on play behavior, you must also code your own application
detection algorithm. Your will need to make your own code check if the Hook app is
installed and code the appropriate behaviors, if it is not installed.

Domain Restrictions

If you are applying domain restrictions to a video or set of videos or to a live stream,
to use Hook with that asset, you'll need to enable www.ooyala.com as an available
domain.  For more information on setting domain restrictions through publishing rules,
see .

iframe Restrictions

If you want to launch Hook from the Ooyala player, you cannot place the player in an
iframe. If the player is in an iframe, Hook does not launch. For more information about
iframe, see Embedding the Player in an HTML iframe.

Overriding Default On Play Behavior

To customize the on play behavior, Hook offers an exposed method called
OO.Hook.useAppDialog(function) that takes in a
function name. The useAppDialog will override our default behavior by
calling your supplied function.

Example: Change
Default Play Behavior

The following example shows how you can insert the
useAppDialog method to include a custom function to change the on

<script src="http://player.ooyala.com/v3/...">          
function customAppDialog(e, pcode, embedCode, token) {                 
    alert("This is a custom function");                
OO.ready(function() { … Player creation code here … }             

this example:

  1. We created the custom function: function
    customAppDialog(e, pcode,
    embedCode, token)
  2. We then called it with the useAppDialog method.

When you create and define this function, you can name it whatever you

 To open the app yourself, you change the website to a URL in the form of:


Or if
you have a playback token, use:


Customization API

To assist you in customizing the Hook on play experience, Ooyala provides a
customization API. This Hook API exposes the following methods:

string OO.Hook.useAppDialog(function)
Takes in a function name.  useAppDialog will override the Ooyala
app’s default behavior by calling your supplied function.
void OO.Hook.launchApp(pcode, embed, token =
Launches App, and sets cookie to never show dialog box again. Includes an
optional initialTime parameter to specify a time offset in
the video.
Specify the time in seconds.
void OO.Hook.launchMarket();
Load the market page for the Ooyala media player
string OO.Hook.getUrl(pcode, embedCode, token =
Provides the URL required to open the Hook app. Includes an optional
initialTime parameter to specify a time offset in the
video. Specify the time in seconds.

Setting Provider Attributes

Ooyala can set additional configuration options, in the form of provider attributes,
that enable you to modify the behavior of Hook. The following is a list of these
provider attributes:

hook_user = <backlot-username>
Required - This is a username of a user who will be used for all start screen
request signing.
hook_default_url = <company_website>
Required - Defines a URL that users can be directed to from the start screen
hook_opt_out = true|false
Optional: enables or disables the provider to show up on the Hook Start

Launching Hook from a Different Application

You can launch Hook from a different application by coding an Android Intent. In the following example, we created a
new Intent and gave it a URI using the format described in the prior section, Setting Provider Attributes.

public class MainActivity extends Activity {
  @Override  protected void onCreate(Bundle savedInstanceState) {
  Intent launchHook = new Intent(Intent.ACTION_VIEW, Uri.parse(<"ooyala://pcode/embed code">));
Note: You can get your pcode (provider code) and your embed code from Backlot. To get the embed
code, see the Backlot topic Embedding An Asset. To get your pcode:
  1. Log into your Backlot account.
  2. Click on the Account tab.
  3. Click on the Developers subtab.
  4. Find your API Key. The API key has the following format:
    <pcode>.<string>. The pcode is the alphanumeric string before the
    period. For example for API Key:
    ABC123xOuTldXc1CiXbzAauYN7Iui.SMqJ, the segment
    "ABC123xOuTldXc1CiXbzAauYN7Iui" is your pcode

Troubleshooting a Launch of Hook Without the App

You have additional options for
launching the Hook app and can specify a time offset into the video. The Hook API includes
an initialTime parameter that you can use to specify in seconds how
much time into the video where you want it to begin at launch. The following examples show
the additional ways you can launch the Hook app and include the use of the
initialTime parameter.

Note: In all of the following
examples, the use of the initialTime parameter is optional. You can
launch the Hook app without it.

Launch Hook from Another App with a Time

In the following example, you can see that we use similar code for
launching Hook from a different application (such as an app you create with our Android
SDK). We added time_in_seconds to specify the point in the video to
start the app. While use of a time offset is optional, to use
time_in_seconds the third section must have a valid token or the
string "null". In the following example we use /null/ instead of a

public class MainActivity extends Activity {
  @Override  protected void onCreate(Bundle savedInstanceState) {
  Intent launchHook = new Intent(Intent.ACTION_VIEW, Uri.parse
  (<"ooyala://pcode/embed code/null/time_in_seconds">));

Hook with the LaunchApp Event in JavaScript

You can launch the Hook app and
set the initial time offset using the launchApp event in JavaScript
for the V3

void OO.Hook.launchApp(pcode, embed, token = null, {initialTime:time_in_seconds}); 

Hook with a Custom URI and an Initial Time

You have the option of launching
the Hook app with a custom URI and an initial time offset. As with the other options for
launching Hook, you can use this method with or without the
initialTime parameter. Using this option with the initialTime
parameter is particularly useful if you want to use Hook with Cross-Device Resume.


For information about using Cross-Device Resume, see "Player for
Cross Device Resume"

Setting initialTime with Hook and Cross Device
Resume (XDR)

The following JavaScript code snippets show how you can use
the initialTime parameter with Hook and Cross Device Resume.

Sample using XDR on OO.Player.create, initial time of 10
seconds (equivalent to 10000 milliseconds):

 <script>var videoPlayer = OO.Player.create('playerwrapper','123FAKETqRxdXHR8ciA09BLMrKx73zwJ', {
       initialTime: 10

Sample using XDR on OO.Hook.launchApp, initial time of
10 seconds (equivalent to 10000 milliseconds):

   document.getElementById("hook_button").addEventListener("click", function(){
     OO.Hook.launchApp("5zb2wxOlZcNCe_HVT3a6cawW298X", "tndWV3ZTqRxdXHR8ciA09BLMrKx73zwJ", null, {initialTime: 10000});
You may
have a case where you have developed an app for use with Hook and the user tries to
launch the app without having downloaded and installed the Hook app. In this case, your
code will throw an exception.  An Intent will fail if there is no application to receive
it.  Intents do not automatically redirect to the app store.  To fix this case, you need
to implement a try/catch for the exception and redirect the user to the link where they
can download the app:

  1. https://play.google.com/store/apps/details?id=com.hooktv.hook&hl=en

  2. market://com.hooktv.hook where market is the
    provider URL