Created and maintained by Vectorform.
Symbiote is an analytics framework that supports multiple platforms, auto enables basic analytics in your app and is easily extensible with event processors. Extended analytics support can be enabled by subclassing UIButtons and UIViewControllers from analytics subclasses and providing a view name. This will enable the framework to automatically build view paths and label buttons with their respective actions correctly. Unsupported analytics platforms may be integrated by implementing a simple event logging protocol. Custom events can be created easily. Events may be filtered and processed (add/edit/remove/analyze data) by adding custom event processors which are filtered by EventFilters to the event bus.
- Amazon Mobile Analytics
- Flurry
- Simple Logging (Debug only!)
You can install this library using Cocoapods. You can get started with Cocoapods by following their install guide, and learn how to use Cocoapods to install dependencies by following this guide.
In your podfile, you want to add pod 'Symbiote', '0.3.0' (Swift 3). Then run pod install inside your terminal. With Cocoapods, we support iOS: 9.0 and above.
For Swift 2 support, you must use version 0.1.2.
You can find the latest reference documentation on Cocoadocs. Install this documentation to Dash or Xcode using Docs for Xcode. On the docs page, click the 'share' button in the upper right.
To run the example project, clone the repo, and run pod install from the Example directory first.
Johannes Start, jstart@vectorform.de
Aaron DeGrow, adegrow@vectorform.com
Symbiote is available under the BSD license. See the LICENSE file for more info.
If you see a bug, feel free to post an issue. Please see the contribution guidelines before proceeding.
To get started with Symbtiote and simple auto analytics integration you will need to add pod 'Symbiote' to your podfile. After running pod install you will be able to use it in your project. Auto analytics use swizzling to integrate into all UIViewControllers and UIEvents to determine when views show, disappear or buttons are pressed. In your AppDelegate's init you have to import Symbiote and enable a log provider:
import UIKit
import Symbiote
@UIApplicationMain
class AppDelegate: UIResponder, UIApplicationDelegate {
var window: UIWindow?
override init() {
super.init()
// Enable simple log provider to print all output.
// TODO: Disable for production build!
Symbiote.SharedInstance.register(analyticsProvider: DebugLogProvider());
}
}The default Provider (DebugLogProvider) will simply print your analytics events for debug purposes. Don't use this provider in production.
To enable one of the supported analytics providers add the relevant subspec to your podfile: pod 'Symbiote/Provider/AWSAnalytics'
Following subspecs are currently available:
pod 'Symbiote/Provider/DebugLog' # Included by default.
pod 'Symbiote/Provider/AWSMobileAnalytics'
pod 'Symbiote/Provider/FlurryAnalytics'To enable advanced automatic analytics you'll need to use the provided base classes for all UIViewControllers, UINavigationControllers and UIButtons or implement the AnalyticsCompatible protocol. This will enable Symbiote to automatically create view paths and hierarchies and log them accordingly.
import UIKit
import Symbiote
class SampleViewController: AnalyticsEnabledViewController {
override func viewDidLoad() {
super.viewDidLoad()
analyticsDescription = "SampleViewController"
}
}import UIKit
import Symbiote
class SampleNavigationController: AnalyticsEnabledNavigationController {
override func viewDidLoad() {
super.viewDidLoad()
analyticsDescription = "SampleNavigationController"
// Optionally set parentViewController
parentViewController = aViewController
}
}let sampleEventButton:AnalyticsEnabledButton = AnalyticsEnabledButton(frame: CGRectMake(100, 200, 100, 50))
sampleEventButton.setTitle("Sample Button Event", forState: UIControlState.Normal)
sampleEventButton.parentViewController = self
sampleEventButton.analyticsDescription = "SampleEventButton"For more flexibility AnalyticsEnabledButton may also be subclassed. UIButtons can use a custom analytics events for UIControlEvents.TouchUpInside:
sampleEventButton.customEvent = Event(sender: AnalyticsExtensions.SampleSender, action: AnalyticsExtensions.SampleAction)Events may be created and logged by using the Event class. Symbiote comes packaged with a few integrated event properties. In most cases it will make sense to create custom event Methods, senders and events since the default ones are limited to basic iOS functionality.
Methods define how the event was logged. This may be via Swizzling, a DirectCall or AppDelegateCall. When creating and sending a custom event the event Method should be Event.Methods.DirectCall - this is the default. Integrated Methods:
- Event.Methods.Generic
- Event.Methods.SwizzleHook
- Event.Methods.SubclassHook
- Event.Methods.AppDelegateCall
- Event.Methods.DirectCall
Custom Methods may be defined by creating a new Event.Method:
let AnalyticsMethodBluetoothDeviceBridge = Event.Method("BluetoothDeviceBridge")Senders represent the class of an object that sends an event. Senders include the AppDelegate (App), a UIViewController (View) or a UIButton (Button). Integrated Senders:
- Event.Senders.Generic
- Event.Senders.Button
- Event.Senders.View
- Event.Senders.App
Senders are created by creating a new Event.Sender:
let AnalyticsSenderMap = Event.Sender("Map") // Map components that log/send eventsActions define what action was applied to the sender. A Button may be Pressed and a View may Appear. Integrated Actions:
- Event.Actions.Generic
- Event.Actions.Press
- Event.Actions.Appear
- Event.Actions.Disappear
- Event.Actions.Start
- Event.Actions.Foreground
- Event.Actions.Background
- Event.Actions.Active
- Event.Actions.Resign
- Event.Actions.Terminate
A custom action for a AnalyticsSenderMap could be the successful location of a user: Located. Actions are defined by creating an Event.Action:
let AnalyticsActionLocated = Event.Action("Located")Events can hold additional data to keep track of important metrics. When a View disappears it's helpful to know how long it was on screen, so the data dictionary of the event could have a key containing this metric. To simplify and standardize these keys Symbiote uses data descriptors. When adding a custom metric to the data dictionary a default DataDescriptor must be used or a custom one must be created. Integrated DataDescriptors:
- Event.DataDescriptors.ViewName
- Event.DataDescriptors.SelectorName
- Event.DataDescriptors.Path
To create a custom DataDescriptor create an Event.DataDescriptor:
let AnalyticsDataDescriptorsLocationAccuracy = Event.DataDescriptor("LocationAccuracy")Event with default parameters:
Symbiote.SharedInstance.log(event: Event(method: Event.Methods.AppDelegateCall, sender: Event.Senders.App, action: Event.Actions.Start, data: [:]))Event with custom parameters:
let locationAccuracy = "10m"
Symbiote.SharedInstance.log(event: Event(sender: AnalyticsSenderMap, action: AnalyticsActionLocated, data: [ AnalyticsDataDescriptorsLocationAccuracy: locationAccuracy ]))Event processors add/edit/remove data from an analytics event or prohibit logging. They are executed right before logging in the order they are added. When adding an event processor a filter must be set to define on what type of event the specific processor may be executed. To enable a processor for all Events use a filter like AllowAllFilter. This is how you register an event processor with a filter:
// Sample of how to prohibit all events with a .App sender
Symbiote.SharedInstance.register(eventProcessor: ProhibitAllProcessor(), filter: SimpleGenericFilter(filterSenders: [Event.Senders.App]))