| TestsTested | ✗ |
| LangLanguage | Obj-CObjective C |
| License | Apache 2 |
| ReleasedLast Release | Oct 2019 |
Maintained by Rune Bromer, Phil Martin, Ben Colenso.
For full details of the SDK and it's capabilities and installation details, continue reading below.
This integration guide is built with Xcode version 8.3.3 and Swift 3. 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:
pod 'Tamoco', '~> 1.1'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 "Embedded Content Contains Swift Code" to YES
Bitcode is an optional XCode compilation setting that optimizes your app for distribution based on specific device.
The Tamoco SDK is not currently compatible with Bitcode. As a result, you’ll need to disable Bitcode support within your app. To disable Bitcode support, go to Project > Build Settings > Build Options and change the “Enable Bitcode” setting to ‘No’
As a proximity SDK, the Tamoco client requires location always permissions. In iOS 8 and beyond, you must include an NSLocationAlwaysUsageDescription string entry within your app’s info.plist. 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:
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 TamocoOr 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"
// listenOnly = false - Set to true if you do not want notifications and pop-up messages in your app. Default's to false
tamoco.listenOnly = false
// By default Tamoco will listen for location updates in the background - set this to false if you do not desire this feature
tamaco.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.
DELEGATE_LOCAL_NOTIFICATIONS:
This optional property determines if the Tamoco sends the local notifications upon trigger actions.
LOCAL_NOTIFICATION_SOUND:
Sound used for local notifications. This value is set to the soundName property of the UILocalNotification object, before UIApplication.sharedApplication().scheduleLocalNotification(...) is called.
ENABLE_DEBUG_LOCAL_NOTIFICATIONS:
This is for debugging purposes. Each time that any trigger actions is happening, the local notification is pushed.
The Tamoco exposes the closure onCommunicationError: ((error: NSError) -> Void)?, which is called if any communication error occurs.
When a proximity event is triggered, the Tamoco iOS Client SDK will automatically create a notification. The Tamoco iOS Client SDK supports two methods for dispatching these proximity notifications. You can configure which method the Tamoco client uses via the DELEGATE_NOTIFICATIONS and DELEGATE_LOCAL_NOTIFICATIONS property.
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).
You can also configure Tamoco iOS SDK client to dispatch standard iOS local notifications. You can manage dispatching this with DELEGATE_LOCAL_NOTIFICATIONS property in configuration (defaults to YES). To use this method, DELEGATE_LOCAL_NOTIFICATIONS should be set to YES and Tamoco object’s didReceiveLocalNotificationUserInfo should be called within the app’s didReceiveLocalNotification as in the following example:
func application(application: UIApplication, didReceiveLocalNotification notification: UILocalNotification) {
tamoco.didReceiveLocalNotificationUserInfo(notification.userInfo)
}
If the app is in the background a local notification will automatically be generated and appear in the mobile device’s notification tray. When the user clicks the local notification, your app will open and the configured action, such as an interstitial, will then execute.
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) {
}];
One of the primary event actions supported by the Tamoco iOS client SDK are hosted interstitials. Interstitials are HTML-based content that, when triggered, will do a full screen takeover of your app presenting the content. Interstitials provides a built-in, localizable close button that allows the user, when clicked, to dismiss the content and return to your app.
NOTE: By default iOS 9 only allows access to SSL web resources. As a result, interstitial or URI actions that are not sent via SSL will not function properly. In the case that your resources cannot be sent via SSL, Xcode provides a means to override its default behaviour via the App Transport Security Settings dictionary option within your app’s info.plist. To modify this setting, first add this entry to your info.plist if it doesn’t already exist. To allow any resources, both SSL and non-SSL set the Allow Arbitrary Loads boolean suboption to YES. To only allow certain domains, select the Domain Exceptions suboption, passing in a dictionary of domains in which SSL should not be enforced.
By default, the Tamoco client uses the system style UIBarButtonSystemItemDone which allows the close button title to be localized to the user’s current language selection. To localize the button, the app must first be configured to support localization. This can be done from the Info > Localizations settings for the project.
The localized string is then placed in a file named proximity.strings which contains the following:
“ProximityDoneTitle”=“localized close button title goes here”;
To override the default text of the close button title across all languages, place a copy of this file in the root of the project. To override specific languages, place a copy of this file within the corresponding .lproj folder in the apps bundle, for example fr.lproj/proximity.strings.
You can provide your own close mechanism from within your HTML content by referencing the following built-in Tamoco close schema.
To close the interstitial from Javascript enter the following:
window.location = “Tamoco://close”
To close the interstitial from an HTML anchor element enter the following:
<a href="Tamoco://close">Close me</a>
This can be found here file.