3D Touch Native Extension

With iPhone 6s and 6s Plus, Apple has introduced a new feature called 3D Touch, which is available on iOS 9.0 and higher. With 3D Touch, an iPhone app can now sense how much pressure a user is exerting on the device screen and accordingly respond to the different pressure levels.

3D Touch Native Extension allows an ActionScript developer to access 3D Touch APIs from the AIR app. This native extension provides the following features:

• Quick Actions: Through this feature, you can add shortcut items on your app icon for specific functions of the app. These quick actions can be accessed when an end-user deep presses the app’s icon on the home screen.
• Pressure Sensitivity: Through this feature, you can get the amount of pressure that an end-user is applying on their app screen. Different actions can be performed based on the pressure applied.

• ActionScript library in the directory 3DTouchLibrary: This directory contains a Flash Builder project for creating the ActionScript side of the 3D Touch extension.
• iOS native library in the directory 3DTouchNativeLibrary: This directory contains an Xcode project for creating the iOS native side of the 3DTouch extension. To build the Xcode project, you need to first copy the file FlashRuntimeExtension.h from the path <AIR_SDK>/include/FlashRuntimeExtensions.h to the directory 3DTouchNativeLibrary.
• A directory called ReadyToUseExtension: This directory contains everything an AIR application developer needs to use native extension - an ANE file, an SWC file, and a text file that contains the extension ID.
• A directory called 3DTouchTest: This directory contains a sample AIR application that uses the 3DTouch native extension.

The ActionScript contains touch3D class. This class provides the following public methods to the AIR application:

• public function addShortcutItem(shortcutItemType:String="",shortcutItemTitle:String=" ", shortcutItemSubtitle:String="",shortcutItemIconType:String=""):void
• public function enableForceTouch():void
• public function isSupported():Boolean
• public function init():void

The ActionScript developers need to use these methods to have the 3D Touch feature in their AIR apps. The AIR application can create many instances of the touch3D class. However, the touch3D class creates only one instance of the ExtensionContext class instance, that all the instances share.

To use the 3D Touch Air Native Extension, an AIR application does the following: 

The example given above uses all the methods that are available in touch3D class. These methods are explained below.

• touch.isSupported(): This method checks whether the 3DTouch feature is supported by the iOS device or not (currently Apple has provided support for this feature on iPhone 6s and iPhone 6s Plus models only). It returns the boolean value true if the device is supported, otherwise it returns false.
• touch.init(): This method is called to complete the initial requirements of the 3DTouch ANE. It will add the required event listener and also map to the init() method of native Library, used to dispatch events for static shortcut item.
• touch.addShortcutItem(): This method is used to add the shortcut items to the app icon. It contains the four parameters used to create a shortcut item. The parameters are:
  
  
  • shortcutItemType: A String that identifies the particular shortcut item. It should be unique for every item.
  • shortcutItemTitle: A String that represents the title of the shortcut item.
  • shortcutItemSubtitle: A String under the title of the shortcut item.
  • shortcutItemIconType: A String indicating the type of icon that developer want to be display next to the shortcut item. The supported Strings for icon display are:
    • UIApplicationShortcutIconTypeCompose
    • UIApplicationShortcutIconTypePlay
    • UIApplicationShortcutIconTypePause
    • UIApplicationShortcutIconTypeAdd
    • UIApplicationShortcutIconTypeLocation
    • UIApplicationShortcutIconTypeSearch
    • UIApplicationShortcutIconTypeShare
    • UIApplicationShortcutIconTypeProhibit
    • UIApplicationShortcutIconTypeContact
    • UIApplicationShortcutIconTypeHome
    • UIApplicationShortcutIconTypeMarkLocation
    • UIApplicationShortcutIconTypeFavorite
    • UIApplicationShortcutIconTypeLove
    • UIApplicationShortcutIconTypeCloud
    • UIApplicationShortcutIconTypeInvitation
    • UIApplicationShortcutIconTypeConfirmation
    • UIApplicationShortcutIconTypeMail
    • UIApplicationShortcutIconTypeMessage
    • UIApplicationShortcutIconTypeDate
    • UIApplicationShortcutIconTypeTime
    • UIApplicationShortcutIconTypeCapturePhoto
    • UIApplicationShortcutIconTypeCaptureVideo
    • UIApplicationShortcutIconTypeTask
    • UIApplicationShortcutIconTypeTaskCompleted
    • UIApplicationShortcutIconTypeAlarm
    • UIApplicationShortcutIconTypeBookmark
    • UIApplicationShortcutIconTypeShuffle
    • UIApplicationShortcutIconTypeAudio
    • UIApplicationShortcutIconTypeUpdate 

• touch.removeShortcutItem(): This method is used for removing the shortcut items from the app icon. It contains a single parameter that is shortcutItemType, which identifies the particular shortcut item that has to be removed. For example: touch.removeShortcutItem("com.shortcutProhibit");

• touch.enableForceTouch(): This method is specifically used for measuring the pressure sensitivity. Through this method, you can get the 'Force Percentage' (amount of pressure) that a user is applying on the device screen. To get value of Force Percentage applied, you need to add an event handler provided by the ANE, that is, touch.addEventListener(Touch3DEvent.PRESSURE,pressureStatus). You also need to write a response for the pressureStatus method call:

The images below show Force Percentage values 46.00 and 100.00 applied by the user on the app screen. 

• Touch3DEvent.SHORTCUT_ITEM: You need to add this event to get the status of shortcut items. It returns two values each for itemType and itemValue. The value for itemType should be the string SHORTCUT_ITEM and for itemValue it would be the string shortcutItemType. So, you can get to know which shortcut item the user has selected and decide what operations you need to perform for it. For example: touch.addEventListener(Touch3DEvent.SHORTCUT_ITEM,itemStatus);

Next, you need to write the response for the itemStatus method call. Add the following function: 

• Touch3DEvent.PRESSURE: You need to add this event to get the values for pressure variation. It returns the percentage value (ranging from 0 to 100) of the force applied by the user on the app screen. It return two values each for - itemType and itemValue. The value for itemType should be the string PRESSURE and for itemValue it would be a percentage value between 0 and 100. For example: touch.addEventListener(Touch3DEvent.PRESSURE,pressureStatus);

Next, you need to write the response for the pressureStatus method call. Add the following function: 

3D Touch ANE also supports static shortcut items, which can be added directly to the app descriptor. So, apart from using the dynamic method through addShortcutItem(), developers can also choose the static method to add the shortcut items. Users can see the static items before the first launch of the app, whereas dynamic items will be available only after the first launch.

A maximum of four shortcuts are supported by iOS. As such, if you use two static shortcuts in your descriptor, you can only add two additional dynamic shortcuts to the app.

Example: How to add static shortcut items in app descriptor?

The iOS native library is implemented in Objective C, using the native extension C API. The native library include the following methods:

• The extension initializer and finalizer are touch3DExtInitializer() and touch3DExtFinalizer().
• The context initializer and finalizer are touch3DContextInitializer() and touch3DContextFinalizer().
• The native methods used for creating the 3D Touch ANE are:
  • Init(): This method checks whether the app has been launched through the shortcut item or not. If it is launched through shortcut item, it dispatches the status event with the string values for that particular item.
  • addShortcutFunction(): This method is used to add the shortcut items. It gets the four parameters from ActionScript - shortcut item type, title, subtitle, and icon and passes them to UIMutableApplicationShortcutItem object.
  • enableForceTouch(): It maps to the custom touch handling event. From there, it gets the force applied by the user on the app screen and gets the force percentage by applying some metrics. At last, it dispatches the status event with the string value of Force Percentage.
  • isSupported(): This method is checks whether 3D Touch feature is supported on that iOS device or not. It return true if 3D Touch feature is supported, otherwise it returns false.

For more information about developing native extensions for Adobe AIR, see:

• Extending Adobe AIR
• Developing Native Extensions for Adobe AIR
• Adobe native extension samples

For more information about using a native extension in an AIR application, see:

• Using native extensions for Adobe AIR