1iOS 2=== 3This chapter deals with the iOS specific properties of the AusweisApp2 SDK. 4The AusweisApp2 core is encapsulated into an **XCFramework** which needs to 5be linked into your application. 6 7Subsequent sections deal with the SDK interface itself and explain which 8steps are necessary in order to talk to the AusweisApp2 SDK. 9 10.. important:: 11 Apple released the necessary NFC API with iOS 13.0! 12 Be aware that it is not possible to support older versions. 13 14 15 16Use XCFramework 17--------------- 18The interface ``AusweisApp2.h`` of the SDK for iOS is provided as **C-Header** 19that you need to import/include into your application. It grants access to 20start and shutdown a separate background thread with the integrated 21AusweisApp2 core. 22 23After you established a connection to the AusweisApp2 SDK your application 24can send :doc:`commands` and receive :doc:`messages`. 25 26 27Clone 28^^^^^ 29The XCFramework is provided in our github repository. It is recommended 30to use at least Xcode 12 and the dependency handling of at 31least Swift 5.3 (Swift Package Manager). 32 33 https://github.com/Governikus/AusweisApp2-SDK-iOS 34 35You can clone and add that repository with Xcode and import it into your 36project under the following menu. 37 38 :menuselection:`File --> Swift Packages --> Add Package Dependency` 39 40 41Import 42^^^^^^ 43After you added the repository to your Xcode project you can import the 44module via ``import AusweisApp2`` in Swift classes or ``@import AusweisApp2;`` 45in Objective-C classes and call the functions of the ``AusweisApp2.h`` header. 46 47.. code-block:: c 48 49 typedef void (* AusweisApp2Callback)(const char* pMsg); 50 bool ausweisapp2_init(AusweisApp2Callback pCallback); 51 void ausweisapp2_shutdown(void); 52 bool ausweisapp2_is_running(void); 53 void ausweisapp2_send(const char* pCmd); 54 55First, you need to define a callback function that will be called by the AusweisApp2 56to request or provide additional information. If your application initializes the 57SDK you must pass that callback to ``ausweisapp2_init``. That function will return 58``false`` if the callback is ``NULL`` or the SDK is already running. 59 60After you called that function the AusweisApp2 SDK will start up. If the 61initialization is finished the SDK calls your callback function once with 62``NULL`` as parameter to indicate that it is ready to accept :doc:`commands`. 63Do not call ``ausweisapp2_send`` until your callback received that message, otherwise 64that command will be ignored. 65 66Once the SDK is ready to go you can send :doc:`commands` by ``ausweisapp2_send``. 67Your callback will receive the :doc:`messages`. 68 69If you call ``ausweisapp2_shutdown`` the AusweisApp2 SDK will be terminated. This 70function joins the thread of the AusweisApp2 and blocks until the AusweisApp2 is 71finished. You should not call this function in your callback as it is called 72by the AusweisApp2 thread. In that case ``ausweisapp2_shutdown`` cannot be a 73blocking call to avoid a deadlock. 74If you call this function while a workflow is running the workflow will be 75canceled automatically before the shutdown. 76 77 78.. important:: 79 Your callback will be called by the separate AusweisApp2 thread. Do **not** 80 make long running or blocking calls! It is recommended to use an async dispatcher. 81 82 Also, you should not call ``ausweisapp2_send`` or ``ausweisapp2_shutdown`` within 83 your callback function. 84 85 86 87Info.plist 88---------- 89You need to enable the card identifier in your applications ``Info.plist`` like this, 90otherwise iOS will not recognize any identity cards. Also, it is necessary to provide 91a message why your application needs access to the NFC hardware. 92 93.. code-block:: xml 94 95 <key>com.apple.developer.nfc.readersession.iso7816.select-identifiers</key> 96 <array> 97 <string>E80704007F00070302</string> 98 </array> 99 100 <key>NFCReaderUsageDescription</key> 101 <string>AusweisApp2 needs NFC to access the ID card.</string> 102 103 104.. seealso:: 105 106 * https://developer.apple.com/documentation/bundleresources/information_property_list/select-identifiers 107 * https://developer.apple.com/documentation/bundleresources/information_property_list/nfcreaderusagedescription 108 109 110 111Entitlements 112------------ 113Your application needs to provide an entitlement file to request the format 114of reader sessions. 115 116.. code-block:: xml 117 118 <?xml version="1.0" encoding="UTF-8"?> 119 <!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd"> 120 <plist version="1.0"> 121 <dict> 122 <key>com.apple.developer.nfc.readersession.formats</key> 123 <array> 124 <string>TAG</string> 125 </array> 126 </dict> 127 </plist> 128 129.. seealso:: 130 131 https://developer.apple.com/documentation/bundleresources/entitlements/com_apple_developer_nfc_readersession_formats 132 133 134 135Logging 136------- 137 138The AusweisApp2 uses default logging of iOS and has its own log file. 139It is **recommended** to collect that log file if an error occurs in 140your application to receive better support. 141 142The log file is in your application path: 143 144.. code-block:: text 145 146 NSTemporaryDirectory() + /AusweisApp2.XXXXXX.log 147 148The *XXXXXX* characters will be replaced by an automatically generated 149portion of the filename to avoid conflicts with previous instances. 150 151A new log file will be created for each new instance of the AusweisApp2 and 152will be deleted after a correct shutdown. 153In case of old or multiple log files, it is highly probable that the 154previous instance crashed. 155 156The AusweisApp2 deletes any log files that are older than 14 days. 157