Skip to main content
Version: Next

Keep Screen Awake

API Reference: keepScreenAwake

By default, mobile devices will try to last their batteries as much as possible. Therefore, due to inactivity, the screen will be turned off after some time to conserve the battery.

However, this behavior can be frustrating, especially if your application has a media content like video or stream. In those situations, you will want to keep the screen on as much as possible.

To prevent the screen to be turned off, you can use keepScreenAwake property on Smartface.

Android Prerequisites for Keep Awake​

To use this feature, WAKE_LOCK permission should be granted on AndroidManifest.xml file. This permission is commented out on default Smartface workspace. Removing the comment will enable the feature.

Keep in mind that this permission is normal permission, therefore users will not be receiving any notification when it is turned on or off.

More info:

tip

On Smartface Emulator, this permission is enabled so you can test the feature while developing your application.

iOS Prerequisites for Keep Awake​

Nothing is required for iOS. You can use the property directly.

Usage of Keep Awake​

Application.keepScreenAwake = true;

The moment you set the property to true, your application will prevent the device from turning off the screen until you set it back to false. It shouldn't stay true through the lifecycle of the Application, you should only use this when it is necessary, otherwise your Application will cause the device to consume battery more than needed.

Therefore, it is recommended to set it to false after the user is done with relevant action.

Application.keepScreenAwake = false;

Ideal Usage​

Typically, keeping the screen on is necessary on a single page. Therefore, your usage should be similar to the code below:

scripts/pages/pgVideo.ts
import PgVideoDesign from "generated/pages/pgVideo";
import { Route, Router } from "@smartface/router";
import Application from "@smartface/native/application";

//You should create new Page from UI-Editor and extend with it.
export default class PgVideo extends PgVideoDesign {
  constructor(private router?: Router, private route?: Route) {
    super({});
  }
  
  onShow() {
    super.onShow();
    //...your implementation goes here
    Application.keepScreenAwake = true;
    // After the page is rendered, the screen will stay open on idle.   
  }

  onLoad() {
    super.onLoad();
    this.centerizeTheChildrenLayout();
      //...your initialization goes here
  }

  onHide() {
    super.onHide();
    Application.keepScreenAwake = false;
    // After user navigates away from the screen, this event will be called.
  }
}
info

It is always better idea to toggle on the property on onShow. onLoad method only triggers when the page is first created on router side. On singleton pages or pop-up pages, onLoad function will not trigger.

To learn more about onHide or onShow event, refer to Page Life Cycle documentation below:

Page Life-Cycle

If you want your application to be open all the time, instead of writing the code above in every single page, you should refer to the code below:

scripts/app.ts
///... Your app.ts code goes here
import Application from "@smartface/native/application";

Application.onMinimize = () => {
  /**
   * This assignment is mostly not necessary,
   * but the behavior of different devices may vary.
   */
  Application.keepScreenAwake = false;
};

Application.onMaximize = () => {
  Application.keepScreenAwake = true;
};
tip

Application events usually should be kept in app.ts or another distinct file. The events affect the whole project.

To learn more about onMinimize and onMaximize, refer to Application events for detailed information.

Application