Using the API
=============

Installation
-------------
The API can be imported in a React-Native project with the following line:

.. code-block:: js

	import { SCWS } from 'scwsapi-react';
	//or 
	import { SCWS, AndroidNfcOverlay } from 'scwsapi-react';

AndroidNfcOverlay is a class that can be used to mimic iOS NFC pop-up behavior on Android. See :ref:`nfcexample`.

When this is in the project source, the **scwsapi-react** package will be automatically installed when installing React-Native dependencies with NPM:

.. code-block:: bash

	npm install

To install the package directly, run

.. code-block:: bash

	npm install scwsapi-react

If the package was installed successfully, the source code can be found in **node_modules/scwsapi-react**. In particular the folder **node_modules/scwsapi-react/src** contains the source files that can be used in JavaScript. 

Inclusion in iOS project
------------------------

To include the API in a iOS project on XCode, a few additional steps must be done:

- add the framework **node_modules/scwsapi-react/ios/ScmApi.framework** to the project with drag and drop
- add the framework path in *Build Settings* / *Framework search paths*: ``$(PROJECT_DIR)/../node_modules/scwsapi-react/ios``
- in the project target, in *General*, in *Frameworks, libraries and Embedded Content*, select **Embed and Sign** for *ScmApi.framework*
    
Configure iOS app for NFC or Bluetooth usage
--------------------------------------------

In order to use the SCWSAPI NFC or Bluetooth capabilities, some configuration must be added to the application project on XCode:

NFC
'''
- The target application must include the Core NFC Framework.
- The target application must add NFC capabilities, and provide a non-empty string for the NFCReaderUsageDescriptionkey in its info.plist file. For the value, enter a string that describes the reason the app needs access to the device’s NFC reader.
- The target application must add the Near Field Communication Tag Reader Session Formats Entitlement to the entitlements file.
- The target application must contain list of application identifiers (AIDs) that may have to be selected. At the bare minimum, all AIDs declared in the EF.DIR of the cards to support should be declared, as well as the AID of the IAS application itself (in the case of a JavaCard implementation).

	- key: "ISO7816 application identifiers for NFC Tag Reader Session"
	- recommended values (depends on the card profile):

		- A000000077010800070000FE00000100
		- E828BD080FF2504F5420415750
		- E828BD080FD2504543432D654944
		- E828BD080FD25047656E65726963
		- E828BD080FA00000050450524F200204
		- A000000018800000000662

Bluetooth
'''''''''
- If the target application plans to use bluetooth smart card readers, it must add the Core Bluetooth Framework.
- If the target application plans to use bluetooth smart card readers, it must provide a non-empty string for the NSBluetoothAlwaysUsageDescription in its info.plist file. For the value, a message that tells the user why the application is requesting the ability to connect to Bluetooth peripherals.