Merge pull request #24 from volodymyrtaliar/master

BlackBerry Dynamics SDK for React Native v10.1 changes

README.md

@@ -3,37 +3,43 @@ This page provides an overview on how to use the BlackBerry Dynamics SDK for Rea
 
 # Supportability
 #### Development environment
- - Mac OS X
+ - Mac OS
  - Windows 10 (Android only)
 #### Node.js
- - 12.x
+ - 12.x (for React Native version < 0.68.0)
+ - 14.x (for React Native version >= 0.68.0)
 #### Package manager
  - yarn
 #### React Native
- - 0.63.x (deprecated)
- - 0.64.x
- - 0.65.x
- - 0.66.x (0.66.1 is latest supported)
+ - 0.64.x (deprecated)
+ - 0.65.x (deprecated)
+ - 0.66.x
+ - 0.67.x
+ - 0.68.x (0.68.2 is latest supported)
 #### iOS
- - Xcode 12+
+ - Xcode 12, 13
  - iOS 13, 14, 15
- - cocoapods 1.10.1+
+ - cocoapods 1.10.2+
 #### Android
- - Android 8+, API 26+
+ - Java 8 (for React Native version < 0.68.0)
+ - Java 11 (for React Native version >= 0.68.0)
+ - Android 9+, API 28+
  - NDK 20.1.5948944 (for React Native version < 0.66.0)
  - NDK 21.4.7075529 (for React Native version >= 0.66.0)
 #### BlackBerry Dynamics
- - BlackBerry Dynamics SDK for iOS v9.2 and v10.0, check environment requirements [here](https://docs.blackberry.com/en/development-tools/blackberry-dynamics-sdk-ios/).
- - BlackBerry Dynamics SDK for Android v9.2 and v10.0, check environment requirements [here](https://docs.blackberry.com/en/development-tools/blackberry-dynamics-sdk-android/).
+ - BlackBerry Dynamics SDK for iOS v10.2, check environment requirements [here](https://docs.blackberry.com/en/development-tools/blackberry-dynamics-sdk-ios/).
+ - BlackBerry Dynamics SDK for Android v10.2, check environment requirements [here](https://docs.blackberry.com/en/development-tools/blackberry-dynamics-sdk-android/).
 #### BlackBerry Dynamics Launcher
- - BlackBerry Dynamics Launcher library for iOS v3.3, check details [here](https://docs.blackberry.com/en/development-tools/blackberry-dynamics-launcher-framework-for-ios).
- - BlackBerry Dynamics Launcher library for Android v3.3, check details [here](https://docs.blackberry.com/en/development-tools/blackberry-dynamics-launcher-framework-for-android).
+ - BlackBerry Dynamics Launcher library for iOS v3.4, check details [here](https://docs.blackberry.com/en/development-tools/blackberry-dynamics-launcher-framework-for-ios).
+ - BlackBerry Dynamics Launcher library for Android v3.4, check details [here](https://docs.blackberry.com/en/development-tools/blackberry-dynamics-launcher-framework-for-android).
 
 # Features
 #### Integration with BlackBerry Dynamics
 Integration of BlackBerry Dynamics SDK for iOS and Android into React Native application is supported by addition of the `BlackBerry-Dynamics-for-React-Native-Base` module.
 ###### "Dynamic Framework" integration on iOS
 Dynamics SDK for React Native v9.0 and above integrates with the iOS "Dynamic Framework" version of BlackBerry Dynamics. The static library integration is no longer supported.
+#### Application configuration and app-specific policy
+`BlackBerry-Dynamics-for-React-Native-Application` module provides access to information that is globally available to any BlackBerry Dynamics Application. The module provides API to read Dynamcis application configuration and app-specific policy.
 #### Secure connectivity
 - Both `XMLHttpRequest` and `fetch` are secured in scope of `BlackBerry-Dynamics-for-React-Native-Networking` module.
 - `<WebView />` is secured in scope of `BlackBerry-Dynamics-for-React-Native-WebView` UI component.
@@ -81,6 +87,7 @@ More details can be found [here](https://docs.blackberry.com/en/development-tool
 # Package contents
 #### Modules
 - `BlackBerry-Dynamics-for-React-Native-Base` - automatically integrates BlackBerry Dynamics SDK for iOS and Android into React Native application
+- `BlackBerry-Dynamics-for-React-Native-Application` - provides API to read Dynamcis application configuration and app-specific policy
 - `BlackBerry-Dynamics-for-React-Native-Networking` - secures `XMLHttpRequest`, `fetch` and `WebSocket` APIs. For more details please refer to [networking](https://facebook.github.io/react-native/docs/network) topic in React Native.
 - `BlackBerry-Dynamics-for-React-Native-SQLite-Storage` - secures SQLite DB usage. It is based on [react-native-sqlite-storage](https://github.com/andpor/react-native-sqlite-storage) 3rd party module.
 - `BlackBerry-Dynamics-for-React-Native-Async-Storage` - secures built-in [AsyncStorage](https://facebook.github.io/react-native/docs/asyncstorage#docsNav).
@@ -99,11 +106,12 @@ More details can be found [here](https://docs.blackberry.com/en/development-tool
 - `ClipboardTestApp` - demonstrates usage of [Clipboard](https://facebook.github.io/react-native/docs/clipboard) API in terms of Data Leakage Prevention. It is possible to change DLP policy on UEM and see how it affects the clipboard within the application. If DLP is on, it will not be possible to copy clipboard data from "Dynamics" application to "non-Dynamics" application and vice-versa.
 - `DLP` - demonstrates usage of `<Text />` and `<TextInput />` UI components together with DLP policy option on UEM. If DLP is on, it will not be possible to do cut-copy-paste operations over data from "Dynamics" to "non-Dynamics" application and vice-versa.
 - `SQLite` - shows example of using secure SQLite DB instance in React Native application.
-- `UnitTests` - runs Jasmine unit tests for `fetch`, `XMLHttpRequest`, `Clipboard`, `AsyncStorage`, `AppKinetics` and `SQLite` in React Native application.
+- `UnitTests` - runs Jasmine unit tests for `fetch`, `XMLHttpRequest`, `WebSocket`, `Clipboard`, `AsyncStorage`, `AppKinetics`, `Application`, `Launcher`, `FileSystem` and `SQLite` in React Native application.
 - `WebViewBrowser` - demonstrates usage of `<WebView />` UI component in React Native application.
 - `FileSystem` - shows example of using secure FileSystem instance in React Native application. It demonstrates how to manage files/directories and how to upload/download files.
 - `AppKinetics` - shows example of using AppKinetics functionality.
-- `WebSockets` - contains `WebSocketClient` and `WebSocketServer` sample apps. It demonstrates usage of secure `WebSocket` API - how to establish connection to WebSocket server using `ws://` or `wss://` protocols, how to send or receive text or binary data over WebSocket connection, how to close WebSocket connection. 
+- `WebSockets` - contains `WebSocketClient` and `WebSocketServer` sample apps. It demonstrates usage of secure `WebSocket` API - how to establish connection to WebSocket server using `ws://` or `wss://` protocols, how to send or receive text or binary data over WebSocket connection, how to close WebSocket connection.
+- `Policy` - shows example of using Application module functionality, reads Dynamcis application configuration and app-specific policy.
 
 ## Preconditions
 Make sure you first setup your environment and install BlackBerry Dynamics.
@@ -125,13 +133,14 @@ To setup, build and run the sample applications please refer to the README for e
 - [FileSystem](./SampleApplications/FileSystem/README.md)
 - [AppKinetics](./SampleApplications/AppKinetics/README.md)
 - [WebSockets](./SampleApplications/WebSockets/README.md)
+- [Policy](./SampleApplications/Policy/README.md)
 
 ### Integrate into new React Native application
 To integrate BlackBerry Dynamics into a new React Native application please follow these [steps](./modules/BlackBerry-Dynamics-for-React-Native-Base/README.md#installation).
 
 ### Integrate into existing React Native application
 To integrate BlackBerry Dynamics into existing React Native application:
- - Check you are using `0.64.x` version of React Native.
+ - Check you are using `0.66.x` or higher version of React Native.
 
       - [React Native Upgrade Helper](https://react-native-community.github.io/upgrade-helper/) may be used to upgrade your application prior to integrating BlackBerry Dynamics. Confirm the application builds and works correctly after upgrade.
 
@@ -153,10 +162,29 @@ To integrate BlackBerry Dynamics into existing React Native application:
      - If `<TextInput />` UI component is used you can secure cut/copy/paste operations by adding `BlackBerry-Dynamics-for-React-Native-TextInput` UI component. See [TextInput UI component](./ui-components/BlackBerry-Dynamics-for-React-Native-TextInput/README.md).
      - If `<WebView />` UI component is used you can secure resource loading within WebView by adding `BlackBerry-Dynamics-for-React-Native-WebView` UI component. See [WebView UI component](./ui-components/BlackBerry-Dynamics-for-React-Native-WebView/README.md).
 
+ - Use other Dynamics React Native modules.
  - Lastly, do not forget to update the imports in your code.
 
 ## Limitations
 ### Flipper is disabled on iOS
 Flipper cannot be used together with BlackBerry Dynamics SDK for React Native on iOS in debug configuration as it disables some BlackBerry Dynamics functionality related to secure networking.
 Flipper is disabled on iOS by default. If your Dynamics React Native application on iOS does not use Secure Connectivity feature (`BlackBerry-Dynamics-for-React-Native-Networking` module) you can enable Flipper by uncommenting `use_flipper!()` line in `Podfile` of your application.
 
+## Known issues
+### Conflict between default and secure SQLite library on iOS
+BlackBerry Dynamcis SDK for iOS uses secure *SQLite* library to provide secure DB connection and management.
+Many standard and 3rd party modules use default *SQLite* library.
+When both default and secure *SQLite* libraries are linked to the project it causes conflict with unpredictable behavior.
+##### Example: react-native-webrtc
+Let's consider a concrete example:
+**`BlackBerry-Dynamics-for-React-Native-Base`** - is main module from **BlackBerry Dynamics SDK for React Native** that integrates BlackBerry Dymamics into React Native application. BlackBerry Dymamics, in turn, provides secure *SQLite* dependency to the project.
+**`BlackBerry-Dynamics-for-React-Native-SQLite-Storage`** - module from **BlackBerry Dynamics SDK for React Native** that provides secure DB connection and management.
+**`react-native-webrtc`** links default *SQLite* library in the project. This is an extract of its podspec:
+```
+s.libraries           = 'c', 'sqlite3', 'stdc++'
+```
+When the project is compiled and run DB functionality works incorrectly.
+> NOTE: There can be more of such cases when to use **BlackBerry Dynamics SDK for React Native** module and some other module that links default SQLite library in Pods. The workaround below can be used to fix the issue.
+
+##### Workaround
+To resolve the conflict **`sqlite3`** dependency should be removed in *<app>/node_modules/react-native-webrtc/react-native-webrtc.podspec*. Then, do **"pod install"** again. This should not break anything as secured **`sqlite3`** dependency will remain linked to the project.

SampleApplications/AppKinetics/README.md

@@ -1,24 +1,63 @@
 ## AppKinetics sample application
-> AppKinetics sample application shows example of using AppKinetics functionality.
+The AppKinetics sample application demonstrates:
+ - Service discovery (using **`transfer-file`** service).
+ - Sending files **to** other Dynamics applications (consumption of **`transfer-file`** service).
+ - Receive files **from** other Dynamics applications (providing **`transfer-file`** service).
+ - Compose secure emails with attachments and send them via **BlackBerry Work**.
 
-#### How to prepare the app
+## Required configuration on UEM
+In order to be able to send files to other Dynamics application the appropriate app should be properly configured on UEM and act as a service provider of **`transfer-file`** service.
+List of Dynamics application-based services can be found [here](https://marketplace.blackberry.com/services).
+
+Some Dynamics apps are already configured on UEM and have functionality to show files contents, such as:
+ - BlackBerry Work available on Apple App Store and Google Play Market
+ - Dynamics AppKinetics for [iOS](https://get.good.com/samples/ios/com.good.gd.example.appkinetics.zip) and [Android](https://get.good.com/samples/android/AppKinetics.zip)
+ - Dynamics Cordova AppKinetics Server - part of Dynamics SDK for Cordova that can be downloaded [here](https://developers.blackberry.com/us/en/resources/downloads)
+ - Dynamics Ionic-Cordova Secure-ICC available on [BlackBerry GitHub](https://github.com/blackberry/BlackBerry-Dynamics-Cordova-Samples/tree/master/Secure-ICC)
+ - Dynamics Ionic-Capacitor Secure-ICC available on [BlackBerry GitHub](https://github.com/blackberry/BlackBerry-Dynamics-Cordova-Samples/tree/master/Secure-ICC-Ionic-Capacitor-Angular)
+
+Any app from the list can be added to your user's allowed apps list on UEM and activated.
+
+#### Enable service discovery
+Any other Dynamics application can be configured and be able to act as a service provider of **`transfer-file`** service and receive files:
+1. Navigate to the "Apps" Tab
+2. Select "+"
+3. Select "Internal BlackBerry Dynamics App"
+4. Input your `GDApplicationID` / `GDApplicationVersion` from `Info.plist`
+5. Save
+6. Under `version` select the "+" option
+7. **Bind** the required services to the application
+	Select the services that the app is going to use. Enabling these in UEM ensures that other Dynamics apps can discover this app as a service provider.
+    **Examples of services:**
+	- `Transfer Multiple Files Service`
+	- `Email Message`
+	- `Transfer File Service`
+	**NOTE**: _If you do not enable **`transfer-file`** service in UEM for your Dynamics app, the AppKinetics sample will not fully function as it will not discover it as app that can receive files._
+8. Go to the "Users" Tab
+9. Assign your newly configured app to your user
+10. Proceed with activation
+
+## How to prepare the app
 Open the sample app directory in Terminal window:
 `$ cd <path>/SampleApplications/AppKinetics`
 
 Install dependencies:
 `$ yarn`
 
-> NOTE: AppKinetics sample is based on `0.64.2` version of React Native. There is a possibility to upgrade to `0.65.0`, `0.65.1` or `0.66.0`, `0.66.1` versions by running following command:
+NOTE: AppKinetics sample is based on `0.66.4` version of React Native. There is a possibility to upgrade to `0.67.x` or `0.68.x` versions (`0.67.0` - `0.67.4`, `0.68.0` - `0.68.2`) by running one of following commands:
 `$ react-native upgrade 0.6x.x`
 for example:
-`$ react-native upgrade 0.65.1`
+`$ react-native upgrade 0.67.4`
 or
-`$ react-native upgrade 0.66.1`
+`$ react-native upgrade 0.68.2`
+
+Generate ios and android directories:
+`$ react-native eject`
 
 Generate ios and android directories:
 `$ react-native eject`
 
-## Dynamics modules
+## Install Dynamics modules
 #### Prerequisites
 There are some dependencies that need to be installed before using `BlackBerry-Dynamics-for-React-Native-Base` module. More information can be found [here](https://github.com/blackberry/BlackBerry-Dynamics-React-Native-SDK/tree/master/modules/BlackBerry-Dynamics-for-React-Native-Base#Preconditions).
 
@@ -31,7 +70,9 @@ There are some dependencies that need to be installed before using `BlackBerry-D
 
 > Allows to update an identifier (required) and name (optional) for your application. This identifier is your iOS Bundle ID or Android Package Name. It will also be used as the Entitlement ID for entitling and activating your application with the BlackBerry UEM management console.
 
-#### How to secure AppKinetics communication
+It is suggested to use **`com.blackberry.bbd.example.cdv.appkinetics.server`** here. An app with this ID (`Dynamics Cordova AppKinetics Server` sample app) is already configured on UEM as a service provider of **`transfer-file`** service, so it can receive files.
+
+#### How to enable ICC communication
 	$ yarn add <path>/modules/BlackBerry-Dynamics-for-React-Native-AppKinetics
 
 ##### iOS
@@ -46,13 +87,62 @@ There are some dependencies that need to be installed before using `BlackBerry-D
 ##### Android
 `$ react-native run-android`
 
-#### Examples of usage
-##### 0.64.2
+#### How to secure FileSystem
+	$ yarn add <path>/modules/BlackBerry-Dynamics-for-React-Native-FileSystem
+
+`FileSystem` module is dependent on `Networking` module, so we need to install it as well:
+
+    $ yarn add <path>/modules/BlackBerry-Dynamics-for-React-Native-Networking
+
+##### iOS
+`$ cd ios`  
+`$ pod install`  
+`$ cd ..`  
+
+#### How to run application
+##### iOS
+`$ react-native run-ios`
+
+##### Android
+`$ react-native run-android`
+
+## Prepare files that will be sent to other app
+In order to send files to other Dynamics applications files need to be stored in appropriate location.
+#### Android
+_`BlackBerry_Dynamics_SDK_for_React_Native_vX.X.X.X/SampleApplications/AppKinetics/android/app/src/main/assets/data`_
+#### iOS
+_`BlackBerry_Dynamics_SDK_for_React_Native_vX.X.X.X/SampleApplications/AppKinetics/ios/AppKinetics/data`_
+Also, open the app in Xcode and drag-n-drop **`data`** folder (from _`AppKinetics/ios/AppKinetics/data`_) to **`AppKinetics`** group so it is recognized as part of the project.
+
+Files then will be copied to secure container using **`copyFilesToSecureStorage`** API from `AppKinetics` module and can be transfered to other Dynamics application that is a service provider of **`transfer-file`** service.
+
+## Enable Keychain Sharing on iOS
+Both Dynamics apps that participate in Inter-Container Communication (ICC) must share the same **`com.good.gd.data`** Keychain group and have **`com.good.gd.discovery.good`** URL scheme set.
+#### Configure service consumer
+Dynamics React Native AppKinetics sample can act as service consumer of **`transfer-file`** service, in other words, it can send files to other Dynamics apps. For this to be done let's enable **`com.good.gd.data`** Keychain group and set **`com.good.gd.discovery.good`** URL scheme:
+1. Open `BlackBerry_Dynamics_SDK_for_React_Native_vX.X.X.X/SampleApplications/AppKinetics/ios/AppKinetics.xcworkspace` in Xcode
+2. Go `Signing & Capabilities` to tab
+3. Click `+` and search for `Keychain Sharing` capability
+4. Add **`com.good.gd.data`** Keychain group
+5. Go `Info` to tab
+6. Expand `URL types` section
+7. Add **`com.good.gd.discovery.good`** URL scheme
+
+#### Configure service provider
+Native Dynamics AppKinetics sample is a service provider of **`transfer-file`** service, in other words, it can receive files from other Dynamics apps. For this **`com.good.gd.data`** Keychain group and **`com.good.gd.discovery.good`** URL scheme should be configured as well:
+1. Download and unzip [native AppKinetics sample for iOS](https://get.good.com/samples/ios/com.good.gd.example.appkinetics.zip).
+2. Open `<path>/com.good.gd.example.appkinetics/AppKinetics.xcodeproj` in Xcode
+3. Do steps **2. - 7.** from the section above
+4. Install and activate
+
+## Examples of usage
+##### 0.66.4
 `$ cd <path>/SampleApplications/AppKinetics`  
 `$ yarn`  
 `$ react-native eject`  
 `$ yarn add <path>/modules/BlackBerry-Dynamics-for-React-Native-Base`  
 `$ yarn set-bundle-id`  
+It is suggested to use **`com.blackberry.bbd.example.cdv.appkinetics.client`** here. An app with this ID is already configured on UEM as a service provider of **`transfer-file`** service, so it can both send and receive files.
 `$ yarn add <path>/modules/BlackBerry-Dynamics-for-React-Native-AppKinetics`  
 `$ yarn add <path>/modules/BlackBerry-Dynamics-for-React-Native-FileSystem`  
 `$ yarn add <path>/modules/BlackBerry-Dynamics-for-React-Native-Networking`  
@@ -63,14 +153,15 @@ For iOS:
 `$ react-native run-ios`  
 For Android:  
 `$ react-native run-android`
-##### 0.65.1
+##### 0.68.2
 `$ cd <path>/SampleApplications/AppKinetics`  
 `$ yarn`  
 `$ cd .. ; git init ; cd AppKinetics`  
-`$ react-native upgrade 0.65.1`  
+`$ react-native upgrade 0.68.2`  
 `$ react-native eject`  
 `$ yarn add <path>/modules/BlackBerry-Dynamics-for-React-Native-Base`  
-`$ yarn set-bundle-id`  
+`$ yarn set-bundle-id`
+It is suggested to use **`com.blackberry.bbd.example.cdv.appkinetics.client`** here. An app with this ID is already configured on UEM as a service provider of **`transfer-file`** service, so it can both send and receive files.
 `$ yarn add <path>/modules/BlackBerry-Dynamics-for-React-Native-AppKinetics`  
 `$ yarn add <path>/modules/BlackBerry-Dynamics-for-React-Native-FileSystem`  
 `$ yarn add <path>/modules/BlackBerry-Dynamics-for-React-Native-Networking`