React Native C8oSDK
TOC
- TOC
- Introduction
- Requirements
- Installation
- Linking
- Documentation
- Import libraries
- Initializing and creating a C8o instance for an Endpoint
- Advanced instance settings
- Calling a Convertigo requestable
- Call parameters
- Handling failures
- Writing the device logs to the Convertigo server
- Using the Local Cache
- Using the Full Sync
- Replicating Full Sync databases
- Full Sync FS_LIVE requests
- Api documentation
Introduction
This is the Convertigo provider for React Native
Convertigo Client SDK is a set of libraries used by mobile or Windows desktop applications to access Convertigo Server services. An application using the SDK can easily access Convertigo services such as Sequences and Transactions.
The Client SDK will abstract the programmer from handling the communication protocols, local cache, FullSync off line data managment, UI thread management and remote logging. So the developer can focus on building the application.
Client SDK is available for:
- Android Native apps as a standard Gradle dependency
- iOS native apps as a standard Cocoapod
- React Native as a NPM package
- Google Angular framework as typescript an NPM package
- Vue.js, ReactJS, AngularJS Framework as a standard Javascript NPM package
- Windows desktop or Xamarin apps as Nugets or Xamarin Components
Requirements
- npm 6.1.x | yarn 1.7.x
- react-native cli 2.0.x
- iOS
- Xcode 9.4
- Cocoapods 1.5.3
- Android
- Android Studio 3.1.x
Installation
Using npm:
npm install --save react-native-c8osdk
or using yarn:
yarn add react-native-c8osdk
Linking
react-native link react-native-c8osdk
Then for each platform:
iOS (via Cocoa Pods)
Add the following dependencies to your the target of your Podfile
pod 'SwiftyJSON', '4.0.0'
pod 'Alamofire', '4.7.2'
pod 'AEXML', '4.3.0'
Also append the following posinstall script to your Podfile
post_install do |installer|
# List of Pods to use as Swift 4.1
myTargets = ['SwiftyJSON', 'Alamofire', 'AEXML']
installer.pods_project.targets.each do |target|
if myTargets.include? target.name
target.build_configurations.each do |config|
config.build_settings['SWIFT_VERSION'] = '4.1'
end
end
end
end
This will configure your pods in the correct swift version.
Then run Pod install
Please be sure to use the workspace and not the project, so be sure to open Project.xcworkspace
Finnaly go to main's Project target => Build Phases => Link Binary with Libraries and add C8o.framework
Android
There is nothing more than the react-native cli link, mentioned above, to do for android
Documentation
Import libraries
import {C8oSettings, C8o, C8oLogLevel} from "react-native-c8osdk";
Initializing and creating a C8o instance for an Endpoint
C8o Object must first be instanciated and then can be initialized, with a endpoint string parameter
// Instanciate C8o
let c8o: C8o = new C8o();
// Init C8o instance with a given endpoint, for example:
c8o.init("http://c8o-dev.convertigo.net:80/cems/projects/ClientSDKtestig");
Advanced instance settings
The endpoint is the mandatory setting to get a C8o instance, but there is additional settings through the C8oSettings class.
A C8oSettings instance should be passed after the endpoint. Settings are copied inside the C8o instance.
Setters of C8oSettings always return its own instance and can be chained.
A C8oSettings can be instantiated from an existing C8oSettings or C8o instance.
// Instanciate C8oSettings
let settings = new C8oSettings();
// Add Settings properties
settings
.setTimeout(3000)
.setDefaultDatabaseName("myfullsyncDbName")
.setTrustAllCertificates(true)
.setLogLevelLocal(C8oLogLevel.TRACE);
// Instanciate C8o
let c8o: C8o = new C8o();
// Init C8o instance with a given endpoint and settings
c8o.init("http://c8o-dev.convertigo.net:80/cems/projects/ClientSDKtestig", settings);
Calling a Convertigo requestable
With a C8o instance you can call Convertigo Sequence and Transaction or make query to your local FullSync database.
The call method expects the requester string of the following syntax:
- For a transaction: [project].connector.transaction
- For a sequence: [project].sequence
The project name is optional, i.e. if not specified, the project specified in the endpoint will be used.
// Assuming c8o is a C8o instance properly instanciated and initiated as describe above, and '.login' is the name of a sequence of your project
let result = await this.c8o.callJson('.login');
Call parameters
Convertigo requestables generally needs key/value parameters encapsuled in a simple javascript object.
The key is always a string and the value can be any object but a string is the standard case.
// Assuming c8o is a C8o instance properly instanciated and initiated as describe above, and '.login' is the name of a sequence of your project
let result = await this.c8o.callJson('.login', {
login: "barnett.christine",
password: "mySuperPassword123"
});
Handling failures
A call can throw an error for many reasons: technical failure, network error and so on.
The standard try/catch should be used to handle this.
// Assuming c8o is a C8o instance properly instanciated and initiated as describe above, and '.login' is the name of a sequence of your project
try{
let result = await this.c8o.callJson('.login', {
login: "barnett.christine",
password: "mySuperPassword123"
});
}
catch(error){
// Do somthing with the error
}
Writing the device logs to the Convertigo server
- Not implemented yet
Using the Local Cache
- Not implemented yet
Using the Full Sync
Full Sync enables mobile apps to handle fully disconnected scenarios, still having data handled and controlled by back end business logic. See the presentation of the Full Sync architecture for more details.
Convertigo Client SDK provides a high level access to local data following the standard Convertigo Sequence paradigm. They differ from standard sequences by a fs:// prefix. Calling these local Full Sync requestable will enable the app to read, write, query and delete data from the local database:
- fs://.create creates the local database if not already exist
- fs://.view queries a view from the local database
- fs://.get reads an object from the local database
- fs://.post writes/update an object to the local database
- fs://.delete deletes an object from the local database
- fs://.all gets all objects from the local database
- fs://.sync synchronizes with server database
- fs://.replicate_push pushes local modifications on the database server
- fs://.replicate_pull gets all database server modifications
- fs://.reset resets a database by removing all the data in it
- fs://.put_attachment Puts (add) an attachment to a document in the database
- fs://.get_attachment Gets an attachment from a document
Where fs:// is the name of a specific FullSync Connector in the project specified in the endpoint. The fs:// name is optional only if the default database name is specified with the method setDefaultDatabaseName on the C8oSetting.
An application can have many databases. On mobile (Android, iOS and Xamarin based) they are stored in the secure storage of the application. On Windows desktop application, they are stored in the user AppData/Local folder, without application isolation.
All platforms can specify a local database prefix that allows many local database copies of the same remote database. Use the method setFullSyncLocalSuffix on the C8oSetting.
// Assuming c8o is a C8o instance properly instanciated and initiated as describe above.
// clear or create the "base" database
// resultReset mustbe equal to { "ok" : true }
let resultReset = await this.c8o.callJson('fs://base.reset');
// creates a new document on "base", with 2 key/value pairs
// resultPost mustbe equal to { "ok": true, "id": "6f1b52df","rev": "1-b0620371" }
let resultPost = await this.c8o.callJson('fs://base.post', {
firstname: "Jhonn",
lastname: "Doe"
});
// retrieves the complet document from its "docid"
// resultGet mustbe equal to { "lastname": "Doe", "rev": "1-b0620371", "firstname": "John", "_id": "6f1b52df" }
let resultGet = await this.c8o.callJson('fs://base.get', {
docid: resultPost['id']
});
Replicating Full Sync databases
FullSync has the ability to replicate mobile and Convertigo server databases over unreliable connections still preserving integrity. Data can be replicated in upload or download or both directions. The replication can also be continuous: a new document is instantaneously replicated to the other side.
The client SDK offers the progress event to monitor the replication progression thanks to a C8oProgress instance.
// Using the Native Event Emitter to fetch progress events
this.c8o.progress.notifications((progress)=>{
// Do stuff with the progress notifications
});
// Assuming c8o is a C8o instance properly instanciated and initiated as describe above.
let result = await this.c8o.callJson('fs://base.replication_pull');
Full Sync FS_LIVE requests
- Not implemented yet