Github user nikhilkh commented on a diff in the pull request:
https://github.com/apache/cordova-docs/pull/461#discussion_r50503985
--- Diff: www/docs/en/dev/guide/platforms/android/lifecycle.md ---
@@ -22,57 +22,127 @@ title: Android Lifecycle Guide
# Android Lifecycle Guide
-Native Android apps typically consist of a series of "activities" that the
user interacts with. Activities can be thought of as the individual screens
that make up an application; different tasks in an app will often have their
own activity. Each activity has a lifecycle, and can be created and destroyed
as the OS sees fit.
-
-In contrast, Cordova applications on the Android platform are executed
within a Webview that is embedded in a *single* Android activity. The lifecycle
of this activity is exposed to your application through the document events
that are fired. These events are not guaranteed to line up with Android's
lifecycle, but they can provide guidelines for saving and restoring your state.
These events roughly map to Android callbacks as follows:
-
-Cordova Event | Rough Android Equivalent
-----------------|-----------------------------------
-`deviceready` | `onCreate()`
-`pause` | `onPause()`
-`resume` | `onResume()`
-
-Often, Cordova applications are confined to the single activity that
contains the Webview. However, there are instances in which other activities
may be launched that push the Cordova activity to the background. It is
important in these cases to be aware of the Android lifecycle and properly
maintain your application's state by respecting it.
-
-## Low memory and the Activity lifecycle
-
-Plugins have the ability to launch activities beyond the Cordova activity
in order to perform some tasks. For example, the Apache camera plugin,
cordova-plugin-camera, launches the device's camera activity in order to take
photos.
-
-The flow of events in this case looks something like this:
+## Cordova and Android
+
+Native Android apps typically consist of a series of "activities" that the
user
+interacts with. Activities can be thought of as the individual screens
that make
+up an application; different tasks in an app will often have their own
activity.
+Each activity has its own lifecycle that is maintained as the activity
enters
+and leaves the foreground of a user's device.
+
+In contrast, Cordova applications on the Android platform are executed
within a
+Webview that is embedded in a *single* Android activity. The lifecycle of
this
+activity is exposed to your application through the document events that
are
+fired. The events are not guaranteed to line up with Android's lifecycle,
but
+they can provide guidelines for saving and restoring your state. These
events
+roughly map to Android callbacks as follows:
+
+Cordova Event | Rough Android Equivalent | Meaning
+----------------|---------------------------|-----------------
+`deviceready` | `onCreate()` | Application is starting (not
from background)
+`pause` | `onPause()` | Application is moving to the
background
+`resume` | `onResume()` | Application is returning to
the foreground
+
+Most other Cordova platforms have a similar concept of lifecycles and
should
+fire these same events when similar actions happen on a user's device.
However,
+Android presents some unique challenges that can sometimes show up thanks
to the
+native Activity lifecycle.
+
+## What makes Android different?
+
+In Android, the OS can choose to kill activities in the background in
+order to free up resources if the device running the application is low on
+memory. Unfortunately, when the activity holding your application is
killed,
+the Webview in which your application lives will be destroyed as well. Any
state
+that your application is maintaining will be lost in this case. When the
user
+navigates back to your application, the Activity and Webview will be
+recreated by the OS, but state will not be automatically restored for your
+Cordova app. For this reason, it is imperative that your application be
aware of
+the lifecycle events that are fired and maintain whatever state is
appropriate
+to make sure a user's context in your app is not lost when they leave the
+application.
+
+## When can this happen?
+
+Your application is susceptible to being destroyed by the OS whenever it
leaves
+the sight of the user. There are two main situations in which this can
occur.
+The first and most obvious case is when the user presses the home button or
+switches to another application.
+
+However, there is a second (and much more subtle) case that certain
plugins can
+introduce. As noted above, Cordova applications are usually confined to the
+single activity that contains the Webview. However, there are instances in
which
+other activities may be launched by plugins and temporarily push the
Cordova
+activity to the background. These other Activities are typically launched
in
+order to perform a specific task using a native application installed on
the
+device. For example, the Apache camera plugin launches whatever camera
activity
+is natively installed on the device in order to take a photo. Reusing the
+installed camera application in this way makes your application feel much
more
+like a native app when the user tries to take a photo. Unfortunately, when
the
+native Activity pushes your app to the background there is a chance the OS
+will kill it.
+
+For a clearer understanding of this second case, let's walk through an
example
+using the camera plugin. Imagine you have an application that requires the
user
+to take a profile photo. The flow of events in the application when
everything
+goes as planned will look something like this:
1. The user is interacting with your app and needs to take a picture
2. The camera plugin launches the native camera activity
- * *The Cordova activity is pushed to the background (`pause` event is
fired)*
+ * *The Cordova activity is pushed to the background (pause event is
fired)*
3. The user takes a photo
4. The camera activity finishes
- * *The Cordova activity is moved to the foreground (`resume` event is
fired)*
+ * *The Cordova activity is moved to the foreground (resume event is
fired)*
5. The user is returned to your application where they left off
-However, this flow of events can be disrupted if a device is low on
memory. The Android OS will often kill background activities in order to free
up memory if necessary. Unfortunately, when the activity holding your
application is killed, the Webview in which your application lives will be
destroyed as well. Any state that your application is maintaining will be lost
in this case. When the user navigates back to your the application, the
Activity and Webview will be recreated by the OS, but state will not be
automatically restored.
-
-If state is not properly saved when the Activity is destroyed, the above
sequence of events instead plays out as follows:
+However, this flow of events can be disrupted if a device is low on
memory. If
+the Activity is killed by the OS, the above sequence of events instead
plays out
+as follows:
1. The user is interacting with your app and needs to take a picture
2. The camera plugin launches the native camera activity
- * *The OS destroys the Cordova activity (`pause` event is fired)*
+ * *The OS destroys the Cordova activity (pause event is fired)*
3. The user takes a photo
4. The camera activity finishes
- * *The OS recreates the Cordova activity (`deviceready` and `resume`
events are fired)*
+ * *The OS recreates the Cordova activity (deviceready and resume
events are fired)*
5. The user is confused as to why they are suddenly back at your app's
login screen
-In this instance, the photo that was taken is lost and the user is given
the confusing and frustrating experience of having your application appear to
randomly restart. The key to preventing this experience is subscribing to
events and properly maintaining state as part of the activity lifecycle.
-
-## Maintaining state
-
-In the examples above, the javascript events that are fired are noted in
italics. These events are your opportunity to save and restore your
application's state. You should register callbacks in your application's
`bindEvents` function that respond to the lifecycle events by saving state.
What information you save and how you save it is left to your discretion, but
you should be sure to save enough information so that you can restore the user
to exactly where they left off when they return to your application.
-
-## Testing the Activity Lifecycle
-
-Android provides a developer setting for debugging Activity destruction on
low memory. Enable the "Don't keep activities" setting in the Developer Options
menu on your device or emulator to simulate low memory scenarios. If your
application launches external activities, you should always do some testing
with this setting enabled to ensure that you are properly handling low memory
scenarios.
+In this instance, the OS killed the application in the background and the
+application did not maintain its state as part of the lifecycle. When the
user
+returned to the app, the Webview was recreated and the app appeared to have
+restarted from scratch (hence the user's confusion). This sequence of
events is
+equivalent to what happens when the home button is pressed or the user
switches
+applications. The key to preventing the above experience is subscribing to
+events and properly maintaining state as part of the activity lifecycle.
+
+## Respecting the Lifecycle
+
+In the examples above, the javascript events that are fired are noted in
+italics. These events are your opportunity to save and restore your
+application's state. You should register callbacks in your application's
+`bindEvents` function that respond to the lifecycle events by saving
state. What
+information you save and how you save it is left to your discretion, but
you
+should be sure to save enough information so that you can restore the user
to
+exactly where they left off when they return to your application.
+
+There is one additional factor in the example above that only applies in
the
+second-discussed situation (i.e. when a plugin launches an external
activity).
+Not only was the state of the application lost when the user finished
taking a
+photo, but so was the photo that the user took. Normally, that photo would
be
+delivered to your application through the callback that was registered
with the
+camera plugin. However, when the Webview was destroyed that callback was
lost
+forever. Luckily, cordova-android 5.1.0 and above provide a means for
getting
+the result of that plugin call when your application resumes.
## Retrieving plugin callback results
-When the OS destroys the Cordova activity in the above example, any
pending callbacks are lost as well. This means that if you passed a callback to
the plugin that launched the new activity (e.g. cordova-plugin-camera), that
callback will NOT be fired when the application is recreated. However, there is
a way for plugins to pass the result of this call to your application. The
`resume` event's payload will contain any pending plugin results from the
plugin request that launched the external activity made prior to the activity
being destroyed.
+When the OS destroys the Cordova activity that was pushed into the
background
+by a plugin, any pending callbacks are lost as well. This means that if you
+passed a callback to the plugin that launched the new activity (e.g. the
camera
+plugin), that callback will NOT be fired when the application is recreated.
+However, starting in cordova-android 5.1.0, the `resume` event's payload
will
--- End diff --
The version needs to be in BOLD and distinctive - perhaps as a top-level
heading
---
If your project is set up for it, you can reply to this email and have your
reply appear on GitHub as well. If your project does not have this feature
enabled and wishes so, or if the feature is enabled but not working, please
contact infrastructure at infrastruct...@apache.org or file a JIRA ticket
with INFRA.
---
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscr...@cordova.apache.org
For additional commands, e-mail: dev-h...@cordova.apache.org
