Native Developer API

Zing projects can be exported as native Xcode and Android Studio projects. Exporting your Zing project allows you to compile it as a native app, and distribute it through the Apple App Store and Google Play Store.

This section covers the details of how native Zing applications work, and the native APIs available to you for interacting with them. To learn more about actually exporting your project, refer to Guide: Native export.

Exporting

The Xcode and Android Studio projects that Zing Studio creates when you export your prototype are both fairly standard, single view app templates.

Into these standard templates, Zing Studio adds the Zing Engine library (Android) or framework (iOS), and an archive of your Zing project.

The Zing Engine is a native library or framework that contains the runtime code necessary to execute your Zing project on Android or iOS. The Zing project archive is a file, named "app.zfs", that contains a compressed copy of your project and all of its assets, that is loaded by the Zing Engine.

When you update a project from Zing Studio, it updates just the Zing Engine and the app.zfs files.

Android Studio

The Zing Engine for Android provides an android.app.Activity derived class, ZingActivity, that manages and displays your archived project when activated.

Zing Engine for Android supports Jelly Bean (4.1) and later, and provides support for the arm, arm64, x86 and x86_64 architectures.

Xcode

The Zing Engine provides a UIViewController derived class, ZingViewController, that manages and displays your archived project.

You can use ZingViewController like any other iOS view controller, although it is best presented as a full screen view.

The Zing Engine for iOS framework supports iOS 8 and later.

Application URL schemes

Due to security features of Apple's embedded browser control, the Zing engine cannot directly intercept the url scheme calls it makes. Instead, you must register your iOS app as handling the URL scheme. Once registered, the system will deliver these calls and Zing can forward them on to your code.

Follow the Apple documentation on how to Register Your URL Scheme in the Info tab of your Xcode project settings. As long as your application also uses the ZingApplicationDelegate application delegate, your project will then receive WebDialog.applicationUrlRequested() events, just like in Zing Preview.

Application delegate

For full functionality, Zing requires that your app's UIApplication delegate instance extends the ZingApplicationDelegate class.

This is necessary for the Zing Engine to receive the application level messages it needs to provide some functionality. Additional details are provided in the ZingApplicationDelegate class documentation.

Application expiration

When you build and install an app on an iOS device directly from Xcode, or when you install an app via ad-hoc distribution, the app includes a provisioning profile created by Xcode. Amongst other things, provisioning profiles define the devices and users that can install the application, and the capabilities the app has when installed.

Provisioning profiles also contain an expiration date. Once the expiration date passes, the app will simply stop launching and iOS does not give you any explanation as to why. You can reset the expiration date by doing a clean build in Xcode and reinstalling.

The expiration date Xcode calculates is different depending on whether you have a free or a paid Apple developer account. Apps built with a paid account expire after a year.

Apps built with a free Apple developer account are set to expire after 7 days. However, as Xcode does not always regenerate the expiration date for every build, it is possible for you app to expire after just a day or two if you have been tweaking it and making builds for several days.

You can ensure the expiration date has been reset for the full amount of time by running "Clean Build Folder" in Xcode before you create the build.

Removing unwanted architectures

In order to run in the iOS simulator, the Zing Engine for iOS framework includes x86 support, in addition to the regular ARM support.

However, as Apple will not accept submissions to the App Store that include x86 binaries, they must be removed prior to uploading the app.

The simplest way to achieve this is with an install script, added as a project build phase. By default, Zing Studio uses the following script. To avoid runtime crashes, the build phase must also be marked as "Run script only when installing".

FRAMEWORK="ZingEngine"
FRAMEWORK_EXECUTABLE_PATH="${BUILT_PRODUCTS_DIR}/${FRAMEWORKS_FOLDER_PATH}/$FRAMEWORK.framework/$FRAMEWORK"

EXTRACTED_ARCHS=()
for ARCH in $ARCHS
do
    lipo -extract "$ARCH" "$FRAMEWORK_EXECUTABLE_PATH" -o "$FRAMEWORK_EXECUTABLE_PATH-$ARCH"
    EXTRACTED_ARCHS+=("$FRAMEWORK_EXECUTABLE_PATH-$ARCH")
done

lipo -o "$FRAMEWORK_EXECUTABLE_PATH-merged" -create "${EXTRACTED_ARCHS[@]}"
rm "${EXTRACTED_ARCHS[@]}"
rm "$FRAMEWORK_EXECUTABLE_PATH"
mv "$FRAMEWORK_EXECUTABLE_PATH-merged" "$FRAMEWORK_EXECUTABLE_PATH"