Cordova integration into native iOS project

Continuing a small series of articles " Crosswalk Project - replacement of Android WebView ", it makes sense to make out a similar task for iOS. This time the Cordova project was chosen as the basis for integration, since It has more functionality and in this case is better suited for the task.

Both Cordova and Crosswalk solutions are based on WKWebView in their version for iOS. Therefore, in this case, they are not a direct replacement for the system WebView, but only expand it.
')
The target language of the demo project is Swift, but for an Objective-C project everything will be the same. It is not necessary only to perform the last step in adapting Cordova for use with Swift.

NB! For Crosswalk, there is a simple integration guide using Cocoa Pods and there is support for the main Cordova plugins that can be expanded.

There are 2 options for embedding Cordova into your application:

1. Manual Cordova Embedding
2. Add the necessary components through Cocoa Pods.

NB! In fact, there is 1 more simple option. After setting up the environment for Cordova, you will get a working Xcode project that can be used separately from Cordova for further development. Just keep in mind that this project is on Objective-C.

Manual Cordova Embedding

I will consider the first option first and add Cordova with the necessary components manually. This option is a bit more complicated, but more flexible and allows you to use the latest versions of cordova-ios and plug-ins, regardless of the creators of the pods.

Software versions used:

• Xcode 8.3.2, Swift 3.1
• Cordova 7.0.1, Cordova iOS 4.4.0
• MacPorts 2.4.1
• npm 4.6.1

Setting up the environment

To implement the 1st option, you must first install the Cordova project itself and the necessary utilities. The installation process is quite simple and is described in detail in the Cordova documentation ; I will only focus on the necessary steps for creating a demo project.

1. Install the npm package manager , with which we will later install Cordova and the necessary plug-ins (I used MacPorts to install npm):

sudo port install npm4 

2. Install Cordova directly :

 sudo npm install -g cordova 

Similarly, you can install only cordova-ios:

 sudo npm install -g cordova-ios 

This can be useful if you do not plan to work with other platforms. However, in this case it will be slightly less convenient to use commands in the console . For example, you will need to use:

 cordova-ios/bin/create 

with full path instead of short command:

 cordova create 

NB! All packages installed using npm will be located here: / opt / local / lib / node_modules / .

3. Next, create a project Cordova , go to its folder and add the target platform iOS :

 cordova create cordova_full cd cordova_full/ cordova platform add ios 

The files we need will be located in the cordova_full / platforms / ios / folder. We will get a similar set with minimal differences if we use the cordova-ios package directly.

NB! When creating a project, you can specify the name of the application and the bundle identifier. See the Cordova documentation for details.

4. Additionally, you can install the plugman utility for working with Cordova plugins :

 sudo npm install -g plugman 

5. We will also install 2 plug-ins for displaying messages in the console and working with the system status bar , they will be useful to us for work. To do this, go to the folder with resources for ios and execute the following commands:

 plugman install --platform ios --project . --plugin cordova-plugin-console plugman install --platform ios --project . --plugin cordova-plugin-statusbar 

NB! For those who want to work with the Ionic Framework toolbar (http://ionicframework.com/) and use its templates, everything looks the same.

Project creation

1. The project was based on the standard Tabbed Application template from Xcode. The created demo project with all resources can be found on github .

The minimally supported Cordova iOS 4.4.0 version of iOS is 9.0, we choose it for the demo project.

2. Transfer to our demo project the necessary resources :

• folder with the project CordovaLib cordova_full / platforms / ios / CordovaLib /
• folder with installed plug-ins cordova_full / platforms / ios / HelloCordova / Plugins /
• configuration file Cordova cordova_full / platforms / ios / HelloCordova /config.xml
• resource folder for the web application cordova_full / platforms / ios / www /

NB! After adding CordovaLib , check in the settings of the main project in the Build Phases → Compile Sources tab. Delete the CordovaLib files from there to avoid conflicts during the build process .

NB! When adding a folder with www / resources, you must select the “Create folder references” option so that the resources are located along the standard path for Cordova.

3. You need to set up a demo project for correct assembly :

• In Build Settings → Other Linker Flags add flag -ObjC
• In Build Settings → Header Search Paths add paths:
  
  

   "$(TARGET_BUILD_DIR)/usr/local/lib/include" "$(OBJROOT)/UninstalledProducts/include" "$(OBJROOT)/UninstalledProducts/$(PLATFORM_NAME)/include" "$(BUILT_PRODUCTS_DIR)" 

  
  
• in Build Phases → Target Dependencies add CordovaLib
• in Build Phases → Link Binaries with Libraries add libCordova.a

NB! Note that you need to add the entire string with quotes.

In the Objective-C version, the configuration is complete and the project can be used.

4. Adaptation for Swift . The Cordova iOS project was originally implemented in Objective-C language and at the moment it is not known about the official plans for porting it to Swift. There is an unofficial port , but it is not finished.

However, there is no fundamental problem for using Cordova in a Swift project. You only need to add a Bridging Header to connect the world of Swift and Objective-C.

To do this, you need to create a file in the .h file (for example, Bridging-Header.h):

 #ifndef Bridging_Header_h #define Bridging_Header_h #import "CDVViewController.h" #endif /* Bridging_Header_h */ 

And add to Build Settings -> Objective-C the Bridging Header path to it:

 CordovaEmbedded/Libraries/Bridging-Header.h 

5. After that we can use Cordova WebView . For example, inherit from the SecondViewController demo project from CDVViewController instead of UIViewController . And with a flick of the wrist, our second tab turns into a full-fledged Cordova app.

6. A few words about Cordova plugins . Initially, we connected 2 plugins to the project:

• to display messages in the console
• to work with the system status bar

The first plugin allows us to receive messages in the Xcode console in an adequate form:

 CordovaEmbedded[31857:638683] Received Event: deviceready 

The second plugin allows you to configure the status bar - set the style, color, etc.

Configuration of plugins is carried out in the config.xml file. In the project template used, the status bar is initially transparent, using the settings of the plugin, you can change its appearance and get a transparent status bar for the first tab and opaque for the second. This shows well the performance of the entire integrated system.

Adding prerequisites through Cocoa Pods

1. To illustrate connecting Cordova through CocoaPods, take the same Tabbed Application project template from Xcode. The created demo project with all resources can be found on github .

2. Create a pod file using the pod init command and add pods to it:

 pod 'Cordova' # Cordova framework and plugins pod 'CordovaPlugin-console' pod 'cordova-plugin-camera' pod 'cordova-plugin-contacts' pod 'cordova-plugin-device' pod 'cordova-plugin-device-orientation' pod 'cordova-plugin-device-motion' pod 'cordova-plugin-globalization' pod 'cordova-plugin-geolocation' pod 'cordova-plugin-file' pod 'cordova-plugin-media-capture' pod 'cordova-plugin-network-information' pod 'cordova-plugin-splashscreen' pod 'cordova-plugin-inappbrowser' pod 'cordova-plugin-file-transfer' pod 'cordova-plugin-statusbar' pod 'cordova-plugin-vibration' pod 'cordova-plugin-wkwebview-engine' pod 'phonegap-ios-template' # Cordova template 

NB! All plugins are added, because they are used in the phonegap-ios-template resource template . Practically, you can add only the necessary ones, but then you will need to adjust the config.xml in the template.

3. Install the pods with the pod install command and open the resulting .xcworkspace . Next, you must perform step 4 from the previous section , on the adaptation of the project for use with the Swift language.

4. Now there is a problem with the configuration and the project does not find all the necessary headers when building . This can be solved by adding the path (with the recursive flag) to the Build Settings → User Header Search Paths :

 "${PODS_ROOT}" 

5. - 6. To illustrate the health of Cordova, you can repeat steps 5 and 6 from the previous section. Everything works the same way.

Conclusions and useful resources

The manual Cordova version is not much more complicated than using Cocoa Pods in this case, but it is more flexible and allows using the latest versions of cordova-ios and plug-ins.

But when using Cocoa Pods there are several drawbacks:

• there is no possibility to upgrade to the required version of Cordova iOS or plugin;
• all the same it is necessary to make a project configuration
• It is necessary to change the configuration of Cordova in the pod-project.

By and large, the main disadvantages are not very good support for pods for Cordova :)

In addition, you can study the integration of Cordova WebView into a native iOS project:

• Cordova Documentation: Embed Cordova in Native apps → iOS WebViews
• Phonegap Documentation: Embedding the Webview
• Repository with pod files for Cordova integration and instructions
• Created demo projects with all resources can be found on github

NB! Please note that the official integration documentation is somewhat outdated and may have extra or missing steps.