Published: SWD

Transcription

1 Android User Guide

2 Published: SWD

3 Contents Getting started...7 Process overview...7 Register for a BlackBerry ID account... 8 Install an app repackaging tool... 9 Plug-in and command-line tools...19 Check the compatibility of.apk files...20 BlackBerry tools for Android development Porting to BlackBerry 10 OS Publish to BlackBerry World... 63

4

5 Documentation This documentation describes how you can use the BlackBerry Tools for Android development to repackage your apps and port them to the BlackBerry 10 OS. View the Android Runtime Documentation as a PDF Documentation 5

6 Documentation 6

7 Getting started Learn how to use the BlackBerry Tools for Android apps to repackage your Android apps and become a BlackBerry World vendor. Introduction to BlackBerry Runtime for Android apps The BlackBerry Runtime for Android apps allows you to run Android apps on BlackBerry 10 devices. Repackaging your Android apps to run on the BlackBerry Runtime allows you to reach a brand new set of potential customers. When you repackage your Android apps as.bar files, you can submit them as BlackBerry 10 apps to the BlackBerry World storefront. Process overview You probably already have an established workflow that you use when you develop Android apps. Bringing your Android apps over to the BlackBerry Runtime allows you to access a whole new group of potential customers. However, before you can distribute your Android apps through the BlackBerry World storefront, they must be repackaged as signed.bar files. There are several options for repackaging your Android apps as BlackBerry 10 compatible.bar files. Chances are, one of these options fits nicely into your current workflow. Tokens, tools, and certificates You need a few items in order to test, debug, and repackage Android apps as BlackBerry 10 compatible.bar files. These items include the following: A BlackBerry ID account A BlackBerry app repackaging tool A BlackBerry ID Signing token and Developer certificate A BlackBerry 10 device or the BlackBerry 10 Device Simulator A BlackBerry device debug token A BlackBerry World Vendor account Stages of the overall process The following diagram illustrates the overall process that you must follow before you can distribute your Android apps through the BlackBerry World storefront. Getting started 7

8 1. Register for a BlackBerry ID account on page 8 2. Install an app repackaging tool on page 9 3. BlackBerry tools for Android development on page Publish to BlackBerry World on page 63 Register for a BlackBerry ID account You must register for a BlackBerry ID account before you begin repackaging your Android apps as.bar files for BlackBerry 10 devices. You can use your BlackBerry ID account to: Create a BlackBerry ID token and a developer certificate to use with the BlackBerry Signing Authority Tool. These two items allow you to test, debug, repackage, and sign all of your Android apps. Login to the BlackBerry World vendor portal, where you can create and manage your account to distribute your signed digital goods. Follow these steps to register for a BlackBerry ID account: 1. Go to BlackBerry ID - Signup website. 2. Enter your information on the form. 3. Click Submit. Android apps on the BlackBerry Runtime for Android apps Before you get started repackaging your Android apps as.bar files that run on BlackBerry 10 devices, review the following information so you understand the differences between running apps on an Android device and running apps on the BlackBerry Runtime for Android. If you're developing for BlackBerry 10 OS version 10.3 or , you can use the BlackBerry Runtime for Android apps to run Android Jelly Bean 4.3 apps. If you're developing for a previous version of BlackBerry 10 OS, use Android Gingerbread Note: For information on repackaging an Android app for the BlackBerry PlayBook, see Plug-in Repackaging Tool for BlackBerry PlayBook. UI differences in repackaged Android apps Here are some of the differences that you can expect to see in your Android app's UI after it has been repackaged to run on a BlackBerry 10 device. Getting started 8

9 UI characteristic Navigation What you can expect Since most BlackBerry 10 devices do not have a Back key, users must tap the Back button that appears at the bottom of the screen to return to a previous screen. Note: A navigation toolbar with a Back button appears at the bottom of most Android apps. For apps that use full-screen mode (for example, games), users can swipe down from the top of the screen to display the navigation toolbar. App menu Notifications Since most BlackBerry 10 devices do not have a Menu key, users must swipe down from the top of the screen to display the app menu. App notifications, including the status of activities that are occurring in the background (for example, music that's playing, or files that are downloading), appear in the BlackBerry Hub. Designing for specific BlackBerry 10 devices You can optimize the layout of your app's UI components to accommodate the characteristics of a specific BlackBerry 10 device. Information on characteristics such as screen size, aspect ratio, display type, and screen density can be found using the links provided below. For information on specific BlackBerry 10 device screen characteristics, see Different screen sizes. For information on the UI framework, and the visual style of the BlackBerry 10 OS, see UI Guidelines for BlackBerry 10. Install an app repackaging tool You can install any one of the tools shown below to repackage your app as a.bar file that you can submit for distribution through the BlackBerry World storefront. Repackaging tool The BlackBerry Plug-in for Android Studio Description The Android Studio plug-in allows you to: Create a BlackBerry ID token and developer certificate. Getting started 9

10 Repackaging tool Description Use the BlackBerry ADB Proxy Manager to run and debug your Android app on a BlackBerry device. Verify that your Android app is compatible with the BlackBerry Runtime. Repackage your Android app as a BlackBerry.bar file. Use Android Studio to sign your Android app. Get the BlackBerry Plug-in for Android Studio. The BlackBerry Plug-in for Android Development Tools for Eclipse The BlackBerry Plug-in for Android Development Tools for Eclipse allows you to: Create a BlackBerry ID token and developer certificate. Use the BlackBerry ADB Proxy Manager to run and debug your Android app on a BlackBerry device. Verify that your Android app is compatible with the BlackBerry Runtime. Repackage your Android app as a BlackBerry.bar file. Use Eclipse to sign your Android app. Get started with the BlackBerry Plug-in for Android Development Tools for Eclipse. The BlackBerry Command-line tools The command-line tools are a set of command-line utilities that can do everything that the above plug-ins do, but from a command-line prompt. You can also use the command-line tools from a point and click UI. Get started with the BlackBerry Command-line tools. Create a BlackBerry ID Signing token A BlackBerry ID Signing token and Developer certificate are used to sign your repackaged BlackBerry 10 apps. An app must be signed before it can be distributed through the BlackBerry World storefront. You must have a BlackBerry ID account to create a BlackBerry ID Signing token and Developer certificate. To register for a BlackBerry ID account and create a BlackBerry ID Signing token: 1. Go to the BlackBerry ID portal and do one of the following: Click the Don't have a BlackBerry ID? Create one link. Enter your BlackBerry ID account credentials and click Sign In. 2. Enter and confirm the password that you want to use to secure your BlackBerry ID Signing token. This password can also be used when you create your Developer certificate. Note: Many developers use their BlackBerry ID account password for their BlackBerry ID Signing token and Developer certificate. This can make those passwords easier to remember. If you forget the password for Getting started 10

11 your BlackBerry ID Signing token, it cannot be retrieved or reset for you. You must create another BlackBerry ID Signing token. 3. Accept the license agreement and click Get Token. 4. Download and save the BlackBerry ID keystore file. Note: The BlackBerry ID Signing token is included in a keystore file, called bbidtoken.csk, that's saved in your Downloads folder. The BlackBerry Signing Authority service uses your BlackBerry ID Signing token for authentication when you sign your app using the associated Developer certificate. Signing your app helps verify its integrity and authenticity to users and to the BlackBerry 10 OS. The BlackBerry APK Packager and the BlackBerry Signing Configuration wizard After you follow these instructions, an author.p12 file is created in the following folder: Windows XP: %HOMEPATH%\Local Settings\Application Data\Research In Motion Windows Vista, Windows 7, and Windows 8: %HOMEPATH%\AppData\Local\Research In Motion Mac OS: ~/Library/Research In Motion UNIX, Linux: ~/.rim You should protect your author.p12 file and its password. The BlackBerry APK Packager has a wizard, called the BlackBerry Signing Configuration, that you can use to create a BlackBerry ID Signing Token and a Developer certificate. To start the BlackBerry Signing Configuration wizard, shown to the right, click the Package button in the BlackBerry APK Packager dialog. Getting started 11

12 When the BlackBerry APK Packager does not find a BlackBerry ID Signing Token on your computer, the Confirmation dialog box shown to the right is displayed. Click Yes to start the BlackBerry Signing Configuration wizard to create a new BlackBerry ID Signing token and Developer certificate. Note: Your BlackBerry ID Signing token and Developer certificate are valid for one year. When they expire, you must create new ones. Set up your test environment You can use either a BlackBerry 10 device or a BlackBerry 10 Device Simulator to test your app. Either choice allows you to see how your app functions. The following sections discuss how to set up and configure each testing environment. Configure your BlackBerry 10 device Ensure that the BlackBerry 10 device that you're using to test your app has the latest version of the BlackBerry 10 OS installed. For more information on updating your BlackBerry 10 device, see BlackBerry Software Updates. After you've installed the latest BlackBerry 10 OS, you must enable Development Mode on your BlackBerry 10 device. To enable Development Mode on your device: 1. On the home screen, swipe down from the top of the screen and select Settings, or find the Settings app on your home screen. 2. Navigate to Security and Privacy > Development Mode. 3. Set the User Development Mode toggle button to On. 4. If you're prompted, enter the password for your device, and click OK. Open your Android project in your IDE, connect your BlackBerry 10 device to your computer with a USB cable, and you're ready to begin developing and repackaging your Android app for the BlackBerry Runtime. Install and configure a BlackBerry 10 Device Simulator When you don't have a BlackBerry 10 device to test your apps, you can use the BlackBerry 10 Device Simulator. The BlackBerry 10 Device Simulator is hosted inside of a virtual machine, which supports accelerated graphics, audio, and peripheral simulation. The BlackBerry 10 Device Simulator lets you test your BlackBerry 10 app and simulate the touch interface using your mouse. Download the BlackBerry 10 Device Simulator. Getting started 12

13 For more information on how to install and configure the simulator, see BlackBerry 10 Device Simulator. When your BlackBerry 10 Device Simulator has been installed and configured, open your Android project in your IDE, start the BlackBerry 10 Device Simulator, and you're ready to begin developing and repackaging your Android app for the BlackBerry Runtime. Related Links Register for a BlackBerry ID account on page 8 Create and deploy a device debug token on page 25 Adjust your Android app on page 13 Adjust your Android app Handling update notifications The BlackBerry World storefront prompts the app user when there are updates available for your app. You must remove any intents, update checks, or prompts for Google Play that may exist in your app code, as they may not work as expected in an app that has been ported to BlackBerry 10, which could lead to a negative user experience. Resizing your app icons The sizes of the app icons on BlackBerry 10 devices are different from the size of the app icons on Android devices. For more information on app icon sizes in relation to various device screen resolutions, see Application icons. For best results, you should create an appropriately sized icon for your app before you repackage it. The BlackBerry Runtime for Android apps allows you to support more than one BlackBerry device in a single release build (.bar file). This flexibility allows you to provide an ideally sized icon for each device supported by your app. Getting started 13

14 Trackball input The BlackBerry Classic smartphone comes with a trackpad (also known as a trackball or Optical Navigation Module) that provides a new method of input for your Android apps. The trackpad uses an infrared sensor to detect finger movements, which are then translated into directional input. Note: In the Android OS, a trackpad is known as a trackball. In this documentation, the terms trackpad and trackball both refer to the same Optical Navigation Module that is found on the BlackBerry Classic smartphone. Modes of user interaction Android supports two distinct modes of user interaction. The first mode, known as Touch mode, relies on the user having direct interaction with UI controls that respond to touch events. Touch mode is the typical way that users interact with all-touch devices that do not have a physical keyboard. Touch mode is automatically deactivated when the device receives input from any one of the following input devices: Trackball (or trackpad) Directional pad (D-pad) keys Getting started 14

15 Keyboard arrow keys There's no official term for the second mode, so we refer to it in this documentation as Non-Touch mode. When a device is in Non-Touch mode, its UI depends on focus. When a UI component can be configured to receive focus, and is therefore focusable, then its View can be set up to accept and handle input events. In Non-Touch mode, input focus is given to one View at a time. A View can change its appearance to show the user that it has focus. Android widgets use a highlight, which serves as visual feedback, to show when they gain focus. When a UI component and its View have focus, they can receive input events. However, the View may or may not handle the events it receives. The OS processes any events that the View does not consume. These unconsumed events may cause the focus to move to another View. This approach is how the OS handles the routine movement of focus in response to input. Some Views are focusable by default. For example, Android components such as the Button, ListView, and EditText are all focusable by default. For more information, see the Android View API reference. You can use the android.focusable attribute to make a UI component focusable. To support accessibility, you can use the AccessibilityNodeInfo class, which can also be used to set focus to UI components. Trackball events A Trackball event is a type of MotionEvent, which is an event that describes movements in terms of an action code and a set of axis values. The source class for these events is the SOURCE_CLASS_TRACKBALL, which is made up of related X and Y axes that can be retrieved using the getaxisvalue() method and axis constants. For example, to get the value of the x axis: // Use the constant AXIS_X as a parameter to get the // value of the x-axis of a motion event getaxisvalue(axis_x); For more information on these constants, see AXIS_X and AXIS_Y. The ACTION_MOVE constants represent all trackball movement values, which occur when users swipe their fingers across the trackball. The constants that represent the press gesture are the ACTION_DOWN and ACTION_UP constants. The OS processes any trackball events that are not consumed, and converts them into their equivalent D-pad key events. These newly generated D-pad key events are sent back to the View that currently has focus. The View interprets these D-pad key events as arrow key presses from an external keyboard. The events are delivered to the View as the KeyEvent parameter for the onkeyup() and onkeydown() event handlers. In a repackaged Android app, the BlackBerry 10 OS converts trackball events into D-pad key events that produce movements that match user expectations. Note: When an existing Android UI control that supports D-pad key events is extended into a custom control, this custom control inherits support for trackball events. However, when you completely customize a UI control, you must add support for navigation events where it makes sense. Getting started 15

16 For more information about Android user interface components, see View. Trackball in Android apps The guidelines for Android development suggest that support for keyboard navigation should be included in all apps. Keyboard navigation support makes the app useable with arrow keys when an external keyboard is available. Keyboard navigation is also a requirement for accessibility. For more information, see Implementing Accessibility. The default behavior of a View for the ontrackballevent() is to ignore it, which means that implementing keyboard navigation makes trackball navigation available as unconsumed trackball events. These unconsumed trackball events are reinjected into the View as D-pad key events. Most Views implement keyboard navigation and use it to provide trackball support. Alternatively, you can choose to override the ontrackballevent() and use it in your app. This approach exposes the raw trackball events with finer granularity than is available when using D-pad key events. This approach makes it possible to implement trackball-specific behaviors. For example, game control and scrolling are a couple of instances where this approach can be useful. The trackpad on BlackBerry Classic smartphones conforms to the Android input event architecture and behaves like an Android device with a trackball. Any Android app that supports the trackball works on BlackBerry Classic. As a minimum, an Android app that supports keyboard navigation automatically gains trackball support. Keyboard navigation does not harness the full potential of raw trackball events, but it does provide a functional trackball experience. Supporting keyboard navigation To support keyboard navigation: 1. Identify the Views in your app hierarchy that accept user interaction, and configure them to be focusable. For more information, see using android.focusable or setfocusable(). 2. Implement a visual highlight when focus is gained. For more information, see onfocuschanged(). 3. Handle D-pad key events for the View that has focus. Focus should stay with the current View. When D-pad key events are not handled, focus eventually moves to the next focusable View. Using the Trackball with a MapView control You can pan and scroll a map in an Android MapView control by using the trackball on the BlackBerry Classic smartphone. The MapView control: Getting started 16

17 Acquires focus when the user clicks on it with the trackball Controls the map position so that the user can pan or scroll the map (the user must use the touch screen for zooming or interacting with map markers) Displays a highlight when it's selected Releases its focus when the user clicks the Back button Getting started 17

18 Getting started 18

19 Plug-in and command-line tools Learn how to use the plug-in or command-line tools to test, debug, and repackage your Android apps for the BlackBerry 10 platform. System requirements Before you proceed, review the following system requirements to make sure that you have the minimum hardware and software components needed to repackage your.apk files as.bar files. Item Hardware Requirement Memory: 4 GB RAM or more Monitor resolution of 1024 x 768 or higher Intel Pentium 4 or AMD Athlon 2 GHz (or faster) 1 GB (or more) available hard disk space Software Eclipse (Luna) version 4.4 BlackBerry Plug-in for Android Development Tool Android SDK tools 23.0 Android API levels required by your apps Note: The maximum API level supported is Android 4.3 (API 18). Java Runtime Environment 1.8 (Java JRE 1.8) or Java SE JDK v1.8 Operating system Windows 7 (64 bit) Mac OS Mountain Lion Linux Ubuntu (32 bit) Virtual environment VMware Player to run the BlackBerry 10 Device Simulator on Windows VMware Fusion to run the BlackBerry 10 Device Simulator on Mac OS Plug-in and command-line tools 19

20 Check the compatibility of.apk files Performing a compatibility check allows you to verify that your Android app is compatible with the BlackBerry 10 OS. Note: Some of the Android SDK APIs are not supported, or are only partially supported, by the BlackBerry Runtime for Android apps. Therefore, not all.apk files are fully compatible with BlackBerry 10 devices. The 2.0 release version of the tools automatically checks the compatibility of your.apk files before trying to repackage them as.bar files. These tools help you assess the level of compatibility that your repackaged Android app has with the BlackBerry 10 OS. BlackBerry tools for Android development The BlackBerry tools for Android Development allow you to repackage your Android apps to run on BlackBerry 10 devices. Repackaging tool options You have the following options when choosing a tool to repackage your Android apps so they can run on BlackBerry 10 devices: BlackBerry Plug-in for Android Studio on page 21 BlackBerry Plug-in for Android Development Tools for Eclipse on page 31 BlackBerry command-line tools on page 42 Plug-in and command-line tools You can use the tools to check your Android apps for compatibility to the BlackBerry Runtime. The tools can be used to: Repackage your Android apps as.bar files. The.bar file format allows your Android apps to run on a BlackBerry 10 device. Debug and run your Android apps on a BlackBerry 10 device or BlackBerry 10 Device Simulator in Eclipse or Android Studio. Create and deploy (upload) a device debug token to your BlackBerry 10 device. A device debug token is required to run an unsigned.bar file, such as your repackaged Android app, on a BlackBerry 10 device. Sign your Android app before it's repackaged and submitted to BlackBerry World. New in this release The tools release provides the following updates: Plug-in and command-line tools 20

21 Support for Eclipse 4.4 (Luna) Support for Java 8 Support for Android Development Tools version Support for Android Studio BlackBerry Plug-in for Android Studio Make sure that you have the latest version of Android Studio and the BlackBerry Plug-in for Android Studio. Installing Android Studio For information about installing Android Studio, see Installing Android Studio. Install the BlackBerry Plug-in for Android Studio Before you begin, make sure that you have the Android Studio correctly installed and configured on your computer. There is an alternate way to install the plug-in on the Mac OS or Linux. You can extract the BlackBerry Plugin for Android Studio zip file directly to <your_android_studio_installation_folder>\plugins folder. 1. Download the BlackBerry Plug-in for Android Studio. 2. Open your project in Android Studio. 3. On the File menu, click Settings. Plug-in and command-line tools 21

22 4. Select Plug-ins from the navigation list on the left. 5. Click Install plugin from disk. Plug-in and command-line tools 22

23 6. Select the location of the zip file containing the BlackBerry Plug-in for Android Studio. 7. Click Apply. You must restart Android Studio for your changes to take effect. After Android Studio restarts, the BlackBerry ADB Proxy Manager icon appears in the main toolbar. The BlackBerry ADB Proxy Manager manages connections to the Android Debug Bridge (ADB). After you install the plug-in, you should verify that Android Studio has successfully installed the Android SDK required for your app. To verify that the required Android SDK (API level) for your app has been installed: 1. Start Android Studio. 2. On the Tools menu, click Android and then click SDK Manager. 3. Verify that the required Android SDK (API level) for your app has a Status of Installed. Note: The maximum API level supported is Android 4.3 (API 18). Plug-in and command-line tools 23

24 The BlackBerry ADB Proxy Manager The BlackBerry Android Device Bridge (ADB) Proxy Manager is added when you install the BlackBerry Plug-in. It displays all of your connected BlackBerry devices and simulators. You can use the BlackBerry ADB Proxy Manager to: Establish an ADB connection between your IDE and your BlackBerry 10 device or BlackBerry 10 Device Simulator Generate a device debug token and deploy it to your BlackBerry 10 device Using the BlackBerry ADB Proxy Manager in Android Studio 1. Connect your BlackBerry 10 device to your computer with a USB cable, or start the BlackBerry 10 Device Simulator. 2. Open your project in Android Studio. 3. Click to start the BlackBerry ADB Proxy Manager. 4. Click the start button to use your BlackBerry 10 device, or BlackBerry 10 Device Simulator with the BlackBerry ADB Proxy Manager. Plug-in and command-line tools 24

25 5. After your device or simulator has connected to the BlackBerry ADB Proxy Manager, run or debug your Android app. Disconnecting the BlackBerry ADB Proxy Manager When you're done working with your Android app, click the stop button to disconnect your device or simulator from the BlackBerry ADB Proxy Manager. Create and deploy a device debug token A device debug token allows you to deploy and debug an unsigned Android app on your BlackBerry 10 device. You don't need a device debug token when you're using the BlackBerry 10 Device Simulator to test and debug your Android apps. For more information, see the BlackBerry 10 Simulator Documentation. Before you begin testing, see Getting started on page 7. Note: You must Create a BlackBerry ID Signing token on page 10 and Developer certificate before you can test and debug your Android app on a BlackBerry 10 device. Plug-in and command-line tools 25

26 When you have a BlackBerry ID Signing token and Developer certificate configured, you can connect a BlackBerry device that doesn't contain a device debug token and use the BlackBerry ADB Proxy Manager to create a new device debug token. Follow these steps to create and deploy a device debug token: 1. Enable Development Mode on your BlackBerry 10 device. For more information, see Set up your test environment on page Connect your BlackBerry 10 device to your computer with a USB cable. 3. Open your project in your IDE. 4. Click on the main toolbar to start the BlackBerry ADB Proxy Manager. In the BlackBerry ADB Proxy Manager, when you try to start a BlackBerry 10 device that doesn't have a device debug token, the Missing Debug Token message appears in the Status column. A dialog box that begins the process of creating a device debug token is displayed. 5. In the Confirmation dialog box, click Yes. Plug-in and command-line tools 26

27 6. In the BlackBerry Debug Token Request dialog box, click Deploy Debug Token. 7. In the Password Prompt dialog box, enter your BlackBerry ID Signing token password and click OK. For more information, see Create a BlackBerry ID Signing token on page 10. The new device debug token is created and deployed (uploaded) to your BlackBerry 10 device. Plug-in and command-line tools 27

28 After you've created and deployed the device debug token, start your BlackBerry 10 device in the BlackBerry ADB Proxy Manager. Repackage an app using the BlackBerry Plug-in for Android Studio The BlackBerry Plug-in for Android Studio allows you to repackage your.apk files as BlackBerry compatible.bar files in Android Studio. Plug-in and command-line tools 28

29 Note: Your device must be connected to your computer with a USB cable, and it must also be in Development Mode to perform the repackaging operations. For more information on how to enable Development Mode on your device, see Set up your test environment on page 12. To repackage your.apk files: 1. Open your Android project in Android Studio. 2. On the main toolbar, select Build > Package APK to BAR. 3. In the BlackBerry APK Packager dialog box, select the Sign check box and click Package. Note: You can generate an unsigned.bar file for testing and debugging purposes. Remove the check from the Sign check box and click Package. 4. Enter your password in the Password Prompt dialog box and click OK to begin the repackaging process. Plug-in and command-line tools 29

30 The BlackBerry APK Packager repackages your.apk file as a signed.bar file. Note: When you generate a.bar file, you can select the Deploy check box and the BlackBerry APK Packager automatically deploys it to a BlackBerry device. Plug-in and command-line tools 30

31 If your Android app was previously signed, you must repackage and sign it every time you make revisions or updates to it. Otherwise, the BlackBerry World portal will reject it. Signing your app is not required until you're ready to submit it to BlackBerry World. BlackBerry Plug-in for Android Development Tools for Eclipse Before you begin: Before you install the BlackBerry Plug-in for Android Development Tools for Eclipse, make sure that you have: Eclipse (Luna) version 4.4 for Windows (or Cocoa 32 for Mac OS X) The Android SDK The latest version of the Android Development Tools installed on your computer These items can be downloaded separately, or together in the Android SDK ADT bundle. For more information on how to install and configure each of the above items, see Items required for the BlackBerry Plug-in for Android Development Tools for Eclipse on page 36. Install the BlackBerry Plug-in 1. Start Eclipse. 2. On the Help menu, click Install New Software 3. Click Add to add a new software site. 4. In the Name field, enter BlackBerry Plug-in for Android Development Tools. 5. In the Location field, enter 6. Click OK. 7. In the Install window, select the BlackBerry Eclipse Plugin for Android Development check box, and also select the check boxes for the subitems under it. 8. Click Next. If you don't have the ADT Plug-in installed on your computer, the newest version of the plug-in is installed. 9. Complete the instructions in the Review Licenses window. 10.Click Finish. After you finish: After you install the plug-in, you should verify that the installation has successfully located the Android SDK in the plug-in preferences. Verify the installation of the plug-in 1. Start Eclipse. 2. On the Window menu, click Preferences. 3. Expand Android. 4. Verify that the path shown in the SDK location field matches the location of your Android SDK installation folder. Plug-in and command-line tools 31

32 5. Verify that all the APIs that your app requires are installed correctly in Eclipse. a. On the Window menu, click Android SDK Manager. b. In the Packages section for each of the APIs that your app requires, verify that the status is Installed. Note: The maximum API level supported is Android 4.3 (API 18). The BlackBerry ADB Proxy Manager The BlackBerry Android Device Bridge (ADB) Proxy Manager is added when you install the BlackBerry Plug-in. It displays all of your connected BlackBerry devices and simulators. You can use the BlackBerry ADB Proxy Manager to: Establish an ADB connection between your IDE and your BlackBerry 10 device or BlackBerry 10 Device Simulator Generate a device debug token and deploy it to your BlackBerry 10 device Use the BlackBerry ADB Proxy Manager in Eclipse 1. Connect your BlackBerry 10 device to your computer with a USB cable or start the BlackBerry 10 Device Simulator. 2. Start Eclipse. 3. Start the BlackBerry ADB Proxy Manager by clicking on the Tools menu. Plug-in and command-line tools 32

33 4. In the BlackBerry ADB Proxy Manager, click the start button to use your BlackBerry 10 device or BlackBerry 10 Device Simulator with the BlackBerry ADB Proxy Manager. 5. After the device or simulator connects to the BlackBerry ADB Proxy Manager, you can run or debug your Android app. 6. When you're done working with your Android app, click the stop button to disconnect your device or simulator from the BlackBerry ADB Proxy Manager. Create and deploy a device debug token A device debug token allows you to deploy and debug an unsigned Android app on your BlackBerry 10 device. You don't need a device debug token when you're using the BlackBerry 10 Device Simulator to test and debug your Android apps. For more information, see the BlackBerry 10 Simulator Documentation. Before you begin testing, see Getting started on page 7. Plug-in and command-line tools 33

34 Note: You must Create a BlackBerry ID Signing token on page 10 and Developer certificate before you can test and debug your Android app on a BlackBerry 10 device. When you have a BlackBerry ID Signing token and Developer certificate configured, you can connect a BlackBerry device that doesn't contain a device debug token and use the BlackBerry ADB Proxy Manager to create a new device debug token. Follow these steps to create and deploy a device debug token: 1. Enable Development Mode on your BlackBerry 10 device. For more information, see Set up your test environment on page Connect your BlackBerry 10 device to your computer with a USB cable. 3. Open your project in your IDE. 4. Click on the main toolbar to start the BlackBerry ADB Proxy Manager. In the BlackBerry ADB Proxy Manager, when you try to start a BlackBerry 10 device that doesn't have a device debug token, the Missing Debug Token message appears in the Status column. A dialog box that begins the process of creating a device debug token is displayed. 5. In the Confirmation dialog box, click Yes. Plug-in and command-line tools 34

35 6. In the BlackBerry Debug Token Request dialog box, click Deploy Debug Token. 7. In the Password Prompt dialog box, enter your BlackBerry ID Signing token password and click OK. For more information, see Create a BlackBerry ID Signing token on page 10. The new device debug token is created and deployed (uploaded) to your BlackBerry 10 device. Plug-in and command-line tools 35

36 After you've created and deployed the device debug token, start your BlackBerry 10 device in the BlackBerry ADB Proxy Manager. Items required for the BlackBerry Plug-in for Android Development Tools for Eclipse You must install Eclipse, the Android SDK, and the Android Development Tools (ADT) before you can install the BlackBerry Plug-in for Android Development Tools for Eclipse. Plug-in and command-line tools 36

37 Note: You can install Eclipse, the Android SDK, and the Android Development Tools all in one step by using the Android SDK ADT bundle installer. The Android SDK ADT bundle is available for several platforms, including Windows 32-bit and 64-bit, Mac OS X 64-bit only, and Linux 32-bit and 64-bit. Configure the Android SDK ADT bundle After you install the Android SDK ADT bundle, follow these steps to make sure it's configured correctly: 1. Start Eclipse. The version of Eclipse included in the ADT bundle already has the Android Development Tools plug-in installed. 2. Navigate to Window > Android SDK Manager. 3. Verify that Android API levels required by your app are installed. If they are not installed, select the check box for each SDK Platform required by your app, and click Install. Note: The maximum API level supported is Android 4.3 (API 18). After you install and configure the Android SDK ADT bundle, you can proceed to install the BlackBerry Plug-in for Android Development Tools for Eclipse. The instructions provided below are only needed if you're installing the above items separately. Proceed to the instructions on how to install the Eclipse Plug-in for Android Development Tools. Install Eclipse version 4.4 (Luna) Visit to download and install Eclipse version 4.4 (Luna). If you're using a Mac, download Eclipse for Mac OS X (Cocoa 32). Install the Android SDK The command-line and plug-in repackaging tools require that you have the Android SDK installed on your computer. 1. Download the Android SDK and follow the installation instructions. 2. In Eclipse, navigate to Window > Android SDK Manager. 3. In the Packages section, select the following packages to install: Android SDK platform-tools Android SDK Build-tools The SDK Platform for all Android API levels required by your apps Note: The maximum API level supported is Android 4.3 (API 18). 4. Click the Install packages button, and accept any license agreements to install the selected packages. 5. Restart Eclipse if necessary. Install the Android Development Tools Plug-in for Eclipse Download the Android Development Tools (ADT) file, and following the installation instructions provided there. Plug-in and command-line tools 37

38 Repackage an app using the BlackBerry Plug-in for Android Development Tools for Eclipse The BlackBerry Plug-in for Android Development Tools for Eclipse allows you to repackage your.apk files as BlackBerry compatible.bar files from within the Android Development Tools for Eclipse IDE. Note: Your device must be connected to your computer with a USB cable, and it must also be in Development Mode to perform the above repackaging operations. For more information on how to enable Development Mode on your device, see Set up your test environment on page 12. To repackage your.apk files: 1. Open your Android project in the Android Development Tools IDE. 2. In the Project Explorer view, right-click your project and select BlackBerry Tools > Add BlackBerry Verifying Builder to Project to automatically perform a compatibility test on your.apk file during the Plug-in and command-line tools 38

39 repackaging process. Plug-in and command-line tools 39

40 3. Right-click your project and select BlackBerry Tools > Export Application Package for BlackBerry to begin the repackaging process. 4. In the BlackBerry APK Packager dialog box, enter the path to your.apk file and the path to where you want to save the.bar file that's generated. Select the Sign check box to sign your.bar file, and click Package to begin the repackaging process. Note: Do not select the Sign check box when you're just debugging your app. You can test and debug an unsigned.bar file by using a device debug token. For more information, see Create and deploy a device debug token on page 25. Plug-in and command-line tools 40

41 5. Enter your BlackBerry ID Signing token password and click OK to begin the repackaging process. The BlackBerry APK Packager repackages your.apk file as a.bar file. Note: When you generate a.bar file, you can select the Deploy check box and the BlackBerry APK Packager automatically deploys the.bar file to a connected BlackBerry 10 device. Plug-in and command-line tools 41

42 You must repackage and sign your Android app every time you make revisions or updates to it. BlackBerry command-line tools The BlackBerry Tools SDK for Android apps provides a set of command-line tools that you can use to test, sign, and repackage your Android.apk file as a BlackBerry 10 compatible.bar file. This section has information about using the command-line tools to test, sign, and repackage your Android apps so that they can be submitted to BlackBerry World. Install the Command-line tools for Android apps 1. Download the Command-line tools for Android Apps. 2. Extract the contents of the BlackBerry command-line tools.zip file to a folder on your computer. Note: All of the command-line tools can be started using their.exe files. Record the location of where you extracted the command-line tool files so you can find these.exe files when needed. Plug-in and command-line tools 42

43 Next steps Make sure you've completed the following tasks before trying to use the command-line tools found in the BlackBerry Tools SDK for Android apps. 1. Register for a BlackBerry ID account on page Create a BlackBerry ID Signing token on page Adjust your Android app on page 13. Repackaging with the BlackBerry APK Packager tool The BlackBerry APK Packager repackages your.apk file as a BlackBerry 10 compatible.bar file. During the repackaging process, the BlackBerry APK Packager performs a compatibility test on your.apk file to determine how compatible your repackaged Android app is with the BlackBerry 10 OS. You can specify a warning level to stop the repackaging process for your.apk file when it generates a warning at the specified level or higher. These warnings are all saved in a.wrn file that's located in the target folder location that you specified. The packager wizard can also sign your.bar file so it can be distributed through the BlackBerry World storefront. The repackaging process The BlackBerry APK Packager creates a.bar file that contains all of the resources that your Android app needs to run on a BlackBerry 10 device. To repackage an.apk file as a.bar file: 1. Go to where you extracted the BlackBerry Command-line tool files. 2. Start the BlackBerry APK Packager.exe application. Plug-in and command-line tools 43

44 3. Browse to an.apk file. 4. Enter the path, or Browse, to a target folder where you want to save the generated repackaging files. 5. Select the Sign check box. 6. Select the Deploy check box. 7. Click Package. 8. When the repackaging operation has successfully completed, a BlackBerry Deploy dialog box appears. Select your device, and enter your device password. Plug-in and command-line tools 44

45 9. Click Install to deploy the generated.bar file onto the selected BlackBerry 10 device. The BlackBerry APK Packager generates a number of files, which it adds to your app's.bar file. The following table shows the files with a description for each file: File app icon manifest file Description The app icon, which is used as the main point of entry to the app from the home screen of a BlackBerry 10 device. The BlackBerry APK Packager extracts the icon from the.apk file, and repackages it using a format that's compatible with the BlackBerry 10 OS. The manifest file defines and provides essential information about the app to the BlackBerry 10 OS. The BlackBerry APK Packager maps the attributes from the AndroidManifest.xml file included in the.apk file, to a manifest file. The BlackBerry APK Packager also generates a.wrn file that contains the results of the compatibility test that the packager ran before it repackaged your.apk file. This file and the.bar file should be in the same folder that you set as the target folder. Plug-in and command-line tools 45

46 Customizing your repackaging options You can use the Advanced Settings in the BlackBerry APK Packager dialog box to customize your app with the following repackaging options: Specify a minimum device OS version for your app. Choose a custom icon for your app. Add a custom manifest file. Specify an Android configuration file. Specify a Launchable Activity Index for the app. Select a custom Author and Author ID using the BlackBerry Debug Token Request dialog box. Related Links Publish to BlackBerry World on page 63 Learn how to submit your repackaged Android apps to BlackBerry World. Testing a repackaged app on a BlackBerry 10 device There's no better way to test an app than loading it on a BlackBerry 10 device. Your apps can be repackaged as unsigned.bar files, which are normally used for testing and debugging. Signing a.bar file is a security measure that's required only when you're ready to submit your app for distribution through the BlackBerry World storefront. Plug-in and command-line tools 46

47 For more information, see Publish to BlackBerry World on page 63. Create and deploy a device debug token You must create device debug token and deploy it to your BlackBerry 10 device before you can test and debug an unsigned.bar file. When you have a BlackBerry ID account, a BlackBerry ID Signing token, and a Developer certificate you can use these items to generate a device debug token. Follow these steps to create and deploy a debug token: 1. Enable Development Mode on your device. For more information on configuring your BlackBerry 10 device for testing, see Set up your test environment on page Connect your BlackBerry 10 device to your computer with a USB cable. 3. Start the BlackBerry ADB Proxy Manager. Go to the directory where you extracted the BlackBerry Command-line tools. Start the BlackBerry ADB Proxy Manager.exe application. In the BlackBerry ADB Proxy Manager, when you try to start a device that doesn't have a device debug token, the Missing Debug Token message appears in the Status column. A dialog box that begins the process of creating a device debug token is displayed. 4. In the Confirmation dialog box, click Yes. Plug-in and command-line tools 47

48 5. In the BlackBerry Debug Token Request dialog box, click Deploy Debug Token. 6. In the Password Prompt dialog box, enter your BlackBerry ID Signing token password and click OK. For more information, see Create a BlackBerry ID Signing token on page 10. The new debug token is created and deployed (uploaded) to your BlackBerry 10 device. Plug-in and command-line tools 48

49 After you've created and deployed the device debug token, start your device in the BlackBerry ADB Proxy Manager. Note: A debug token is valid for 30 days. When that token expires, the BlackBerry 10 OS no longer allows unsigned apps that rely on that token to run. Plug-in and command-line tools 49

50 Plug-in and command-line tools 50

51 Porting to BlackBerry 10 OS Learn how to port your Adobe AIR and Android apps to run on BlackBerry 10 devices. You have two options for porting your Android apps to the BlackBerry 10 OS. You can choose to take your existing Android.apk files, and repackage them as.bar files that run on BlackBerry 10 devices, or you can develop your app from scratch using the BlackBerry 10 Native SDK. Which option you choose can depend on many factors, including your app's functionality when it has been repackaged as a BlackBerry 10 app. Before deciding which option to choose, you can use our repackaging tools to run a compatibility test on your.apk file. This test allows you to assess the level of compatibility that your Android app has to the BlackBerry Runtime. Port your Adobe AIR app If you develop apps using Adobe AIR, you can repackage your existing BlackBerry 10 Adobe AIR apps as Android apps. Then you can use our repackaging tools to port those Android apps to BlackBerry 10. The BlackBerry Runtime for Android apps is available on the BlackBerry 10 OS version or later. Note: The BlackBerry/QNX Native Extensions that are supported in the BlackBerry 10 SDK for Adobe AIR are not available in the Google Android SDK. If your app uses Adobe AIR 3.7 and Adobe Flex 4.5 or earlier, you must include the captive runtime in your app. Note: As of Adobe AIR 3.8 and Adobe Flex 4.6, the Adobe AIR captive runtime is packaged in the.apk file by default. Removing the air. prefix from your app Package-Name on page 51 Exporting an.apk file with Adobe Flash Builder on page 52 Exporting an.apk file with FDT PowerFlasher on page 58 Repackage your.apk file for BlackBerry 10 on page 60 Removing the air. prefix from your app Package-Name You must use the same signing key and package name when you want to update one of your existing apps on BlackBerry World. Using the same signing key and package name avoids having your update rejected by the BlackBerry World portal. For more information on this error, see Error "File bundle (your_name) has been rejected.". Repackaging an Adobe AIR app often causes an air. prefix to be added to its.bar file Package-Name attribute. The air. prefix makes it appear as though your update is a new app. The reason your app appears Porting to BlackBerry 10 OS 51

52 to be a new app is because it has a different Package-Name than the original app, which would not have had the air. prefix in it. When an app with a new signing key or Package-Name is posted to BlackBerry World, it's treated by the system as an entirely new app. This issue can cause problems with an app update because the seemingly new app appears on users devices with a duplicate icon of the original app. The duplicate icon makes it appear to users that the app has been installed twice. Also, the seemingly new app does not have access to any data that the original app had previously saved. To avoid this issue, the air. prefix must be removed from the Package-Name attribute of your app's.bar file when repackaging your app for BlackBerry World. When the air. prefix has been removed the app continues to have the same name as the original that was registered with BlackBerry World and can be updated without issue. Before you begin 1. Download the latest Adobe AIR SDK. 2. Extract the Adobe AIR SDK to a new folder on your computer. 3. Create an environment variable called AIR_NOANDROIDFLAIR, set its value to true. This environment variable helps you control when the air. prefix is added to your repackaged Adobe AIR files. Note: The value of the AIR_NOANDROIDFLAIR variable is case-sensitive, therefore the variable name must all be in uppercase, and its value of true must all be in lowercase. Remove the AIR_NOANDROIDFLAIR environment variable, or set it to false before you repackage an update to an existing Adobe AIR app for submission to the Google or Apple app stores. Performing one of the above actions ensures that the air. prefix is present in those updates. After you've completed the above instructions, you are ready to export your Adobe AIR app as an.apk file, which can then be repackaged as a.bar file. If you are using FDT PowerFlasher, proceed to Exporting an.apk file with FDT PowerFlasher on page 58. Exporting an.apk file with Adobe Flash Builder Top Select the instructions below that apply to the specific version of the Adobe AIR SDK that you're using. These instructions guide you through the process of removing the air. prefix from an app update before it's repackaged as a.bar file, and submitted to BlackBerry World. Using Flash Builder with Adobe AIR SDK before 3.8 The steps in this section should be used only when you want to continue using a version of the Adobe AIR SDK before version 3.8 in Flash Builder. The compilation of your SWF files can still be done using your existing version of the Adobe AIR SDK. 1. Start Flash Builder. Porting to BlackBerry 10 OS 52

53 2. Right-click your project in Flash Builder, select Export. 3. Expand the Flash Builder folder and select Release Build. 4. Click Next. 5. In the Export Release Build dialog box, in the Target platforms section, select Google Android as the only Target Platform. Porting to BlackBerry 10 OS 53

54 6. In the Export section, select Keep bin-release-temp folder. Porting to BlackBerry 10 OS 54

55 7. Click Next. 8. Click Cancel to end the process. The process is stopped because only the files that are created in the binrelease-temp folder that is displayed in your Adobe AIR project are required. The bin-release-temp folder contains the -app.xml, bar-descriptor.xml, and the.swf files for your app. 9. Copy the above files from the bin-release-temp folder to a new folder on your computer, and note the new folder's location. 10.Open a command prompt, and navigate to the new folder that you created in the previous step. 11.Update the following command parameters so they match your paths, password, and app name. java.exe -jar "PATH_WHERE_YOU_UNZIPPED_LATEST_AIR_SDK\lib\adt.jar" -package -target apk-captive-runtime -storetype pkcs12 -keystore "PATH_TO_YOUR\AndroidCert.p12" -storepass yourandroidcertpassword YourApp.apk YourApp-app.xml YourApp.swf bar-descriptor.xml 12.Open a command prompt screen, enter the updated command from above into the command prompt. The above command creates an.apk file for your Adobe AIR app. Proceed to Repackage your.apk file for BlackBerry 10 on page 60. Using Flash Builder with Adobe AIR SDK 3.8 or later 1. Start Flash Builder. 2. Right click on your project in Flash Builder, click Export. Porting to BlackBerry 10 OS 55

56 3. Expand the Flash Builder folder and select Release Build. 4. Click Next. 5. In the Export Release Build dialog box, in the Target platforms section, select Google Android as the only Target Platform. Porting to BlackBerry 10 OS 56

57 6. In the Export section, select Keep bin-release-temp folder. Porting to BlackBerry 10 OS 57

58 7. Select Keep bin-release-temp folder. 8. Click Next. 9. Select Export app with captive runtime. 10.Click Finish. Exporting an.apk file with FDT PowerFlasher Top To use the FDT IDE to export your Adobe AIR app as an.apk file: 1. Open your app in FDT PowerFlasher. 2. Choose Project > Properties. 3. In the Properties dialog box, from the left navigation menu, select Android. Porting to BlackBerry 10 OS 58

59 4. Select the Build tab. 5. Select or create your app descriptor file, and your app's SWF file. 6. Select the Deploy tab. 7. In Application Store settings, select Export app with captive runtime. 8. In Export Application, set the Deploy Location field. This value is the path to where you want to save the.apk file that's created. Porting to BlackBerry 10 OS 59

60 9. Click Export Application. 10.Click OK to close the dialog box. When FDT has finished compiling and repackaging your app as an.apk file, a dialog box is displayed telling you that the operation was successful. Repackage your.apk file for BlackBerry 10 Top Your app's.apk file must be repackaged as a.bar file before it can run on the BlackBerry 10 OS. Your app's.apk file must also be checked to verify that the air. prefix has been removed. Performing these actions prepares your app for submission to the BlackBerry World portal, and ensures that it can be updated there when needed. Follow these instructions to repackage your.apk file as a.bar file, and check for the air. prefix: 1. Install an app repackaging tool on page 9 to repackage your.apk file as a.bar file. 2. Open your app's new.bar file with the same tool you used to create it. For example, Android Studio. 3. Verify that the Package-Name attribute in the \META-INF\manifest.mf file does not contain the air. prefix. Porting to BlackBerry 10 OS 60