MediaPlayer:API:Callbacks

Revision as of 09:18, 10 July 2012 (view source) 66.214.240.97 (Talk) ← Older edit		Latest revision as of 09:19, 10 July 2012 (view source) 66.214.240.97 (Talk) (→‎Example Usage)
(6 intermediate revisions by one user not shown)
Line 185:		Line 185:
	<script type="text/javascript">		<script type="text/javascript">
−		+
	metrix_onPlayheadUpdate = function(obj) {		metrix_onPlayheadUpdate = function(obj) {
	var complete = Math.floor(100 * obj.curTime / obj.totalTime);		var complete = Math.floor(100 * obj.curTime / obj.totalTime);
Line 191:		Line 191:
	return true;		return true;
	}		}
−
	== metrix_onLoad ==		== metrix_onLoad ==
Line 207:		Line 206:
	<script type="text/javascript">		<script type="text/javascript">
−		+
	metrix_onLoad = function(obj) {		metrix_onLoad = function(obj) {
	alert("This player is ready.");		alert("This player is ready.");
Line 231:		Line 230:
	<script type="text/javascript">		<script type="text/javascript">
−		+
	metrix_onComplete = function(obj) {		metrix_onComplete = function(obj) {
	alert("This player is done playing.");		alert("This player is done playing.");
Line 258:		Line 257:
	<script type="text/javascript">		<script type="text/javascript">
−		+
	metrix_onNoCamerasDetected = function(obj) {		metrix_onNoCamerasDetected = function(obj) {
	alert("Sorry... it looks like you don't have a webcam.");		alert("Sorry... it looks like you don't have a webcam.");
Line 285:		Line 284:
	<script type="text/javascript">		<script type="text/javascript">
−		+
	metrix_onBroadcastError = function(obj) {		metrix_onBroadcastError = function(obj) {
	alert("Sorry... it looks like there was a problem broadcasting.");		alert("Sorry... it looks like there was a problem broadcasting.");
	return true;		return true;
	}		}
−
	== metrix_onBroadcastDenied ==		== metrix_onBroadcastDenied ==
Line 313:		Line 311:
	<script type="text/javascript">		<script type="text/javascript">
−		+
	metrix_onBroadcastError = function(obj) {		metrix_onBroadcastError = function(obj) {
	alert("Sorry... it looks like you did not grant permission to use the camera.");		alert("Sorry... it looks like you did not grant permission to use the camera.");
Line 340:		Line 338:
	<script type="text/javascript">		<script type="text/javascript">
−		+
	metrix_onBroadcastError = function(obj) {		metrix_onBroadcastError = function(obj) {
	alert("Sorry... it looks like you did not grant permission to use the camera.");		alert("Sorry... it looks like you did not grant permission to use the camera.");
	return true;		return true;
	}		}

---

Latest revision as of 09:19, 10 July 2012

Contents 1 Getting Started 2 Callbacks 3 metrix_navigateToURL 3.1 Parameters 3.2 Example Usage 4 metrix_isFullscreenDisabled 4.1 Parameters 4.2 Example Usage 5 metrix_onStateChange 5.1 Parameters 5.2 Example Usage 6 metrix_onDisplayChange 6.1 Parameters 6.2 Example Usage 7 metrix_filterComObject 7.1 Parameters 7.2 Example Usage 8 metrix_updateRoster 8.1 Parameters 8.2 Example Usage 9 metrix_onPlayheadUpdate 9.1 Parameters 9.2 Example Usage 10 metrix_onLoad 10.1 Parameters 10.2 Example Usage 11 metrix_onComplete 11.1 Parameters 11.2 Example Usage 12 metrix_onNoCamerasDetected 12.1 Parameters 12.2 Return Values 12.3 Example Usage 13 metrix_onBroadcastError 13.1 Parameters 13.2 Return Values 13.3 Example Usage 14 metrix_onBroadcastDenied 14.1 Parameters 14.2 Return Values 14.3 Example Usage 15 metrix_onBroadcastInit 15.1 Parameters 15.2 Return Values 15.3 Example Usage

[edit] Getting Started

The media player has many callbacks that can be defined in JavaScript to provide more granular control over the media player and how it interacts with certain actions.

[edit] Callbacks

Callbacks are simply global JavaScript functions that the media player tries to call. If they don't exist, then the media player skips over them. It is important to always return a value or the media player will assume it was unable to successfully complete the callback.

[edit] metrix_navigateToURL

This callback is useful when the media player wants to redirect itself to a new URL and you need better control over how to perform this redirect rather than the default implementation offered by Flash.

[edit] Parameters

url

this is the URL to which the media player wants to redirect.

[edit] Example Usage

<script type="text/javascript">

 metrix_navigateToURL = function(url) {
   document.location = url;
   return true;
 }

</script>

[edit] metrix_isFullscreenDisabled

This callback is useful for when you want to control access to fullscreen mode. Sometimes this is desired during chat sessions, because fullscreen mode does not allow input from the keyboard.

[edit] Parameters

This function has no parameters.

[edit] Example Usage

<script type="text/javascript">

 metrix_isFullscreenDisabled = function() {
   return false;
 }

</script>

[edit] metrix_onStateChange

This callback notifies the viewer on the current state and previous state of the media player. This allows you to have control and detect errors more easily with playback.

[edit] Parameters

state

this is the current state of the media player.

lastState

this is the previous state of the media player.

[edit] Example Usage

<script type="text/javascript">

 metrix_onStateChange = function(state, lastState) {
   if (state == "connectionError") {
     alert("A connection error has occurred.");
   }
   return true;
 }

</script>

[edit] metrix_onDisplayChange

This callback notifies the viewer that a display change is taking place.

[edit] Parameters

display

this is the new display mode. Allowable values are "normal" and "fullscreen".

[edit] Example Usage

<script type="text/javascript">

 metrix_onDisplayChange = function(display) {
   if (display == "fullscreen") {
     alert("Enjoy the show!");
   }
   return true;
 }

</script>

[edit] metrix_filterComObject

This callback is extremely important for doing a custom live event implementation. All of the live events go through this function. Returning true will prevent the event from occurring.

[edit] Parameters

obj

this is an object with several properties. Take a look at the example below to see the implementation details.

[edit] Example Usage

<script type="text/javascript">

 metrix_filterComObject = function(obj) {
   var id = obj.id;
   var msgtype = parseInt(obj.type);
   var user = obj.user;
   var msg = obj.msg;
   var host = obj.host;
   
   switch(msgtype) {
     case MCONST_CHAT: {
     } break;
     case MCONST_ENTER: {
     } break;
     case MCONST_LEAVE: {
     } break;
     case MCONST_GIFT: {
     } break;
     case MCONST_ENTER_VOYEUR: {
     } break;
     case MCONST_ACCESS_PUBLIC: {
     } break;
     case MCONST_ACCESS_PRIVATE_EXCLUSIVE: {
     } break;
     case MCONST_ACCESS_PRIVATE_GROUP: {
     } break;
     case MCONST_MODE_CHANGE: {
     } break;
     case MCONST_SHUTDOWN: {
     } break;
   }
 
   return false;
 };

</script>

[edit] metrix_updateRoster

This callback allows you to build your own chat roster of who is viewing the live event.

[edit] Parameters

user

this is the username of the viewer being updated.

host

this is whether or not the viewer is the host.

add

this is a boolean determining if the viewer is entering or leaving the event.

[edit] Example Usage

<script type="text/javascript">

var roster = {};

metrix_updateRoster = function(user, host, add) {
  if (add) {
    roster[user] = true;
  } else {
   delete roster[user];
  }
  return true;
}

[edit] metrix_onPlayheadUpdate

This callback allows you to dynamically adjust your playhead cursor as your media plays.

[edit] Parameters

obj

this is an object.

curTime

this is the current time in seconds of the media playing.

totalTime

this is the total time in seconds of the media playing.

playerId

this is the HTML DOM id of the media player.

[edit] Example Usage

<script type="text/javascript">

metrix_onPlayheadUpdate = function(obj) {
  var complete = Math.floor(100 * obj.curTime / obj.totalTime);
  alert("This player is " + complete + "% complete.");
  return true;
}

[edit] metrix_onLoad

This callback allows you know when the media player is ready for interaction.

[edit] Parameters

obj

this is an object.

playerId

this is the HTML DOM id of the media player.

[edit] Example Usage

<script type="text/javascript">

metrix_onLoad = function(obj) {
  alert("This player is ready.");
  return true;
}

[edit] metrix_onComplete

This callback allows you know when the media player is done with playback for the current media.

[edit] Parameters

obj

this is an object.

mode

the mode param has the following values: pre and post. The pre value is before the next transition begins and the post value is after the next transition begins.

playState

this is actual state of the playback. Possible values are pre, play, or post. The pre/post roll functionality uses pre and post values.

playerId

this is the HTML DOM id of the media player.

[edit] Example Usage

<script type="text/javascript">

metrix_onComplete = function(obj) {
  alert("This player is done playing.");
  return true;
}

[edit] metrix_onNoCamerasDetected

This callback allows you know when the media player is unable to detect any cameras.

[edit] Parameters

obj

this is an object.

playerId

this is the HTML DOM id of the media player.

[edit] Return Values

false

this stops the default execution for handling this callback

true

this continues with the default execution for handling this callback

[edit] Example Usage

<script type="text/javascript">

metrix_onNoCamerasDetected = function(obj) {
  alert("Sorry... it looks like you don't have a webcam.");
  return true;
}

[edit] metrix_onBroadcastError

This callback allows you know when the media player is unable to successfully broadcast.

[edit] Parameters

obj

this is an object.

playerId

this is the HTML DOM id of the media player.

[edit] Return Values

false

this stops the default execution for handling this callback

true

this continues with the default execution for handling this callback

[edit] Example Usage

<script type="text/javascript">

metrix_onBroadcastError = function(obj) {
  alert("Sorry... it looks like there was a problem broadcasting.");
  return true;
}

[edit] metrix_onBroadcastDenied

This callback allows you know when the media player is unable to get permission from the user to use the camera.

[edit] Parameters

obj

this is an object.

playerId

this is the HTML DOM id of the media player.

[edit] Return Values

false

this stops the default execution for handling this callback

true

this continues with the default execution for handling this callback

[edit] Example Usage

<script type="text/javascript">

metrix_onBroadcastError = function(obj) {
  alert("Sorry... it looks like you did not grant permission to use the camera.");
  return true;
}

[edit] metrix_onBroadcastInit

This callback allows you know when the media player is about to prompt for camera settings, which leads into starting the broadcast. By returning false, you have the opportunity to create your own camera settings dialog in HTML. This can be used along with metrix_getBroadcastSettings and metrix_initBroadcast.

[edit] Parameters

obj

this is an object.

playerId

this is the HTML DOM id of the media player.

[edit] Return Values

false

this stops the default execution for handling this callback

true

this continues with the default execution for handling this callback

[edit] Example Usage

<script type="text/javascript">

metrix_onBroadcastError = function(obj) {
  alert("Sorry... it looks like you did not grant permission to use the camera.");
  return true;
}