iOS Plugins

This section provides details for how to implement native plugin code
on the iOS platform. Before reading this, see Application Plugins for
an overview of the plugin's structure and its common JavaScript
interface. This section continues to demonstrate the sample echo
plugin that communicates from the Cordova webview to the native
platform and back.

An iOS plugin is implemented as an Objective-C class that extends the
CDVPlugin class. For JavaScript's exec method's service
parameter to map to an Objective-C class, each plugin class must be
registered as a <feature> tag in the named application directory's
config.xml file.

Plugin Class Mapping

The JavaScript portion of a plugin uses the cordova.exec method as
follows:

The feature's name attribute should match what you specify as the
JavaScript exec call's service parameter. The value attribute
should match the name of the plugin's Objective-C class. The <param>
element's name should always be ios-package. If you do not follow
these guidelines, the plugin may compile, but Cordova may still not be
able to access it.

Plugin Initialization and Lifetime

One instance of a plugin object is created for the life of each
UIWebView. Plugins are ordinarily instantiated when first referenced
by a call from JavaScript. Otherwise they can be instantiated by
setting a param named onload to true in the config.xml file:

There is no designated initializer for plugins. Instead, plugins
should use the pluginInitialize method for their startup logic.

Plugins with long-running requests, background activity such as media
playback, listeners, or that maintain internal state should implement
the onReset method to clean up those activities. The method runs
when the UIWebView navigates to a new page or refreshes, which
reloads the JavaScript.

Writing an iOS Cordova Plugin

A JavaScript call fires off a plugin request to the native side, and
the corresponding iOS Objective-C plugin is mapped properly in the
config.xml file, but what does the final iOS Objective-C plugin
class look like? Whatever is dispatched to the plugin with
JavaScript's exec function is passed into the corresponding plugin
class's action method. A plugin method has this signature:

For more details, see
[CDVInvokedUrlCommand.h](https://github.com/apache/cordova-ios/blob/master/CordovaLib/Classes/CDVInvokedUrlCommand.h),
[CDVPluginResult.h](https://github.com/apache/cordova-ios/blob/master/CordovaLib/Classes/CDVPluginResult.h),
and
[CDVCommandDelegate.h](https://github.com/apache/cordova-ios/blob/master/CordovaLib/Classes/CDVCommandDelegate.h).

iOS CDVPluginResult Message Types

You can use CDVPluginResult to return a variety of result types back to
the JavaScript callbacks, using class methods that follow this pattern:

You can create String, Int, Double, Bool, Array,
Dictionary, ArrayBuffer, and Multipart types. You can also leave
out any arguments to send a status, or return an error, or even choose
not to send any plugin result, in which case neither callback fires.

Note the following for complex return values:

messageAsArrayBuffer expects NSData* and converts to an
ArrayBuffer in the JavaScript callback. Likewise, any
ArrayBuffer the JavaScript sends to a plugin are converted to
NSData*.

messageAsMultipart expects an NSArray* containing any of the
other supported types, and sends the entire array as the arguments
to your JavaScript callback. This way, all of the arguments are
serialized or deserialized as necessary, so it is safe to return
NSData* as multipart, but not as Array/Dictionary.

Echo iOS Plugin Example

To match the JavaScript interface's echo feature described in
Application Plugins, use the plugin.xml to inject a feature
specification to the local platform's config.xml file:

The necessary imports at the top of the file extends the class from
CDVPlugin. In this case, the plugin only supports a single echo
action. It obtains the echo string by calling the objectAtIndex
method get the first parameter of the arguments array, which
corresponds to the arguments passed in by the JavaScript exec()
function.

It checks the parameter to make sure it is not nil or an empty
string, returning a PluginResult with an ERROR status if so. If
the parameter passes the check, it returns a PluginResult with an
OK status, passing in the original echo string. Finally, it sends
the result to self.commandDelegate, which executes the exec
method's success or failure callbacks on the JavaScript side. If the
success callback is called, it passes in the echo parameter.

iOS Integration

The CDVPlugin class features other methods that your plugin can
override. For example, you can capture the pause, resume, app
terminate and handleOpenURL events. See the
CDVPlugin.h
and
CDVPlugin.m
class for guidance.

Threading

Plugin methods ordinarily execute in the same thread as the main
interface. If your plugin requires a great deal of processing or
requires a blocking call, you should use a background thread. For
example: