Requirements
Prerequisite knowledge

Basic familiarity with building mobile apps on Adobe AIR, including familiarity with Adobe Native Extensions.
Required Adobe Products

Flash Builder (Download trial)
Required third-party products

iOS SDK
Xcode
User level

All
Sample files

3DTouch.zip (115 KB) 3D Touch native extension files with a sample AIR application.

 
Introduction

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.
The attached zip file contains:
  • 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 library

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.
 

 
Application usage

To use the 3D Touch Air Native Extension, an AIR application does the following: 
 
var touch:Touch3D = new Touch3D(); if(touch.isSupported()) { touch.init(); touch.addEventListener(Touch3DEvent.SHORTCUT_ITEM,itemStatus); touch.addEventListener(Touch3DEvent.PRESSURE,pressureStatus); touch.addShortcutItem("com.shortcutMail","Send Mail","For Sending Mails","UIApplicationShortcutIconTypeMail"); touch.addShortcutItem("com.shortcutProhibit","Prohibit Item","Show Prohibited Screen","UIApplicationShortcutIconTypeProhibit"); touch.enableForceTouch(); }
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 
3D Touch shortcut items on AIR App icon
Fig 1. Shortcut items on AIR App icon
Fig 2. App launched through 3D Touch shortcut item
Fig 2. App launched through shortcut item
  • 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:
protected function pressureStatus (event: Touch3DEvent):void { var pressureValue:String = "Pressure Value: "+event.itemType+" "+event.itemValue; }
The images below show Force Percentage values 46.00 and 100.00 applied by the user on the app screen. 
 
3D Touch Pressure sensitivity with Force Percentage of 46.00.
Figure 3: Pressure sensitivity with Force Percentage of 46.00.
3D Touch Pressure sensitivity with Force Percentage of 100.00.
Figure 4: Pressure sensitivity with Force Percentage of 100.00.
  • 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: 
 
protected function itemStatus(event:Touch3DEvent):void { textTitle.text = event.itemType; textLabel.text = "Launched through shortcut item, "+ event.itemValue; }
  • 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: 
 
protected function pressureStatus(event:Touch3DEvent):void { textTitle.text = event.itemType; textLabel.text = "Pressure value is: "+ event.itemValue; }
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?
 
<iPhone> <InfoAdditions><![CDATA[ <key>UIDeviceFamily</key> <array> <string>1</string> <string>2</string> </array> <key>UIApplicationShortcutItems</key> <array> <dict> <key>UIApplicationShortcutItemIconFile</key> <string>open-favorites</string> <key>UIApplicationShortcutItemTitle</key> <string>No Icon Screen</string> <key>UIApplicationShortcutItemType</key> <string>com.shortcut</string> <key>UIApplicationShortcutItemUserInfo</key> <dict> <key>key1</key> <string>value1</string> </dict> </dict> <dict> <key>UIApplicationShortcutItemIconType</key> <string>UIApplicationShortcutIconTypeCompose</string> <key>UIApplicationShortcutItemTitle</key> <string>Compose Mail</string> <key>UIApplicationShortcutItemType</key> <string>com.shortcutCompose</string> <key>UIApplicationShortcutItemUserInfo</key> <dict> <key>key2</key> <string>value2</string> </dict> </dict> </array> ]]></InfoAdditions> <requestedDisplayResolution>high</requestedDisplayResolution> </iPhone>

 
The iOS native library

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.

 
Where to go from here

For more information about developing native extensions for Adobe AIR, see:
 
For more information about using a native extension in an AIR application, see: