Building and Testing Your Hybrid App

Introduction

To build and test a hybrid app that uses the Amazon WebView API, you must set up your development environment. This includes:

  • The Android SDK and any of its requirements for your development system.
    Note: To support Amazon WebView you must install the API level 17 SDK package.
  • The Java Development Kit.

It is also useful to have an integrated development environment installed such as Eclipse.

For information about setting up your environment for Kindle Fire development, see Setting Up Your Development Environment.


Downloading the Amazon WebView SDK

Before configuring your project, download the Amazon WebView API. By downloading the SDK, you agree to our Program Materials License Agreement. Extract the contents of the downloaded zip file to a location of your choice.


Developing With Amazon WebView

Amazon WebView (AWV) provides the AmazonWebKitFactories factory class to facilitate WebView creation. If the device on which the app is installed does not support AWV, you can choose to allow AWV to create the WebView using the Android WebView components.

Note: In order for this creation to happen, you must import and build the awv_android_factory.jar into your app.

To use AWV, you must do the following:


Configuring Your Project in Eclipse

To configure Eclipse to use the Amazon WebView API, do the following:

  1. In the Eclipse IDE, create or navigate to your Android project.
  2. Open the project properties; for example, right-click the root folder for the project, and then click Properties.
  3. In the dialog box, click Android.
  4. Under Project Build Target, select a build target of your choosing.
  5. Click Java Build Path.
  6. On the Libraries tab, click Add External JARs.
  7. Navigate to where you extracted the contents of the downloaded awv_api.zip file.
  8. Select the awv_interface.jar file for the Amazon WebView API and click Open.
  9. Click the Order and Export tab.
  10. Select export check box next to the awv_interface.jar file.

    Important: You must select the 'export' check box to ensure the classes in the awv_interface.jar are built into your application. The awv_interface.jar contains the implementation of the AmazonWebKitFactories class, which must be present to load the shared Amazon WebView library on the device.

  11. Click OK.

To add optional support for Kindle Fire tablets (1st and 2nd Gen) and other Android devices, do the following:

  1. In the Eclipse IDE, create or navigate to your Android project.
  2. Open the project properties; for example, right-click the root folder for the project, and then click Properties.
  3. In the dialog box, click Android.
  4. Under Project Build Target, select a build target of your choosing.
  5. Click Java Build Path.
  6. On the Libraries tab, click Add External JARs.
  7. Navigate to where you extracted the contents of the downloaded awv_api.zip file.
  8. Select the awv_android_factory.jar file for the Amazon WebView API and click Open.
  9. Click the Order and Export tab.
  10. Select export check box next to the awv_android_factory.jar file.

    Important: You must select the 'export' check box to ensure the classes in the awv_android_factory.jar are built into your application.

  11. Click OK.

Configuring Your Project from the Command Line

To configure the Amazon WebView API from the command line, do the following:

  1. Run a command such as the following to create a new project. The following example creates a project that targets Android API level 17 with an activity named AmazonWebViewActivity and package name com.example.amazon.amazonwebview. For <path>, specify where you want to create the project.
    android create project --path <path> --target android-17 --activity AmazonWebViewActivity --package com.example.amazon.amazonwebview
  2. Navigate to where you extracted the contents of the awv_api.zip file.
  3. Copy the awv_interface.jar file to your project's libs directory.
    IMPORTANT: The awv_interface.jar contains the implementation of the AmazonWebKitFactories class, which must be present to load the shared Amazon WebView library on the device.
  4. To build your project, assuming that you have already updated your AndroidManifest.xml, run the following command from the root directory for your project:
                                       
    ant debug
    

To add optional support for Kindle Fire tablets (1st and 2nd Gen) and other Android devices, do the following:

  1. Navigate to where you extracted the contents of the awv_api.zip file.
  2. Copy the awv_interface.jar file to your project's libs directory.

Make sure that you take similar steps to configure the projects that test your Amazon WebView app.


Updating the AndroidManifest.xml File

Before building your app, in the AndroidManifest.xml file, do the following:

  1. Request android.permission.INTERNET and other permissions as you would when using Android WebView.
  2. Add several <service ...> lines to the section of the AndroidManifest.xml file to create the processes required by the Chromium rendering engine.

For example:

                                    <?xml version= "1.0" encoding= "utf-8" ?>
                                    <manifest xmlns:android="http://schemas.android.com/apk/res/android"
                                      package ="com.example.android.myapp" >
                                      ...
                                      <application>
                                        <uses-library android:name="com.amazon.webview" android:required="false"/>

                                        	<service android:name="org.chromium.content.app.SandboxedProcessService0" android:process=":sandboxed_process0"
												 android:permission="org.chromium.content_shell.permission.SANDBOX" android:exported="false" />
                                            <service android:name="org.chromium.content.app.SandboxedProcessService1" android:process=":sandboxed_process1"
												 android:permission="org.chromium.content_shell.permission.SANDBOX" android:exported="false" />
                                            <service android:name="org.chromium.content.app.SandboxedProcessService2" android:process=":sandboxed_process2"
												 android:permission="org.chromium.content_shell.permission.SANDBOX" android:exported="false" />
                                            <service android:name="org.chromium.content.app.SandboxedProcessService3" android:process=":sandboxed_process3"
												 android:permission="org.chromium.content_shell.permission.SANDBOX" android:exported="false" />
                                            <service android:name="org.chromium.content.app.SandboxedProcessService4" android:process=":sandboxed_process4"
												 android:permission="org.chromium.content_shell.permission.SANDBOX" android:exported="false" />
                                            <service android:name="org.chromium.content.app.SandboxedProcessService5" android:process=":sandboxed_process5"
												 android:permission="org.chromium.content_shell.permission.SANDBOX" android:exported="false" />

                                        ...
                                      </application>
                                    </manifest>
                                

If you are using the optional support for non third-generation Kindle Fire tablets and other Android devices, you must also add a <uses-library ...> element to the section of your AndroidManifest.xml file to declare the use of the Amazon WebView shared library. See the full example below.

                                      ...
                                      <application>
                                        <uses-library android:name="com.amazon.webview" android:required="false"/>
                                      ...
 
                                      </application>
                                    </manifest>
                                

Initialize the Amazon WebView Factory

Initialize the Amazon WebView factory once when your app launches. For a simple app, put the code in the main activity's onCreate() method, as this provides the activity context needed by the initialize call.

import com.amazon.android.webkit.AmazonWebKitFactories;
import com.amazon.android.webkit.AmazonWebKitFactory;
import com.amazon.android.webkit.AmazonWebView;
    ...


    private static boolean sFactoryInit = false;
    private AmazonWebKitFactory factory = null;
    protected void onCreate(Bundle savedInstanceState) {
        ...

        if (!sFactoryInit) {
            factory = AmazonWebKitFactories.getDefaultFactory();
            if (factory.isRenderProcess(this)) {
                return; // Do nothing if this is on render process
            }
            factory.initialize(this.getApplicationContext());

            // factory configuration is done here, for example:
            factory.getCookieManager().setAcceptCookie(true);

            sFactoryInit = true;
        } else {
            factory = AmazonWebKitFactories.getDefaultFactory();
        }
        ...
    }

Note: If your app has more than one activity that uses the AmazonWebView object, you must provide the application context to the factory. Be sure to pass context.getApplicationContext() as the parameter to factory.initialize(). Do not pass the activity context.

You can use the code above in the Application.onCreate() method, or you can initialize the factory from any activity. However, you must only initialize the Amazon WebView factory once, even if your app has multiple activities or multiple processes.


Replacing WebView with Amazon WebView

When you migrate an app to the Amazon WebView API, replace all references to classes in the android.webkit namespace with the equivalent classes in the com.amazon.android.webkit. For example, replace all android.webkit.WebView classes with the equivalent com.amazon.android.webkit.AmazonWebView versions as shown below.


WebView Declared as a Layout in Your App Resources

You must call factory.initializeWebView() before using the WebView object. For example, if your current implementation declares the WebView object as a resource in the app layout, the code looks something like this:

import android.webkit.WebView;

WebView mWebView;

mWebView = (WebView) findViewById(R.id.myWebView);
mWebView.getSettings().setJavaScriptEnabled(true);

... 

To use the Amazon WebView API, modify the code as shown below:

 import com.amazon.android.webkit.AmazonWebView;

AmazonWebView mWebView;

mWebView = (AmazonWebView) findViewById(R.id.myWebView);
factory.initializeWebView(mWebView, 0xFFFFFF, false, null);
mWebView.getSettings().setJavaScriptEnabled(true);

...
                                                                                                                 

For information, see initializeWebView() in the Amazon WebView documentation.


WebView References in Your App Resources

In the resource files for your app, change each Android WebView reference to an Amazon WebView reference. Use the full path name for the Amazon WebView reference. For example, in your res/layout/[activityname].xml layout file the Android WebView element appears as follows:

<WebView
    android:id="@+id/myWebView"
    android:layout_width="fill_parent"
    android:layout_height="fill_parent"
/>
    

Change the element to reference the Amazon WebView namespace. To avoid unbound prefix errors, you should use a LinearLayout for your view as below:

<?xml version="1.0" encoding="utf-8"?>
<LinearLayout xmlns:android="http://schemas.android.com/apk/res/android"
    android:layout_width="fill_parent"
    android:layout_height="fill_parent"
    android:orientation="vertical" >

    <com.amazon.android.webkit.AmazonWebView
        android:id="@+id/myWebView"
        android:layout_width="fill_parent"
        android:layout_height="fill_parent" />
	...
</LinearLayout>


Testing Your App on an Amazon Device

Installing and Running Your App

Because of the way that the Amazon WebView binaries are deployed, you must have a third-generation Kindle Fire tablet to test the Amazon WebView functionality. For general information on how to send your app to a device for testing, see Testing Your App on a Kindle Fire Emulator or Tablet.

Note: The Kindle Fire emulators do not include the Amazon WebView libraries. If you run your app on a Kindle Fire emulator, it will fail unless you include the awv_android_factory.jar file in your build to allow the Android WebView to render pages.

Guidelines for Testing Your App

Make sure that you include the following in your test plans:

  • Test whether your web pages appear when you run your app.
  • Test whether you set the needed permissions in your AndroidManifest.xml.
  • Test all of your web-related functionality.
  • Where the Android WebView and the Amazon WebView functionality differ, verify that your app works as you intended, particularly if you migrated the app from Android WebView.
  • Verify that your app gracefully adjusts to devices that do not support Amazon WebView. For example, test your app on a first or second-generation Kindle Fire device to ensure that the app runs successfully with all functionality gracefully degraded.

Return to Kindle Fire

Unavailable During Maintenance