Skip to content

Android API

NZ Player API for Android

The NZ Player API for Android allows an Android application to embed the NZ Player functionality. The NZ Player API provides the ability to launch/close an NZ App with a given URL. The launched app is rendered in a View that can be attached to an Android view hierarchy. It also provides the ability to send/receive messages to/from the NZ App running in the cloud.

The NZ Player API for Android requires minimum Android API version 19

Class NZPlayerApi

This is the main class for the API. This is a singleton class, the functions in the class must be accessed using the instance() method, e.g. NZPlayerApi.instance().init(...).

Summary

Nested Classes
@interface NZPlayerApi.PlayerStatusListener Callback that can be used to listen for NZPlayer status events
@interface NZPlayerApi.AppStatusListener Callback that can be used to listen for NZPlayer status events for a single NZ App
enum NZPlayerApi.DeviceType The type of android device: Phone, Tablet, TV etc.
enum NZPlayerApi.NZPlayerApiConstants API constants

public static abstract @interface NZPlayerApi.PlayerStatusListener

Callback Methods:

void onNZPlayerInit(boolean success, String error)
This method is called in response to the init call on the NZPlayerApi. It indicates the initialization status of the NZPlayer
  • success If the initialization was successful, the value of this parameter is set to true. Otherwise, it is set to false.
  • error If the initialization failed i.e. success is false, then this parameter is set to a description of the error
void onNZPlayerShutdown(boolean success, String error)
This callback method is called to indicate the shutdown status of the NZPlayer. It can either be called as a response to the shutdown call on the NZPlayerApi or it can be called as a result of internal shutdown by the NZPlayer
  • success If this method is called as a response to shutdown call, then this parameter is set to the result of the shutdown. If the shutdown was successful, the value of this parameter is set to true. Otherwise, it is set to false.
  • error Whether it was initiated by the shutdown method or it was an internal NZPlayer shutdown, this parameter is set to the shutdown reason/error.
void onNZPlayerHide()
This callback method is called when the NZPlayer instance is transitioning to the background.
void onNZPlayerShow()
This callback method is called when the NZPlayer instance is transitioning to the foreground.
void onShowMessageBox(int error, int flags, String caption, String message, int msgId)
This callback method is called to display a message box.
  • error Error condition that initiated the messagebox display
  • flags Messagebox flags NZPlayerApi.NZPlayerApiConstants.QZ_MESSAGEBOX_*
  • caption Messagebox text caption.
  • message Messagebox text.
  • msgId ID for messagebox
void onDismissMessageBox(int response)
This callback method is called when a message box button has been clicked (by user or programmatically)
  • response Response code NZPlayerApi.NZPlayerApiConstants.QZ_MESSAGEBOX_RSP_*
void onShowWaitCursor(int cursorId)
This callback method is called when NZPlayer is busy
  • cursorId Suggested wait cursor style to display NZPlayerApi.NZPlayerApiConstants.QZ_WAIT_CURSOR_*
void onDismissWaitCursor()
This callback method is called when NZPlayer is not busy and wait cursor should be removed

public static abstract @interface NZPlayerApi.AppStatusListener

This callback interface is provided as a parameter in the launchApp method to receive app specific status events from the NZPlayer.

Callback Methods:

void onNZPlayerAppLaunchStarted(int appHandle)
This method is called in response to the launchApp call on the NZPlayerApi. It indicates the launch has started
  • appHandle This parameter is set to the application handle corresponding to the NZ App for which this callback is called
void onNZPlayerAppLaunch(int appHandle, boolean success, String error)
This method is called in response to the launchApp call on the NZPlayerApi. It indicates the launch status of the NZPlayer
  • appHandle This parameter is set to the application handle corresponding to the NZ App for which this callback is called
  • success If the NZ App launch was successful, the value of this parameter is set to true. Otherwise, it is set to false.
  • error If the NZ App launch failed i.e. success is false, then this parameter is set to a description of the error
void onNZPlayerAppShutdown(int appHandle, boolean success, String error)
This callback method is called to indicate the shutdown status of the NZPlayer. It can either be called as a response to the shutdown call on the NZPlayerApi or it can be called as a result of internal app shutdown by the NZPlayer
  • appHandle This parameter is set to the application handle corresponding to the NZ App for which this callback is called
  • success If this method is called as a response to shutdownApp call, then this parameter is set to the result of the shutdown. If the shutdown was successful, the value of this parameter is set to true. Otherwise, it is set to false.
  • error Whether it was initiated by the shutdownApp call or it was an internal NZPlayer app shutdown, this parameter is set to the shutdown reason/error.
void onNZPlayerAppReceiveRawDataMsg(int appHandle, int param1, byte[] rawData)
This method is called whenever a raw data message sent by the NZ App with the given appHandle is received by the NZPlayer.
  • appHandle This parameter is set to the application handle corresponding to the NZ App for which this callback is called
  • param1 An integer parameter that is included in the raw data message. This parameter is set by the NZ App and is passed as is by the NZPlayer.
  • rawData Raw data message bytes sent by the NZ App. The NZPlayer passes this parameter without any modification

public static final enum NZPlayerApi.DeviceType

This enum type specifies the type of the Android device on which the NZPlayer is launched
  • PHONE Device is a phone
  • TABLET Device is a tablet
  • TV Device is a TV
  • DESKTOP Device is a desktop
  • GOGGLES Device is Google GOGGLES

public static NZPlayerApi.NZPlayerApiConstants

This class specifies NZPlayerApi constants
  • QZ_MESSAGEBOX_ID_INVALID Unset messagebox ID
  • QZ_MESSAGEBOX_NO_BUTTONS Messagebox with no buttons
  • QZ_MESSAGEBOX_BUTTON_OK [OK] Button
  • QZ_MESSAGEBOX_BUTTON_CANCEL [CANCEL] Button
  • QZ_MESSAGEBOX_BUTTON_OK_CANCEL [OK] [CANCEL] Buttons
  • QZ_MESSAGEBOX_BUTTON_YES [YES] Button
  • QZ_MESSAGEBOX_BUTTON_NO [NO] Button
  • QZ_MESSAGEBOX_BUTTON_YES_NO [YES] [NO] Button
  • QZ_MESSAGEBOX_BUTTON_RECONNECT [RECONNECT] Button
  • QZ_MESSAGEBOX_BUTTON_RETRY [RETRY] Button
  • QZ_MESSAGEBOX_BUTTON_EXIT [EXIT] Button
  • QZ_MESSAGEBOX_BUTTON_MASK Mask to isolate the button bit fields
  • QZ_MESSAGEBOX_INFO Messagebox severity - informative
  • QZ_MESSAGEBOX_WARNING Messagebox severity - warning
  • QZ_MESSAGEBOX_ERROR Messagebox severity - error
  • QZ_MESSAGEBOX_DETAILS Messagebox severity - details
  • QZ_MESSAGEBOX_SEVERITY_MASK Mask to isolate the severity bit fields
  • QZ_MESSAGEBOX_RSP_INVALID Messagebox response - invalid
  • QZ_MESSAGEBOX_RSP_TIMEOUT Messagebox response - Timed out waiting for input
  • QZ_MESSAGEBOX_RSP_OK Messagebox response - [OK] Button pressed
  • QZ_MESSAGEBOX_RSP_CANCEL Messagebox response - [CANCEL] Button pressed
  • QZ_MESSAGEBOX_RSP_YES Messagebox response - [YES] Button pressed
  • QZ_MESSAGEBOX_RSP_NO Messagebox response - [NO] Button pressed
  • QZ_MESSAGEBOX_RSP_RECONNECT Messagebox response - [RECONNECT] Button pressed
  • QZ_MESSAGEBOX_RSP_RETRY Messagebox response - [RETRY] Button pressed
  • QZ_MESSAGEBOX_RSP_EXIT Messagebox response - [EXIT] Button pressed
  • QZ_WAIT_CURSOR_INVALID Wait Cursor type - unset
  • QZ_WAIT_CURSOR_DEFAULT Wait Cursor type - default
  • QZ_WAIT_CURSOR_NONE Wait Cursor type - none
  • QZ_WAIT_CURSOR_SQUARES Wait Cursor type - squares
  • QZ_WAIT_CURSOR_SPIN Wait Cursor type - spinning
  • QZ_WAIT_CURSOR_BLACK_DOTS Wait Cursor type - black dots
  • QZ_WAIT_CURSOR_WHITE_DOTS Wait Cursor type - white dots
  • QZ_WAIT_CURSOR_BLACK_BALLS Wait Cursor type - black balls
  • QZ_WAIT_CURSOR_WHITE_BALLS Wait Cursor type - white balls
  • QZ_WAIT_CURSOR_LARGE_BLACK_BALLS Wait Cursor type - large black balls
  • QZ_WAIT_CURSOR_LARGE_WHITE_BALLS Wait Cursor type - large white balls
  • QZ_WAIT_CURSOR_BLACK_WHITE_CIRCLE Wait Cursor type - black and white circle
  • QZ_WAIT_CURSOR_LARGE_BLACK_WHITE_CIRCLE Wait Cursor type - large black and white circle
  • c_DeviceProfile_None Device profile - none specified
  • c_DeviceProfile_Simple Device profile - simple
  • c_DeviceProfile_Hybrid Device profile - hybrid
  • c_DeviceProfile_Smart Device profile - smart

Public Methods

type method
static NZPlayerApi instance Access the singleton NZPlayerApi instance
boolean init(Context context, String devKey, DeviceType deviceType, PlayerStatusListener clientStatusListener) initialize the NZPlayer
void pause Pause the NZPlayer
void resume Resume the NZPlayer
void resume(String sReasonCode) Resume the NZPlayer with reason code
int launchApp(Context appContext, String appUrl, int appWidth, int appHeight, AppStatusListener appStatusListener, String appDeviceProfile, String additionalParams) Launch an NZ application in the cloud with the given URL
boolean shutdown(String sReason) Shutdown the NZPlayerApi with the given reason
boolean shutdownApp(int appHandle, String sReason) Shutdown the NZ App with the given appHandle
boolean shutdownAppClearListener(int appHandle, String sReason) Shutdown the NZ App with the given appHandle and clear the app status listener at the same time. In this version, the listener won't be called after the completion of app shutdown
FrameLayout getAppView(int appHandle) Retreive the View of the NZ App corresponding to the given appHandle. Listener will be called when the app shutdown has completed
boolean resizeApp(int appHandle) Resize the display size of the NZ App with the given appHandle
void clearFocus(int appHandle) Clear the input focus (if any) from the NZ App with the given appHandle
void sendKeyDown(int keycode, int metaState) Send keyboard key down event
void sendKeyUp(int keycode, int metaState) Send keyboard key up event
boolean sendRawDataMsg(int appHandle, int param1, byte[] rawData) Send a raw data message to the NZ App with the given appHandle
instance

Call this function to access the singleton instance of the NZPlayerApi

static NZPlayerApi instance()

Returns:
NZPlayerApi The singleton instance of the NZPlayerApi
init

Call this function to initialize the NZPlayer. This method only triggers the initialization, the result of the initialization is reported by the NZPlayer by calling the onNZPlayerInit callback. Note that this method must be called prior to any other methods.

boolean init(Context context, String devKey, DeviceType deviceType, PlayerStatusListener clientStatusListener)

Parameters:
context Android Activity context in which the NZPlayer is embedded
devKey Developer key to be used for authentication, not currently used, pass empty string.
deviceType The type of Android device. See DeviceType
playerStatusListener A callback interface object whose methods will be called by the NZPlayer to report overall player events. See PlayerStatusListener
Returns:
boolean If the initialization has started successfully, true is returned. Otherwise, false is returned
shutdown

Call this function to shutdown the NZPlayer. It initiates the shutdown and the result of the shutdown is reported by the NZPlayer by calling the onNZPlayerShutdown callback.

boolean shutdown(String sReason)

Parameters:
sReason Shutdown reason string
Returns:
boolean If the shutdown has started successfully, true is returned. Otherwise, false is returned
pause

Call this function to pause the NZPlayer. Typically this should be called in the activity onPause method

void pause()

resume

Call this function to resume the NZPlayer. Typically this should be called in the activity onResume method

void resume()

void resume(String sReasonCode)

Parameters:
sReasonCode Resume reason code
launchApp

This function can be called to launch an NZ App with the given URL

int launchApp(Context appContext, String appUrl, int appWidth, int appHeight, AppStatusListener appStatusListener, String appDeviceProfile, String additionalParams)

Parameters
context Android Activity context in which the NZPlayer view for this NZApp is embedded
appUrl URL corresponding to the NZ App that is to be launched
appWidth Width of the rectangle for the embedded NZ App
appHeight Height of the rectangle for the embedded NZ App
appStatusListener A callback interface object whose methods will be called by the NZPlayer to report player events for the launched app. See AppStatusListener
appDeviceProfile Device profile from NZPlayerApi.NZPlayerApiConstants.c_DeviceProfile_*
additionalParams Additional app params
Returns:
int The application handle that is passed to the API for methods that further control the embedded application.
shutdownApp

This function can be used to shutdown a previously launched NZ App. It initiates the shutdown of the app and the result of the shutdown is reported by the NZPlayer by calling the onNZPlayerAppShutdown callback.

boolean shutdownApp(int appHandle, String sReason)

Parameters
appHandle An application handle corresponding to the NZ App that should be shutdown
sReason Reason string for shutdown
Returns:
boolean If the app shutdown has started successfully, true is returned. Otherwise, false is returned
shutdownAppClearListener

This function can be used to shutdown a previously launched NZ App and at the same time clear the app listener provided when the app was launched. It initiates the shutdown of the app but does not call any callbacks

boolean shutdownAppClearListener(int appHandle, String sReason)

Parameters
appHandle An application handle corresponding to the NZ App that should be shutdown
sReason Reason string
Returns:
boolean If the app shutdown has started successfully, true is returned. Otherwise, false is returned
getAppView

Get the Android View into which the NZ App given by the appHandle is rendered. Note that the app should have been launched previously. This method should be called after calling the launchApp method and the returned View should be attached to the android view hierarchy. This ensures that the NZPlayer can render the output into the View. Without attachment to the Android view hierarchy, NZPlayer may not be able to render the NZ App into the View

FrameLayout getAppView(int appHandle)

Parameters
appHandle An application handle corresponding to the NZ App whose View needs to be retreived
Returns:
FrameLayout A view root into which the NZ App with the given appHandle will be rendered by the NZPlayer
resizeApp

This function can be used to resize a previously launched NZ App

boolean resizeApp(int appHandle, int appWidth, int appHeight)

Parameters
appHandle An application handle corresponding to the NZ App that should be resized
appWidth New Width of the rectangle for the embedded NZ App
appHeight New Height of the rectangle for the embedded NZ App
Returns:
boolean If the app is resized successfully, true is returned. Otherwise, false is returned
clearFocus

This function should be called to clear the focus from the View corresponding to the NZ App given by appHandle. For any given NZ App, if a touch is detected by the View corresponding to that app, it grabs the focus. This ensures that any inputs (touch, keyboard, mouse etc) are intercepted by the NZPlayer and forwarded to the NZ App running in the cloud. In order for the host application to get focus back, they have to call this clearFocus method to ensure that the embedded app no longer has the focus. The host app developer is responsible for determining when the focus should be taken away from the embedded app

void clearFocus(int appHandle)

Parameters
appHandle An application handle corresponding to the NZ App from which focus should be cleared
sendKeyDown

This function is called to send a keyboard key down event

sendKeyDown(int keycode, int metaState)

Parameters
keycode Key event code from Android Dev Keycodes
metaState Meta key state flags from Android Dev Keycodes
sendKeyUp

This function is called to send a keyboard key up event

sendKeyUp(int keycode, int metaState)

Parameters
keycode Key event code from Android Dev Keycodes
metaState Meta key state flags from Android Dev Keycodes
sendRawDataMsg

This function can be used to send an NZ App specific raw data message to the NZ App running in the cloud.

Parameters
appHandle An application handle corresponding to the NZ App to which raw data message is sent
param1 An integer parameter that is included in the raw data message. This parameter is sent to the NZ App without any modification
rawData Raw data message bytes to be sent to the NZ App. The NZPlayer passes this parameter to NZ App without any modification
Returns:
boolean If the raw data message is sent successfully, true is returned. Otherwise, false is returned