conichiSDK for iOS
Meta
- Point People: @David-Henner
- Point People: @ShengHuaWu
- Point People: @vincentjacquesson
Overview
conichiSDK
for iOS is a tool that allows users to be recognized around the Beacon through Bluetooth Low Energy (BLE). Operated as a Software-as-a-Service (SaaS) solution, conichi’s features focus on personal guest recognition, fast-forwarding check-in, enabling mobile payment (thus check-out), identifying personal preferences, rewarding loyalty.
Kits
conichiSDK
is following the idea of splitting functionality into different modules (so called kit
) and now there are 6 modules available.
- CNISDKCoreKit - provides beacon recognition, simple check-in/check-out, and guest personalization
- CNISDKPaymentKit - provides abstract layer for managing of payment instruments, checkout request with payment
- CNISDKPaylevenKit - provides abstract layer for managing payment through Payleven
- CNISDKSumUpKit - provides abstract layer for managing payment through SumUp
- CNISDKGeoFencingKit - provides conichi's venues tracking by apple geofencing
- CNISDKPMSKit - provides mobile check-in/check-out with property management system integration
Getting Started
Installation
Install as a framework
To use Conichi SDK
, head on over to the releases page, and download the Frameworks.zip
. Extract the zip file and drag and drop all frameworks to the Project target -> general -> Embedded Binaries
.
Install via CocoaPods
The preferred way to integrate CNISDKCoreKit
is via CocoaPods
. Add the following lines to your Podfile
:
source 'git@github.com:CocoaPods/Specs.git'
use_frameworks!
target 'your_tagret' do
pod 'CNISDKCoreKit'
end
Run pod install
, and you should now have the latest CNISDKCoreKit
release.
Install via Carthage
To integrate CNISDKCoreKit
via Carthage add the following line to your Cartfile
:
github "conichiGMBH/conichi-ios-sdk"
Run carthage update
, and you should now have the latest version of CNISDKCoreKit
in your Carthage folder.
Partial Installation
Following the links below you can find the instructions in the Getting Started section on how to install a specific kit
:
Update info plist
Then, you must add the NSLocation
keys to your project’s Info.plist containing the message to be prompted to the user.
<key>NSLocationAlwaysAndWhenInUseUsageDescription</key>
<string>This app needs your location so you can be recognized in conichi Hotels</string>
<key>NSLocationAlwaysUsageDescription</key>
<string>This app needs your location so you can be recognized in conichi Hotels</string>
<key>NSLocationUsageDescription</key>
<string>This app needs your location so you can be recognized in conichi Hotels</string>
<key>NSLocationWhenInUseUsageDescription</key>
<string>This app needs your location so you can be recognized in conichi Hotels</string>
Be careful, if you decide not to use all the keys, The app may not work properly. If you wish to know why those keys are necessary, you can check out this link
If you're going to use our development
or staging
environment, you'll need to add the following lines to your info.plist
<key>NSAppTransportSecurity</key>
<dict>
<key>NSAllowsArbitraryLoads</key>
<true/>
</dict>
Enable some capabilities
Conichi cares about the security and therefore the SDK stores the authorization information in the iOS Keychain, but to be able to read and write values even if the SDK is not running, iOS system requires the Keychain Sharing
capability.
Target -> Capabilities -> Keychain Sharing - Turn the switch On
.
Initialization
Example below shows the simplest setup for conichiSDK CoreKit
that points to our development
server.
Objective-C
//Create a configuration for the sdk instance
CNISDKConfiguration *configuration = [CNISDKConfiguration configurationWithBlock:^(id<CNISDKMutableConfiguration> \_Nonnull mutableConfiguration) {
mutableConfiguration.logLevel = CNISDKLogLevelInfo;
mutableConfiguration.apiKey = @"your-api-key";
mutableConfiguration.apiSecret = @"your-api-secret";
mutableConfiguration.kits = @[ ];
mutableConfiguration.environment = CNISDKEnvironmentDevelopment;
}];
//Setups the sdk delegate - it can be any object that conforms to CNISDKDelegate protocol
id<CNISDKDelegate> delegate = [self yourMethodToSetupSDKDelegate];
//Start the sdk with the given configuration
[CNISDK startWithConfiguration:configuration delegate:delegate];
Swift
//Create configuration for the sdk instance
let config: CNISDKConfiguration = CNISDKConfiguration() {
(mutableConfig: CNISDKMutableConfiguration) in
mutableConfig.logLevel = CNISDKLogLevel.info
mutableConfig.apiKey = "your-api-key"
mutableConfig.apiSecret = "your-api-secret"
mutableConfig.kits = []
mutableConfig.environment = CNISDKEnvironment.development
}
//Setups the sdk delegate - make sure that you conform to the CNISDKDelegate protocol
let delegate: CNISDKDelegate = self
//Start the sdk with given configuration
CNISDK.start(with: config, delegate: delegate)
After this setup you have an access to the instance of the [CNISDK sharedInstance]
in Obj-C or CNISDK.sharedInstance()
in Swift.
Authorization
To start any real actions with the guest, the sdk
requires the guest to be authorized. All methods related to authorization
are in CNISDKAPIManager+Authentication
category. The example below shows how to do a sign up for a new guest.
Objective-C
//Create a sign up request
CNISDKSignUpRequestInfo *info = [[CNISDKSignUpRequestInfo alloc] init];
info.firstName = @"Jenessa";
info.lastName = @"Gretta";
info.email = @"jenessa.gretta@gmail.com";
info.password = @"strongestpasswordever=)";
//Perform sign up
[CNISDKAPIManager manager] signUpWithRequest:info completion:^(CNISDKGuest *guest, NSError *error){
if (error) {
//handle error during the sign up
}
else {
//handle authorized guest
}
}];
Swift
// Create a signup request
let info = CNISDKSignUpRequestInfo()
info.firstName = "Jenessa"
info.lastName = "Gretta"
info.email = "jenessa.gretta@gmail.com"
info.password = "strongestpasswordever=)"
// Instantiate APImanager
let apiManager = CNISDKAPIManager()
// Perform signup
apiManager.signUp(withRequest: info) {
(guest, error) in
if let error = error {
//handle error during the sign up
return
}
//handle authorized guest
}
You can also use the CNISDKExternalSignUpRequestInfo
object to provide an external ID instead of the email
password
combination and perform the signup by using - (void)signUpWithExternalIDRequestInfo:(CNISDKExternalSignUpRequestInfo *)requestInfo completion:(nullable CNISDKGuestErrorBlock)completion;
Monitoring
If the guest is authorized, the following code will enable beacon monitoring
Objective-C
[[CNISDK sharedInstance] startMonitoring];
Swift
CNISDK.sharedInstance().startMonitoring()
Now, when a guest gets in range of a conichi beacon, the following callback should be fired:
- (void)conichiSDKDidDiscoverVenue:(CNISDKVenue *)venue;
Depending on the scenario, different callbacks can be called. All callbacks can be found in CNISDKDelegate.h
Trackins
Trackins can be created by guests when they enter a beacon region in a given venue. Trackins can be fetched using the web API.
Merchant apps can use trackins to display a list of users around a beacon region.
The following code shows how to start a trackin after a venue has been discovered
Objective-C
- (void)conichiSDKDidDiscoverVenue:(CNISDKVenue *)venue {
// Get the region ID
NSString *regionID = venue.regions.firstObject.conichiID;
// Start tracking guest in region
[[CNISDKAPIManager manager] startTrackingGuestInRegionWithID:regionID completion:^(id trackin, NSError *error) {
if error {
// Handle error
} else {
// Do something with trackin
}
}];
}
Swift
func conichiSDKDidDiscover(_ venue: CNISDKVenue) {
// Get the region ID
guard let regionID = currentVenue?.regions?.first?.conichiID else {
return
}
// Instantiate API Manager if needed
let apiManager = CNISDKAPIManager()
// Start tracking guest in region
apiManager.startTrackingGuestInRegion(withID: regionID) { (trackin, error) in
if let unwrappedError = error {
// Handle error
} else {
// Do something with trackin
}
}
}
Checkins
Checkins are associated to venues. They allow users to perform different actions related to a venue, such as payments or receiving messages from the venue. Checkins can be created manually by using the web API, or automatically via PMS integration.
Checkout requests
Checkout requests allow guests to request their checkin to be closed (checking out). They can be created with or without deliverable items (items to be paid such as minibar items).
As for checkins, they are associated to venues. They can be created using the SDK and fetched using the web API.
The example below shows how to do a checkout request without deliverables for a guest, using CNISDKCoreKit
Objective-C
// Get the guest's credit card
CNISDKCreditCard *creditCard = guest.creditCards.firstObject;
// Create checkout request
[[CNISDKAPIManager manager] createCheckoutRequestWithDeliverableCountableItems:nil selectedCreditCard:creditCard completion:^(id checkoutRequest, NSError *error) {
if (error) {
// Handle error
} else {
// Do something with checkoutRequest
}
}];
Swift
// Get the guest's credit card
let creditCard = guest.creditCards.first
// Instantiate API Manager if needed
let apiManager = CNISDKAPIManager()
// Create checkout request
apiManager.createCheckoutRequest(with: nil, selectedCreditCard: creditCard.conichiID ) { (checkoutRequest, error) in
if error {
// Handle error
} else {
// Do something with checkoutRequest
}
}
Fetching the guest's status
You can use the following code to fetch the guest from conichi's cloud.
Objective-C
// Fetch guest status
[[CNISDK sharedInstance] fetchGuestStatus];
// Implement delegate method of CNISDKDelegate
- (void)conichiSDKDidUpdateGuestStatus:(CNISDKGuest *)guest {
// do something with guest
}
Swift
// Fetch guest status
CNISDK.sharedInstance().fetchGuestStatus()
// Implement delegate method of CNISDKDelegate
func conichiSDKDidUpdateGuestStatus(_ guest: CNISDKGuest) {
// do something with guest
}
Note
While the above documentation should be enough to get you started, it only covers a small part of the SDK's functionalities. If you have any questions regarding it's use, please don't hesitate to contact us.
Documentation
Documentation for each kit is available at the following links:
Documentation about Push Notifications integration can be found here:
Changelog
To see what has changed in recent versions of conichiSDK
, see the CHANGELOG.
License
Copyright (c) 2016-present, сonichi GmbH.
All rights reserved.