top

Multitasking

This topic describes multitasking, which allows you to save the application state when the user launches another application or TV channel, and restore it when the application is resumed. You can also monitor for changes in the visibility of your application.

When the user switches from your application to another application or TV channel, JavaScript execution is paused, and your application must save its current state to RAM and hide in the background. The application state is recovered when the application is resumed.

All Samsung TVs since 2015 support multitasking. Multitasking is also supported on the TV emulator since Tizen TV Extension 2.1.2.

Note

To be published on Samsung Apps TV, your application must handle multitasking appropriately.

A running application can be hidden based on the application logic, or through user interaction:

  • Based on the application logic:
    • Use the Application API to launch another application or hide the current application.
  • Through user interaction:
    • The user can use the remote control to launch another application or change the input source.
    • The user can switch off the TV, if “Samsung Instant On” mode is enabled in the TV settings.

Prerequisites

To be able to launch other applications, the application has to request permission by adding the following privilege to the “config.xml” file:

<tizen:privilege name='http://tizen.org/privilege/application.launch'/> 

Launching Other Applications

You can launch another application in 2 ways:

  • Calling the launch() method:

    tizen.application.launch(...);
    
  • Calling the launchAppControl() method:

    tizen.application.launchAppControl(...);
    

Hiding Applications

To hide the current application, call the hide() method:

tizen.application.getCurrentApplication().hide();

Monitoring Visibility Changes

To monitor the visibility state of your application, create a listener for the visibilitychange event. The listener is notified each time your application is hidden or resumed, for example due to user interaction.

document.addEventListener('visibilitychange', function() {
  if (document.hidden) {
    //Something you want to do when an application is hidden.
  } else {
    //Something you want to do when an application is resumed.
  }
});
Note

The visibilitychange event also fires when the application exits.

Special Multitasking Scenarios

Some special scenarios can occur during multitasking. You must pay attention to these and ensure that your application responds appropriately.

  • Using the AVPlay API for media playback
    When using the AVPlay API to play media content, do not call the pause() and play() methods when the application is hidden and resumed. Instead, call the suspend() method to save the playback state, and the restore() method to restore it. These methods are not needed when using the HTML5 standard video element for media playback.

    • If the media content URL is static or the session does not expire:

      document.addEventListener('visibilitychange', function() {
        if (document.hidden) {
          //Mandatory. If you use avplay, call this method
          webapis.avplay.suspend(); 
        } else {
          webapis.avplay.restore();
        }
      });
      
    • If the DRM session must be reset when the application is resumed:

      document.addEventListener('visibilitychange', function() {
        if (document.hidden) {
          webapis.avplay.suspend(); 
        } else {
          webapis.avplay.restore(url, resumeposition, true);
          webapis.avplay.setDrm('', '', '');
          webapis.avplay.prepare();
          webapis.avplay.play();
        }
      });
      
    • If the media content URL changes periodically, use the new URL as a parameter for the restore() method. For example, a Live Channel session can expire or the content URL can have a dynamic token appended to it.

      document.addEventListener('visibilitychange', function() {
        if (document.hidden) {
          webapis.avplay.suspend(); 
        } else {
          webapis.avplay.restore(url, resumeposition, true);
        }
      });
      
  • Restoring focus and highlights
    When running an application, the focus and highlight of the application must be on an element, such as the video control bar, a popup, or a button. Store the focus and highlight states when the application is hidden, and restore them to the element when the application is resumed.

  • Checking network status
    The network connection status can change while your application is hidden, preventing the application from functioning properly when it is resumed.
    To check for network connectivity when your application resumes:

    document.addEventListener('visibilitychange', function() {
      if (document.hidden) {
        ...
      } 
      else {
        var gatewayStatus = webapis.network.isConnectedToGateway();
        if (!gatewayStatus) {
          //Something you want to do when network is disconnected
        }
      }
    });
    

    If the network is disconnected, you must stop jobs requiring a network connection, such as network media playback and server request sending. Return the user to the previous page, inform them of the disconnected status using a popup, and monitor for network reconnection. For more information, see Checking Network Status.

  • Handling expired data
    If an application is hidden for a long time, the stored runtime data can become invalid because of the service’s security policy. You must check whether these data are still valid when the application is resumed. The following are examples of situations where you need to handle expired data:

    • Login sessions
      Many service providers have policies where a login session expires after several hours and the user must log in again to use the service. When your application resumes, check the login session validity. If it has expired, show a logged out screen and a popup requesting to log in again.
    • Media content using digital rights management (DRM)
      For media content using DRM, the content URL can expire after some time and change to a new URL. The content cannot play using the expired URL. When your application resumes, check the content URL validity. If it has expired, return the user to the previous page and show a popup informing them of the expired status.
  • Calculating time
    Be careful when using the time() method. When an application is in the hidden state, JavaScript execution is paused, potentially affecting time calculations:

    • Do not calculate data expiration time internally. Instead, check for data expiry by communicating with the service provider’s server.
    • Notification popups which close automatically after a few seconds can fail to close if the application has entered the hidden state. Implement the popup timeout carefully.