org.xwalk.core

Class XWalkUpdater

java.lang.Object

org.xwalk.core.XWalkUpdater

public class XWalkUpdater
extends java.lang.Object

XWalkUpdater is a follow-up solution for XWalkInitializer in case the initialization failed. The users of XWalkActivity don't need to use this class.

XWalkUpdater helps to download the Crosswalk runtime and displays dialogs to interact with the user. By default, it will navigate to the Crosswalk runtime's page on the default application store, subsequent process will be up to the user. If the developer specified the download URL of the Crosswalk runtime, it will launch the download manager to fetch the APK. To specify the download URL, insert a meta-data element named "xwalk_apk_url" inside the application tag in the Android manifest.

 <application>
     <meta-data android:name="xwalk_apk_url" android:value="http://host/XWalkRuntimeLib.apk" />
 </application>
 

To download the Crosswalk runtime APK for the specified CPU architecture, xwalk_apk_url will be appended with a query string named "?arch=CPU_ABI" when the download request is sent to server, then server can send back the APK which is exactly built for the specified CPU architecture. The CPU_ABI here is exactly same as the value returned from "getprop ro.product.cpu.abi".

After the proper Crosswalk runtime is downloaded and installed, the user will return to current activity from the application store or the installer. The developer should check this point and invoke XWalkInitializer.initAsync() again to repeat the initialization process. Please note that from now on, the application will be running in shared mode.

For example:

 public class MyActivity extends Activity
         implements XWalkInitializer.XWalkInitListener, XWalkUpdater.XWalkUpdateListener {
     XWalkUpdater mXWalkUpdater;

     ......

     @Override
     protected void onResume() {
         super.onResume();

         // Try to initialize again when the user completed update and returned to current
         // activity. The initAsync() will do nothing if the initialization has already been
         // completed successfully or previous update dialog is still being displayed.
         mXWalkInitializer.initAsync();
     }

     @Override
     public void onXWalkInitFailed() {
         if (mXWalkUpdater == null) mXWalkUpdater = new mXWalkUpdater(this, this);

         // The updater won't be launched if previous update dialog is showing.
         mXWalkUpdater.updateXWalkRuntime();
     }

     @Override
     public void onXWalkUpdateCancelled() {
         // The user clicked the "Cancel" button during download.
         // Perform error handling here.
     }
 }
 

To download the Crosswalk runtime, you need to grant following permissions in the Android manifest:

 <uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
 <uses-permission android:name="android.permission.CHANGE_NETWORK_STATE" />
 <uses-permission android:name="android.permission.ACCESS_WIFI_STATE" />
 <uses-permission android:name="android.permission.CHANGE_WIFI_STATE" />
 <uses-permission android:name="android.permission.INTERNET" />
 <uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE" />
 

There is an experimental way to update the Crosswalk runtime. All of the download process are executed in background silently without interrupting the user.

For example:

 public class MyActivity extends Activity
         implements XWalkInitializer.XWalkInitListener, XWalkUpdater.XWalkBackgroundUpdateListener {
     XWalkUpdater mXWalkUpdater;

     ......

     @Override
     protected void onResume() {
         super.onResume();
     }

     @Override
     public void onXWalkInitFailed() {
         if (mXWalkUpdater == null) mXWalkUpdater = new mXWalkUpdater(this, this);
         mXWalkUpdater.updateXWalkLibrary();
     }

     @Override
     public void onXWalkUpdateStarted() {
         // Download started in background
         // Nothing particular to do here.
     }

     @Override
     public void onXWalkUpdateProgress(int percentage) {
         // Update the progress of download
         // Nothing particular to do here.
     }

     @Override
     public void onXWalkUpdateCancelled() {
         // Background download is cancelled by invoking cancelBackgroundDownload().
         // Perform error handling here
     }

     @Override
     public void onXWalkUpdateFailed() {
         // Background download failed.
         // Perform error handling here
     }

     @Override
     public void onXWalkUpdateCompleted() {
         // Try to initialize again when the Crosswalk libraries are ready.
         mXWalkInitializer.initAsync();
     }
 }
 

If you grant following permission further, the download doesn't show in the notifications.

 <uses-permission android:name="android.permission.DOWNLOAD_WITHOUT_NOTIFICATION" />
 

Signature check is enabled by default in download mode, it requires the crosswalk runtime APK must be signed with the same key used in application APK signing. Developer can insert a meta-data "xwalk_verify" in AndroidManifest to disable the signature check.

 <application>
     <meta-data android:name="xwalk_verify" android:value="disable" />
 </application>
 

We have crosswalk runtime auto-update enabled by default in download mode, it requires that the build version of the xwalk_shared_library which you used to bundle with your application has to match the build version of the downloaded crosswalk runtime, if the build versions differ it will trigger an update to download a new crosswalk runtime from the server. If you want to disable auto update, you could call setAutoUpdate(false) before starting to initialization.

In download mode, we support two kinds of crosswalk runtime APKs, one is the original XWalkRuntimeLib.apk, another one is XWalkRuntimeLibLzma.apk which contains compressed libraries and resources and then it has smaller size but it will take a little more time at the first launch.

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static interface	XWalkUpdater.XWalkBackgroundUpdateListener Interface used to update the Crosswalk runtime silently
static interface	XWalkUpdater.XWalkUpdateListener Interface used to update the Crosswalk runtime

Constructor Summary

Constructors

Constructor and Description
XWalkUpdater(XWalkUpdater.XWalkBackgroundUpdateListener listener, android.app.Activity activity) Create XWalkUpdater for single activity.
XWalkUpdater(XWalkUpdater.XWalkUpdateListener listener, android.app.Activity activity) Create XWalkUpdater for single activity

Method Summary

Methods

Modifier and Type	Method and Description
boolean	cancelBackgroundDownload() Cancel the background download
boolean	dismissDialog() Dismiss the dialog showing and waiting for user's input.
static boolean	getAutoUpdate() Get the crosswalk runtime auto update status in download mode.
static void	setAutoUpdate(boolean enable) Enable/disable crosswak runtime auto update in download mode.
void	setXWalkApkUrl(java.lang.String url) Set the download URL of the Crosswalk runtime.
boolean	updateXWalkRuntime() Update the Crosswalk runtime.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

XWalkUpdater

public XWalkUpdater(XWalkUpdater.XWalkUpdateListener listener,
            android.app.Activity activity)

Create XWalkUpdater for single activity

Parameters:

listener - The XWalkUpdater.XWalkUpdateListener to use

activity - The activity which initiate the update

XWalkUpdater

public XWalkUpdater(XWalkUpdater.XWalkBackgroundUpdateListener listener,
            android.app.Activity activity)

Create XWalkUpdater for single activity. This updater will download silently.

Parameters:

listener - The XWalkUpdater.XWalkBackgroundUpdateListener to use

activity - The activity which initiate the update

Method Detail

updateXWalkRuntime

public boolean updateXWalkRuntime()

Update the Crosswalk runtime. There are 2 ways to download the Crosswalk runtime: from the play store or the specified URL. It will download from the play store if the download URL is not specified. To specify the download URL, insert a meta-data element with the name "xwalk_apk_url" inside the application tag in the Android manifest.

Please try to initialize by XWalkInitializer first and only invoke this method when the initialization failed. This method must be invoked on the UI thread.

Returns:

True if the updater is launched, false if is in updating, or the Crosswalk runtime doesn't need to be updated, or the Crosswalk runtime has not been initialized yet.

dismissDialog

public boolean dismissDialog()

Dismiss the dialog showing and waiting for user's input.

Returns:

Return false if no dialog is being displayed, true if dismissed the showing dialog.

setXWalkApkUrl

public void setXWalkApkUrl(java.lang.String url)

Set the download URL of the Crosswalk runtime. By default, the updater will get the URL from the Android manifest.

Parameters:

url - The download URL.

cancelBackgroundDownload

public boolean cancelBackgroundDownload()

Cancel the background download

Returns:

Return false if it is not a background updater or is not downloading, true otherwise.

setAutoUpdate

public static void setAutoUpdate(boolean enable)

Enable/disable crosswak runtime auto update in download mode. It's enabled by default.

Parameters:

enable - True to enable auto update, otherwise disable it.

getAutoUpdate

public static boolean getAutoUpdate()

Get the crosswalk runtime auto update status in download mode.

Returns:

Return true if auto update is enabled, otherwise it's disabled.