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 Crosswalk Project runtime and displays dialogs to interact with the user. By default, it will navigate to the page of Crosswalk Project on the default application store of the device, subsequent process will be up to the user. If the developer specified the download URL, it will launch the download manager to fetch the APK.

After proper Crosswalk Project 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.

Besides shared mode, there is another way to update Crosswalk Project runtime that all of download process are executed in background silently without interrupting the user.

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

Edit Activity

Here is the sample code for embedded mode and shared mode:

 import android.app.Activity;
 import android.os.Bundle;

 import org.xwalk.core.XWalkInitializer;
 import org.xwalk.core.XWalkUpdater;
 import org.xwalk.core.XWalkView;

 public class MainActivity extends Activity implements
        XWalkInitializer.XWalkInitListener,
        XWalkUpdater.XWalkUpdateListener {

     private XWalkView mXWalkView;
     private XWalkInitializer mXWalkInitializer;
     private XWalkUpdater mXWalkUpdater;

     @Override
     protected void onCreate(Bundle savedInstanceState) {
         super.onCreate(savedInstanceState);

         // Must call initAsync() before anything that involves the embedding
         // API, including invoking setContentView() with the layout which
         // holds the XWalkView object.

         mXWalkInitializer = new XWalkInitializer(this, this);
         mXWalkInitializer.initAsync();

         // Until onXWalkInitCompleted() is invoked, you should do nothing with the
         // embedding API except the following:
         // 1. Instantiate the XWalkView object
         // 2. Call XWalkPreferences.setValue()
         // 3. Call mXWalkView.setXXClient(), e.g., setUIClient
         // 4. Call mXWalkView.setXXListener(), e.g., setDownloadListener
         // 5. Call mXWalkView.addJavascriptInterface()

         setContentView(R.layout.activity_main);
         mXWalkView = (XWalkView) findViewById(R.id.xwalkview);
     }

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

         // Try to initialize again when the user completed updating and
         // returned to current activity. The initAsync() will do nothing if
         // the initialization is proceeding or has already been completed.

         mXWalkInitializer.initAsync();
     }

     @Override
     public void onXWalkInitStarted() {
     }

     @Override
     public void onXWalkInitCancelled() {
         // Perform error handling here

         finish();
     }

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

     @Override
     public void onXWalkInitCompleted() {
         // Do anyting with the embedding API

         mXWalkView.load("https://crosswalk-project.org/", null);
     }

     @Override
     public void onXWalkUpdateCancelled() {
         // Perform error handling here

         finish();
     }
 }
 

For download mode, the code is almost the same except you should use XWalkUpdater.XWalkBackgroundUpdateListener instead of XWalkUpdater.XWalkUpdateListener.

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

     ......

     @Override
     public void onXWalkUpdateStarted() {
     }

     @Override
     public void onXWalkUpdateProgress(int percentage) {
         // Update the progress to UI or do nothing
     }

     @Override
     public void onXWalkUpdateCancelled() {
         // Perform error handling here

         finish();
     }

     @Override
     public void onXWalkUpdateFailed() {
         // Perform error handling here

         finish();
     }

     @Override
     public void onXWalkUpdateCompleted() {
         // Start to initialize again once update finished

         mXWalkInitializer.initAsync();
     }
 }
 

Edit App Manifest

For shared mode and download mode, you might need to edit the Android manifest to set some properties.

Shared Mode

If you want the end-user to download Crosswalk Project runtime from specified URL instead of switching to the application store, add following <meta-data> element inside the <application> element:

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

Please note that when the HTTP request is sent to server, the URL will be appended with "?arch=CPU_API" to indicate that on which CPU architecture it's currently running. The CPU_API is the same as the value returned from "adb shell getprop ro.product.cpu_abi", e.g. x86 for IA 32bit, x86_64 for IA 64bit, armeabi-v7a for ARM 32bit and arm64-v8a for ARM 64bit.

The specified APK will be downloaded to SD card, so you have to grant following permission:

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

Download Mode

Firstly, you need to add following <meta-data> element to enable download mode:

 <application>
     <meta-data android:name="xwalk_download_mode" android:value="enable"/>
 

In download mode, the value of xwalk_apk_url is mandatory. However, the downloaded Apk will be saved into application's private storage, so the permission of writing to SD card is not needed anymore.

By default, the application will verify the signature of downloaded Crosswalk Project runtime, which is required to be the same as your application. But you can disable it by adding following <meta-data> element:

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

If your application has already downloaded Crosswalk Project runtime but the application got an update after that, the build version of shared library you used to bundle with your new application may be newer than the build version of downloaded Crosswalk Project runtime. In this case, it will download new version of Crosswalk Project runtime from the server again. If you want to continue using old version of Crosswalk Project runtime, you could add following <meta-data> element:

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

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.
XWalkUpdater(XWalkUpdater.XWalkUpdateListener listener, android.app.Activity activity, XWalkDialogManager dialogManager) Create XWalkUpdater for single activity.

Method Summary

Modifier and Type	Method and Description
boolean	cancelBackgroundDownload() Cancel the background download
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.XWalkUpdateListener listener,
                    android.app.Activity activity,
                    XWalkDialogManager dialogManager)

Create XWalkUpdater for single activity.

Parameters:

listener - The XWalkUpdater.XWalkUpdateListener to use

activity - The activity which initiate the update

dialogManager - The XWalkDialogManager to use

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.

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:

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