Tutorials
Getting started
Chart interface
Web components
Chart internals
Data integration
Customization
Frameworks and bundlers
Mobile development
Trading
Time Span Events
Term structures
ScriptIQ
Troubleshooting
Glossary
Reference
JSFiddles

Getting Started on Mobile: Android

This page will discuss how to integrate the ChartIQ mobile SDK into your native Android app and how to instantiate and interact with a ChartIQ chart. The ChartIQ mobile SDK project comes prepackaged with a working application and can be used right out of the box.

Contents:


Overview

The ChartIQ mobile SDK provides a native interface for Android developers to instantiate and interact with a ChartIQ chart. The interface will create a WebView and populate it with a predefined html file that loads the ChartIQ JavaScript library, supporting CSS, and a JavaScript “bridge” file which interfaces with the native interface.

What occurs in the WebView will be hidden, automatic, and not dependent on developer configuration. The developer should be able to instantiate the object as they would any other native component and essentially “feel” like they are working with a native component.

Important!

Although the mobile SDK for Android and the JavaScript library may use the same function call names at times, they are not the same, and they are not interchangeable.

  • When using the mobile SDK, follow the documentation in the mobile native API.
  • When directly calling the JavaScript API, follow the documentation in the JavaScript CIQ core library.

Requirements

The list of Requirements can be found here.

Return to the top


Download the ChartIQ mobile SDK

If you have a fresh checkout of the Android sample application, the latest SDK is included with the main branch. If you want a previous version, please check out the appropriate tag.

Now, let's create a ChartIQ view in the app.

Return to the top


Initialize and deploy the ChartIQ mobile SDK

  1. Deploy the mobile SDK so it can be used by the application.

    • Copy sample-template-native-sdk.html from the mobile directory into the root directory of the library package.
    • Make sure DEFAULT_CHART_URL is set to the path where your ChartIQ HTML5 library is deployed so your WebView can be initialized. For this application, the path is set in BuildConfig in the build.gradle file in the demo directory.
    • Note: If you are deploying your app using localhost, it is important to know that you have to use your local machine IP address for the URL path. Do not use "localhost" or "127.0.0.1", as the Android emulator or real device won't recognize that path because the app is technically on it's own device.
    android {
        // ...
        defaultConfig {
            // ...
            buildConfigField("String", "DEFAULT_CHART_URL", "\"http://deploypath/sample-template-native-sdk.html\"")
        }
    }
    

    Loading sample-template-native-sdk.html as a local resource

    By default, this app is configured to load the sample HTML template and corresponding library files remotely via HTTP.

    If instead you will load the library files as local resources, you'll need to ensure that the files can be found by the app. It is recommended to use WebViewAssetLoader.

    Alternatively, files can also be loaded by file://, but you will need to bundle the app first (see mobile example in the webpack-example directory) to abide by cross-origin rules.

    If you are planning on bundling the library with your application, please let us know so we can send you a suitable package. The standard domain locked library will not work in this case. See Sidebar: Advantages of Remote Deployment for details on these two approaches.

  2. Build and run your app. You should see a ChartIQ view loaded and populated with a chart.

Return to the top


Extend the ChartIQ mobile SDK

So now that you have the chart working, it will be useful to know how to extend the the mobile SDK. A simple example of how to add your own function to the nativeSdkBridge.js file is in the Getting Started on Mobile tutorial, but how does the Android native code call the JavaScript functions? The Android Webview has a native method, executeJavascript, that takes a string that will represent the call you want to make in JavaScript. An example using the files that come with the Android mobile SDK and ChartIQ SDK is below.

Let's say you want a method that will return the series object that represents all the series that are currently drawn on the chart.

  1. First modify your nativeSdkBridge.js file that is packaged with your ChartIQ SDK (chartiq/mobile/nativeSdkBridge.js).

    CIQ.MobileBridge.getAllSeries = function () {
    	// clone the object if you plan on modifying any of the fields before passing back to Android
    	const allSeries = CIQ.clone(stxx.chart.series);
    	// convert to a string first if you are passing back an object
    	return JSON.stringify(seriesObj);
    };
    
  2. Now add a wrapper method to ChartHandler.kt. Since we are returning a value, we will need to use evaluateJavaScriptWithReturn method.

    override fun getAllSeries(callback: OnReturnCallback<List<Series>>) {
    	val script = "CIQ.MobileBridge.getAllSeries();"
    	executeJavascript(script) {
    		// do what you want with the return data
    		val objectResult = Gson().fromJson(it, Object::class.java)
    		callback.onReturn(objectResult)
    	}
    

    Alternatively you can call the chart engine JavaScript object (stxx in the example below) directly from the Android side. This is not encouraged as putting a helper method in the nativeSdkBridge script allows for easier debugging and less confusion when one script is providing a layer of abstraction.

    override fun getAllSeries(callback: OnReturnCallback<List<Series>>) {
    	val script = "stxx.chart.series;" // not encouraged
    	executeJavascript(script) {
    		// do what you want with the return data
    		val objectResult = Gson().fromJson(it, Object::class.java)
    		callback.onReturn(objectResult)
    	}
    }
    
  3. This new Android method can now be called by the ChartIQ object.

    private fun messingWithSeries() {
    	// series business
    	...
    	val allTheSeries = chartIQ.getAllSeries()
    	// now do what you want with the series data
    	...
    }
    

The ability to extend the ChartIQ mobile SDK is powerful, as it gives you access to all the functions that the ChartIQ SDK uses. We cannot one-to-one map all the ChartIQ functions, as that would create a bridge file much too large, but if there are certain functions you absolutely need, we encourage you to extend them in the nativeSdkBridge.

Return to the top

Next steps

See the following: