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

Required

This step is required if your project uses the WebDialog.applicationUrlScheme mechanism to register for custom url scheme callbacks.

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

Optional

The Xcode project Zing Studio creates already handles this step for you.

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.

Removing unwanted architectures

Optional

The Xcode project Zing Studio creates already handles this step for you.

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"