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

Publishers

For publishers, Hook:

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

Consumers

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 player.  

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

Devices

Exceptions

Player V3

Android 2.2+ 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 topics:
    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 playback.
  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 table.

If the user clicks...

then..

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 user.

I already have it,

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

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 market://com.ooyala.hooktv.hook.

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 events.  

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 play behavior.

<script src="http://player.ooyala.com/v3/...">          
<script>                 
function customAppDialog(e, pcode, embedCode, token) {                 
    alert("This is a custom function");                
}                 
OO.Hook.useAppDialog(customAppDialog);             
OO.ready(function() { … Player creation code here … }             
<script>               
                        
In 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 want.

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

ooyala://<provider_code>/<content_id>

Or if you have a playback token, use:

ooyala://<provider_code>/<content_id>/<playback_token>

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 = null),{initialTime:time_in_seconds});
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 = null),{initialTime:time_in_seconds});
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 Screen.

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) {
    super.onCreate(savedInstanceState);
    setContentView(R.layout.activity_main);
                  
  Intent launchHook = new Intent(Intent.ACTION_VIEW, Uri.parse(<"ooyala://pcode/embed code">));
    startActivity(launchHook);
  }
}            
 
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 Offset

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 valid token.

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

Launch 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 Player.

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

Launch 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.

ooyala://<provider_code>/<content_id>
ooyala://<provider_code>/<content_id>/<playback_token>
ooyala://<provider_code>/<content_id>/<playback_token>/initial_time_in_seconds

Note: 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
     });
 </script> 
Sample using XDR on OO.Hook.launchApp, initial time of 10 seconds (equivalent to 10000 milliseconds):
<script>
   document.getElementById("hook_button").addEventListener("click", function(){
     OO.Hook.launchApp("5zb2wxOlZcNCe_HVT3a6cawW298X", "tndWV3ZTqRxdXHR8ciA09BLMrKx73zwJ", null, {initialTime: 10000});
   })
 </script>
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

Download PDF Ooyala Developer Documentation