Android

API R

efer

ence

Published: 2015-01-07SWD-20150107142123710

Contents

Overview of Android API support..................................................................................................................7

Unsupported APIs for Jelly Bean (10.2.1 or later)........................................................................................ 9App features.................................................................................................................................................. 9App permissions.......................................................................................................................................... 10BlackBerry Balance limitations.....................................................................................................................11Hardware features....................................................................................................................................... 11Intents......................................................................................................................................................... 13Unsupported functions and APIs.................................................................................................................. 14Unsupported media formats.........................................................................................................................15Software features......................................................................................................................................... 16

Android Native support..............................................................................................................................21

In-app payments support........................................................................................................................... 23

Mapping support........................................................................................................................................25Using a WebView to access Google Maps......................................................................................................25Replacing Google Maps with OpenStreetMap............................................................................................... 28

Creating Push-enabled Android apps......................................................................................................... 33

Video encoding recommendations............................................................................................................. 37

Battery life recommendations.................................................................................................................... 39

Features and Unsupported APIsThe following sections outline Android features that are supported and not supported by the BlackBerry Runtime for Android apps.

View API Support as a PDF

Features and Unsupported APIs 5

Features and Unsupported APIs 6

Overview of Android API supportFind out which APIs are not supported by the BlackBerry 10 OS.

When you test your app's compatibility level, the tools compare your app's features with the features available in the BlackBerry Runtime. The tool generates a warning for each unsupported feature that it finds. Warnings range from mild (level 1) to severe (level 5). Apps that receive no warnings higher than level 1 are considered compatible with the BlackBerry 10 OS. Apps that receive warnings of level 2 or higher are considered to be incompatible with the BlackBerry Runtime for Android apps.

You should test your repackaged app's functionality on a BlackBerry 10 device before submitting it to BlackBerry World. Apps that fail to meet BlackBerry quality standards are rejected.

In-app purchases are supported on the BlackBerry Runtime for Android apps through BlackBerry World, but not through the Android Market. We highly recommend that you modify your app to use the BlackBerry World in-app payments. Apps that rely heavily on the Android Market and that don't provide a good user experience without it are rejected by the BlackBerry World vendor portal.

Overview of Android API support 7

Overview of Android API support 8

Unsupported APIs for Jelly Bean (10.2.1 or later)Find details about Android features that the BlackBerry Runtime for Android apps on BlackBerry 10 does not support.

The following sections outline the Android Jelly Bean features that the BlackBerry Runtime for Android apps on BlackBerry 10 does not support.

App featuresThe following types of apps are not supported, and are not permitted for sale or distribution.

Unsupported APIs for Jelly Bean (10.2.1 or later) 9

Added 10.3 support for apps that need Android API level 18.

BlackBerry 10 OS version 10.2.1 does not support the following:• Apps that need an Android API level greater than

17 or whose maximum supported level is less than 10.

• Apps that do not include a launchable activity.• Apps with more than one launch icon.• Widget apps and apps that are only meant to be

Widgets. Apps that include widget functionality as a secondary feature are supported, as long as they define one launchable activity in their manifest.

• Apps that implement an alternate home screen.

App permissionsThe Android app permissions listed in the following table are not supported. The impact of these unsupported permissions on your app may vary. Some of these unsupported permissions are likely to have an adverse impact on your app and others are less likely to have an adverse impact, but an adverse impact on your app is still possible.

Unsupported permissions and their impact on your app

Adverse impact is likely Adverse impact is possibleBIND_DEVICE_ADMIN CHANGE_CONFIGURATION

BIND_INPUT_METHOD CHANGE_WIFI_MULTICAST_STATE

BIND_REMOTEVIEWS CLEAR_APP_CACHE

BIND_WALLPAPER DISABLE_KEYGUARD

CHANGE_NETWORK_STATE PERSISTENT_ACTIVITY

Unsupported APIs for Jelly Bean (10.2.1 or later) 10

CHANGE_WIFI_STATE REORDER_TASKS

GLOBAL_SEARCH SET_TIME_ZONE

MASTER_CLEAR SET_WALLPAPER_HINTS

READ_INPUT_STATE SYSTEM_ALERT_WINDOW

SET_PREFERRED_APPLICATIONS

BlackBerry Balance limitations

Android apps cannot be deployed within the work perimeter using BlackBerry Balance. Android apps do not have access to any work space data, including email, contacts, and calendar.

Hardware featuresThe BlackBerry 10 OS does not support the following hardware features. Test your apps that use any of these features on a BlackBerry 10 device. Testing is needed to ensure that your app's usability and functionality are not negatively impacted by the lack of these features.

Category FeaturesCamera • Face detection

Unsupported APIs for Jelly Bean (10.2.1 or later) 11

• White balance and focus areas• Continuous autofocus• Time-lapse video recording

Connectivity and communication BlackBerry 10 OS 10.2.1 does not support the following:

• USB host/accessory and low-level control• Bluetooth Low Energy (supported in BlackBerry

10 OS 10.3 and later, but not in BlackBerry 10 OS 10.2 and earlier)

• Wi-Fi Direct• NFC (supported in BlackBerry 10 OS 10.3 and

later, but not in BlackBerry 10 OS 10.2 and earlier)

Key configuration requirements • Five-way navigation keys• Hardware keyboard• Twelve-key keyboard• D-pad, trackball, or wheel navigation

Sensors, input, display, and others • Altimeter sensor• Low-latency audio pipeline

(android.hardware.audio.low_latency)• Five or more simultaneous independent touch

events (android.hardware.touchscreen.multitouch.jazzhand)

• Multiple displays

Telephony Features • SIM Info Access• PhoneStateListener

• LISTEN_CALL_FORWARDING_INDICATOR• LISTEN_DATA_ACTIVITY

• DATA_ACTIVITY_NONE • DATA_ACTIVITY_IN• DATA_ACTIVITY_OUT

Unsupported APIs for Jelly Bean (10.2.1 or later) 12

• DATA_ACTIVITY_INOUT• DATA_ACTIVITY_DORMANT

• LISTEN_MESSAGE_WAITING_INDICATOR• SMSManager• SMSMessage• TelephonyManager

• getDataActivity• getLine1Number• getSubscriberId• getVoiceMessageCount• getVoiceMailAlphaTag• getVoiceMailNumber

IntentsNote: Launcher (Home Screen) intents are not supported.

Android apps cannot provide system-wide services to the rest of the device. For example, dialing services such as handling the android.intent.action.ACTION_DIAL activity action are not supported.

Intents that are not broadcastandroid.intent.action.BOOT_COMPLETED

android.intent.action.PACKAGE_DATA_CLEARED

android.intent.action.ACTION_POWER_CONNECTED

android.intent.action.ACTION_POWER_DISCONNECTED

android.intent.action.ACTION_SHUTDOWN

android.intent.action.USER_PRESENT

android.hardware.usb.action.ACTION_USB_ACCESSORY_ATTACHED

android.hardware.usb.action.ACTION_USB_ACCESSORY_DETACHED

android.hardware.usb.action.ACTION_USB_DEVICE_ATTACHED

android.hardware.usb.action.ACTION_USB_DEVICE_DETACHED

Unsupported APIs for Jelly Bean (10.2.1 or later) 13

android.media.RINGER_MODE_CHANGED

Device setting invocations that are not supportedandroid.settings.APPLICATION_DETAILS_SETTINGS

android.settings.APPLICATION_SETTINGS

android.settings.MANAGE_ALL_APPLICATIONS_SETTINGS

android.settings.QUICK_LAUNCH_SETTINGS

Unsupported functions and APIs

Unsupported Media APIs

FunctionMTP / PTP APIs (Media/Picture transfer Protocol)

5.1 channel audio encoding

Pluggable DRM framework

Unsupported AudioManager functions

Function ResponseAudioManager.setRingerMode Do nothing

Unsupported APIs for Jelly Bean (10.2.1 or later) 14

Unsupported MediaPlayer functions

Function ResponseMediaPlayer.attachAuxEffect Do nothing

MediaPlayer.setAuxEffectSendLevel Do nothing

Unsupported media formats

The tables below describe the media formats that are not supported by the BlackBerry Runtime for Android apps.

Audio

Format/Codec Unsupported Encoder/Decoder

Unsupported APIs for Jelly Bean (10.2.1 or later) 15

HE-ACC v1 (ACC+) Encoder

ACC ELD (Enhanced low delay ACC) Encoder/Decoder

AMR -NB Encoder

AMR -WB Encoder

Video

Format/Codec Unsupported Encoder/Decoder

Unsupported File Type

H.263 Encoder

VP8 Encoder/Decoder WebM (.webm) Matroska (.mkv)

Image

Format/Codec Unsupported Encoder/Decoder

Unsupported File Type

WEBP Encoder/Decoder WebP (.webp)

Software featuresThe BlackBerry 10 OS does not support the following software features. Test your apps that use any of these features on a BlackBerry 10 device. Testing is needed to ensure that your app's usability and functionality are not negatively impacted by the lack of these features.

Unsupported APIs for Jelly Bean (10.2.1 or later) 16

Feature Description

Add-on libraries All libraries defined by the tag in the app's manifest other than android.test.runner or that depend on a library specified by <uses-library>.

Background service Apps can run services only while the user runs them, either in full screen or in thumbnail mode.

BackupAgent No support for app data backup.

ContactsContract Contacts cannot be extended with app-specific data or actions.

Contacts Provider The following Contacts Provider APIs are not supported:

• Social APIs• Social Stream APIs

Daydream No support for the DreamService APIs used to implement DayDream interactive screen savers.

Google accounts No support for access to a Google account (Google authentication).

Android apps that use authentication for user login can be set up and managed from within the BlackBerry 10 accounts settings.

Near Field Communication (NFC) Android apps that integrate with NFC are supported. NFC support includes reading and writing tags, as well as sharing data between NFC-enabled devices.

Access to the secure element is not supported, for example, in payment type apps.

Java software packages The following Java software packages are not supported:

• TTS, VoIP, and SIP services

Unsupported APIs for Jelly Bean (10.2.1 or later) 17

Linux virtual file systems Limited support for the Linux virtual file systems (/proc, /sys, and /dev).

Locked device activities No ability to show an activity above the device lock screen (WindowManager.LayoutParams.FLAG_SHOW_WHEN_LOCKED).

Maps Apps that use MapView from Google Maps v1 are supported using OpenStreetMaps, however the following features are not supported:

• Embedding MapView v2• Invoking the device's Maps app

Multiplayer support No support for multiple participants in games apps.

Networking The following network features are not supported:

• Network usage• Metered network APIs• Third-party VPN services• Certificate management

Notifications Notifications posted by an app are displayed using cards, but only text is supported.

OpenGL ES 3.0 Added BlackBerry 10.3 support for OpenGL ES 3.0 (on supported hardware only).

In BlackBerry 10.2.1 and earlier, OpenGL ES 3.0 is not supported.

RenderScript support RenderScript supported since BlackBerry 10.3.

In BlackBerry 10.2.1 and earlier, the RenderScript framework is not supported.

Search Voice search supported since BlackBerry 10.3.

Unsupported APIs for Jelly Bean (10.2.1 or later) 18

Android apps cannot participate in providing results to device-wide searches using SearchManager or SearchableInfo APIs.

Third-party spell checkers No support for third-party spell check services.

Third-party TTS No support for third-party text-to-speech.

Thread priority All threads are running with the same priority. Use caution when setting individual priorities to threads; doing so can negatively impact your app. For example, if a thread is given an inappropriately high priority, the app may not start.

Voicemail provider Voicemail provider APIs are not supported.

Wallpaper Live wallpaper is not supported.

Retrieving the currently set wallpaper is not supported. However, an app can set the wallpaper.

Wi-Fi Network Service Discovery Unable to use Wi-Fi Direct and Network Service Discovery to discover services available on nearby devices.

Unsupported APIs for Jelly Bean (10.2.1 or later) 19

Unsupported APIs for Jelly Bean (10.2.1 or later) 20

Android Native supportKnown issues and limitations when using the Android NDK and a native-code language in your app.

Using the Android NDK in your apps

The Android NDK allows you to write parts of your app using native-code languages, such as C and C++. While this flexibility can help you reuse existing code libraries written in either of these languages, most apps don't need the Android NDK to work. Using the Android NDK in order to write your app using a native-code language doesn't usually result in improved performance. It does however, increase the complexity of your app, which can make it more difficult to maintain.

Some good choices for using the Android NDK with a native-code language include self-contained, CPU-intensive operations that don't allocate much memory, such as signal processing or physics simulation.

Do not use the Android NDK to write generic native code that runs on Android devices. Instead, your apps should be written in Java, should handle Android system events, and should deal with the Android app life-cycle.

BlackBerry 10 supports both the ARMv5TE and ARMv7-A machine code instruction sets.

Android Native support 21

For installation information and downloads for the Android NDK, see System and Software Requirements on the Android NDK website. If you have any issues with repackaging Android NDK apps for BlackBerry 10, please provide feedback.

Known Issues and Limitations

The following table lists known issues and limitations when using the Android NDK or when repackaging Android NDK apps for BlackBerry 10

Known issues and limitations

Limited support for the Linux virtual file systems (/proc, /sys, and /dev).

Many of the native system libraries in the Android system images are not frozen and could be changed or deleted in later updates.

The Android NDK does not work with the BlackBerry 10 Device Simulator, as native calls are not supported.

The Android C++ runtime provides minimal support for C++ features. However, the Android NDK provides more advanced runtimes that you can link into your app.

The Android NDK supports a limited set of system header files for native APIs. To see the list of supported header files, visit Development tools on the Android NDK website.

Inter-process communication APIs for UNIX System V are not supported.

The Android NDK comes with documentation included in the installation .zip file. You can find a more detailed list of limitations in the <ndk>/docs/ directory.

Android Native support 22

In-app payments supportFind out how the BlackBerry Runtime for Android supports in-app payments through BlackBerry World.

In-app purchases and item IDs

The BlackBerry Runtime for Android supports in-app payments through the BlackBerry World vendor portal. You can add your digital goods in the BlackBerry World vendor portal, and then offer them for sale in your apps. You can use the same ItemId value that you used in the Android payment system as your digital good's digitalSKU value. Using the item ID for your digital goods in this way means that users who purchased goods in the Android payment system can access them on their BlackBerry devices.

Note: The Google Play™ service is not supported in BlackBerry Runtime for Android. If your app uses the In-app Billing version 3 API, you must reconfigure your project to use the In-app Billing version 2 API or earlier.

Things to know about adding in-app purchasing functionality to a ported Android app

• You can test your in-app purchases by following the steps outlined in the support article called How To: Live Testing the Payment SDK with PlayBook Applications, which also applies to testing in-app purchases in BlackBerry 10.

• Only one purchase can be made at a time. Concurrent transactions are not supported.• Refunds are not supported in the APIs.

In-app payments support 23

• Subscriptions are not supported. However, you can offer users an alternative way to buy the content that's available through subscriptions. For example, you could create standard in-app products (as one-time purchases) that give access to content that's similar to your subscriptions, but for longer intervals, such as a year.

• Transaction responses are not signed, so they cannot be verified.

Transaction responses

In the BlackBerry Runtime for Android apps, transaction responses are not signed. If your app tries to verify the transaction response signature, change your app code to ignore this value when testing your app on a BlackBerry 10 device.

You can use the following code to programmatically test if your app is running on a BlackBerry device:

java.lang.System.getProperty("os.name").equals("qnx")

If the above check returns true, skip the code block in your app that verifies the transaction signature.

Terminology

The Android payment system and the BlackBerry World payment system use slightly different terminology. The following table shows the differences between the names used in each system:

Android BlackBerry

ItemId digitalSKU

Managed transactions • Equivalent to Not Consumable transactions on the BlackBerry platform.

• Can be bought only once.• BlackBerry World saves the purchases, and

manages them in the event of a device switch.

Unmanaged transactions • Equivalent to Consumable transactions on the BlackBerry platform.

• BlackBerry World manages purchased consumable items. The Android Market does not.

Optional developer payload Metadata

In-app payments support 24

Mapping supportFind out how the BlackBerry Runtime for Android apps supports location-based intents to display Google Maps.

The BlackBerry Runtime for Android apps doesn't support Google Maps. If your app uses Google Maps, there are two ways that you can support mapping in your app. One option is to replace the Google Maps library with a WebView that integrates the web version of Google Maps.

For more information on this process, see Using a WebView to access Google Maps on page 25.

Another option is to replace Google Maps with OpenStreetMap, which is a free worldwide map.

For more information on this process, see Replacing Google Maps with OpenStreetMap on page 28.

Using a WebView to access Google MapsThe BlackBerry Runtime for Android apps supports location-based intents to display Google Maps. Once triggered, these intents are converted into web intents that carry the corresponding URL for the Google Maps that are to be displayed in the browser.

Mapping support 25

The following intent URIs are supported:

geo:latitude,longitudegeo:latitude,longitude?z=zoomgeo:0,0?q=address+business+or+keywords

Instead of starting a location intent, you can create an instance of a WebView and load the URL of the Google Maps mobile website. You can add parameters to the URL, which allows you to use more functionality than is available using the Java-based Google Maps API.

The following sample demonstrates how you can create an instance of a WebView to display a mobile Google Maps URL with parameters in an Android app. The main activity of your app should contain the following lines in its onCreate() method:

@Overridepublic void onCreate(Bundle savedInstanceState) { super.onCreate(savedInstanceState); setContentView(R.layout.main); WebView webView = (WebView) findViewById(R.id.mywebview); webView.getSettings().setJavaScriptEnabled(true); webView.loadUrl("http://maps.googleapis.com/maps/api/staticmap? ll=36.97,%20-122&lci=bike&z=13&t=p&size=500x500&sensor=true");}

For more information about the Google Static Maps API URL, see URL Parameters.

The following table highlights some of the differences in functionality between using the Google Maps Java API and using the URL parameters of Google Maps.

Note: A Java-based mapping API library and Geo-coding API for Google Maps are not available for the BlackBerry Runtime for Android apps.

Feature Google Maps Java API URL Parameters of Google Maps

Available map types and customization

Road

Satellite

Custom projections

Road

Satellite

Hybrid

Terrain

Mapping support 26

UI controls Zoom Zoom

Query input field

Layers

Current location

Get Directions

Places

Overlays Built-in overlay types are not available, but you can implement your own

Markers

Layers Traffic Bicycling

Traffic

Transit

YouTube

Wikipedia

Panoramio

Direction service Not available Source/destination query

Intermediate addresses

Travel mode (driving, bicycling, walking)

Unit systems

Departure and arrival times for transit

Geo-coding service Not part of the mapping library. Can be done using a separate Google service for Android (not available in BlackBerry Runtime for Android apps)

Keyword query support

Nearby location

Search mode (businesses, mapped webpages, real estate, and so forth)

Mapping support 27

Replacing Google Maps with OpenStreetMapDownload the source code for the OpenStreetMap library from GitHub. After you download the source code, compile it so the library is current.

Change the layout

In your source code, locate the following section of code:

<com.google.android.maps.MapView android:id="@+id/mapview" android:layout_width="fill_parent" android:layout_height="fill_parent" android:apiKey="@+string/mapviewkey" android:clickable="true"/>

Change it to the code below.

<org.osmdroid.views.MapView android:id="@+id/mapview" android:layout_width="fill_parent" android:layout_height="fill_parent"/>

Note: Unlike Google Maps, OpenStreetMap requires no key.

Change the imported library

Locate the following code:

import com.google.android.maps.GeoPoint;import com.google.android.maps.MapController;import com.google.android.maps.MapView;

Change it to the code below.

import org.osmdroid.util.GeoPoint;import org.osmdroid.views.MapController;import org.osmdroid.views.MapView;

Mapping support 28

If you want to include PINs or markers, add the following code:

import org.osmdroid.views.overlay.ItemizedIconOverlay;import org.osmdroid.views.overlay.ItemizedIconOverlay.OnItemGestureListener;import org.osmdroid.views.overlay.OverlayItem;import org.osmdroid.views.overlay.OverlayManager;import org.osmdroid.views.overlay.mylocation.GpsMyLocationProvider;import org.osmdroid.views.overlay.mylocation.MyLocationNewOverlay;

The default class for using resources is DefaultResourceProxyImpl.

ResourceProxyImpl resProxyImp = newResourceProxyImpl(this);

Note: English is the only language that this class supports at this time. You must create your own class to support other languages.

Customize your map

Locate the following code to customize the mapView and mMyLocationOverlay classes:

mapView = (MapView) findViewById(R.id.mapview);mapView.setBuiltInZoomControls(true);

mMyLocationOverlay = new MyLocationOverlay(this, mapView);mapView.getOverlays().add(mMyLocationOverlay);

Change it to the code below.

mapView = (MapView) findViewById(R.id.mapview);mapView.setUseSafeCanvas(false);

To enable zoom controls, include the following:

mapView.setBuiltInZoomControls(true);

To enable multitouch controls, include the following:

mapView.setMultiTouchControls(true);

Mapping support 29

The GpsMyLocationProvider class provides information about an object's position using GPS and cell towers. You can replace this class with your own class or add it using the following code:

GpsMyLocationProvider imlp = newGpsMyLocationProvider(this.getBaseContext());

To set a minimum distance (in meters) for updating the location, include the following:

/** * public void setLocationUpdateMinDistance(final float meters) */imlp.setLocationUpdateMinDistance(1000);

To set a minimum time (in milliseconds) for updating the location, include the following:

/** * public void setLocationUpdateMinTime(final long milliSeconds) */imlp.setLocationUpdateMinTime(60000);

Create the mMyLocationOverlay object.

mMyLocationOverlay = newMyLocationNewOverlay(this.getBaseContext(), imlp, mapView, resProxyImp);mMyLocationOverlay.setUseSafeCanvas(false);mMyLocationOverlay.setDrawAccuracyEnabled(true);

Add the mMyLocationOverlay object to the MapView overlay collection.

mapView.getOverlays().add(mMyLocationOverlay);

Add a marker overlay

You can use the ItemizedIconOverlay class to create an overlay and add it to the map:

ItemizedIconOverlay markersOverlay = newItemizedIconOverlay<OverlayItem>(new LinkedList<OverlayItem>(),myMarker, null, resProxyImp);mapView.getOverlays().add(markersOverlay);

Mapping support 30

Next, add the markers:

OverlayItem ovm = new OverlayItem("title", "description", newGeoPoint(s.LatitudeE6(), s.LongitudeE6()));ovm.setMarker(myMarker);markersOverlay.addItem(ovm);

Mapping support 31

Mapping support 32

Creating Push-enabled Android appsFind out how to create a push-enabled Android app for BlackBerry devices.

When you repackage your app for BlackBerry 10 devices, you can use the push technology of the BlackBerry Application Platform. The BlackBerry Application Platform provides similar functionality to Google Cloud Messaging (GCM). Push technology gives your users immediate access to content that has been sent (pushed) to their device.

The Android Cloud to Device Messaging Framework (C2DM) has been officially deprecated. For more information, see Android Cloud to Device Messaging Framework.

Note: The Google Play Services SDK is not supported on BlackBerry 10. If your app includes GCM services, you must set up your project to use the stand-alone GCM SDK.

To create a push-enabled Android app, you need to:

• Register with the Push Service.• Create the configuration file.• Specify push as a required permission in the .bar file's manifest file.• In the push initiator (the server-side app used to send out pushes), convert the data so that it's sent to the

BlackBerry Application servers instead of the Google app servers.

Creating Push-enabled Android apps 33

Registering with the Push Service

Before you can register to start your app, you must first register for evaluation.

• Register to evaluate the Push Service. This registration allows you to test your app or service in a test environment.

• Register to start your app in production.

Creating the android.cfg file

After you register with the Push Service, you must create a configuration file (the android.cfg file). This file provides the BlackBerry Push configuration, and allows your Android app to work without any code changes, or the need to recompile it again. Using any ZIP utility, add the android.cfg file to the .bar file. You must create this configuration file before you sign the .bar package.

When you register for a Push Service, you receive a registration ID unique to your device. Registration IDs from Google are in the form of APA91bHun4MxP5egoKMwt2KZFBaFUH-1RYqx, and BlackBerry registration IDs contain eight characters. To differentiate between BlackBerry and Android devices on the app server, you can prefix the registration ID with the token prefix in the android.cfg file.

When you register for the Push Service, you also received a PPG Base URL and an app ID. In the repackaged .bar file, create a file named android.cfg, and add the URL and app ID.

Here's a sample android.cfg file:

<?xml version="1.0" encoding="utf-8"?> <android> <push> <appid>some_appID</appid> <ppgurl>http://cpXXX.pushapi.eval.blackberry.com</ppgurl> <tokenprefix>bb-</tokenprefix> </push></android>

Here is a sample .bar file structure:

PushApp.bar/META-INFO/MANIFEST.MFPushApp.bar/android/android.cfg PushApp.bar/android/PushApp.apkPushApp.bar/android/res/drawable-hdpi/ic_launcher.png

Creating Push-enabled Android apps 34

Manifest permission

The Push Service requires that your signing keys have push capability enabled, and that push is specified as a required permission in the .bar file's manifest file. The required line is:

Entry-Point-System-Actions: _sys_use_consumer_push

Server changes

With the GCM services, the Google app servers sends push messages through a web request. BlackBerry Application Servers send push messages to BlackBerry devices through a similar web request. You must convert your data before you send it to the Google app server. BlackBerry Push Service does not impose a format on the message. However, because an Android app receives the message, you must convert the data to the JSON format:

{ "key":"value", key2: value2, "key3": value3, key4 : "value 4" ... }

Finally, your Push Initiator must send the data to the BlackBerry Application Servers instead of Google app servers.

The Android Runtime queues your pushes until the app is started. For more information about the BlackBerry Push Service, see Push technology for the enterprise.

Creating Push-enabled Android apps 35

Creating Push-enabled Android apps 36

Video encoding recommendationsGet examples of video encoding profiles and parameters that the Android media framework supports for playback.

Video encoding profiles and parameters

The following table lists examples of video encoding profiles and parameters that the Android media framework supports for playback.

Item Lower quality Higher quality

Video codec H.264 Baseline Profile H.264 Baseline Profile

Video resolution 176 x 144 px

720p resolution is supported

480 x 360 px

1080p resolution is supported

Video encoding recommendations 37

Video frame rate 12 fps 30 fps

Video bitrate 56 Kbps 500 Kbps

Audio codec AAC-LC AAC-LC

Audio channels 1 (mono) 2 (stereo)

Audio bitrate 24 Kbps 128 Kbps

In addition to these encoding parameters, a device's video recording profiles can be used as a proxy for media playback capabilities. These profiles can be inspected using the CamcorderProfile class, which is available since API level 8.

Video content that is streamed over HTTP or RTSP

There are additional requirements for video content that is streamed over HTTP or RTSP:

• For 3GPP and MPEG-4 containers, the moov Atom must precede any mdat Atom.• For 3GPP, MPEG-4, and WebM containers, audio and video samples corresponding to the Sametime offset

cannot be more than 500 KB apart. To minimize this audio / video drift, consider interleaving audio and video in smaller chunk sizes.

Video encoding recommendations 38

Battery life recommendationsFind out how to make your app a good citizen.

When you develop an app, you should consider whether it's efficient. An efficient app doesn't consume unnecessary resources and minimally impacts the life of the device battery. When your app adheres to these standards, it's considered to be a good citizen. Being conservative with power consumption and having a great user experience aren't mutually exclusive concepts. In fact, being conservative with power usage might increase your user's satisfaction with your app.

The sections below discuss how you can make your app a good citizen.

Monitor the battery and charging state

It's a good idea to consider the impact of running app updates. Performing updates while a device is charging causes minimal battery drain, so you can create your app to maximize its update rate when the device is charging. You can also conserve battery life by reducing the update rate when the device is not connected.

You can use BatteryManager to monitor battery and charging details. BatteryManager triggers an event whenever your device is connected to or disconnected from power. You can use these events to decide how often to start your app in a background state.

To monitor changes in the charging state, you can register a BroadcastReceiver in your app manifest to listen for these events by defining ACTION_POWER_CONNECTED and ACTION_POWER_DISCONNECTED. Generally, only battery changes that are significant should be monitored. You can use intents to monitor significant battery changes. Some significant battery changes include ACTION_BATTERY_LOW and ACTION_BATTERY_OKAY. You can use these event to determine when to disable background updates.

For a tutorial, see Monitoring the Battery Level and Charging State.

A problem with using a BroadcastReceiver is that your app wakes up each time any of the receivers are triggered. However, you can disable or enable the broadcast receivers at runtime. You can use system events to trigger the receivers that you declared in the manifest, and only when necessary. Use the PackageManager to toggle the enabled state on any component defined in the manifest.

If your app determines that connectivity has been lost, it can disable all of the receivers except android.net.conn.CONNECTIVITY_CHANGE, which informs your app of changes in the status of its Internet connectivity. Use this technique to delay large file downloads by enabling a broadcast receiver that initiates file downloads only when the device is connected to Wi-Fi.

For a full tutorial, see Manipulating Broadcast Receivers On Demand.

Stop animations when they're not needed

Although animations are important to the look and feel of most apps, they can affect the life of the device battery. Generally, animations should be stopped when they're not needed.

Battery life recommendations 39

For example, consider an app that frequently requests remote data, or performs intensive operations, such as running SQL queries. Although it's important to provide a visual cue indicating that some process is underway, you must consider how often that animation runs. An example of such an animation could be a ProgressBar or your own animation. If the animation is constantly running, you might want to reconsider how you present this information to your users.

In most cases, you can replace an animation with a static image that the user recognizes and associates with a particular process. For example, in a mapping app, an image of a compass rose or an arrow might indicate that the app is receiving location updates. Using these techniques can reduce the impact that animations have on the life of the device battery.

For more information about animations, see Animations.

Be conservative with location requests

Your app should be conservative with how often it sends location requests. Frequent location requests are needed when your app constantly needs to know the device's precise geographic coordinates, for example, when used in a mapping or navigation app. Otherwise, frequent location updates should not be used.

Consider a social networking app that tags updates with a user's current location, or a restaurant finder app that's designed to search for restaurants near the user's current location. For these apps, it's probably sufficient to make one location request, when needed. While it might seem useful to have the user's precise location always available, this requirement can cause a significant drain on the device battery.

For information about how you can retrieve the location of the device, see Retrieving the Current Location.

Push data to your apps

In BlackBerry 10, the preferred approach for receiving remote data is to use the Push Service. Push technology allows a server-side app to notify a client app when new data is available by pushing a notification with a small payload to the device.

Using this approach, you can conserve processor power and network usage because the client app sends requests only when it knows there's data available. The result is an app that not only conserves battery power, but also has the added benefit of near real-time updates.

For more information about using the Push Service with Android, see Creating Push-enabled Android apps on page 33.

Battery life recommendations 40