Native API Access #

What exactly does it mean for NativeScript to "Empower JavaScript with native APIs"?

This means you can go directly to platform source documentation like Apple API Docs and Android API Docs and work with it right away without leaving your JavaScript codebase.

Let's explore this more by looking at some concrete use cases.

Android Walkthrough #

The Java code below will get the Android device battery level. This example is only for Android API 21+. To get the battery level prior to Android 21 a different approach was necessary. The purpose of this example is to explain the approach of converting Java to JavaScript.

BatteryManager bm = (BatteryManager) context.getSystemService(BATTERY_SERVICE);
int batLevel = bm.getIntProperty(BatteryManager.BATTERY_PROPERTY_CAPACITY);

Below is the working JavaScript to achieve the same end result that Java code would provide.

import { Utils, Device } from '@nativescript/core'

if (global.isAndroid && Device.sdkVersion >= '21') {
  const bm = Utils.android
    .getApplicationContext()
    .getSystemService(android.content.Context.BATTERY_SERVICE)
  const batLevel = bm.getIntProperty(android.os.BatteryManager.BATTERY_PROPERTY_CAPACITY)
}

Now for a short walkthrough of one way to go about translating Java to JavaScript.

1. JavaScript uses const, let, var to declare variables. Further with TypeScript we can assign any variable a platform native type using the @nativescript/types package.

2. Next we see the method getSystemService(BATTERY_SERVICE) is being executed. We can find the getSystemService method is documented here on Android docs.

   The method is a public abstract of the android.content.Context. In the Java code you typically see context which would be an instance of the Application Context. In NativeScript we can use Utils from @nativescript/core which provides a method to get the Android context: Utils.android.getApplicationContext().

3. The getSystemService(java.lang.String) method accepts a String. When programming in Android you can use BATTERY_SERVICE if the import android.content.Context is declared in the .java file. The compiler will know that BATTERY_SERVICE is the static final string declared here.

   You could also write the getSystemService("batterymanager") using the static constant value: "batterymanager". In your NativeScript code, you could do the same, but if you prefer to use the full namespace path to the static value, you can write it like the example does with android.content.Context.BATTERY_SERVICE.

4. Now we have an instance of the Android BatteryManager which is what the docs state as the return value for this system service.

5. The next line we see getIntProperty() method called on the BatteryManager instance we have from the first line.

   We see that the method expects an int id as the argument and returns an int. Now we need to determine what the BatteryManager.BATTERY_PROPERTY_CAPACITY value is. You can see that BatteryManager is the class and what looks like a static value. Searching the Android BatteryManager docs for BATTERY_PROPERTY_CAPACITY you will find the constant value of the static final: Constant Value: 4 (0x00000004).

   You could execute the getIntProperty(int id) method passing in 4 as the argument in Java and it would work, same as you could in NativeScript. In order to use the full namespace in NativeScript you would use the fully qualified namespace path to the static int android.os.BatteryManager.BATTERY_PROPERTY_CAPACITY. Again, you typically do not use the full namespace path to values in Java because you can import the class. So import android.os.BatteryManager would be in the example java file allowing you to use the static value and the compiler know what you are trying to do and compile correctly at build time.

iOS Walkthrough #

Here is the Objective-C code to get the current battery level from an iOS device:

float batteryLevel = [[UIDevice currentDevice] batteryLevel];

Here's the same thing in JavaScript using our abilities with NativeScript:

if (global.isIOS) {
  const batteryLevel = UIDevice.currentDevice.batteryLevel
}

Now for a short walkthrough of one way to go about translating Objective-C to JavaScript.

1. In Objective-C we see UIDevice, so you can search for UIDevice on the iOS Documentation.

2. Next we see currentDevice property being accessed. In the iOS documentation for UIDevice you will find the currentDevice property of the UIDevice class.

3. Lastly, Objective-C is accessing batteryLevel synchronously to get the value. So we can access the exact same value synchronously in our JavaScript code to read the battery level just as the iOS platform API is designed to do.