Nativescript: Update Android TypeScript definitions to include latest Android APIs

[kspearrin]

Did you verify this is a real problem by searching the [NativeScript Forum]

Yes, see https://discourse.nativescript.org/t/what-version-of-android-are-the-typescript-declarations-for/5942

Tell us about the problem

I am not sure what version of the Android SDK that the TypeScript declarations are currently generated from (22 maybe?), but there are several new Android APIs that are missing from it. Namely, I am interested in using some APIs that are part of Oreo such as the Autofill Framework.

Which platform(s) does your issue occur on?

Android

Please provide the following version numbers that your issue occurs with:

• CLI: 4.0.0
• Cross-platform modules: 4.0.0
• Runtime(s): 4.0.1
• Plugin(s): n/a

Please tell us how to recreate the issue in as much detail as possible.

Just create a new NS Android project. Include TS definitions and try to use newer Android APIs, such as https://developer.android.com/reference/android/service/autofill/AutofillService

Is there code involved? If so, please share the minimal amount of code needed to recreate the problem.

n/a

[NickIliev]

@kspearrin thank you for logging this issue - indeed there are some missing APIs from the currently generated declaration files. Marking this as a feature request that can be handled by anyone who is interested in contributing to NativeScript.

The tool originally used for generating the Android declaration file is located here.

[NickIliev]

@kspearrin we should consider that if you generate declarations for newer API level you should target the code to be executed only for that API level and above. Otherwise, you risk breaking the app on lower API levels. This said it makes sense that the default definitions are targeting the lowest supported API (17) so it would be compatible with all API levels supported by default.

So if you need to generate declaration files for newer API levels, you should either change the target minimum SDK version in your AndroidManifest.xml file or wrap the code in an SDK version check.

For anyone interested here are the steps to generate declaration file for newer APIs:

// install gradle https://docs.gradle.org/current/userguide/installation.html
// build wrapper
gradle wrapper

git clone https://github.com/NativeScript/android-dts-generator
cd dts-generator

gradlew jar
java -jar build\libs\dts-generator.jar -input %ANDROID_HOME%\platforms\android-25\android.jar

The generated definitions will be outputed in dts-generator\out folder. The example above is generating declartion files for API25 (change the number in android-25 to wanted API level)

Closing this feature request as it wouldn't make sense to add definitions for APIs that might break lower levels - the choice should be left in the developer's hands (by using the steps above and manually generating the needed files)

[kspearrin]

Thanks for the info. I have ran the dts-generator on Android 26 and was able to build an android.d.ts that works at that API level. I would add that, in my opinion, the NS team should consider officially shipping various versions of the Android SDK definitions so that people can easily choose the API level that they want to target and install from NPM. That way people don't have to go through this boilerplate process each time.

[NickIliev]

@kspearrin that is a reasonable idea! The only thing that is stopping us from shipping the files for the different API levels is their enormous size (approx between 5 and 20mb each d.ts for API level) which would make tns-platform-declarations one really large plugin. That would be OK as the plugin is meant to be used as devDependency however, there is a possibility that some plugins are referring it as a dependency which would cause a ridiculously large projects.

[simonbuchan]

Would it make sense to have @{ver}-api-{api} NPM versions, e.g. [email protected] to keep the package size reasonable? That's a bit of a pain for semver (does 4.x-api-26 work?) so another option would be using the minor version as the sdk version, e.g. 4.26.22, but that's confusing.

The ideal option would probably be to have something like tns update-android-sdk 26 to script the above, but probably not worth the edge-case handling hassle.

[AresDev]

@NickIliev I've created the android.d.ts file with the process you described before. In order for my project to work with all developers in my team, I should include that large file in source control and reference it from references.d.ts? or is there another alternative?

How can I do this process reproducible in order to build the project from a build pipeline?

I've also tried changing the minskd version in the AndroidManifest.xml but it always install the 17 version.

[NickIliev]

@AresDev regarding the minimum SDK version you could use this approach if the AndroidManifest is not respecting the value

Regarding the declaration files - yes you have to provide the file to your source control -if you want to be used by multiple devs. However, there is another alternative - we have just updated the tns-platform-declarations plugin to include different declaration files for all PIs from 17 to 27 including the support library. The files are generated out-of-the-box and can be used by simply referring the proper file. The change was implemented a few days ago and is still not officially published so you would need the next version if you want to use it.

npm i tns-platform-declaration@next --save-dev

And then refer the API you need in your reference.d.ts

For example to have references for API21 and above

/// <reference path="./node_modules/tns-platform-declarations/android-21.d.ts" />

At this moment the info for tns-platform-declarations can be found here - The article will go live once the new version is officially published

[NickIliev]

@kspearrin @simonbuchan @AresDev

Feature implemented via https://github.com/NativeScript/NativeScript/pull/5890 (see above comment for details)

[AresDev]

Thanks @NickIliev ! I'm pleased to see how active the community is, great job!

[lock[bot]]

This thread has been automatically locked since there has not been any recent activity after it was closed. Please open a new issue for related bugs.