CNISDKPMSKit 4.1.37

CNISDKPMSKit 4.1.37

TestsTested
LangLanguage Obj-CObjective C
License NOASSERTION
ReleasedLast Release Apr 2019

Maintained by ShengHua Wu, David Henner, Vincent Jacquesson, conichi iOS devs, Joseph Tseng.



 
Depends on:
CNISDKCoreKit= 4.1.37
CNISDKPaymentKit= 4.1.37
 

  • By
  • conichiGMBH

conichiSDK for iOS

Requires Carthage compatible CocoaPods Compatible Build Status

Meta

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.

Alt text

Install via CocoaPods

The preferred way to integrate CNISDKCoreKit is via CocoaPods. Add the following lines to your Podfile:

source '[email protected]: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.

Alt text

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 = @"[email protected]";
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 = "[email protected]"
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.