diff options
48 files changed, 2751 insertions, 125 deletions
diff --git a/core/java/android/content/Intent.java b/core/java/android/content/Intent.java index 77a7c691e7d3..86b00a61d479 100644 --- a/core/java/android/content/Intent.java +++ b/core/java/android/content/Intent.java @@ -115,7 +115,7 @@ import java.util.Set; * </li> * <li> <p><b>{@link #ACTION_VIEW} <i>tel:123</i></b> -- Display * the phone dialer with the given number filled in. Note how the - * VIEW action does what what is considered the most reasonable thing for + * VIEW action does what is considered the most reasonable thing for * a particular URI.</p> * </li> * <li> <p><b>{@link #ACTION_DIAL} <i>tel:123</i></b> -- Display @@ -358,7 +358,7 @@ import java.util.Set; * <category android:name="{@link #CATEGORY_DEFAULT android.intent.category.DEFAULT}" /> * <data android:mimeType="vnd.android.cursor.item/<i>vnd.google.note</i>" /> * </intent-filter></pre> - * <p>This filter describes the ability return to the caller a note selected by + * <p>This filter describes the ability to return to the caller a note selected by * the user without needing to know where it came from. The data type * <code>vnd.android.cursor.item/vnd.google.note</code> is a URI from which * a Cursor of exactly one (<code>vnd.android.cursor.item</code>) item can @@ -1287,14 +1287,14 @@ public class Intent implements Parcelable, Cloneable { "android.intent.extra.ASSIST_INPUT_DEVICE_ID"; /** - * Activity Action: List all available applications + * Activity Action: List all available applications. * <p>Input: Nothing. * <p>Output: nothing. */ @SdkConstant(SdkConstantType.ACTIVITY_INTENT_ACTION) public static final String ACTION_ALL_APPS = "android.intent.action.ALL_APPS"; /** - * Activity Action: Show settings for choosing wallpaper + * Activity Action: Show settings for choosing wallpaper. * <p>Input: Nothing. * <p>Output: Nothing. */ @@ -1856,7 +1856,7 @@ public class Intent implements Parcelable, Cloneable { /** * Broadcast Action: An existing application package has been removed from * the device. The data contains the name of the package. The package - * that is being installed does <em>not</em> receive this Intent. + * that is being removed does <em>not</em> receive this Intent. * <ul> * <li> {@link #EXTRA_UID} containing the integer uid previously assigned * to the package. @@ -1890,9 +1890,9 @@ public class Intent implements Parcelable, Cloneable { public static final String ACTION_PACKAGE_FULLY_REMOVED = "android.intent.action.PACKAGE_FULLY_REMOVED"; /** - * Broadcast Action: An existing application package has been changed (e.g. - * a component has been enabled or disabled). The data contains the name of - * the package. + * Broadcast Action: An existing application package has been changed (for + * example, a component has been enabled or disabled). The data contains + * the name of the package. * <ul> * <li> {@link #EXTRA_UID} containing the integer uid assigned to the package. * <li> {@link #EXTRA_CHANGED_COMPONENT_NAME_LIST} containing the class name @@ -1964,9 +1964,9 @@ public class Intent implements Parcelable, Cloneable { public static final String ACTION_UID_REMOVED = "android.intent.action.UID_REMOVED"; /** - * Broadcast Action: Sent to the installer package of an application - * when that application is first launched (that is the first time it - * is moved out of the stopped state). The data contains the name of the package. + * Broadcast Action: Sent to the installer package of an application when + * that application is first launched (that is the first time it is moved + * out of the stopped state). The data contains the name of the package. * * <p class="note">This is a protected intent that can only be sent * by the system. @@ -1994,8 +1994,9 @@ public class Intent implements Parcelable, Cloneable { public static final String ACTION_PACKAGE_VERIFIED = "android.intent.action.PACKAGE_VERIFIED"; /** - * Broadcast Action: Sent to the system intent filter verifier when an intent filter - * needs to be verified. The data contains the filter data hosts to be verified against. + * Broadcast Action: Sent to the system intent filter verifier when an + * intent filter needs to be verified. The data contains the filter data + * hosts to be verified against. * <p class="note"> * This is a protected intent that can only be sent by the system. * </p> diff --git a/core/java/android/hardware/input/InputManager.java b/core/java/android/hardware/input/InputManager.java index 444f0201b448..d519ce82be32 100644 --- a/core/java/android/hardware/input/InputManager.java +++ b/core/java/android/hardware/input/InputManager.java @@ -107,7 +107,7 @@ public final class InputManager { * </p><p> * The <code>android:name</code> attribute specifies an identifier by which * the keyboard layout will be known in the package. - * The <code>android:label</code> attributes specifies a human-readable descriptive + * The <code>android:label</code> attribute specifies a human-readable descriptive * label to describe the keyboard layout in the user interface, such as "English (US)". * The <code>android:keyboardLayout</code> attribute refers to a * <a href="http://source.android.com/tech/input/key-character-map-files.html"> diff --git a/core/java/android/nfc/tech/NfcBarcode.java b/core/java/android/nfc/tech/NfcBarcode.java index 8901f287c47a..421ba7827cb1 100644 --- a/core/java/android/nfc/tech/NfcBarcode.java +++ b/core/java/android/nfc/tech/NfcBarcode.java @@ -113,10 +113,10 @@ public final class NfcBarcode extends BasicTagTechnology { * <p>Does not cause any RF activity and does not block. * * @return a byte array containing the barcode - * @see <a href="http://www.kovio.com/docs/kovionfcbarcode.pdf"> - * Kovio 128-bit NFC barcode datasheet</a> - * @see <a href="http://kovio.com/docs/kovio-128-nfc-barcode-data-format.pdf"> - * Kovio 128-bit NFC barcode data format</a> + * @see <a href="http://www.thinfilm.no/docs/thinfilm-nfc-barcode-datasheet.pdf"> + * Thinfilm NFC Barcode tag specification (previously Kovio NFC Barcode)</a> + * @see <a href="http://www.thinfilm.no/docs/thinfilm-nfc-barcode-data-format.pdf"> + * Thinfilm NFC Barcode data format (previously Kovio NFC Barcode)</a> */ public byte[] getBarcode() { switch (mType) { diff --git a/docs/html/about/dashboards/index.jd b/docs/html/about/dashboards/index.jd index 471dc07479e1..2eecd45b610a 100644 --- a/docs/html/about/dashboards/index.jd +++ b/docs/html/about/dashboards/index.jd @@ -59,7 +59,7 @@ Platform Versions</a>.</p> </div> -<p style="clear:both"><em>Data collected during a 7-day period ending on January 4, 2016. +<p style="clear:both"><em>Data collected during a 7-day period ending on February 1, 2016. <br/>Any versions with less than 0.1% distribution are not shown.</em> </p> @@ -90,7 +90,7 @@ Screens</a>.</p> </div> -<p style="clear:both"><em>Data collected during a 7-day period ending on January 4, 2016. +<p style="clear:both"><em>Data collected during a 7-day period ending on February 1, 2016. <br/>Any screen configurations with less than 0.1% distribution are not shown.</em></p> @@ -110,7 +110,7 @@ support for any lower version (for example, support for version 2.0 also implies <img alt="" style="float:right" -src="//chart.googleapis.com/chart?chl=GL%202.0%7CGL%203.0%7CGL%203.1&chf=bg%2Cs%2C00000000&chd=t%3A54.3%2C38.9%2C6.8&chco=c4df9b%2C6fad0c&cht=p&chs=400x250"> +src="//chart.googleapis.com/chart?chl=GL%202.0%7CGL%203.0%7CGL%203.1&chf=bg%2Cs%2C00000000&chd=t%3A53.2%2C39.7%2C7.1&chco=c4df9b%2C6fad0c&cht=p&chs=400x250"> <p>To declare which version of OpenGL ES your application requires, you should use the {@code android:glEsVersion} attribute of the <a @@ -128,21 +128,21 @@ uses.</p> </tr> <tr> <td>2.0</td> -<td>54.3%</td> +<td>53.2%</td> </tr> <tr> <td>3.0</td> -<td>38.9%</td> +<td>39.7%</td> </tr> <tr> <td>3.1</td> -<td>6.8%</td> +<td>7.1%</td> </tr> </table> -<p style="clear:both"><em>Data collected during a 7-day period ending on January 4, 2016</em></p> +<p style="clear:both"><em>Data collected during a 7-day period ending on February 1, 2016</em></p> @@ -156,19 +156,19 @@ var SCREEN_DATA = "Large": { "hdpi": "0.6", "ldpi": "0.3", - "mdpi": "5.4", - "tvdpi": "2.5", - "xhdpi": "0.6" + "mdpi": "5.0", + "tvdpi": "2.3", + "xhdpi": "0.5" }, "Normal": { - "hdpi": "41.1", - "mdpi": "5.5", + "hdpi": "41.5", + "mdpi": "5.1", "tvdpi": "0.1", - "xhdpi": "22.1", - "xxhdpi": "14.7" + "xhdpi": "22.9", + "xxhdpi": "14.8" }, "Small": { - "ldpi": "2.6" + "ldpi": "2.4" }, "Xlarge": { "hdpi": "0.3", @@ -176,8 +176,8 @@ var SCREEN_DATA = "xhdpi": "0.7" } }, - "densitychart": "//chart.googleapis.com/chart?chd=t%3A2.9%2C14.4%2C2.6%2C42.0%2C23.4%2C14.7&chf=bg%2Cs%2C00000000&chco=c4df9b%2C6fad0c&chl=ldpi%7Cmdpi%7Ctvdpi%7Chdpi%7Cxhdpi%7Cxxhdpi&cht=p&chs=400x250", - "layoutchart": "//chart.googleapis.com/chart?chd=t%3A4.5%2C9.4%2C83.5%2C2.6&chf=bg%2Cs%2C00000000&chco=c4df9b%2C6fad0c&chl=Xlarge%7CLarge%7CNormal%7CSmall&cht=p&chs=400x250" + "densitychart": "//chart.googleapis.com/chart?cht=p&chs=400x250&chl=ldpi%7Cmdpi%7Ctvdpi%7Chdpi%7Cxhdpi%7Cxxhdpi&chco=c4df9b%2C6fad0c&chd=t%3A2.7%2C13.6%2C2.4%2C42.4%2C24.1%2C14.8&chf=bg%2Cs%2C00000000", + "layoutchart": "//chart.googleapis.com/chart?cht=p&chs=400x250&chl=Xlarge%7CLarge%7CNormal%7CSmall&chco=c4df9b%2C6fad0c&chd=t%3A4.5%2C8.7%2C84.4%2C2.4&chf=bg%2Cs%2C00000000" } ]; @@ -185,57 +185,57 @@ var SCREEN_DATA = var VERSION_DATA = [ { - "chart": "//chart.googleapis.com/chart?chd=t%3A0.2%2C3.0%2C2.7%2C24.7%2C36.1%2C32.6%2C0.7&chf=bg%2Cs%2C00000000&chco=c4df9b%2C6fad0c&chl=Froyo%7CGingerbread%7CIce%20Cream%20Sandwich%7CJelly%20Bean%7CKitKat%7CLollipop%7CMarshmallow&cht=p&chs=500x250", + "chart": "//chart.googleapis.com/chart?cht=p&chs=500x250&chl=Froyo%7CGingerbread%7CIce%20Cream%20Sandwich%7CJelly%20Bean%7CKitKat%7CLollipop%7CMarshmallow&chco=c4df9b%2C6fad0c&chd=t%3A0.1%2C2.7%2C2.5%2C23.9%2C35.5%2C34.1%2C1.2&chf=bg%2Cs%2C00000000", "data": [ { "api": 8, "name": "Froyo", - "perc": "0.2" + "perc": "0.1" }, { "api": 10, "name": "Gingerbread", - "perc": "3.0" + "perc": "2.7" }, { "api": 15, "name": "Ice Cream Sandwich", - "perc": "2.7" + "perc": "2.5" }, { "api": 16, "name": "Jelly Bean", - "perc": "9.0" + "perc": "8.8" }, { "api": 17, "name": "Jelly Bean", - "perc": "12.2" + "perc": "11.7" }, { "api": 18, "name": "Jelly Bean", - "perc": "3.5" + "perc": "3.4" }, { "api": 19, "name": "KitKat", - "perc": "36.1" + "perc": "35.5" }, { "api": 21, "name": "Lollipop", - "perc": "16.9" + "perc": "17.0" }, { "api": 22, "name": "Lollipop", - "perc": "15.7" + "perc": "17.1" }, { "api": 23, "name": "Marshmallow", - "perc": "0.7" + "perc": "1.2" } ] } diff --git a/docs/html/about/versions/android-4.0.3.jd b/docs/html/about/versions/android-4.0.3.jd index 4c2ccb96bfd3..f9627a305f0b 100644 --- a/docs/html/about/versions/android-4.0.3.jd +++ b/docs/html/about/versions/android-4.0.3.jd @@ -264,7 +264,7 @@ profiles. Quality level is represented by the {@link android.media.CamcorderProfile#QUALITY_TIME_LAPSE_QVGA} constants.</li> <li>New methods {@link android.hardware.Camera.Parameters#setVideoStabilization(boolean) setVideoStabilization()}, -{@link android.hardware.Camera.Parameters#getVideoStabilization() setVideoStabilization()}, and {@link android.hardware.Camera.Parameters#isVideoStabilizationSupported() isVideoStabilizationSupported()} +{@link android.hardware.Camera.Parameters#getVideoStabilization() getVideoStabilization()}, and {@link android.hardware.Camera.Parameters#isVideoStabilizationSupported() isVideoStabilizationSupported()} let you check and manage video stabilization for a {@link android.hardware.Camera}.</li> </ul> diff --git a/docs/html/auto/images/assets/landing/01.gif b/docs/html/auto/images/assets/landing/01.gif Binary files differindex 7a75f87d63d3..1433463728e2 100644 --- a/docs/html/auto/images/assets/landing/01.gif +++ b/docs/html/auto/images/assets/landing/01.gif diff --git a/docs/html/auto/images/assets/landing/02.gif b/docs/html/auto/images/assets/landing/02.gif Binary files differindex 655c5bcc6f5a..c0f9e525098c 100644 --- a/docs/html/auto/images/assets/landing/02.gif +++ b/docs/html/auto/images/assets/landing/02.gif diff --git a/docs/html/auto/images/assets/landing/03.gif b/docs/html/auto/images/assets/landing/03.gif Binary files differindex 195315a6a776..7dacf5997472 100644 --- a/docs/html/auto/images/assets/landing/03.gif +++ b/docs/html/auto/images/assets/landing/03.gif diff --git a/docs/html/auto/images/assets/landing/04.png b/docs/html/auto/images/assets/landing/04.png Binary files differindex aecdb584b2b1..2e0df02ec1a5 100644 --- a/docs/html/auto/images/assets/landing/04.png +++ b/docs/html/auto/images/assets/landing/04.png diff --git a/docs/html/auto/images/assets/landing/05.png b/docs/html/auto/images/assets/landing/05.png Binary files differindex a3baba461f9d..564a6fd0a9ec 100644 --- a/docs/html/auto/images/assets/landing/05.png +++ b/docs/html/auto/images/assets/landing/05.png diff --git a/docs/html/auto/images/assets/landing/06.png b/docs/html/auto/images/assets/landing/06.png Binary files differindex fe74a4960e11..dcbba9a8439d 100644 --- a/docs/html/auto/images/assets/landing/06.png +++ b/docs/html/auto/images/assets/landing/06.png diff --git a/docs/html/guide/components/fundamentals.jd b/docs/html/guide/components/fundamentals.jd index 80125ba4f07a..f1b30703f79c 100644 --- a/docs/html/guide/components/fundamentals.jd +++ b/docs/html/guide/components/fundamentals.jd @@ -298,7 +298,7 @@ app.</p> <p>In the <code><a href="{@docRoot}guide/topics/manifest/activity-element.html"><activity></a></code> element, the {@code android:name} attribute specifies the fully qualified class name of the {@link -android.app.Activity} subclass and the {@code android:label} attributes specifies a string +android.app.Activity} subclass and the {@code android:label} attribute specifies a string to use as the user-visible label for the activity.</p> <p>You must declare all app components this way:</p> diff --git a/docs/html/guide/components/services.jd b/docs/html/guide/components/services.jd index 69ba1d60d2c6..41c6d69d98b6 100644 --- a/docs/html/guide/components/services.jd +++ b/docs/html/guide/components/services.jd @@ -336,14 +336,11 @@ public class HelloIntentService extends IntentService { protected void onHandleIntent(Intent intent) { // Normally we would do some work here, like download a file. // For our sample, we just sleep for 5 seconds. - long endTime = System.currentTimeMillis() + 5*1000; - while (System.currentTimeMillis() < endTime) { - synchronized (this) { - try { - wait(endTime - System.currentTimeMillis()); - } catch (Exception e) { - } - } + try { + Thread.sleep(5000); + } catch (InterruptedException e) { + // Restore interrupt status. + Thread.currentThread().interrupt(); } } } @@ -405,14 +402,11 @@ public class HelloService extends Service { public void handleMessage(Message msg) { // Normally we would do some work here, like download a file. // For our sample, we just sleep for 5 seconds. - long endTime = System.currentTimeMillis() + 5*1000; - while (System.currentTimeMillis() < endTime) { - synchronized (this) { - try { - wait(endTime - System.currentTimeMillis()); - } catch (Exception e) { - } - } + try { + Thread.sleep(5000); + } catch (InterruptedException e) { + // Restore interrupt status. + Thread.currentThread().interrupt(); } // Stop the service using the startId, so that we don't stop // the service in the middle of handling another job diff --git a/docs/html/guide/topics/ui/menus.jd b/docs/html/guide/topics/ui/menus.jd index 4f81c93d73c0..11e84f11de6c 100644 --- a/docs/html/guide/topics/ui/menus.jd +++ b/docs/html/guide/topics/ui/menus.jd @@ -166,7 +166,7 @@ appearance and behavior. The items in the above menu include the following attri <dl> <dt>{@code android:id}</dt> - <dd>A resource ID that's unique to the item, which allows the application can recognize the item + <dd>A resource ID that's unique to the item, which allows the application to recognize the item when the user selects it.</dd> <dt>{@code android:icon}</dt> <dd>A reference to a drawable to use as the item's icon.</dd> diff --git a/docs/html/images/build.png b/docs/html/images/build.png Binary files differindex bf4cf4edb96a..94cc21b8b963 100644 --- a/docs/html/images/build.png +++ b/docs/html/images/build.png diff --git a/docs/html/images/tools/ai-ilightbulb.png b/docs/html/images/tools/ai-ilightbulb.png Binary files differnew file mode 100644 index 000000000000..e9522f323e21 --- /dev/null +++ b/docs/html/images/tools/ai-ilightbulb.png diff --git a/docs/html/images/tools/ai-lint.png b/docs/html/images/tools/ai-lint.png Binary files differnew file mode 100644 index 000000000000..2a0aabc8f1a3 --- /dev/null +++ b/docs/html/images/tools/ai-lint.png diff --git a/docs/html/images/training/performance/network_traffic_colors.png b/docs/html/images/training/performance/network_traffic_colors.png Binary files differnew file mode 100644 index 000000000000..e3f40147fd26 --- /dev/null +++ b/docs/html/images/training/performance/network_traffic_colors.png diff --git a/docs/html/images/training/performance/optimal_network_traffic_pattern.png b/docs/html/images/training/performance/optimal_network_traffic_pattern.png Binary files differnew file mode 100644 index 000000000000..a32c19addd06 --- /dev/null +++ b/docs/html/images/training/performance/optimal_network_traffic_pattern.png diff --git a/docs/html/images/training/performance/suboptimal_network_traffic_pattern.png b/docs/html/images/training/performance/suboptimal_network_traffic_pattern.png Binary files differnew file mode 100644 index 000000000000..c35c673efcd1 --- /dev/null +++ b/docs/html/images/training/performance/suboptimal_network_traffic_pattern.png diff --git a/docs/html/ndk/downloads/index.jd b/docs/html/ndk/downloads/index.jd index f67499360aee..03eef03b562b 100644 --- a/docs/html/ndk/downloads/index.jd +++ b/docs/html/ndk/downloads/index.jd @@ -314,9 +314,6 @@ injunctive remedies (or an equivalent type of urgent legal relief) in any jurisd NDK Revision History.</a></p> -<h2 id="Downloads">Downloading</h2> - - <script> $('#Downloads').after($('#download-table')); </script> diff --git a/docs/html/ndk/guides/audio/basics.jd b/docs/html/ndk/guides/audio/basics.jd new file mode 100644 index 000000000000..a5f0ff5fe0af --- /dev/null +++ b/docs/html/ndk/guides/audio/basics.jd @@ -0,0 +1,125 @@ +page.title=OpenSL ES™ Basics +@jd:body + +<div id="qv-wrapper"> + <div id="qv"> + <h2>On this page</h2> + + <ol> + <li><a href="#adding">Adding OpenSL ES to Your App</a></li> + <li><a href="#building">Building and Debugging</a></li> + <li><a href="#samples">Samples</a></li> + </ol> + </div> + </div> + + +<p> +The Khronos Group's OpenSL ES standard exposes audio features +similar to those in the {@link android.media.MediaPlayer} and {@link android.media.MediaRecorder} +APIs in the Android Java framework. OpenSL ES provides a C language interface as well as +C++ bindings, allowing you to call it from code written in either language. +</p> + +<p> +This page describes how to add these audio APIs into your app's source code, and how to incorporate +them into the build process. +</p> + +<h2 id="adding">Adding OpenSL ES to your App</h2> + +<p> +You can call OpenSL ES from both C and C++ code. To add the core OpenSL ES +feature set to your app, include the {@code OpenSLES.h} header file: + +</p> +<pre> +#include <SLES/OpenSLES.h> +</pre> + +<p> +To add the OpenSL ES <a href="{@docRoot}ndk/guides/audio/opensl-for-android.html#ae"> +Android extensions</a> as well, include the {@code OpenSLES_Android.h} header file: +</p> +<pre> +#include <SLES/OpenSLES_Android.h> +</pre> + + +<h2 id="building">Building and Debugging</h2> + +<p> +You can incorporate OpenSL ES into your build by specifying it in the +<a href="{@docRoot}ndk/guides/android_mk.html">{@code Android.mk}</a> file that serves as one of the +NDK build system's makefiles. Add the following line to +<a href="{@docRoot}ndk/guides/android_mk.html">{@code Android.mk}</a>: +</p> + +<pre> +LOCAL_LDLIBS += -lOpenSLES +</pre> + +<p> +For robust debugging, we recommend that you examine the {@code SLresult} value that most of +the OpenSL ES APIs return. You can use +<a class="external-link" href="http://en.wikipedia.org/wiki/Assertion_(computing)">asserts</a> +or more advanced error-handling logic for debugging; neither offers +an inherent advantage for working with OpenSL ES, although one or the other might be more suitable +for a given use case. +</p> + +<p> +We use asserts in our <a href="https://github.com/googlesamples/android-ndk">examples</a>, because +they help catch unrealistic conditions that would indicate a coding error. We have used explicit +error handling for other conditions more likely to occur in production. +</p> + +<p> +Many API errors result in a log entry, in addition to a non-zero result code. Such log entries +can provide additional detail that proves especially useful for relatively complex APIs such as +<a class="external-link" href="https://www.khronos.org/registry/sles/specs/OpenSL_ES_Specification_1.1.pdf"> +{@code Engine::CreateAudioPlayer}</a>. +</p> + +<p> +You can view the log either from the command line or from Android Studio. To examine the log from +the command line, type the following: +</p> + +<pre class="no-pretty-print"> +$ adb logcat +</pre> + +<p> +To examine the log from Android Studio, either click the <em>Logcat</em> tab in the +<a href="{@docRoot}tools/debugging/debugging-studio.html#runDebug"><em>Debug</em></a> +window, or click the <em>Devices | logcat</em> tab in the +<a href="{@docRoot}tools/debugging/debugging-studio.html#systemLogView"><em>Android DDMS</em></a> +window. +</p> + +<h2 id="samples">Samples</h2> + +<p> +Supported and tested example code that you can use as a model for your own code resides both locally +and on GitHub. The local examples are located in +{@code platforms/android-9/samples/native-audio/}, under your NDK root installation directory. +On GitHub, they are available from the +<a class="external-link" href="https://github.com/googlesamples/android-ndk">{@code android-ndk}</a> +repository, in the +<a class="external-link" href="https://github.com/googlesamples/android-ndk/tree/master/audio-echo"> +{@code audio-echo}</a> and +<a class="external-link" href="https://github.com/googlesamples/android-ndk/tree/master/native-audio"> +{@code native-audio}</a> directories. +</p> +<p>The Android NDK implementation of OpenSL ES differs +from the reference specification for OpenSL ES 1.0.1 in a number of respects. +These differences are an important reason as to why sample code that +you copy directly from the OpenSL ES reference specification may not work in your +Android app. +</p> +<p> +For more information on differences between the reference specification and the +Android implementation, see +<a href="{@docRoot}ndk/guides/audio/opensl-for-android.html"> +OpenSL ES™ for Android</a>. diff --git a/docs/html/ndk/guides/audio/index.jd b/docs/html/ndk/guides/audio/index.jd new file mode 100644 index 000000000000..ac6e5395542e --- /dev/null +++ b/docs/html/ndk/guides/audio/index.jd @@ -0,0 +1,15 @@ +page.title=NDK Audio: OpenSL ES™ +@jd:body + +<p>The NDK package includes an Android-specific implementation of the +<a href="https://www.khronos.org/opensles/">OpenSL ES</a> API +specification from the <a href="https://www.khronos.org">Khronos Group</a>. This library +allows you to use C or C++ to implement high-performance, low-latency audio in your game or other +demanding app.</p> + +<p>This section begins by providing some +<a href="{@docRoot}ndk/guides/audio/basics.html">basic information</a> about the API, including how +to incorporate it into your app. It then explains what you need to know about the +<a href="{@docRoot}ndk/guides/audio/opensl-for-android.html">Android-specific implementation</a> +of OpenSL ES, focusing on differences between this implementation and the reference specification. +</p> diff --git a/docs/html/ndk/guides/audio/opensl-for-android.jd b/docs/html/ndk/guides/audio/opensl-for-android.jd new file mode 100644 index 000000000000..763da5a059e7 --- /dev/null +++ b/docs/html/ndk/guides/audio/opensl-for-android.jd @@ -0,0 +1,881 @@ +page.title=Native Audio: OpenSL ES™ for Android +@jd:body + +<div id="qv-wrapper"> + <div id="qv"> + <h2>On this page</h2> + + <ol> + <li><a href="#inherited">Features Inherited from the Reference Specification</a></li> + <li><a href="#ae">Android Extensions</a></li> + </ol> + </div> + </div> + +<p> +This page provides details about how the NDK implementation of OpenSL ES™ differs +from the reference specification for OpenSL ES 1.0.1. When using sample code from the +specification, you may need to modify it to work on Android. +</p> + +<h2 id="inherited">Features Inherited from the Reference Specification</h2> + +<p> +The Android NDK implementation of OpenSL ES inherits much of the feature set from +the reference specification, although with certain limitations. +</p> + +<h3>Global entry points</h3> + +<p> +OpenSL ES for Android supports all of the global entry points in the Android specification. +These entry points include: +</p> + +<ul> +<li>{@code slCreateEngine} +</li> +<li>{@code slQueryNumSupportedEngineInterfaces}</code> +</li> +<li>{@code slQuerySupportedEngineInterfaces}</code> +</li> +</ul> + +<h3>Objects and interfaces</h3> + +<p> +Table 1 shows which objects and interfaces the Android NDK implementation of +OpenSL ES supports. Green cells indicate features available in this implementation. +</p> + +<p class="table-caption" id="Objects-and-interfaces"> + <strong>Table 1.</strong> Android NDK support for objects and interfaces.</p> +<table> + <tr> + <th scope="col">Feature</th> + <th scope="col">Audio player</th> + <th scope="col">Audio recorder</th> + <th scope="col">Engine</th> + <th scope="col">Output mix</th> + </tr> + <tr> + <td>Bass boost</td> + <td>Yes</td> + <td>No</td> + <td>No</td> + <td>Yes</td> + </tr> + <tr> + <td>Buffer queue</td> + <td>Yes</td> + <td>No</td> + <td>No</td> + <td>No</td> + </tr> + <tr> + <td>Dynamic interface management</td> + <td>Yes</td> + <td>Yes</td> + <td>Yes</td> + <td>Yes</td> + </tr> + <tr> + <td>Effect send</td> + <td>Yes</td> + <td>No</td> + <td>No</td> + <td>No</td> + </tr> + <tr> + <td>Engine</td> + <td>No</td> + <td>No</td> + <td>Yes</td> + <td>No</td> + </tr> + <tr> + <td>Environmental reverb</td> + <td>No</td> + <td>No</td> + <td>No</td> + <td>Yes</td> + </tr> + <tr> + <td>Equalizer</td> + <td>Yes</td> + <td>No</td> + <td>No</td> + <td>Yes</td> + </tr> + <tr> + <td>Metadata extraction</td> + <td>Yes: Decode to PCM</td> + <td>No</td> + <td>No</td> + <td>No</td> + </tr> + <tr> + <td>Mute solo</td> + <td>Yes</td> + <td>No</td> + <td>No</td> + <td>No</td> + </tr> + <tr> + <td>Object</td> + <td>Yes</td> + <td>Yes</td> + <td>Yes</td> + <td>Yes</td> + </tr> + <tr> + <td>Play</td> + <td>Yes</td> + <td>No</td> + <td>No</td> + <td>No</td> + </tr> + <tr> + <td>Playback rate</td> + <td>Yes</td> + <td>No</td> + <td>No</td> + <td>No</td> + </tr> + <tr> + <td>Prefetch status</td> + <td>Yes</td> + <td>No</td> + <td>No</td> + <td>No</td> + </tr> + <tr> + <td>Preset reverb</td> + <td>No</td> + <td>No</td> + <td>No</td> + <td>Yes</td> + </tr> + <tr> + <td>Record</td> + <td>No</td> + <td>Yes</td> + <td>No</td> + <td>No</td> + </tr> + <tr> + <td>Seek</td> + <td>Yes</td> + <td>No</td> + <td>No</td> + <td>No</td> + </tr> + <tr> + <td>Virtualizer</td> + <td>Yes</td> + <td>No</td> + <td>No</td> + <td>Yes</td> + </tr> + <tr> + <td>Volume</td> + <td>Yes</td> + <td>No</td> + <td>No</td> + <td>No</td> + </tr> + <tr> + <td>Buffer queue data locator</td> + <td>Yes: Source</td> + <td>No</td> + <td>No</td> + <td>No</td> + </tr> + <tr> + <td>I/O device data locator</td> + <td>No</td> + <td>Yes: Source</td> + <td>No</td> + <td>No</td> + </tr> + <tr> + <td>Output mix locator</td> + <td>Yes: Sink</td> + <td>No</td> + <td>No</td> + <td>No</td> + </tr> + <tr> + <td>URI data locator</td> + <td>Yes: Source</td> + <td>No</td> + <td>No</td> + <td>No</td> + </tr> + </table> + +The next section explains limitations of some of these features. + +<h3>Limitations</h3> + +<p> +Certain limitations apply to the features in Table 1. These limitations +represent differences from the reference specification. The rest of this section provides +information about these differences.</p> + +<h4>Dynamic interface management</h4> + +<p> +OpenSL ES for Android does not support {@code RemoveInterface} or +{@code ResumeInterface}. +</p> + +<h4>Effect combinations: environment reverb and preset reverb</h4> + +<p> +You cannot have both environmental reverb and preset reverb on the same output mix. +</p> +<p> +The platform might ignore effect requests if it estimates that the +CPU load would be too high. +</p> + +<h4>Effect send</h4> + +<p> +<code>SetSendLevel()</code> supports a single send level per audio player. +</p> + +<h4>Environmental reverb</h4> + +<p> +Environmental reverb does not support the <code>reflectionsDelay</code>, +<code>reflectionsLevel</code>, or <code>reverbDelay</code> fields of +the <code>SLEnvironmentalReverbSettings</code> struct. +</p> + +<h4>MIME data format</h4> + +<p> +You can use the MIME data format only with the URI data locator, and only for an audio +player. You cannot use this data format for an audio recorder. +</p> +<p> +The Android implementation of OpenSL ES requires you to initialize <code>mimeType</code> +to either <code>NULL</code> or a valid UTF-8 string. You must also initialize +<code>containerType</code> to a valid value. +In the absence of other considerations, such as portability to other +implementations, or content format that an app cannot identify by header, +we recommend that you +set <code>mimeType</code> to <code>NULL</code> and <code>containerType</code> +to <code>SL_CONTAINERTYPE_UNSPECIFIED</code>. +</p> +<p> +OpenSL ES for Android supports the following audio formats, so long as the +Android platform supports them as well:</p> + +<ul> +<li>WAV PCM</li> +<li>WAV alaw</li> +<li>WAV ulaw</li> +<li>MP3 Ogg Vorbis</li> +<li>AAC LC</li> +<li>HE-AACv1 (AAC+)</li> +<li>HE-AACv2 (enhanced AAC+)</li> +<li>AMR</li> +<li>FLAC</li> +</ul> + +<p> +For a list of audio formats that Android supports, see +<a href="{@docRoot}guide/appendix/media-formats.html">Supported Media Formats</a>. +</p> + +<p> +The following limitations apply to handling of these and other formats in this +implementation of OpenSL ES: +</p> + +<ul> +<li>AAC formats must be reside within an MP4 or ADTS container.</li> +<li>OpenSL ES for Android does not support MIDI.</li> +<li>WMA is not part of <a class="external-link" href="https://source.android.com/">AOSP</a>, and we +have not verified its compatibility with OpenSL ES for Android.</li> +<li>The Android NDK implementation of OpenSL ES does not support direct +playback of DRM or encrypted content. To play back protected audio content, you must +decrypt it in your application before playing, with your app enforcing any DRM +restrictions.</li> +</ul> + +<h4>Object-related methods</h4> + +<p> +OpenSL ES for Android does not support the following methods for manipulating objects: +</p> + +<ul> +<li>{@code Resume()}</li> +<li>{@code RegisterCallback()}</li> +<li>{@code AbortAsyncOperation()}</li> +<li>{@code SetPriority()}</li> +<li>{@code GetPriority()}</li> +<li>{@code SetLossOfControlInterfaces()}</li> +</ul> + +<h4>PCM data format</h4> + +<p> +PCM is the only data format you can use with buffer queues. Supported PCM +playback configurations have the following characteristics: +</p> + +<ul> +<li>8-bit unsigned or 16-bit signed.</li> +<li>Mono or stereo.</li> +<li>Little-endian byte ordering.</li> +<li>Sample rates of: 8,000, 11,025, 12,000, 16,000, 22,050, 24,000, 32,000, 44,100, or +48,000 Hz.</li> +</ul> + +<p> +The configurations that OpenSL ES for Android supports for recording are +device-dependent; usually, 16,000 Hz mono 16-bit signed is available regardless of device. +</p> +<p> +The value of the <code>samplesPerSec</code> field is in units of milliHz, despite the misleading +name. To avoid accidentally using the wrong value, we recommend that you initialize this field using +one of the symbolic constants defined for this purpose, such as {@code SL_SAMPLINGRATE_44_1}. +</p> +<p> +Android 5.0 (API level 21) and above support <a href="#fp">floating-point data</a>. +</p> + +<h4>Playback rate</h4> + +<p> +An OpenSL ES <i>playback rate</i> indicates the speed at which an +object presents data, expressed in thousandths of normal speed, or <i>per mille</i>. For example, +a playback rate of 1,000 per mille is 1,000/1,000, or normal speed. +A <i>rate range</i> is a closed interval that expresses possible rate ranges. +</p> + +<p> +Support for playback-rate ranges and other capabilities may vary depending +on the platform version and implementation. Your app can determine these capabilities at runtime by +using <code>PlaybackRate::GetRateRange()</code> or +<code>PlaybackRate::GetCapabilitiesOfRate()</code> to query the device. +</p> + +<p> +A device typically supports the same rate range for a data source in PCM format, and a unity rate +range of 1000 per mille to 1000 per mille for other formats: that is, the unity rate range is +effectively a single value. +</p> + +<h4>Record</h4> + +<p> +OpenSL ES for Android does not support the <code>SL_RECORDEVENT_HEADATLIMIT</code> +or <code>SL_RECORDEVENT_HEADMOVING</code> events. +</p> + +<h4>Seek</h4> + +<p> +The <code>SetLoop()</code> method enables whole-file looping. To enable looping, +set the <code>startPos</code> parameter to 0, and the value of the <code>endPos</code> parameter +to <code>SL_TIME_UNKNOWN</code>. +</p> + +<h4>Buffer queue data locator</h4> + +<p> +An audio player or recorder with a data locator for a buffer queue supports PCM data format only. +</p> + +<h4>I/O Device data locator</h4> + +<p> +OpenSL ES for Android only supports use of an I/O device data locator when you have +specified the locator as the data source for <code>Engine::CreateAudioRecorder()</code>. +Initialize the device data locator using the values contained in the following code snippet. +</p> + +<pre> +SLDataLocator_IODevice loc_dev = + {SL_DATALOCATOR_IODEVICE, SL_IODEVICE_AUDIOINPUT, + SL_DEFAULTDEVICEID_AUDIOINPUT, NULL}; +</pre> + +<h4>URI data locator</h4> + +<p> +OpenSL ES for Android can only use the URI data locator with MIME data format, +and only for an audio player. You cannot use this data format for an audio recorder. It supports +{@code http:} and {@code file:} schemes. It does not support other schemes, such as {@code https:}, +{@code ftp:}, or +{@code content:}. +</p> + +<p> +We have not verified support for {@code rtsp:} with audio on the Android platform. +</p> + +<h2 id="ae">Android Extensions</h2> + +<p> +OpenSL ES for Android extends the reference OpenSL ES specification to make it compatible with +Android, and to take advantage of the power and flexibility of the Android platform. +</p> + +<p> +The definition of the API for the Android extensions resides in <code>OpenSLES_Android.h</code> +and the header files that it includes. Consult {@code OpenSLES_Android.h} +for details about these extensions. This file is located under your installation root, in the +{@code platforms/android-<version>/<abi>/include/SLES} directory. Unless otherwise +noted, all interfaces are explicit. +</p> + +<p> +These extensions limit your application's portability to +other OpenSL ES implementations, because they are Android-specific. You can mitigate this issue by +avoiding use of the extensions or by using {@code #ifdef} to exclude them at compile time. +</p> + +<p> +Table 2 shows the Android-specific interfaces and data locators that Android OpenSL ES supports +for each object type. Green cells indicate interfaces and data locators available for each +object type. +</p> + +<p class="table-caption" id="Android-extensions"> + <strong>Table 2.</strong> Interfaces and data locators, by object type.</p> +<table> + <tr> + <th scope="col">Feature</th> + <th scope="col">Audio player</th> + <th scope="col">Audio recorder</th> + <th scope="col">Engine</th> + <th scope="col">Output mix</th> + </tr> + <tr> + <td>Android buffer queue</td> + <td>Yes: Source (decode)</td> + <td>No</td> + <td>No</td> + <td>No</td> + </tr> + <tr> + <td>Android configuration</td> + <td>Yes</td> + <td>Yes</td> + <td>No</td> + <td>No</td> + </tr> + <tr> + <td>Android effect</td> + <td>Yes</td> + <td>No</td> + <td>No</td> + <td>Yes</td> + </tr> + <tr> + <td>Android effect capabilities</td> + <td>No</td> + <td>No</td> + <td>Yes</td> + <td>No</td> + </tr> + <tr> + <td>Android effect send</td> + <td>Yes</td> + <td>No</td> + <td>No</td> + <td>No</td> + </tr> + <tr> + <td>Android simple buffer queue</td> + <td>Yes: Source (playback) or sink (decode)</td> + <td>Yes</td> + <td>No</td> + <td>No</td> + </tr> + <tr> + <td>Android buffer queue data locator</td> + <td>Yes: Source (decode)</td> + <td>No</td> + <td>No</td> + <td>No</td> + </tr> + <tr> + <td>Android file descriptor data locator</td> + <td>Yes: Source</td> + <td>No</td> + <td>No</td> + <td>No</td> + </tr> + <tr> + <td>Android simple buffer queue data locator</td> + <td>Yes: Source (playback) or sink (decode)</td> + <td>Yes: Sink</td> + <td>No</td> + <td>No</td> + </tr> +</table> + +<h3>Android configuration interface</h3> + +<p> +The Android configuration interface provides a means to set +platform-specific parameters for objects. This interface is different from other OpenSL ES +1.0.1 interfaces in that your app can use it before instantiating the corresponding object; thus, +you can configure the object before instantiating it. The +{@code OpenSLES_AndroidConfiguration.h} header file</code>, which resides at +{@code platforms/android-<version>/<abi>/include/SLES}, +documents the following available configuration keys and values: +</p> + +<ul> +<li>Stream type for audio players (default <code>SL_ANDROID_STREAM_MEDIA</code>).</li> +<li>Record profile for audio recorders (default <code>SL_ANDROID_RECORDING_PRESET_GENERIC</code>). +</li> +</ul> + +<p> +The following code snippet shows an example of how to set the Android audio stream type on an audio +player: +</p> + +<pre> +// CreateAudioPlayer and specify SL_IID_ANDROIDCONFIGURATION +// in the required interface ID array. Do not realize player yet. +// ... +SLAndroidConfigurationItf playerConfig; +result = (*playerObject)->GetInterface(playerObject, + SL_IID_ANDROIDCONFIGURATION, &playerConfig); +assert(SL_RESULT_SUCCESS == result); +SLint32 streamType = SL_ANDROID_STREAM_ALARM; +result = (*playerConfig)->SetConfiguration(playerConfig, + SL_ANDROID_KEY_STREAM_TYPE, &streamType, sizeof(SLint32)); +assert(SL_RESULT_SUCCESS == result); +// ... +// Now realize the player here. +</pre> + +<p> +You can use similar code to configure the preset for an audio recorder: +</p> +<pre> +// ... obtain the configuration interface as the first four lines above, then: +SLuint32 presetValue = SL_ANDROID_RECORDING_PRESET_VOICE_RECOGNITION; +result = (*playerConfig)->SetConfiguration(playerConfig, + RECORDING_PRESET, &presetValue, sizeof(SLuint32)); +</pre> + +<h3>Android effects interfaces</h3> + +<p> +Android's effect, effect send, and effect capabilities interfaces provide +a generic mechanism for an application to query and use device-specific +audio effects. Device manufacturers should document any available device-specific audio effects +that they provide. +</p> + +<h3>Android file descriptor data locator</h3> + +<p> +The Android file descriptor data locator permits you to specify the source for an +audio player as an open file descriptor with read access. The data format must be MIME. +</p> +<p> +This extension is especially useful in conjunction with the native asset manager, because +the app reads assets from the APK via a file descriptor. +</p> + +<h3 id="simple">Android simple buffer queue data locator and interface</h3> + +<p> +The Android simple buffer queue data locator and interface are +identical to those in the OpenSL ES 1.0.1 reference specification, with two exceptions: You +can also use Android simple buffer queues with both audio players and audio recorders. Also, PCM +is the only data format you can use with these queues. +In the reference specification, buffer queues are for audio players only, but +compatible with data formats beyond PCM. +</p> +<p> +For recording, your app should enqueue empty buffers. When a registered callback sends +notification that the system has finished writing data to the buffer, the app can +read the buffer. +</p> +<p> +Playback works in the same way. For future source code +compatibility, however, we suggest that applications use Android simple +buffer queues instead of OpenSL ES 1.0.1 buffer queues. +</p> + +<h3>Dynamic interfaces at object creation</h3> + +<p> +For convenience, the Android implementation of OpenSL ES 1.0.1 +permits your app to specify dynamic interfaces when it instantiates an object. +This is an alternative to using <code>DynamicInterfaceManagement::AddInterface()</code> +to add these interfaces after instantiation. +</p> + +<h3>Buffer queue behavior</h3> + +<p> +The Android implementation does not include the +reference specification's requirement that the play cursor return to the beginning +of the currently playing buffer when playback enters the {@code SL_PLAYSTATE_STOPPED} +state. This implementation can conform to that behavior, or it can leave the location of the play +cursor unchanged. +</p> + +<p> +As a result, your app cannot assume that either behavior occurs. Therefore, +you should explicitly call the <code>BufferQueue::Clear()</code> method after a transition to +<code>SL_PLAYSTATE_STOPPED</code>. Doing so sets the buffer queue to a known state. +</p> + +<p> +Similarly, there is no specification governing whether the trigger for a buffer queue callback must +be a transition to <code>SL_PLAYSTATE_STOPPED</code> or execution of +<code>BufferQueue::Clear()</code>. Therefore, we recommend against creating a dependency on +one or the other; instead, your app should be able to handle both. +</p> + +<h3>Reporting of extensions</h3> +<p> +There are three methods for querying whether the platform supports the Android extensions. These +methods are: +</p> + +<ul> +<li><code>Engine::QueryNumSupportedExtensions()</code></li> +<li><code>Engine::QuerySupportedExtension()</code></li> +<li><code>Engine::IsExtensionSupported()</code></li> +</ul> + +<p> +Any of these methods returns <code>ANDROID_SDK_LEVEL_<API-level></code>, +where {@code API-level} is the platform API level; for example, {@code ANDROID_SDK_LEVEL_23}. +A platform API level of 9 or higher means that the platform supports the extensions. +</p> + + +<h3 id="da">Decode audio to PCM</h3> + +<p> +This section describes a deprecated Android-specific extension to OpenSL ES 1.0.1 +for decoding an encoded stream to PCM without immediate playback. +The table below gives recommendations for use of this extension and alternatives. +</p> + +<table> +<tr> + <th>API level</th> + <th>Alternatives</th> +</tr> +<tr> + <td>13 and below</td> + <td>An open-source codec with a suitable license.</td> +</tr> +<tr> + <td>14 to 15</td> + <td>An open-source codec with a suitable license.</td> +</tr> +<tr> + <td>16 to 20</td> + <td> + The {@link android.media.MediaCodec} class or an open-source codec with a suitable license. + </td> +</tr> +<tr> + <td>21 and above</td> + <td> + NDK MediaCodec in the {@code <media/NdkMedia*.h>} header files, the + {@link android.media.MediaCodec} class, or an open-source codec with a suitable license. + </td> +</tr> +</table> + +<p> +A standard audio player plays back to an audio device, specifying the output mix as the data sink. +The Android extension differs in that an audio player instead +acts as a decoder if the app has specified the data source either as a URI or as an Android +file descriptor data locator described in MIME data format. In such a case, the data sink is +an Android simple buffer queue data locator with PCM data format. +</p> + +<p> +This feature is primarily intended for games to pre-load their audio assets when changing to a +new game level, similar to the functionality that the {@link android.media.SoundPool} class +provides. +</p> + +<p> +The application should initially enqueue a set of empty buffers in the Android simple +buffer queue. After that, the app fills the buffers with with PCM data. The Android simple +buffer queue callback fires after each buffer is filled. The callback handler processes +the PCM data, re-enqueues the now-empty buffer, and then returns. The application is responsible for +keeping track of decoded buffers; the callback parameter list does not include +sufficient information to indicate which buffer contains data or which buffer to enqueue next. +</p> + +<p> +The data source implicitly reports the end of stream (EOS) by delivering a +<code>SL_PLAYEVENT_HEADATEND</code> event at the end of the stream. After the app has decoded +all of the data it received, it makes no further calls to the Android simple buffer queue callback. +</p> +<p> +The sink's PCM data format typically matches that of the encoded data source +with respect to sample rate, channel count, and bit depth. However, you can decode to a different +sample rate, channel count, or bit depth. +For information about a provision to detect the actual PCM format, see <a href="#meta"> +Determining the format of decoded PCM data via metadata</a>. +</p> +<p> +OpenSL ES for Android's PCM decoding feature supports pause and initial seek; it does not support +volume control, effects, looping, or playback rate. +</p> +<p> +Depending on the platform implementation, decoding may require resources +that cannot be left idle. Therefore, we recommend that you make sure to provide +sufficient numbers of empty PCM buffers; otherwise, the decoder starves. This may happen, +for example, if your app returns from the Android simple buffer queue callback without +enqueueing another empty buffer. The result of decoder starvation is +unspecified, but may include: dropping the decoded +PCM data, pausing the decoding process, or terminating the decoder outright. +</p> + +<p class="note"><strong>Note: </strong> +To decode an encoded stream to PCM but not play back immediately, for apps running on +Android 4.x (API levels 16–20), we recommend using the {@link android.media.MediaCodec} class. +For new applications running on Android 5.0 (API level 21) or higher, we recommend using the NDK +equivalent, {@code <NdkMedia*.h>}. These header files reside under +the {@code media/} directory, under your installation root. +</p> + +<h3>Decode streaming ADTS AAC to PCM</h3> + +<p> +An audio player acts as a streaming decoder if the data source is an +Android buffer queue data locator with MIME data format, and the data +sink is an Android simple buffer queue data locator with PCM data format. +Configure the MIME data format as follows: +</p> + +<ul> +<li>Container: {@code SL_CONTAINERTYPE_RAW}</li> +<li>MIME type string: {@code SL_ANDROID_MIME_AACADTS}</li> +</ul> + +<p> +This feature is primarily intended for streaming media applications that +deal with AAC audio but need to perform custom audio processing +prior to playback. Most applications that need to decode audio to PCM +should use the method that <a href="#da">Decode audio to PCM</a> describes, +as that method is simpler and handles more audio formats. The technique described +here is a more specialized approach, to be used only if both of these +conditions apply: +</p> + +<ul> +<li>The compressed audio source is a stream of AAC frames contained in ADTS headers. +</li> +<li>The application manages this stream. The data is <em>not</em> located within +a network resource whose identifier is a URI or within a local file whose identifier is +a file descriptor. +</li> +</ul> + +<p> +The application should initially enqueue a set of filled buffers in the Android buffer queue. +Each buffer contains one or more complete ADTS AAC frames. +The Android buffer queue callback fires after each buffer is emptied. +The callback handler should refill and re-enqueue the buffer, and then return. +The application need not keep track of encoded buffers; the callback parameter +list includes sufficient information to indicate which buffer to enqueue next. +The end of stream is explicitly marked by enqueuing an EOS item. +After EOS, no more enqueues are permitted. +</p> + +<p> +We recommend that you make sure to provide full +ADTS AAC buffers, to avoid starving the decoder. This may happen, for example, if your app +returns from the Android buffer queue callback without enqueueing another full buffer. +The result of decoder starvation is unspecified. +</p> + +<p> +In all respects except for the data source, the streaming decode method is the same as +the one that <a href="#da">Decode audio to PCM</a> describes. +</p> +<p> +Despite the similarity in names, an Android buffer queue is <em>not</em> +the same as an <a href="#simple">Android simple buffer queue</a>. The streaming decoder +uses both kinds of buffer queues: an Android buffer queue for the ADTS +AAC data source, and an Android simple buffer queue for the PCM data +sink. For more information about the Android simple buffer queue API, see <a href="#simple">Android +simple buffer queue data locator and interface</a>. +For more information about the Android buffer queue API, see the {@code index.html} file in +the {@code docs/Additional_library_docs/openmaxal/} directory under the installation root. +</p> + +<h3 id="meta">Determining the format of decoded PCM data via metadata</h3> + +<p> +The <code>SLMetadataExtractionItf</code> interface is part of the reference specification. +However, the metadata keys that indicate the actual format of decoded PCM data are specific to +Android. The <code>OpenSLES_AndroidMetadata.h</code> header file defines these metadata keys. +This header file resides under your installation root, in the +{@code platforms/android-<version>/<abi>/include/SLES} directory. +</p> + +<p> +The metadata key indices are available immediately after +the <code>Object::Realize()</code> method finishes executing. However, the associated values are not +available until after the app decodes the first encoded data. A good +practice is to query for the key indices in the main thread after calling the {@code +Object::Realize} method, and to read the PCM format metadata values in the Android simple +buffer queue callback handler when calling it for the first time. Consult the +<a href="https://github.com/googlesamples/android-ndk">example code in the NDK package</a> +for examples of working with this interface. +</p> + +<p> +Metadata key names are stable, but the key indices are not documented, +and are subject to change. An application should not assume that indices +are persistent across different execution runs, and should not assume that +multiple object instances share indices within the same run. +</p> + +<h3 id="fp">Floating-point data</h3> + +<p> +An app running on Android 5.0 (API level 21) and higher can supply data to an AudioPlayer in +single-precision, floating-point format. +</p> +<p> +In following example code, the {@code Engine::CreateAudioPlayer} method creates an audio player +that uses floating-point data: +</p> + +<pre> +#include <SLES/OpenSLES_Android.h> +... +SLAndroidDataFormat_PCM_EX pcm; +pcm.formatType = SL_ANDROID_DATAFORMAT_PCM_EX; +pcm.numChannels = 2; +pcm.sampleRate = SL_SAMPLINGRATE_44_1; +pcm.bitsPerSample = 32; +pcm.containerSize = 32; +pcm.channelMask = SL_SPEAKER_FRONT_LEFT | SL_SPEAKER_FRONT_RIGHT; +pcm.endianness = SL_BYTEORDER_LITTLEENDIAN; +pcm.representation = SL_ANDROID_PCM_REPRESENTATION_FLOAT; +... +SLDataSource audiosrc; +audiosrc.pLocator = ... +audiosrc.pFormat = &pcm; +</pre> diff --git a/docs/html/ndk/guides/guides_toc.cs b/docs/html/ndk/guides/guides_toc.cs index 981eb5131fac..4c4c64e2f95f 100644 --- a/docs/html/ndk/guides/guides_toc.cs +++ b/docs/html/ndk/guides/guides_toc.cs @@ -63,6 +63,16 @@ </ul> </li> + <li class="nav-section"> + <div class="nav-section-header"><a href="<?cs var:toroot ?>ndk/guides/audio/index.html"> + <span class="en">Audio</span></a></div> + <ul> + <li><a href="<?cs var:toroot ?>ndk/guides/audio/basics.html">Basics</a></li> + <li><a href="<?cs var:toroot ?>ndk/guides/audio/opensl-for-android.html">OpenSL ES for + Android</a></li> + </ul> + </li> + </ul> diff --git a/docs/html/sdk/index.jd b/docs/html/sdk/index.jd index bf571ea7404b..96169b82d647 100644 --- a/docs/html/sdk/index.jd +++ b/docs/html/sdk/index.jd @@ -390,7 +390,7 @@ Studio</a>.</p> <h3>Windows</h3> <ul> -<li>Microsoft® Windows® 8/7/Vista (32 or 64-bit)</li> +<li>Microsoft® Windows® 8/7/Vista (32- or 64-bit)</li> <li>2 GB RAM minimum, 4 GB RAM recommended</li> <li>400 MB hard disk space</li> <li>At least 1 GB for Android SDK, emulator system images, and caches</li> @@ -430,6 +430,7 @@ rendering. You can then configure your project to use Java Development Kit (JDK) <li>At least 1 GB for Android SDK, emulator system images, and caches</li> <li>1280 x 800 minimum screen resolution</li> <li>Oracle® Java Development Kit (JDK) 7 </li> +<li>64-bit distribution capable of running 32-bit applications</li> </ul> <p>Tested on Ubuntu® 14.04, Trusty Tahr (64-bit distribution capable of running 32-bit applications).</p> diff --git a/docs/html/sdk/installing/create-project.jd b/docs/html/sdk/installing/create-project.jd index 68fd57250d17..c44f401bafc4 100644 --- a/docs/html/sdk/installing/create-project.jd +++ b/docs/html/sdk/installing/create-project.jd @@ -190,8 +190,8 @@ with complete source files for each of them as shown in figure 6.</p> <li>Select a <strong>Theme</strong>. This setting specifies which standard Android <a href="{@docRoot}design/style/themes.html">visual style</a> is applied to your application. Select activity template. For more information about Android code templates, see - <a href="{@docRoot}tools/projects/templates.html">Using Code Templates</a>Leave the <strong> - Create activity</strong> option checked so you can start your + <a href="{@docRoot}tools/projects/templates.html">Using Code Templates</a>. Leave the + <strong>Create activity</strong> option checked so you can start your application with some essential components. </li> <li>Click the check box for the required Support Libraries then click <strong>Next</strong>.</li> diff --git a/docs/html/sdk/installing/index.jd b/docs/html/sdk/installing/index.jd index 203d2ffcf8aa..c47b9c3d6c6d 100644 --- a/docs/html/sdk/installing/index.jd +++ b/docs/html/sdk/installing/index.jd @@ -89,7 +89,7 @@ where they are installed. For example:</p> </li> </ol> -<p>If you need use the Android SDK tools from a command line, +<p>If you need to use the Android SDK tools from a command line, you can access them at:</p> <p><code>/Users/<user>/Library/Android/sdk/</code></p> diff --git a/docs/html/sdk/installing/studio-build.jd b/docs/html/sdk/installing/studio-build.jd index 54691bfb9a08..a4868175a8f3 100755 --- a/docs/html/sdk/installing/studio-build.jd +++ b/docs/html/sdk/installing/studio-build.jd @@ -84,7 +84,7 @@ directory.</p> usage when the application is -running on a device.</li> </ul> -<p class="note"><b>Note:</b> Apps are limited to a 64K method reference limit. If your app reaches +<p class="note"><b>Note:</b> Apps are limited to a 65K method reference limit. If your app reaches this limit, the build process outputs the following error message: <pre>Unable to execute dex: method ID not in [0, 0xffff]: 65536.</pre> diff --git a/docs/html/tools/building/building-studio.jd b/docs/html/tools/building/building-studio.jd index 443119412090..ef6e94bcfb23 100644 --- a/docs/html/tools/building/building-studio.jd +++ b/docs/html/tools/building/building-studio.jd @@ -32,6 +32,7 @@ parent.link=index.html Using the Android Emulator</a></li> <li><a href="{@docRoot}tools/publishing/app-signing.html"> Signing Your Applications</a></li> + <li><a href="{@docRoot}tools/help/app-link-indexing.html">Deep Link and App Indexing API Support in Android Studio</a></li> </ol> </div> diff --git a/docs/html/tools/data-binding/guide.jd b/docs/html/tools/data-binding/guide.jd index 6acc38c2f144..b57fba7f822f 100644 --- a/docs/html/tools/data-binding/guide.jd +++ b/docs/html/tools/data-binding/guide.jd @@ -153,42 +153,6 @@ versions back to <strong>Android 2.1</strong> (API level 7+).</p> <p>To use data binding, Android Plugin for Gradle <strong>1.5.0-alpha1</strong> or higher is required.</p> -<h4>Beta release</h4> - -<div class="caution"> - <p>Please note that the Data Binding library is a <strong>beta release</strong>. - While Data Binding is in beta, developers should be aware of the following - caveats:</p> - <ul> - <li> - This is a beta release of the feature intended to generate developer - feedback. It might contain bugs, and it might not work for your use case, - so use it at your own risk. That said, we do want your feedback! Please - let us know what is or isn’t working for you using the <a - href="https://code.google.com/p/android-developer-preview/">issue - tracker</a>. - </li> - <li> - The Data Binding library beta release is subject to significant changes, - including those which are not source code compatible with your app. That is, - significant rework may be required to take updates to the library in the future. - </li> - <li> - Developers should feel free to publish apps built with the Data Binding - library beta release, with the caveats that the standard Android SDK and - Google Play terms of service apply, and it’s always a great idea to test your - app thoroughly when adopting new libraries or tools. - </li> - <li> - We’re just getting started with Android Studio support at this time. - Further Android Studio support will come in the future. - </li> - <li> - By using the Data Binding library beta release, you acknowledge these - caveats.</li> - </ul> -</div> - <h2 id="build_environment"> Build Environment </h2> @@ -408,6 +372,36 @@ ListItemBinding binding = DataBindingUtil.<em>inflate</em>(layoutInflater, R.lay </LinearLayout> </layout> </pre> + +<p> + Some specialized click event handlers exist and they need an attribute other than + <code>android:onClick</code> to avoid a conflict. The following attributes have been created + to avoid such conflicts: +</p> + +<table> + <tr> + <th>Class</th> + <th>Listener Setter</th> + <th>Attribute</th> + </tr> + <tr> + <td>{@link android.widget.SearchView}</td> + <td>{@link android.widget.SearchView#setOnSearchClickListener}</td> + <td><code>android:onSearchClick</code></td> + </tr> + <tr> + <td>{@link android.widget.ZoomControls}</td> + <td>{@link android.widget.ZoomControls#setOnZoomInClickListener}</td> + <td><code>android:onZoomIn</code></td> + </tr> + <tr> + <td>{@link android.widget.ZoomControls}</td> + <td>{@link android.widget.ZoomControls#setOnZoomOutClickListener}</td> + <td><code>android:onZoomOut</code></td> + </tr> +</table> + <h2 id="layout_details"> Layout Details </h2> @@ -540,6 +534,14 @@ ListItemBinding binding = DataBindingUtil.<em>inflate</em>(layoutInflater, R.lay <code>boolean</code>, etc. </p> +<p> + A special variable named <code>context</code> is generated for use in binding + expressions as needed. The value for <code>context</code> is the + <code>Context</code> from the root View's {@link android.view.View#getContext}. + The <code>context</code> variable will be overridden by an explicit variable + declaration with that name. +</p> + <h3 id="custom_binding_class_names"> Custom Binding Class Names </h3> diff --git a/docs/html/tools/help/app-link-indexing.jd b/docs/html/tools/help/app-link-indexing.jd new file mode 100644 index 000000000000..611373a28ab5 --- /dev/null +++ b/docs/html/tools/help/app-link-indexing.jd @@ -0,0 +1,514 @@ +page.title=Deep Link and App Indexing API Support in Android Studio +parent.title=Tools +parent.link=index.html +page.tags=app indexing +@jd:body + +<div id="qv-wrapper"> +<div id="qv"> + <h2>In this document</h2> +<ol> + <li><a href="#workflow">Typical Workflow</a></li> + <li><a href="#intent">Adding an Intent Filter for Deep Linking and Google Search</a></li> + <li><a href="#indexing">Adding App Indexing API Skeleton Code to an Activity</a></li> + <li><a href="#testintent">Testing a Deep Link</a></li> + <li><a href="#testindexing">Viewing App Indexing API Messages in the logcat Monitor</a></li> + <li><a href="#lint">Configuring Lint</a></li> +</ol> + + <h2>See also</h2> + <ol> + <li><a href="https://developers.google.com/app-indexing/introduction" + class="external-link">App Indexing</a></li> + <li><a href="{@docRoot}training/app-indexing/index.html" + >Making Your App Content Searchable by Google</a></li> + <li><a href="{@docRoot}training/app-links/index.html">Handling App Links</a></li> + <li><a href="{@docRoot}tools/debugging/improving-w-lint.html" + >Improving Your Code with lint</a></li> + <li><a href="{@docRoot}tools/help/am-logcat.html">logcat Monitor</a></li> + <li><a href="https://www.google.com/webmasters/tools/home" + class="external-link">Google Search Console</a></li> + <li><a href="https://developers.google.com/android/guides/overview" + class="external-link">Google Play Services</a></li> + </ol> + + <h2>Video</h2> + <ol> + <li><a href="https://www.youtube.com/watch?v=aISUYHTkTOU" + class="external-link">DevBytes: App Indexing</a></li> + </ol> + + <h2>Dependencies and prerequisites</h2> + <ul> + <li>Android 2.3 (API level 9) or higher</li> + <li>Android Studio 1.5 or higher</li> + <li>Google Play Services 8.1.0 or higher</li> + </ul> + +</div> +</div> + +<p>Android Studio helps you add deep links, app indexing, and search functionality to your apps. + These features can help to drive more traffic to your + app, discover which app content is used most, make it easier for users to find content in an + installed app, and attract new users.</p> + +<h2 id="workflow">Typical Workflow</h2> + +<p>To use Android Studio to add deep link, app indexing, and search features to your app, follow + these basic steps:</p> + +<ol> +<li>Add intent filters and code to handle incoming intents.</li> +<li>Associate a website with your app.</li> +<li>Add App Indexing API code.</li> +</ol> + +<p>Intent filters and the App Indexing API are ways to implement deep links and app indexing, but + there are other possible implementations as well. See + <a href="https://developers.google.com/app-indexing/reference/deeplinks" + class="external-link">Alternate Android Indexing Methods</a> + for more information.</p> + +<h3 id="aboutintent">Intent filters for deep links</h3> + +<p>Android Studio can create a basic intent filter in your manifest that you can customize to + define deep link URLs for your app. You can then write Java code in an activity to handle the + intent. This implementation lets users directly open the specified app activity by + clicking a deep link. Users can see the deep links in google.com in a browser, in the + Google Search app, and in Google Now on Tap. </p> + +<h3 id="aboutassociation">Website association with deep links</h3> + +<p>After setting up deep links for your app, you can associate your website with your app by using + the Google Search Console and Google Play Developer Console. Afterward, Google indexes your app + for URLs defined in + your intent filters and begins to include them in search results. In addition, you can optionally + exclude app content from Google Search. After you associate a website with your app, features + such as Now on Tap and enhanced search result display (like including your app icon) + become available.</p> + +<p>As an alternative to associating your app with a website, + for Android 6.0 (API level 23) and higher, you can add + <a href="{@docRoot}training/app-links/index.html" + >default handlers and verification for deep links</a> + instead.</p> + +<p>Chrome displaying google.com serves search results with deep links that are accessible to both + signed-in users and those who aren't. Google Search app users must be signed in to see deep links + in their search results. </p> + +<h3 id="aboutapi">App Indexing API code in activities</h3> + +<p>Next, if you want to support additional search features, such as autocompletions, you can + add App Indexing API code to your app. Android Studio can create skeleton code in an activity + that you can then customize to support app indexing. The App Indexing API allows app indexing + even if + <a href="https://developers.google.com/app-indexing/reference/deeplinks#allow-access-by-googlebot-optional" + class="external-link">Googlebot</a> + can’t get content from your app.</p> + +<h3 id="abouttest">Deep link and App Indexing API testing</h3> + +<p>Android Studio helps you test your code with the following features:</p> + +<ul> +<li>Deep link testing helps you verify that a specified deep link can launch an app. </li> +<li>The logcat Monitor helps you test App Indexing API calls in an activity. </li> +<li>The Android Lint tool has warnings for certain issues involving deep links and the App Indexing + API. These warnings and errors appear in the Code Editor and in Lint inspection results.</li> +</ul> + +<p>The details for implementing deep links and app indexing are described next. + + +<h2 id="intent">Adding an Intent Filter for Deep Linking and Google Search</h2> + +<p>To use Android Studio features to add an intent filter defining a deep link, follow these + steps:</p> + +<ol> +<li>In the <a href="{@docRoot}sdk/installing/create-project.html#ProjectView">Android view</a> + of the <em>Project</em> window, double-click the <code>AndroidManifest.xml</code> file to open it + in the Code Editor.</li> +<li>Insert an intent filter in one of the following ways:</li> +<ul> +<li>In an <code><activity></code> element, click in the left column so the light bulb + <img src="{@docRoot}images/tools/ai-ilightbulb.png" + style="vertical-align:sub;margin:0;height:17px" alt="Lightbulb icon" /> appears. Click + <img src="{@docRoot}images/tools/ai-ilightbulb.png" + style="vertical-align:sub;margin:0;height:17px" alt="Lightbulb icon" /> + and select <strong>Create Deep Link</strong>.</li> +<li>Right-click in an <code><activity></code> element and select <strong>Generate</strong> + > <strong>Deep Link</strong>.</li> +<li>Place your cursor in an activity, and then select <strong>Code</strong> > + <strong>Generate</strong> > <strong>Deep Link</strong>.</li> +</ul> + +<p>The Code Editor adds skeleton code using the + <a href="https://www.jetbrains.com/idea/help/intention-actions.html" + class="external-link">intention action</a> and + <a href="https://www.jetbrains.com/idea/help/generating-code.html" + class="external-link">generate code</a> mechanisms.</p> + +<p>The Code Editor adds an intent filter similar to the following:</p> +<pre> +<!-- ATTENTION: This intent was auto-generated. Follow instructions at + https://g.co/AppIndexing/AndroidStudio to publish your Android app deep links. --> +<intent-filter> + <action android:name="android.intent.action.VIEW" /> + + <category android:name="android.intent.category.DEFAULT" /> + <category android:name="android.intent.category.BROWSABLE" /> + <!-- ATTENTION: This data URL was auto-generated. + We recommend that you use the HTTP scheme. + TODO: Change the host or pathPrefix as necessary. --> + <data + android:host="www.example.com" + android:pathPrefix="/gizmos" + android:scheme="http" /> +</intent-filter> +</pre> + +<li><a href="{@docRoot}training/app-indexing/deep-linking.html#adding-filters">Modify the + <code><data></code> element</a> + and optionally the <code><category></code> element, as needed.</li> + + +<p>We recommend that you define a <code><data></code> element that supports URLs that you’ll + add in the future. In the previous sample code, for example, Google will index any URLs starting + with <code>www.example.com/gizmos</code>. Also, remember to + include a deep link for your app home screen so it’s included in search results. </p> + +<p>Deep link URLs can be the same as the URLs of the comparable pages on your website.</p> + +<li>In the corresponding activity, + <a href="{@docRoot}training/app-indexing/deep-linking.html#handling-intents">add Java code</a> + to read data from the intent filter and direct the app to respond accordingly. </li> +<li><a href="#testintent">Test your deep link</a>.</li> + +</ol> + +<p>To support Google Search for your deep links, follow these steps:</p> +<ol> +<li><a href="https://developers.google.com/app-indexing/android/app#declare-a-website-association" + class="external-link">Define an association</a> + between your app and your website.</li> +<p>Alternatively, for Android 6.0 (API level 23) and higher, add + <a href="{@docRoot}training/app-links/index.html">link default handling and verification</a>.</p> +<li>Optionally + <a href="https://developers.google.com/app-indexing/android/app#create-the-noindexxml-file" + class="external-link">exclude app URLs</a> + from the Google index.</li> +<li>Optionally <a href="#indexing">add App Indexing API code</a> to support additional search + features.</li> +</ol> + + +<p>To test and debug your links, you can use the following Android Studio features:</p> +<ul> +<li><a href="#testintent">Launch your deep link</a> in Android Studio to test that it works.</li> +<li><a href="#lint">Enable the following Android Lint categories</a>:</li> +<ul> +<li><strong>Missing Support for Google App Indexing</strong></li> +<li><strong>Incorrect Usage of App Link for Google App Indexing</strong></li> +</ul> +</ul> + +<p>In addition, you can + <a href="https://developers.google.com/app-indexing/android/test#preview-your-apk-on-search-console" + class="external-link">preview your APK in the Google Search Console</a> + to test your deep links, whether the app is associated with a website or not. </p> + + + +<h2 id="indexing">Adding App Indexing API Skeleton Code to an Activity</h2> + +<p>After adding deep links, you can add App Indexing API code to an activity to support additional + search features. </p> + +<p>To add App Indexing API code to an activity, follow these steps:</p> +<ol> +<li>In <a href="{@docRoot}sdk/installing/create-project.html#ProjectView">Android view</a> + in the <em>Project</em> window, double-click the activity Java file to open it in the + Code Editor.</li> +<li>Insert skeleton code in one of the following ways:</li> +<ul> +<li>In an activity definition, click in the Java code so the light bulb + <img src="{@docRoot}images/tools/ai-ilightbulb.png" + style="vertical-align:sub;margin:0;height:17px" alt="Lightbulb icon" /> appears. + Click <img src="{@docRoot}images/tools/ai-ilightbulb.png" + style="vertical-align:sub;margin:0;height:17px" alt="Lightbulb icon" /> + and select <strong>Insert App Indexing API Code</strong>.</li> +<li>Right-click in an activity definition and select <strong>Generate</strong> > + <strong>App Indexing API Code</strong>.</li> +<li>Place the cursor in an activity, and then select <strong>Code</strong> > + <strong>Generate</strong> > + <strong>App Indexing API Code</strong>.</li> +</ul> + + +<p>The Code Editor adds skeleton code using the + <a href="https://www.jetbrains.com/idea/help/intention-actions.html" + class="external-link">intention action</a> and + <a href="https://www.jetbrains.com/idea/help/generating-code.html" + class="external-link">generate code</a> + mechanisms.</p> + +<p>If you don’t see the <strong>App Indexing API Code</strong> menu item, make sure your cursor is + within an activity, and check your code for App Indexing API methods. The Code Editor can insert + skeleton Java code into an activity in the following circumstances:</p> + +<ul> +<li>The activity doesn’t have an <code>onStart()</code> method, or the <code>onStart()</code> + method doesn’t contain an <code>AppIndexApi.start()</code> or <code>AppIndexApi.view()</code> + call.</li> +<li>The activity doesn’t have an <code>onStop()</code> method, or the <code>onStop()</code> + method doesn’t contain an <code>AppIndexApi.end()</code> or <code>AppIndexApi.viewEnd()</code> + call.</li> +</ul> + + +<p>The Code Editor adds Java code similar to the following:</p> +<pre> + /** + * ATTENTION: This was auto-generated to implement the App Indexing API. + * See https://g.co/AppIndexing/AndroidStudio for more information. + */ + private GoogleApiClient client; + + // ATTENTION: This was auto-generated to implement the App Indexing API. + // See https://g.co/AppIndexing/AndroidStudio for more information. + client = new GoogleApiClient.Builder(this).addApi(AppIndex.API).build(); + } + + + @Override + public void onStart() { + super.onStart(); + + // ATTENTION: This was auto-generated to implement the App Indexing API. + // See https://g.co/AppIndexing/AndroidStudio for more information. + client.connect(); + Action viewAction = Action.newAction( + Action.TYPE_VIEW, // TODO: choose an action type. + "Main Page", // TODO: Define a title for the content shown. + // TODO: If you have web page content that matches + // this app activity's content, + // make sure this auto-generated web page URL is correct. + // Otherwise, set the URL to null. + Uri.parse("http://host/path"), + // TODO: Make sure this auto-generated app deep link URI is correct. + Uri.parse("android-app://com.example/http/host/path") + ); + AppIndex.AppIndexApi.start(client, viewAction); + } + + @Override + public void onStop() { + super.onStop(); + + // ATTENTION: This was auto-generated to implement the App Indexing API. + // See https://g.co/AppIndexing/AndroidStudio for more information. + Action viewAction = Action.newAction( + Action.TYPE_VIEW, // TODO: choose an action type. + "Main Page", // TODO: Define a title for the content shown. + // TODO: If you have web page content that matches + // this app activity's content, + // make sure this auto-generated web page URL is correct. + // Otherwise, set the URL to null. + Uri.parse("http://host/path"), + // TODO: Make sure this auto-generated app deep link URI is correct. + Uri.parse("android-app://com.example/http/host/path") + ); + AppIndex.AppIndexApi.end(client, viewAction); + client.disconnect(); + } +} +</pre> + +<p>For more information about the App Indexing API methods, see + <a href="https://developers.google.com/app-indexing/reference/package-summary" + class="external-link">Android API for App Indexing</a>. + For information about the action types, see the + <a href="https://developers.google.com/android/reference/com/google/android/gms/appindexing/Action#constant-summary" + class="external-link">Action Class Constant Summary</a>. +</p> + +<p>If your app isn’t already configured for the Google Play Services App Indexing API, the Code + Editor also modifies your <code>build.gradle</code> and <code>AndroidManifest.xml</code> files + to include it. If your app already depends on it but the version is lower than 8.1.0, your app + is upgraded to version 8.1.0. For more information and to correct any issues, see + <a href="https://developers.google.com/app-indexing/android/publish#add-google-play-services" + class="external-link">Add Google Play Services</a> + and <a href="https://developers.google.com/android/guides/setup" + class="external-link">Setting Up Google Play Services</a>. +</p> + +<li>Customize the skeleton code, as needed.</li> + +<p>Pay attention to the comments, which help you find areas that need work, such as setting the + title and URLs. For more information, see + <a href="https://developers.google.com/app-indexing/android/publish" + class="external-link">Add the App Indexing API</a>. +</p> +<li><a href="#testindexing">Verify that your app indexing code is working</a> by using + the logcat Monitor.</li> +</ol> + + + +<p>To test and debug your App Indexing API code, you can use the following Android Studio + features:</p> +<ul> +<li><a href="#testindexing">Examine logcat Monitor Messages</a>.</li> +<li><a href="#lint">Enable the following Android Lint category</a>: + <strong>Missing Support for Google App Indexing API</strong></li> +</ul> + +<p>In addition, you can + <a href="https://developers.google.com/app-indexing/android/test#preview-your-apk-on-search-console" + class="external-link">preview your APK in the Google Search Console</a>.</p> + + +<h2 id="testintent">Testing a Deep Link</h2> + +<p>When you run your app from Android Studio, you can specify a deep link to launch so you can + test it.</p> + +<p>To launch a deep link from Android Studio, follow these steps:</p> +<ol> +<li>In Android Studio, open your project in + <a href="{@docRoot}sdk/installing/create-project.html#ProjectView">Android view</a>.</li> +<li>After opening a project, select <strong>Run</strong> > <strong>Edit Configurations</strong>. +</li> +<li>In the <em>Run/Debug Configurations</em> dialog, beneath <strong>Android Application,</strong> + select the module you want to test.</li> +<li>Select the <strong>General</strong> tab. </li> +<li>In the <strong>Launch</strong> field, select <strong>Deep Link</strong>. </li> +<li>In the <strong>Deep Link</strong> field, click <strong>…</strong> to select from a list of + defined deep links.</li> + +<p>Or type the URL you want to test, for example, <code>http://example.com/gizmos</code>. </p> +<li>Click <strong>OK</strong>.</li> +<li>Select <strong>Run</strong> > <strong>Run app</strong> or <strong>Debug app</strong>.</li> +<li>If the <em>Device Chooser</em> dialog appears, select a connected device or an + emulator, and click <strong>OK</strong>.</li> + +<p>If the link is successful, the app launches in the device or emulator, and displays the app at + the specified activity. Otherwise, an error message appears in the <em>Run</em> window.</p> +</ol> + +<p>For more information about creating run configurations at the project, default, and module + levels, see + <a href="{@docRoot}tools/building/building-studio.html">Building and Running from Android Studio</a>. +</p> + +<p>You can view App Indexing API log messages while the app is running, as described next.</p> + + +<h2 id="testindexing">Viewing App Indexing API Messages in the logcat Monitor</h2> + +<p>The logcat Monitor can display app indexing log messages to determine if your App Indexing API + code is pushing the correct data to the cloud. For example, you can check the app title and the + URL. The logcat Monitor is part of Android Monitor in Android Studio. </p> + +<p>Follow these steps:</p> +<ol> +<li>Run your app in Android Studio so it <a href="#testintent">launches a deep link</a>.</li> +<li><a href="{@docRoot}tools/help/android-monitor.html#displaying">Display Android Monitor</a> + and click the <strong>logcat</strong> tab.</li> +<li><a href="{@docRoot}tools/help/am-logcat.html#level">Set the log level</a> to + <strong>Verbose</strong>.</li> +<li>In the filter menu, select <strong>No Filters</strong>.</li> +<li><a href="{@docRoot}tools/help/am-logcat.html#searching">Search the log</a> for the string + "appindex".</li> + +<p>App indexing log messages should appear. If they don’t, check the following items:</p> +<ul> +<li>Is Google Play Services installed on the device or emulator? You can check the settings on + the device. </li> +<li>Is the Google Play Services version on the device or emulator lower than the version specified + in the <code>build.gradle</code> file? If so, it might be out-of-date and should be upgraded to + a higher version. </li> +</ul> + +<p>For more information, see the + <a href="https://play.google.com/store/apps/details?id=com.google.android.gms&hl=en" + class="external-link">Google Play Services Download</a> + page and <a href="https://developers.google.com/android/guides/setup" + class="external-link">Setting Up Google Play Services</a>. +</p> +<li>Visit app pages that trigger App Indexing API calls. </li> +</ol> + + +<h2 id="lint">Configuring Lint</h2> + +<p>You can use the Android Studio built-in Lint tool to check whether you have valid deep links + defined in the manifest and have implemented the App Indexing API correctly in activities.</p> + +<p>You can view deep link and app indexing warnings and errors in two ways: </p> +<ul> +<li>As pop-up text in the Code Editor. When Lint finds a problem, it highlights the problematic + code in yellow, or underlines the code in red for more serious issues.</li> +<li>In the Lint <em>Inspection Results</em> window after you select <strong>Analyze</strong> > + <strong>Inspect Code</strong>.</li> +</ul> + + + +<p>To set default Lint checks for deep links and the App Indexing API, follow these steps:</p> +<ol> +<li>In Android Studio, open your project in + <a href="{@docRoot}sdk/installing/create-project.html#ProjectView">Android view</a>. +</li> +<li>Select <strong>File</strong> > <strong>Other Settings</strong> > + <strong>Default Settings</strong>.</li> +<li>In the <em>Default Preferences</em> dialog, select <strong>Editor</strong> > + <strong>Inspections</strong>. </li> +<li>In the <strong>Profile</strong> field, select <strong>Default</strong> or + <strong>Project Default</strong> to set the scope for Android Studio or just for this project, + respectively. </li> +<li>Expand the <strong>Android Lint</strong> category and change the Lint settings as needed:</li> +<ul> +<li><strong>Missing Support for Google App Indexing</strong> - Reports a warning if the app hasn’t + implemented deep links, which are used by Google Search. This warning setting is enabled by + default.</li> +<li><strong>Missing Support for Google App Indexing API</strong> - Reports if an app hasn’t + implemented the App Indexing API at all. This warning setting is disabled by default.</li> +<li><strong>Incorrect Usage of App Link for Google App Indexing</strong> - Reports deep link + errors in manifest code. This error setting is enabled by default.</li> +</ul> + +<p>For example, the following Lint warning appears for the first setting:</p> +<p><img src="{@docRoot}images/tools/ai-lint.png" /></p> + +<li>Click <strong>OK</strong>.</li> +</ol> + + + +<p>To produce a list of Lint checks displayed in the <em>Inspection Results</em> window, + follow these steps:</p> +<ol> +<li>In Android Studio, open your project in + <a href="{@docRoot}sdk/installing/create-project.html#ProjectView">Android view</a> + and select a portion of your project that you want to test.</li> +<li>Select <strong>Analyze</strong> > <strong>Inspect Code</strong>.</li> +<li>In the <em>Specify Inspection Scope </em>dialog, select the inspection scope and profile. </li> + +<p>The scope specifies the files you want to analyze, and the profile specifies the Lint checks + you’d like to perform.</p> +<li>If you want to change the Lint settings, click <strong>…</strong>. In the <em>Inspections</em> + dialog, optionally click <strong>Manage</strong> to define a new profile, specify the Lint + settings you want, and then click <strong>OK</strong>.</li> +<p>In the <em>Inspections</em> dialog, you can search for the string "app indexing" +to find the deep link and App Indexing API Lint checks. Note that changing Lint settings for a +profile in the <em>Inspections</em> dialog doesn’t change the default settings, as described in +the previous procedure. It does change the settings for profiles displayed in the +<em>Inspections</em> dialog, however.</p> +<li>Click <strong>OK</strong>.</li> +<p>The results appear in the <em>Inspection Results</em> window.</p> + +</ol> diff --git a/docs/html/tools/help/index.jd b/docs/html/tools/help/index.jd index a97a5516c3e5..e7b911119197 100755 --- a/docs/html/tools/help/index.jd +++ b/docs/html/tools/help/index.jd @@ -43,6 +43,11 @@ avd</code>) the emulator (<code>emulator</code>), and the Dalvik Debug Monitor S <dt><a href="{@docRoot}tools/help/android.html">android</a></dt> <dd>Lets you manage AVDs, projects, and the installed components of the SDK.</dd> + <dt><a href="{@docRoot}tools/help/app-link-indexing.html">Deep Link and App Indexing API Support</a></dt> + <dd>Helps you add deep links, app indexing, and search functionality to your apps. + These features can make it easier to find content in an installed app, drive more traffic to your + app, discover which app content is used most, and attract new users.</dd> + <dt><a href="{@docRoot}tools/help/hierarchy-viewer.html">Hierarchy Viewer (hierarchyviewer)</a></dt> <dd>Provides a visual representation of the layout's View hierarchy with performance information for each node in the layout, and a magnified view of the display to closely examine the @@ -139,7 +144,7 @@ content is allowed.</dd> <dt><a href="{@docRoot}tools/help/image-asset-studio.html">Image Asset Studio</a></dt> <dd>Helps you to generate custom icons for your Android applications from existing images, cliparts, or text. - It generates a set of icons at the appropriate resolution for each generalized screen density that your app + It generates a set of icons at the appropriate resolution for each generalized screen density that your app supports.</dd> <dt><a href="{@docRoot}tools/help/vector-asset-studio.html">Vector Asset Studio</a></dt> diff --git a/docs/html/tools/sdk/tools-notes.jd b/docs/html/tools/sdk/tools-notes.jd index 3859ecfa737f..64e4f59347a1 100644 --- a/docs/html/tools/sdk/tools-notes.jd +++ b/docs/html/tools/sdk/tools-notes.jd @@ -21,11 +21,31 @@ Tools you are using, refer to the "Installed Packages" listing in the Android SD <p>For a summary of all known issues in SDK Tools, see <a href="http://tools.android.com/knownissues">http://tools.android.com/knownissues</a>.</p> - - <div class="toggle-content opened"> <p><a href="#" onclick="return toggleContent(this)"> <img src="{@docRoot}assets/images/triangle-opened.png" class="toggle-content-img" + alt=""/>SDK Platform-tools, Revision 23.1.0</a> <em>(December 2015)</em> + </p> + + <div class="toggle-content-toggleme"> + + <dl> + <dt>General Notes:</dt> + <dd> + <ul> + <li>Changed Linux requirements for Android SDK Platform-tools revision 23.1.0 and later: + it now requires 64-bit Linux.</li> + </ul> + </dd> + + + + </div> +</div> + +<div class="toggle-content closed"> + <p><a href="#" onclick="return toggleContent(this)"> + <img src="{@docRoot}assets/images/triangle-closed.png" class="toggle-content-img" alt=""/>SDK Tools, Revision 24.4.1</a> <em>(October 2015)</em> </p> diff --git a/docs/html/tools/tools_toc.cs b/docs/html/tools/tools_toc.cs index 04ed7057ede3..14af176a470a 100644 --- a/docs/html/tools/tools_toc.cs +++ b/docs/html/tools/tools_toc.cs @@ -146,8 +146,9 @@ class="en">Tools Help</span></a></div> </li> <li><a href="<?cs var:toroot ?>tools/help/avd-manager.html">AVD Manager</a></li> <li><a href="<?cs var:toroot ?>tools/help/bmgr.html">bmgr</a> - <li><a href="<?cs var:toroot ?>tools/help/monitor.html">Device Monitor</a></li> + <li><a href="<?cs var:toroot ?>tools/help/app-link-indexing.html">Deep Link and App Indexing API Support</a></li> <li><a href="<?cs var:toroot ?>tools/help/desktop-head-unit.html">Desktop Head Unit</a></li> + <li><a href="<?cs var:toroot ?>tools/help/monitor.html">Device Monitor</a></li> <li><a href="<?cs var:toroot ?>tools/help/dmtracedump.html">dmtracedump</a></li> <li><a href="<?cs var:toroot ?>tools/help/draw9patch.html">Draw 9-Patch</a></li> <li><a href="<?cs var:toroot ?>tools/help/emulator.html">Emulator</a></li> diff --git a/docs/html/training/app-indexing/index.jd b/docs/html/training/app-indexing/index.jd index 15a6367289fd..a1a47e96844f 100644 --- a/docs/html/training/app-indexing/index.jd +++ b/docs/html/training/app-indexing/index.jd @@ -22,6 +22,7 @@ startpage=true target="_blank">App Indexing for Google Search</a></li> <li><a href="{@docRoot}guide/components/intents-filters.html">Intents and Intent Filters</a></li> +<li><a href="{@docRoot}tools/help/app-link-indexing.html">Deep Link and App Indexing API Support in Android Studio</a></li> </ul> </div> </div> diff --git a/docs/html/training/app-links/index.jd b/docs/html/training/app-links/index.jd index 7ce95e646df3..27b648028793 100644 --- a/docs/html/training/app-links/index.jd +++ b/docs/html/training/app-links/index.jd @@ -14,6 +14,10 @@ page.tags=androidm,marshmallow <li><a href="#web-assoc">Declare Website Associations</a></li> <li><a href="#testing">Test App Links</a></li> </ol> + <h2>See also</h2> + <ol> + <li><a href="{@docRoot}tools/help/app-link-indexing.html">Deep Link and App Indexing API Support in Android Studio</a></li> + </ol> </div> </div> diff --git a/docs/html/training/auto/audio/index.jd b/docs/html/training/auto/audio/index.jd index 75974e44d1c7..9144900a9d99 100644 --- a/docs/html/training/auto/audio/index.jd +++ b/docs/html/training/auto/audio/index.jd @@ -19,6 +19,7 @@ page.image=auto/images/assets/icons/media_app_playback.png <ol> <li><a href="#overview">Provide Audio Services</a></li> <li><a href="#config_manifest">Configure Your Manifest</a></li> + <li><a href="#isconnected">Determine if Your App is Connected</a></li> <li><a href="#implement_browser">Build a Browser Service</a></li> <li><a href="#implement_callback">Implement Play Controls</a></li> <li><a href="#support_voice">Support Voice Actions</a></li> @@ -210,12 +211,12 @@ href="https://www.youtube.com/watch?v=Q96Sw6v4ULg"> <p class="note"><strong>Note:</strong> The icon you provide should have transparency enabled, so the icon's background gets filled in with the app's primary color.</p> -<h2 id=isconnected">Determine if Your App is Connected</h2> +<h2 id="isconnected">Determine if Your App is Connected</h2> <p> It is possible to determine if your app is selected as the current media app.</p> <p> -Android Auto broadcasts an intent with <code>com.google.android.gms.car.media. -STATUS</code> action when a user connects or disconnects from a media app. The broadcast intent is +Android Auto broadcasts an intent with <code>com.google.android.gms.car.media.STATUS</code> +action when a user connects or disconnects from a media app. The broadcast intent is scoped to the package name of the media app selected. You can register a broadcast receiver in your app, preferably in your <a href="{@docRoot}reference/android/service/media/MediaBrowserService.html"> MediaBrowserService</a> implementation and listen for this intent diff --git a/docs/html/training/efficient-downloads/redundant_redundant.jd b/docs/html/training/efficient-downloads/redundant_redundant.jd index f77c8de94474..0825b5dba8cb 100644 --- a/docs/html/training/efficient-downloads/redundant_redundant.jd +++ b/docs/html/training/efficient-downloads/redundant_redundant.jd @@ -37,7 +37,7 @@ next.link=connectivity_patterns.html <p>To ensure that your caching doesn't result in your app displaying stale data, be sure to extract the time at which the requested content was last updated, and when it expires, from within the HTTP response headers. This will allow you to determine when the associated content should be refreshed.</p> -<pre>long currentTime = System.currentTimeMillis()); +<pre>long currentTime = System.currentTimeMillis(); HttpURLConnection conn = (HttpURLConnection) url.openConnection(); @@ -84,4 +84,4 @@ if (lastModified < lastUpdateTime) { <p>With the cache installed, fully cached HTTP requests can be served directly from local storage, eliminating the need to open a network connection. Conditionally cached responses can validate their freshness from the server, eliminating the bandwidth cost associated with the download.</p> -<p>Uncached responses get stored in the response cache for future requests.</p>
\ No newline at end of file +<p>Uncached responses get stored in the response cache for future requests.</p> diff --git a/docs/html/training/monitoring-device-state/index.jd b/docs/html/training/monitoring-device-state/index.jd index 95079568dd4b..1e1ce20744cb 100644 --- a/docs/html/training/monitoring-device-state/index.jd +++ b/docs/html/training/monitoring-device-state/index.jd @@ -1,5 +1,8 @@ page.title=Optimizing Battery Life -page.tags=network,internet +page.tags=battery,network,internet +page.metaDescription=Learn how to optimize your app to reduce battery drain and use power-hungry resources efficiently. + +page.article=true trainingnavtop=true startpage=true @@ -23,12 +26,13 @@ startpage=true </div> <p>For your app to be a good citizen, it should seek to limit its impact on the battery life of its -host device. After this class you will be able to build apps that modify their functionality -and behavior based on the state of the host device.</p> +device. After this class you will be able to build apps that modify their functionality +and behavior based on the state of its device.</p> -<p>By taking steps such as disabling background service updates when you lose connectivity, or -reducing the rate of such updates when the battery level is low, you can ensure that the impact of -your app on battery life is minimized, without compromising the user experience.</p> +<p>By taking steps such as batching network requests, disabling background service updates when you +lose connectivity, or reducing the rate of such updates when the battery level is low, you can +ensure that the impact of your app on battery life is minimized, without compromising the user +experience.</p> <h2>Lessons</h2> @@ -37,6 +41,11 @@ These should be short and to the point. It should be clear from reading the summ will want to jump to a lesson or not.--> <dl> + <dt><b><a href="{@docRoot}training/performance/battery/network/index.html">Reducing Network Battery +Drain</a></b></dt> + <dd>Learn how to analyze your app's use of network resources and optimize it to reduce +power consumption.</dd> + <dt><b><a href="doze-standby.html">Optimizing for Doze and App Standby</a></b></dt> <dd>Learn how to test and optimize your app for the power-management features introduced in Android 6.0 Marshmallow.</dd> diff --git a/docs/html/training/performance/battery/network/action-any-traffic.jd b/docs/html/training/performance/battery/network/action-any-traffic.jd new file mode 100644 index 000000000000..eafb3b894f67 --- /dev/null +++ b/docs/html/training/performance/battery/network/action-any-traffic.jd @@ -0,0 +1,100 @@ +page.title=Optimizing General Network Use +trainingnavtop=true + +@jd:body + +<div id="tb-wrapper"> +<div id="tb"> + +<h2>This lesson teaches you to</h2> +<ol> + <li><a href="#compress-data">Compress Data</a> + <li><a href="#cache-locally">Cache Files Locally</a></li> + <li><a href="#pre-fetch">Optimize Pre-Fetch Cache Size</a></li> +</ol> + +</div> +</div> + +<p> + In general, reducing the amount of network traffic helps reduce battery drain. + In addition to the battery-optimization techniques of the previous lessons, + you should look at these general-purpose techniques and see if you can apply + them to your app. +</p> + +<p> + This lesson briefly covers techniques that you can use to lower network traffic and + consequently reduce the battery drain caused by your app. +</p> + +<h2 id="compress-data">Compress Data</h2> + +<iframe width="448" height="252" + src="//www.youtube.com/embed/IwxIIUypnTE?autohide=1&showinfo=0" + frameborder="0" allowfullscreen="" + style="float: right; margin: 0 0 20px 20px;"></iframe> + + +<p> + Reducing the amount of data sent or received over a network connection also + reduces the duration of the connection, which conserves battery. You can: +</p> + +<ul> + <li>Compress data, using a compression technique such as GZIP compression.</li> + + <li>Use succinct data protocols. While JSON and XML offer human-readability, and + language-flexibility, they are bandwidth-heavy formats, with + high serialization costs in the Android platform. Binary serialization formats, + such as <a href="https://developers.google.com/protocol-buffers/">Protocol Buffers</a> or + <a href="https://google.github.io/flatbuffers/">FlatBuffers</a> offer a smaller on-the-wire + packet size, as well as faster encoding and decoding time. If your application transfers a lot + of serialized data on a regular basis, these formats can yield benefits for decoding time and + transfer size. + </li> +</ul> + + +<h2 id="cache-locally">Cache Files Locally</h2> + +<iframe width="448" height="252" + src="//www.youtube.com/embed/7lxVqqWwTb0?autohide=1&showinfo=0" + frameborder="0" allowfullscreen="" + style="float: left; margin: 0 20px 20px 0;"></iframe> + + +<p> + Your app can avoid downloading duplicate data by caching. Always cache static resources, + including on-demand downloads such as full size images, and cache them for as long as reasonably + possible. +</p> + +<p> + For example, you should consider this approach for a networked app that displays data from + user-initiated network requests as the primary content on the screen. When the user opens this + screen the first time, the app should display a splash screen. Subsequent loads should initially + load with the data that was cached from the last network request. The screen reloads with + new data once the network request is complete. +</p> + +<p> + To learn about caching, watch the video. To implement caching in your app, see <a href= + "{@docRoot}training/efficient-downloads/redundant_redundant.html#LocalCache">Cache Files + Locally</a>. +</p> + + +<h2 id="pre-fetch">Optimize Pre-Fetch Cache Size</h2> + +<p> + Optimize pre-fetch cache size based on local file system size and current network connectivity. + You can use the connectivity manager to determine what type of networks (Wi-FI, LTE, HSPAP, EDGE, + GPRS) are active and modify your pre-fetching routines to minimize battery load. +</p> + +<p> + For more information, see + <a href="{@docRoot}training/efficient-downloads/connectivity_patterns.html#Bandwidth">Use + Modifying your Download Patterns Based on the Connectivity Type</a>. +</p> diff --git a/docs/html/training/performance/battery/network/action-app-traffic.jd b/docs/html/training/performance/battery/network/action-app-traffic.jd new file mode 100644 index 000000000000..d62461eb630c --- /dev/null +++ b/docs/html/training/performance/battery/network/action-app-traffic.jd @@ -0,0 +1,134 @@ +page.title=Optimizing App-Initiated Network Use +trainingnavtop=true + +@jd:body + +<div id="tb-wrapper"> +<div id="tb"> + +<h2>This lesson teaches you to</h2> +<ol> + <li><a href="#batch-schedule">Batch and Schedule Network Requests</a> + <li><a href="#check-connect">Allow System to Check for Connectivity</a></li> +</ol> + +</div> +</div> + +<p> + Network traffic initiated by your app can usually be significantly optimized, since you can plan + for what network resources it needs and set a schedule for accessing them. By applying careful + scheduling, you can create significant periods of rest for the device radio and, thereby, save + power. There are several Android APIs that can help with network access scheduling, and some of + these functions can coordinate network access for other apps, further optimizing battery + performance. +</p> + +<p> + This lesson teaches you how to reduce battery consumption by applying techniques for + optimizing app-initiated network traffic. +</p> + + +<h2 id="batch-schedule">Batch and Schedule Network Requests</h2> + +<iframe width="448" height="252" + src="//www.youtube.com/embed/Ecz5WDZoJok?autohide=1&showinfo=0" + frameborder="0" allowfullscreen="" + style="float: right; margin: 0 0 20px 20px;"></iframe> + + +<p> + On a mobile device, the process of turning on the radio, making a connection, and keeping the + radio awake uses a large amount of power. For this reason, processing individual requests at + random times can consume significant power and reduce battery life. A more efficient approach is + to queue a set of network requests and process them together. This allows the system to pay the + power cost of turning on the radio just once, and still get all the data requested by an app. +</p> + + +<iframe width="448" height="252" + src="//www.youtube.com/embed/orlRuEwlDoM?autohide=1&showinfo=0" + frameborder="0" allowfullscreen="" + style="float: left; margin: 0 20px 20px 0;"></iframe> + +<p> + Using a network access scheduler API for queuing and processing your app data requests can + significantly increase the power efficiency of your app. Schedulers conserve battery power by + grouping requests together for the system to process. They can further improve efficiency by + delaying some requests until other requests wake up the mobile radio, or waiting until the + device is charging. Schedulers defer and batch network requests system-wide, across all apps on + the device, which gives them an optimizing advantage over what any individual app can do. +</p> + + +<h3 id="choosing-scheduler">Choosing a batch-and-scheduling API</h3> + +<p> + Android provides three different APIs for your app to batch and schedule network requests. For + most operations, these techniques are functionally equivalent. These APIs are listed in the + following table with the most highly recommended first. +</p> + +<table> + <tr> + <th>Scheduler</th> + <th>Requirements</th> + <th>Implementation Ease</th> + </tr> + <tr> + <td style="white-space: nowrap;"><a href="https://developers.google.com/cloud-messaging/network-manager"> + GCM Network Manager</a></td> + <td>GCM Network Manager requires that your app use the Google Play services client library, + version 6.1.11 or higher — use the latest available version.</td> + <td>Straightforward</td> + </tr> + <tr> + <td><a href="{@docRoot}reference/android/app/job/JobScheduler.html">Job Scheduler</a></td> + <td>Job Scheduler does not require Google Play services, but is available only when targeting + Android 5.0 (API level 21) or higher.</td> + <td>Straightforward</td> + </tr> + <tr> + <td> + <a href="{@docRoot}training/sync-adapters/index.html">Sync Adapter for scheduled syncs</a> + </td> + <td>Sync Adapter does not require the Google Play services client library and has been + available since Android 2.0 (API level 5).</td> + <td>Complex</td> + </tr> +</table> + + +<p class="note"> + <strong>Note:</strong> For scheduled data synchronization, you should <em>always</em> prefer GCM + Network Manager or Job Scheduler over Sync Adapter if your requirements allow it. +</p> + + +<h2 id="check-connect">Allow System to Check for Connectivity</h2> + +<p> + One of the most serious and unexpected causes of battery drain is when a user travels beyond the + reach of any cell tower or access point. In this situation, the user is typically not using their + device, but they notice the device getting warm, and then see that the battery is low or has run + out. +</p> + +<p> + In this scenario, the problem is that an app is running a background process that keeps + waking up the mobile radio at regular intervals to search for a cellular signal, but finds none. + Searching for a cell signal is one of the most power-draining operations there is. +</p> + +<p> + The way to avoid causing this kind of problem for a user with your app is to use a + battery-efficient method for checking connectivity. For app-initiated network requests, use a + <a href="#choosing-scheduler">scheduler</a>, which automatically uses <a href= + "{@docRoot}training/monitoring-device-state/connectivity-monitoring.html">Connectivity + Manager</a> to check for connectivity before calling into your app. As a result, if there's no + network, the Connectivity Manager conserves battery because it performs the connectivity check + itself, without loading the app to run the check. Battery is further conserved because schedulers + use <a href="http://en.wikipedia.org/wiki/Exponential_backoff" class="external-link">exponential + backoff</a> to check for connectivity less frequently as time progresses. +</p> diff --git a/docs/html/training/performance/battery/network/action-server-traffic.jd b/docs/html/training/performance/battery/network/action-server-traffic.jd new file mode 100644 index 000000000000..e568c8a35e98 --- /dev/null +++ b/docs/html/training/performance/battery/network/action-server-traffic.jd @@ -0,0 +1,78 @@ +page.title=Optimizing Server-Initiated Network Use +trainingnavtop=true + + +@jd:body + +<div id="tb-wrapper"> +<div id="tb"> + +<h2>This lesson teaches you to</h2> +<ol> + <li><a href="#gcm">Send Server Updates with GCM</a> +</ol> + +</div> +</div> + +<p> + Network traffic sent by server programs to your app can be challenging to optimize. A + solution to this problem is for your appp to periodically poll the server to check for updates. + This approach can waste network connection and power when your app starts up a device's radio, + only to receive an answer that no new data is available. A far more efficient approach would be + for the to notify your app when it has new data, but figuring out how to send a notification + from your server to potentially thousands of devices was previously no easy feat. +</p> + +<p> + The <a href="https://developers.google.com/cloud-messaging/gcm">Google Cloud Messaging</a> (GCM) + service solves this communication problem by allowing your servers to send notifications to + instances of your app wherever they are installed, enabling greater network efficiency and + lowering power usage. +</p> + +<p> + This lesson teaches you how to apply the GCM service to reduce network use for server-initiated + actions and reduce battery consumption. +</p> + + +<h2 id="gcm">Send Server Updates with GCM</h2> + +<p> + Google Cloud Messaging (GCM) is a lightweight mechanism used to transmit brief messages from an + app server to your app. Using GCM, your app server uses a message-passing + mechanism to notify your app that there is new data available. This approach eliminates network + traffic that your app would perform, by not contacting a backend server for new data when no + data is available. +</p> + +<p> + An example use of GCM is an app that lists speaker sessions at a conference. When sessions are + updated on your server, the server sends a brief message to your app telling it updates are + available. Your app can then call the server to update the sessions on the device only when + the server has new data. +</p> + +<p> + GCM is more efficient than having your app poll for changes on the server. The GCM service + eliminates unnecessary connections where polling would return no updates, and it avoids running + periodic network requests that could cause a device's radio to power up. Since GCM can be used by + many apps, using it in your app reduces the total number of network connections needed on a + device and allows the device radio to sleep more often. +</p> + +<p> + For more information about GCM and how to implement it for your app, see + <a href="https://developers.google.com/cloud-messaging/gcm">Google Cloud Messaging</a>. +</p> + +<p class="note"> + <strong>Note:</strong> When using GCM, your app can pass messages in normal or high priority. + Your server should typically use <a href= + "https://developers.google.com/cloud-messaging/concept-options#setting-the-priority-of-a-message"> + normal priority</a> to deliver messages. Using this priority level prevents devices from being + woken up if they are inactive and in a low-power <a href= + "https://developer.android.com/training/monitoring-device-state/doze-standby.html">Doze</a> + state. Use high priority messages only if absolutely required. +</p> diff --git a/docs/html/training/performance/battery/network/action-user-traffic.jd b/docs/html/training/performance/battery/network/action-user-traffic.jd new file mode 100644 index 000000000000..e3ddaa25337f --- /dev/null +++ b/docs/html/training/performance/battery/network/action-user-traffic.jd @@ -0,0 +1,128 @@ +page.title=Optimizing User-Initiated Network Use +trainingnavtop=true + +@jd:body + +<div id="tb-wrapper"> +<div id="tb"> + +<h2>This lesson teaches you to</h2> +<ol> + <li><a href="#pre-fetch-data">Pre-fetch Network Data</a> + <li><a href="#check-or-listen">Check for Connectivity or Listen for Changes</a></li> + <li><a href="#reduce-connections">Reduce the Number of Connections</a></li> +</ol> + +</div> +</div> + +<p> + Quick handling of user requests helps ensure a good user experience, especially when it comes to + user actions that require network access. You should prioritize low latency over power + conservation to provide the fastest response when optimizing network use that is a direct result + of user actions. Attaining an optimal network traffic profile for your app, while making sure + that your users get fast responses, can be a bit challenging. +</p> + +<p> + This lesson teaches you how to optimize network use for user-initiated + actions and reduce battery consumption. +</p> + + +<h2 id="pre-fetch-data">Pre-fetch Network Data</h2> + +<iframe width="448" height="252" + src="//www.youtube.com/embed/Rk1u7VVmadE?autohide=1&showinfo=0" + frameborder="0" allowfullscreen="" + style="float: right; margin: 0 0 20px 20px;"></iframe> + +<p> + Pre-fetching data is an effective way to reduce the number of independent data transfer sessions + that your app runs. With pre-fetching, when the user performs an action in your app, the app + anticipates which data will most likely be needed for the next series of user actions and fetches + that data in bulk. Battery power consumption is reduced for two reasons: + <ul> + <li> + Because your app pre-fetches data only when the the mobile radio is already awake from + the user's action, and so does not incur the overhead of waking up the mobile radio. + </li> + <li> + The app pre-fetches data for anticipated user actions, each of which might otherwise + require separate requests that each incur waking up the mobile radio. + </li> + </ul> + +</p> + +<p class="note"> + <strong>Tip:</strong> To explore whether your app might benefit from pre-fetching, review your + app's network traffic and look for situations where a specific series of user actions almost + always results in multiple network requests over the course of the task. For instance, an app + that incrementally downloads article content as a user views it might be able to pre-fetch one or + more articles in categories the user is known to view. +</p> + +<p> + Watch the video on effective pre-fetching which describes what pre-fetching is, where to + use it, and how much data to pre-fetch. For more details, see <a href= + "{@docRoot}training/efficient-downloads/efficient-network-access.html#PrefetchData">Optimizing + Downloads for Efficient Network Access</a>. +</p> + + +<h2 id="check-or-listen">Check for Connectivity or Listen for Changes</h2> + +<p> + Searching for a cell signal is one of the most power-draining operations on a mobile + device. Your app should always check for connectivity before sending a user-initiated network + request. If you use a scheduling service, <a href= + "{@docRoot}training/performance/battery/network/action-app-traffic.html#choosing-scheduler">Schedulers</a> + do this automatically for you. +</p> + +<ul> + <li>If only certain buttons in your activity depend on a network connection, use <a href= + "{@docRoot}reference/android/net/ConnectivityManager.html">Connectivity Manager</a> to check for + a network connection before sending the network request, as instructed in <a href= + "{@docRoot}training/monitoring-device-state/connectivity-monitoring.html#MonitorChanges">Monitor + for Changes in Connectivity</a>. If there's no network, the app can save battery by not forcing + the mobile radio to search. + </li> + + <li>If your entire activity's user interface is non-functional without network access, then use + <a href="{@docRoot}training/monitoring-device-state/manifest-receivers.html">Manipulate Broadcast + Receivers on Demand</a>. This technique listens for connectivity changes when your activity is in + the foreground, and prevents network requests from proceeding when no connectivity exists. That + is, if your app detects that connectivity has been lost, it disables all of its receivers, except + for the connectivity-change receiver. An example would be a news app that presents an activity + with a full-screen view of news snippets and does no pre-fetching. Any snippet a user taps would + require a network connection. + </li> +</ul> + + +<p> + A best practice for user-initiated traffic is to first check for a connection using <a href= + "{@docRoot}reference/android/net/ConnectivityManager.html">Connectivity Manager</a>, and if there + is no connection, <a href="#heading=h.a114i7ic2bxc">schedule</a> the network request for when the + connection is made. Schedulers will use techniques such as exponential backoff to save battery, + where each time the attempt to connect fails, the scheduler doubles the delay before the next + retry. +</p> + +<p class="note"> + <strong>Note:</strong> To check for connectivity for app-initiated traffic, see <a href= + "action-app-traffic.html#check-connect">Optimizing App-Initiated Network Use</a>. +</p> + + +<h2 id="reduce-connections">Reduce the Number of Connections</h2> + +<p> + In general, it's more efficient to reuse existing network connections than to initiate new ones. + Reusing connections also allows the network to more intelligently react to congestion and related + network data issues. For more information on reducing the number of connections used by your app, + see <a href="{@docRoot}training/efficient-downloads/efficient-network-access.html#ReduceConnections"> + Optimizing Downloads for Efficient Network Access</a>. +</p> diff --git a/docs/html/training/performance/battery/network/analyze-data.jd b/docs/html/training/performance/battery/network/analyze-data.jd new file mode 100644 index 000000000000..593201af8a16 --- /dev/null +++ b/docs/html/training/performance/battery/network/analyze-data.jd @@ -0,0 +1,215 @@ +page.title=Analyzing Network Traffic Data +trainingnavtop=true + +@jd:body + +<div id="tb-wrapper"> +<div id="tb"> + +<h2>This lesson teaches you to</h2> +<ol> + <li><a href="#general-traffic">Analyze App Network Traffic</a></li> + <li><a href="#traffic-types">Analyze Network Traffic Types</a></li> +</ol> + +</div> +</div> + +<p> + In the previous section, you tagged your app code with traffic identifiers, ran tests, and + collected data. This lesson teaches you how to look at the network traffic data you have + collected and directs you to actions for improving your app's networking performance and + reducing power consumption. +</p> + + +<h2 id="general-traffic">Analyze App Network Traffic</h2> + +<p> + Efficient use of network resources by an app is characterized by significant periods where + the network hardware is not in use. + + On mobile devices, there is a significant cost associated with starting up the radio + to send or receive data, and with keeping the mobile radio active for long periods. If your app + is accessing the network efficiently, you should see that its communications over the network are + tightly grouped together, well spaced with periods where the app is making no connection requests. +</p> + +<p> + Figure 1 shows suboptimal network traffic from app, as measured by the Network Traffic tool. The + app is making frequent network requests. This traffic has few periods of + rest where the radio could switch to a standby, low-power mode. The network access behavior of + this app is likely to keep the radio on for extended periods of time, which is + battery-inefficient. +</p> + +<img src="{@docRoot}images/training/performance/suboptimal_network_traffic_pattern.png" + alt="" id="figure1" /> +<p class="img-caption"> + <strong>Figure 1.</strong> Battery-inefficient network activity measured from an app. +</p> + +<p> + Figure 2 shows an optimal network traffic pattern. The app sends network requests in bursts, + separated by long periods of no traffic where the radio can switch to standby. This chart shows + the same amount of work being done as Figure 1, but the requests have been shifted and grouped to + allow the radio to be in standby most of the time. +</p> + +<img src="{@docRoot}images/training/performance/optimal_network_traffic_pattern.png" + alt="" id="figure2" /> +<p class="img-caption"> + <strong>Figure 2.</strong> Battery-efficient network activity measured from an app. +</p> + +<p> + If the network traffic for your app looks similar to the graph in Figure 2, you are in good + shape! Congratulations! You may want to pursue further networking efficiency by checking out the + techniques described in <a href= + "{@docRoot}training/performance/battery/network/action-any-traffic.html">Optimizing General Network + Use</a> +</p> + +<p> + If the network traffic for your app looks more like the graph in Figure 1, it's time to take a + harder look at how your app accesses the network. You should start by analyzing what types of + network traffic your app is generating. +</p> + + +<h2 id="traffic-types">Analyze Network Traffic Types</h2> + +<p> + When you look at the network traffic generated by your app, you need to understand the source of + the traffic, so you can optimize it appropriately. Frequent network activity generated by your + app may be entirely appropriate if it is responding to user actions, but completely inappropriate + if you app is not in the foreground or if the device in a pocket or purse. This section discusses + how to analyze the types of network traffic being generated by your app and directs you to + actions you can take to improve performance. +</p> + +<p> + In the previous lesson, you tagged your app code for different traffic types and used the Network + Traffic tool to collect data on your app and produce a graph of activity, as shown in Figure 3. +</p> +<img src="{@docRoot}images/training/performance/network_traffic_colors.png" /> +<p class="img-caption"> + <strong>Figure 3.</strong> Network traffic tagged for the three categories: user, app, and + server. +</p> + +<p> + The Network Traffic tool colors traffic based on the tags you created in the previous lesson. The + colors are based on the traffic type <a href= + "{@docRoot}training/performance/battery/network/gather-data.html#constants">constants you defined</a> in + your app code. Refer back to your app code to confirm which constants represent user, app, or + server-initiated traffic. +</p> + +<p> + The following sections discuss how to look at network traffic types and provides recommendations + on how to optimize traffic. +</p> + + +<h3 id="user">Analyzing user-initiated network traffic</h3> + +<p> + Network activity initiated by the user may be efficiently grouped together while a user is + performing a specific activity with your app, or spread out unevenly as the user requests additional + information your app needs to get. Your goal in analyzing user-initiated network traffic is to + look for patterns of frequent network use over time and attempt to create, or increase the size + of, periods where the network is not accessed. +</p> + +<p> + The unpredictability of user requests makes it challenging to optimize this type of network use + in your app. In addition, users expect fast responses when they are actively using an app, so + delaying requests for efficiency can lead to poor user experiences. In general, you should + prioritize a quick response to the user over efficient use of the network while a user is + directly interacting with your app. +</p> + +<p> + Here are some approaches for optimizing user-initiated network traffic: +</p> + +<ul> + <li> + <a href="{@docRoot}training/performance/battery/network/action-user-traffic.html#pre-fetch-data"> + Pre-fetch Network Data</a> - When the user performs an action in your app, the app + anticipates which data may be needed for the next user actions, fetches it in bulk + in a single connection, and holds it until the user requests it. + </li> + + <li> + <a href="{@docRoot}training/performance/battery/network/action-user-traffic.html#check-or-listen"> + Check for Connectivity or Listen for Changes</a> - Check for network connectivity or listen + for connectivity changes before performing an update. + </li> + + <li> + <a href="{@docRoot}training/performance/battery/network/action-user-traffic.html#reduce-connections"> + Reduce the Number of Connections</a> - Use server APIs that allow data to be downloaded in sets. + </li> +</ul> + +<p class="caution"> + <strong>Caution:</strong> Beware of network activity grouping bias in your user activity test + data! If you ran a set of user scenarios with your network testing plan, the graph of + user-initiated network access may be unrealistically grouped together, potentially causing you to + optimize for user behavior that does not actually occur. Make sure your user network test + scenarios reflect realistic use of your app. +</p> + + +<h3 id="app">Analyzing app-initiated network traffic</h3> + +<p> + Network activity initiated by your app code is typically an area where you can have a significant + impact on the efficient use of network bandwidth. In analyzing the network activity of your app, + look for periods of inactivity and determine if they can be increased. If you see patterns of + consistent network access from your app, look for ways to space out these accesses to allow the + device radio to switch into low power mode. +</p> + +<p> + Here are some approaches for optimizing app-initiated network traffic: +</p> + +<ul> + <li> + <a href="{@docRoot}training/performance/battery/network/action-app-traffic.html#batch-schedule"> + Batch and Schedule Network Requests</a> - Defer your app's network requests so they can be + processed together and at a time which is advantageous for battery life. + </li> + + <li> + <a href="{@docRoot}training/performance/battery/network/action-app-traffic.html#check-connect"> + Allow System to Check for Connectivity</a> - Avoid the battery cost of running your app just + to check for a network connection when you can let the system run the check while your app + sleeps. + </li> +</ul> + + +<h3 id="server">Analyzing server-initiated network traffic</h3> + +<p> + Network activity initiated by servers communicating with your app is also typically an area where + you can have a significant impact on the efficient use of network bandwidth. In analyzing the + network activity from server connections, look for periods of inactivity and determine if they + can be increased. If you see patterns of consistent network activity from servers, look for ways + to space out this activity to allow the device radio to switch into low power mode. +</p> + +<p> + Here is an approach for optimizing app-initiated network traffic: +</p> + +<ul> + <li> + <a href="action-server-traffic.html#gcm">Use GCM for Server Updates</a> - Consider using + the Google Cloud Messaging service for server side updates instead of polling. + </li> +</ul> diff --git a/docs/html/training/performance/battery/network/gather-data.jd b/docs/html/training/performance/battery/network/gather-data.jd new file mode 100644 index 000000000000..32edcd541fd7 --- /dev/null +++ b/docs/html/training/performance/battery/network/gather-data.jd @@ -0,0 +1,267 @@ +page.title=Collecting Network Traffic Data +trainingnavtop=true + +@jd:body + +<div id="tb-wrapper"> +<div id="tb"> + +<h2>This lesson teaches you to </h2> +<ol> + <li><a href="#tag-requests">Tag Network Requests</a></li> + <li><a href="#build-type">Configure a Network Test Build Type</a></li> + <li><a href="#deploy-apk">Deploy the Network Test APK</a></li> + <li><a href="#network-tool">Run Network Traffic Tool</a></li> +</ol> + +</div> +</div> + +<p> + The network traffic generated by an app can have a significant impact on the battery life of the + device where it is running. In order to optimize that traffic, you need to both measure it and + identify its source. Network requests can come directly from a user action, requests from your own + app code, or from a server communicating with your app. +</p> + +<p> + The <a href="{@docRoot}tools/debugging/ddms.html#network">Network Traffic tool</a> (part of the + DDMS tools) enables you to view how and when your app transfers data over a network. +</p> + +<p> + This lesson shows you how to measure and categorize network requests by tagging your source code, + then shows you how to deploy, test and visualize your apps's network traffic. +</p> + + +<h2 id="tag-requests">Tag Network Requests</h2> + +<p> + Apps use the networking hardware on a device for various reasons. In order to properly optimize + your app's use of networking resources, you must understand how frequently your app is using the + network and for what reasons. For performance analysis purposes, you should break down use of + network hardware into these categories: +</p> + +<ul> + <li> + <strong>User-initiated network requests</strong> - Requests initiated by the user, such as a + user request for an updated articles list in a news app. + </li> + + <li> + <strong>App-initiated network requests</strong> - Requests initiated within Android app code + that are not used to immediately satisfy a user action, such as an app request to cache the + text of unread articles in a news app. + </li> + + <li> + <strong>Server-initiated network requests</strong> - Requests initiated by a server to your app + that are not used to immediately satisfy a user action, such as notification of a newly + available article in a news app. + </li> +</ul> + +<p> + This procedure shows you how to tag your app's source code with constants to categorize traffic + as one of these three request types. The Network Traffic tool represents each type of traffic + with a different color, so you can visualize and optimize each traffic stream separately. + The technique described here reports network traffic based on the execution of threads in your + app which you identify as a user, app or server source. +</p> + +<ol> + <li>In your app's development project, define three constants to represent the different types + of network use: + +<pre id="constants"> +public static final int USER_INITIATED = 0x1000; +public static final int APP_INITIATED = 0x2000; +public static final int SERVER_INITIATED =0x3000; +</pre> + </li> + + <li>Find networking code in your app by searching for the most common classes used for + this purpose: + <ol type="a"> + <li>In Android Studio, choose <strong>Edit > Find > Find in Path</strong>.</li> + <li>Paste the following string into the <strong>Text to find</strong> field:<br> + <code>extends GcmTaskService|extends JobService|extends + AbstractThreadedSyncAdapter|HttpUrlConnection|Volley|Glide|HttpClient</code> + </li> + <li>Check <strong>Regular expression</strong>.</li> + <li>Check <strong>File mask(s)</strong> and type <code>*.java</code>.</li> + <li>Click the <strong>Find</strong> button.</li> + </ol> + </li> + +<li> + Based on your findings in the previous step, tag your app's use of network traffic by adding the + {@link android.net.TrafficStats#setThreadStatsTag} method to each execution thread in your app + that uses network resources, as shown in the following code example. + +<pre> +if (BuildConfig.NETWORK-TEST && Build.VERSION.SDK_INT >= 14) { + try { + TrafficStats.setThreadStatsTag(USER_INITIATED); + // make network request using HttpClient.execute() + } finally { + TrafficStats.clearThreadStatsTag(); + } +} +</pre> + + <p class="note"> + <strong>Note:</strong> Ensure the tagging does not get into your production code by making + inclusion of this code conditional, based on the build type used to generate the APK. + In the example above, the <code>BuildConfig.NETWORK-TEST</code> field identifies this + APK as a test version. + </p> + + </li> +</ol> + +<p class="note"> + <strong>Note:</strong> This technique for tagging network traffic from your app depends on + how the APIs that you are using access and manage network sockets. Some networking libraries + may not allow the {@link android.net.TrafficStats} utilities to tag traffic from your app. +</p> + +<p> + For more information about tagging and tracking network traffic with the Network Traffic tool, + see <a href="http://tools.android.com/recent/detailednetworkusageinddms">Detailed Network Usage + in DDMS</a>. +</p> + + +<h2 id="build-type">Configure a Network Test Build Type</h2> + +<p> + When you run performance tests, your APK should be as close as possible to the production + build. In order to achieve this for your network testing, create a <code>network-test</code> + build type, rather than using <code>debug</code> build type. +</p> + +<ol> + <li>Open your app in Android Studio.</li> + <li>Create a debuggable build type for your network test by modifying your project's + <code>build.gradle</code> file as shown in the following code example: + +<pre> +android { + ... + buildTypes { + debug { + // debuggable true is default for the debug buildType + } + <strong>network-test { + debuggable true + }</strong> + } + ... +} +</pre> + </li> +</ol> + + +<h2 id="deploy-apk">Deploy the Network Test APK</h2> + +<p> + To deploy the APK generated by the {@code network-test} build type configured in the previous + proceedure: +</p> + +<ol> + <li>Check that <strong>Developer Options</strong> are enabled on your test device. For + information about how to check and enable this option, see <a href= + "{@docRoot}tools/device.html#developer-device-options">Using Hardware Devices</a>. + </li> + + <li>Using a USB cable, connect your test device to your development computer. + </li> + + <li>In Android Studio, select <strong>Build Variants</strong> on the left edge of the window. + </li> + + <li>Click the <strong>Sync Project with Gradle Files</strong> button to populate the + Build Variants list with <code>network-test</code> for the app module. + </li> + + <li>Choose <code>network-test</code> from the list. + </li> + + <li>Deploy the debuggable version of your app to your device by choosing + <strong>Run</strong> > <strong>Debug</strong>. + </li> +</ol> + + +<h2 id="network-tool">Run Network Traffic Tool</h2> + +<p> + The Network Traffic tool in Android Studio helps you see how your app uses network resources + in real time, while it is running. +</p> + +<p> + To improve the repeatability of your testing, you should start with a known initial state for + your app by clearing app data. The following procedure includes a step that shows you how to + clear <em>all</em> app data including previously cached data and networking data. This step + puts your app back to a state where it must re-cache all previously cached data. Do not skip + this step. +</p> + +<p> + To start the Network Traffic tool and visualize the network requests: +</p> + +<ol> + <li>Start the Network Traffic tool by launching Android Studio and choosing <strong>Tools > + Android > Android Device Monitor</strong>. When asked, allow incoming network connections. + </li> + + <li>In the Android Device Monitor window, click the <strong>DDMS</strong> button along the top + and choose the <strong>Network Statistics</strong> tab. If you don't see this tab, widen the + window and then try <strong>Window > Reset Perspective</strong>. + </li> + + <li>Select your app to debug from the list of debuggable apps on your device in the + <strong>Devices</strong> tab, then click the <strong>Start</strong> button in the + <strong>Network Statistics</strong> tab. + + <p class="note"> + <strong>Note:</strong> You may be prompted to <strong>Allow USB Debugging</strong> on your + device. Select <strong>OK</strong> to allow debugging to proceed. + </p> + </li> + + <li>Clear your app data using the following adb command: +<pre class="no-pretty-print"> +adb shell pm clear <em>package.name.of.app</em> +</pre> + </li> + + <li>Start your app and run a testing plan that exercises your app's primary use cases. Your plan + should also allow for app idle time, where the user is not interacting with the app, to allow + app-initiated and server-initiated network access to occur. + </li> + + <li>Repeat the test by clearing the app data and running your test plan again. You should repeat + the test a few times to verify the repeatability of your performance data. + </li> +</ul> +</ol> + +<p> + Use of tagging for network traffic helps you visually distinguish each request category by + producing a different color for each network traffic in the Network Traffic tool, as shown in + Figure 1. +</p> + +<img src="{@docRoot}images/training/performance/network_traffic_colors.png" /> +<p class="img-caption"> + <strong>Figure 1.</strong> Network traffic tagged for the three categories. +</p> + diff --git a/docs/html/training/performance/battery/network/index.jd b/docs/html/training/performance/battery/network/index.jd new file mode 100644 index 000000000000..1da30cfb869e --- /dev/null +++ b/docs/html/training/performance/battery/network/index.jd @@ -0,0 +1,86 @@ +page.title=Reducing Network Battery Drain +page.article=true + +page.tags=battery +page.metaDescription=Learn how to optimize your app to reduce battery drain and use network resources efficiently. + +@jd:body + + +<iframe width="448" height="252" + src="//www.youtube.com/embed/fEEulSk1kNY?autohide=1&showinfo=0" + frameborder="0" allowfullscreen="" + style="float: right; margin: 0 0 20px 20px;"></iframe> + +<p> + Requests that your app makes to the network are a major cause of battery drain because they turn + on the power-hungry mobile or Wi-Fi radios. Beyond the power needed to send and receive packets, + these radios expend extra power just turning on and keeping awake. Something as simple as a + network request every 15 seconds can keep the mobile radio on continuously and quickly use up + battery power. +</p> + +<p> + This lesson shows you how to tag your app's source code to categorize, visualize and color + your network requests according to how they are initiated. From there, each category + identifies areas of your app that you can make more battery-efficient. +</p> + + +<h2>Performance Actions</h2> + +<dl> + <dt> + <strong><a href="gather-data.html"> + Collecting Network Traffic Data</a></strong> + </dt> + <dd> + Learn how to instrument your app's code and gather data on its use of network resources. + </dd> + + <dt> + <strong><a href="analyze-data.html"> + Analyzing Network Traffic Data</a></strong> + </dt> + <dd> + Learn how to analyze your app's use of network resources in response to user actions + and optimize it to reduce power consumption. + </dd> + + <dt> + <strong><a href="action-user-traffic.html"> + Optimizing User-Initiated Network Use</a></strong> + </dt> + <dd> + Learn how to optimize your app's use of network resources in response to user actions + to reduce power consumption. + </dd> + + <dt> + <strong><a href="action-app-traffic.html"> + Optimizing App-Initiated Network Use</a></strong> + </dt> + <dd> + Learn how to optimize your app's requests for network resources to reduce + power consumption. + </dd> + + <dt> + <strong><a href="action-server-traffic.html"> + Optimizing Server-Initiated Network Use</a></strong> + </dt> + <dd> + Learn how to optimize your app's requests for network resources and to reduce + power consumption. + </dd> + + <dt> + <strong><a href="action-any-traffic.html"> + Optimizing General Network Use</a></strong> + </dt> + <dd> + Learn how to optimize your app's requests for network resources and to reduce + power consumption. + </dd> + +</dl> diff --git a/docs/html/training/training_toc.cs b/docs/html/training/training_toc.cs index 9dbbe241bcbd..183fa6994ffb 100644 --- a/docs/html/training/training_toc.cs +++ b/docs/html/training/training_toc.cs @@ -1943,6 +1943,7 @@ results." </li> </ul> </li> + <li class="nav-section"> <div class="nav-section-header"> <a href="<?cs var:toroot ?>training/monitoring-device-state/index.html" @@ -1956,7 +1957,42 @@ results." </a> </div> <ul> - <li><a href="<?cs var:toroot ?>training/monitoring-device-state/doze-standby.html" + + <li class="nav-section"> + <div class="nav-section-header"> + <a href="<?cs var:toroot ?>training/app/battery/network/index.html"> + Reducing Network Battery Drain + </a> + </div> + <ul> + <li><a href="<?cs var:toroot ?>training/app/battery/network/gather-data.html"> + Collecting Network Traffic Data + </a> + </li> + <li><a href="<?cs var:toroot ?>training/app/battery/network/analyze-data.html"> + Analyzing Network Traffic Data + </a> + </li> + <li><a href="<?cs var:toroot ?>training/app/battery/network/action-user-traffic.html"> + Optimizing User-Initiated Network Use + </a> + </li> + <li><a href="<?cs var:toroot ?>training/app/battery/network/action-app-traffic.html"> + Optimizing App-Initiated Network Use + </a> + </li> + <li><a href="<?cs var:toroot ?>training/app/battery/network/action-server-traffic.html"> + Optimizing Server-Initiated Network Use + </a> + </li> + <li><a href="<?cs var:toroot ?>training/app/battery/network/action-any-traffic.html"> + Optimizing General Network Use + </a> + </li> + </ul> + </li> <!-- End of Reducing Network Battery Drain --> + + <li><a href="<?cs var:toroot ?>training/monitoring-device-state/doze-standby.html" >Optimizing for Doze and App Standby</a> </li> <li><a href="<?cs var:toroot ?>training/monitoring-device-state/battery-monitoring.html" |
