330 lines (206 sloc) 9.13 KB

API Changes in cordova-ios-4.0

  • CDVViewController.h (updated)
  • CDVPlugin.h (updated)
  • CDVPluginResult.h (updated)
  • NSData+Base64.h (removed)
  • CDVAppDelegate.h (new)
  • CDVJSON.h (removed)
  • CDVJSON_private.h (removed)
  • CDVWebViewEngineProtocol.h (new)
  • CDVURLRequestFilter.h (new)
  • NSDictionary+CordovaPreferences.h (new)
  • CDVWebViewDelegate.h (removed)
  • NSDictionary+Extensions.h (removed)
  • NSArray+Comparisons.h (removed)
  • CDVHandleOpenURL.h (removed)
  • CDVLocalStorage.h (removed)
  • UIDevice+Extensions.h (removed)
  • CDVShared.h (removed)
  • CDVDebug.h (removed)
  • Conditional Compilation

CDVViewController.h (updated)



+ (NSDictionary*)getBundlePlist:(NSString*)
+ (NSString*)applicationDocumentsDirectory
- (void)javascriptAlert:(NSString*)
- (void)printMultitaskingInfo
- createGapView
- (BOOL)URLisAllowed:(NSURL*)url


@property BOOL loadFromString



@property id<CDVWebViewEngineProtocol> webViewEngine
@property NSInteger* userAgentLockToken



- (UIView*)newCordovaViewWithFrame:(CGRect)bounds


@property UIView* webView

Upgrade Notes:

The webView property is a UIView now, to take into account the different type of WebView engines that might be installed.

To test and cast the webView property to UIWebView:

if ([self.webView isKindOfClass:[UIWebView class]) {
    // call a UIWebView specific method here, for example
    [((UIWebView*)self.webView) goBack];

CDVPlugin.h (updated)



- (CDVPlugin*)initWithWebView:(UIWebView*)
- (NSString*)writeJavascript:(NSString*)
- (NSString*)success:(CDVPluginResult*) callbackId:(NSString*)
- (NSString*)error:(CDVPluginResult*) callbackId:(NSString*)


@property CDVWhitelist* whitelist



- (NSURL*)errorURL;
- (BOOL)shouldOverrideLoadWithRequest:(NSURLRequest*) navigationType:(UIWebViewNavigationType)


@property id<CDVWebViewEngineProtocol> webViewEngine


const CDVLocalNotification
const CDVRemoteNotification
const CDVRemoteNotificationError

These constants were unfortunately not removed in 4.0, but will be removed in 5.0. Local and remote push notification functionality was removed in the core in 4.0.


@property UIView* webView



- (BOOL)shouldOverrideLoadWithRequest:(NSURLRequest*) navigationType:(UIWebViewNavigationType)

Upgrade Notes:

Put your initialization code from initWithWebView into pluginInitialize. pluginInitialize is backwards-compatible, it has been there since cordova-ios-2.x.

For example, if you have this:

- (CDVPlugin*) initWithWebView:(UIWebView*)webView {
    self = [super initWithWebView:webView];
    if (self) {
        // Initialization code here
    return self;

Move your initialization code to:

- (void) pluginInitialize {
    // Initialization code here

CDVPluginResult.h (updated)



+ (CDVPluginResult*)resultWithStatus:(CDVCommandStatus)statusOrdinal messageAsNSInteger:(NSInteger)theMessage;
+ (CDVPluginResult*)resultWithStatus:(CDVCommandStatus)statusOrdinal messageAsNSUInteger:(NSUInteger)theMessage;

NSData+Base64.h (removed)

This class has been removed.



+ (NSData*)dataFromBase64String:(NSString*)aString CDV_DEPRECATED(3.8 .0, "Use cdv_dataFromBase64String");
- (NSString*)base64EncodedString CDV_DEPRECATED(3.8 .0, "Use [NSData cdv_base64EncodedString]");
+ (NSData*)cdv_dataFromBase64String:(NSString*)aString;
- (NSString*)cdv_base64EncodedString;

Upgrade Notes:

Plugin authors are encouraged to use the (iOS 7+) base64 encoding and decoding methods available in NSData instead.

// Decode a Base64 encoded string
NSData* data = [[NSData alloc] initWithBase64EncodedString:encodedString options:0]

// Encode a string to Base64
NSString* encodedString = [data base64EncodedStringWithOptions:0];

CDVAppDelegate.h (new)

This class is new. The default template's AppDelegate class inherits from this now for you to override.

Upgrade Notes:

Apps that add code in the default template's old AppDelegate.m should add the appropriate function override in the new AppDelegate.m. Don't forget to call the superclass' implementation as well in your override.

CDVJSON.h (removed)

These Objective-C Categories have been removed.

Upgrade Notes:

To convert from an NSArray/NSDictionary object to a JSON string:

id object; // this is the NSArray/NSDictionary to convert from
NSError* error = nil;
NSString* jsonString = nil;
NSData* jsonData = [NSJSONSerialization dataWithJSONObject:object

if (error == nil) {
    jsonString = [[NSString alloc] initWithData:jsonData encoding:NSUTF8StringEncoding];

To convert from an NSString to an NSArray/NSDictionary object:

NSString* jsonString; // this is the JSON to convert from
NSError* error = nil;
id object = [NSJSONSerialization JSONObjectWithData:[jsonString dataUsingEncoding:NSUTF8StringEncoding]

if (error != nil) {
    NSLog(@"NSString can't be converted to an NSArray/NSDictionary error: %@", [error localizedDescription]);

CDVJSON_private.h (removed)

These Objective-C Categories have been removed from the public API, and is private to CordovaLib.

CDVWebViewEngineProtocol.h (new)

This is new in cordova-ios-4.0. An Objective-C protocol for plugins to implement, if they want to be an alternative WebView engine.

NSDictionary+CordovaPreferences.h (new)

This is new in cordova-ios-4.0. An Objective-C Category helper for NSDictionary to get/set preferences.

CDVWebViewDelegate.h (removed)

This protocol has been removed from the public API, and is part of a private plugin to CordovaLib (CDVUIWebViewEngine).

NSDictionary+Extensions.h (removed)

This Objective-C Category has been removed.

NSArray+Comparisons.h (removed)

This Objective-C category has been removed.

Upgrade Notes:

The Objective-C Category method was used as a helper for the arguments property of a CDVInvokedURLCommand object. Use the argumentAtIndex methods provided in the CDVInvokedURLCommand object instead.

CDVHandleOpenURL.h (removed)

This plugin has been removed from the public API, and is now private to CordovaLib.

CDVLocalStorage.h (removed)

This plugin has been removed from the public API, and is now private to CordovaLib.

UIDevice+Extensions.h (removed)

This implementation has been removed and is part of the core plugin cordova-plugin-device.

CDVShared.h (removed)

This legacy header has been removed; it was for core plugin compatibility that has been not been needed since the Aug 2014 core plugin release.

CDVDebug.h (removed)

This file has been removed from the public API, and is private to CordovaLib.

Conditional Compilation

You can conditionally compile code based on the cordova-ios platform version that is installed. This might be for API calls that have no backwards-compatible equivalents.

// this import below must be declared first
#import <Cordova/CDVAvailability.h>

#ifdef __CORDOVA_4_0_0
    // Execute/declare code on cordova-ios-4.x or newer 
    // Execute/declare code for cordova-ios versions *less than* 4.x 


#ifndef __CORDOVA_4_0_0
    // Execute/declare code for cordova-ios versions *less than* 4.x