Tamoco iOS SDK
Homepage Repository CocoaPods Documentation
pod try Tamoco
For full details of the SDK and it's capabilities and installation details, continue reading below.
The Tamoco iOS Client SDK support iOS 8 and above.
To install the SDK using CocoaPods, include the following in your Podfile for your target:
If your require support for Xcode 10 enter the line below into your Podfile.
Our recommneded versions of the TamocoSDK
pod 'Tamoco', '~> 1.4.9'
If you require a different version of the TamocoSDK without this API call CNCopyCurrentNetworkInfo then enter the line below into your Podfile.
pod 'Tamoco', :git => 'https://bitbucket.org/tamoco/tamoco-ios-sdk.git', :tag => '1.4.9NoWifi'
This will install the SDK as a new framework in your Pods directory. Please note that at this time a binary framework is included which can be run on iOS devices and the Xcode Simulator.
Your app project will require the following configuration settings to function properly with the Tamoco SDK.
If you are using Obj C project, then you need to go to Build Settings of your target and under "Build Options" set "Always Embed Swift Standard Libraries" to YES
As a proximity SDK, the Tamoco client requires location always permissions.
Add the NSLocationWhenInUseUsageDescription key and the NSLocationAlwaysAndWhenInUseUsageDescription key to your Info.plist file. (Xcode displays these keys as "Privacy - Location When In Use Usage Description" and "Privacy - Location Always and When In Use Usage Description" in the Info.plist editor.)
If your app supports iOS 10 and earlier, add the NSLocationAlwaysUsageDescription key to your Info.plist file. (Xcode displays this key as "Privacy - Location Always Usage Description" in the Info.plist editor.)
The string entered here will appear within the permissions dialog that is presented to the user when the app requests location permissions. This description should provide a clear explanation and value for why the app requires location information.
You need to enable background modes for Location updates, otherwise you will get an runtime error similar to this:
Terminating app due to uncaught exception 'NSInternalInconsistencyException', reason: 'Invalid parameter not satisfying: !stayUp || CLClientIsBackgroundable(internal->fClient)'
Go to yor target and select "Capabilities" then enable "Background Modes" and thick:
Also enable: (Xcode 10 only)
The first step to configure and initialize the Tamoco Client SDK into your app is to modify your main AppDelegate files. While initializing Tamoco client, you need to provide proper API Key, API Secret and custom ID. To change any of this parameters in runtime, just re-instantiate the Tamoco client.
In your AppDelegate file, start by including the Tamoco module:
import Tamoco
Or in case of using Objective C
#import <Tamoco/Tamoco-Swift.h>
Then, add the following additional Tamoco property:
var tamoco: Tamoco!
Next, implement SDK initialisation in method
func application(application: UIApplication, didFinishLaunchingWithOptions launchOptions: [NSObject: AnyObject]?) -> Bool`
//Set the Logging level
TamocoLogger.level = .error
//Set the API Keys
tamoco = Tamoco(apiKey: "TEST-API-KEY", apiSecret: "YOUR-SECRET")
// Custom ID is an optional setting and could be set in the following way:
tamoco.customId = "CUSTOM_ID"
// By default Tamoco will listen for location updates in the background - set this to false if you do not desire this feature
tamoco.backgroundLocationUpdates = true
// By default Tamoco listens for location within an accuracy of 100 metres, you can set this higher or lower in accordance with the CLLocation
CLLocationAccuracy definition
tamoco.regionMonitoringAccuracy = 100
//Optionally set an object as the Tamoco delegate in order to recieve custom payloads on event triggers set up via the Tamoco web portal
tamoco.delegate = <delegateObject: TamocoDelegate>
The TamocoDelegate is defined with the following protocol:
public protocol TamocoDelegate: class {
func didReceiveJSON(payload: [String: Any])
}
Custom ID is an optional setting related to sending additional tracking attribute e.g. application user ID.
For debug output messages, the level is needed to be set TamocoLogger.level
. For all possible options, check LogLevel
enum.
Before initializing the Tamoco object you may custom configure a number of client settings. These settings allow you to balance the performance of the client relative to proximity responsiveness and battery consumption.
These settings are configured via an TamocoConfig.plist file included into the main bundle. Please note that if an entry is not defined, the default settings will apply.
For testing and development purposes, it is common to use aggressive values to see immediate results. However the default configuration values are the recommended production settings to optimize battery performance.
The following settings are available for configuration:
ENABLE_GEOFENCE_RANGING:
This optional boolean property determines if the Tamoco geofence ranging functionality should be enabled (YES) or disabled (NO).
ENABLE_BEACON_RANGING:
This optional boolean property determines if the Tamoco beacon ranging functionality should be enabled (YES) or disabled (NO).
ENABLE_WIFI_RANGING:
This optional boolean property determines if the Tamoco WIFI ranging functionality should be enabled (YES) or disabled (NO).
TRIGGERS_UPDATE_TIME: The minimum amount of time that needs to elapse between fetch operations.
REGION_MONITORING_ACCURACY:
This is set to desiredAccuracy
of the CLLocationManager
object for Geofence and Beacon ranging.
WIFI_MONITORING_ACCURACY:
This is set to desiredAccuracy
of the CLLocationManager
object for WiFi ranging. For WiFi ranging the didUpdateLocations
is used, to check for the current WiFi.
DELEGATE_NOTIFICATIONS:
This optional property determines if the Tamoco triggers the callbacks upon trigger actions to the designated closures.
The Tamoco exposes the closure onCommunicationError: ((error: NSError) -> Void)?
, which is called if any communication error occurs.
The first method is to trigger proximity closure. You can set onCustomBeaconAction, onCustomFenceAction, onCustomWIFIAction closures, regarding to which actions you want to listen on. You can enable/disable triggering these closures by setting DELEGATE_NOTIFICATIONS property in configuration (defaults to YES).
These are library class properties that can be used to access inventory returned from backend service. Check below snippet how to use it:
let allBeacons: Set<BeaconTrigger>? = tamoco.beacons
All beacons that were returned from server. To listen for updates, start listen for 'TamocoOnTriggersFetched' on NSNotificationCenter.defaultCenter().
All GeoFences that were returned from server. To listen for updates, start listen for 'TamocoOnTriggersFetched' on NSNotificationCenter.defaultCenter().
All WiFis that were returned from server. To listen for updates, start listen for 'TamocoOnTriggersFetched' on NSNotificationCenter.defaultCenter().
Current beacons that are in range.
Current GeoFences that are in range.
Current WiFis that are in range.
You are able to send keys to the Vault service. The Vault stores client encrypted keys with a Device ID (IDFA/AAID). Before pushing to the Vault, SDK validates the key to meet server requirements. Key must be a 40-character (HEX) string (20 byte).
You can use Vault via vault property of the Tamoco SDK instance:
tamoco.vault.pushKey(“abcdef1234...”) { (exception) in {
}
Or in case of Objective C:
[self.tamoco.vault pushKey:@"abcdef1234..." finished:^(NSInteger exception, NSString \* \_Nullable key) {
}];
VaultError is enum which is returned as parameter on callback. For Objective c this enum is splitted to two parts, an integer and String which is the key that was used.
VaultError:
NoError
(Objective C integer value 0)
NonValidFormat
(Objective C integer value 1)
NonValidLength
(Objective C integer value 2)
NonValidDataLength
(Objective C integer value 3)
CantConvertToData
(Objective C integer value 4)
PushFailed
(Objective C integer value 5)
You are able to use this for any kind of additional tracking needed.
You can use Tracking via track property of the Tamoco SDK instance:
tamoco.track.tap("code", variant: "qr") { (isError) in
}
Or in case of Objective C:
[self.tamoco.track tap:@"code" variant:@"qr" completion:^(BOOL) {
}];
This can be found here file.