Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/prolificinteractive/simcoe
A simple, light analytics framework for iOS.
https://github.com/prolificinteractive/simcoe
adobe analytics analytics-providers analytics-tracking carthage cocoapods mparticle podfile protocol protocol-oriented providers-simcoe subspecs track-analytics
Last synced: about 2 months ago
JSON representation
A simple, light analytics framework for iOS.
- Host: GitHub
- URL: https://github.com/prolificinteractive/simcoe
- Owner: prolificinteractive
- License: mit
- Created: 2016-03-16T16:06:41.000Z (almost 9 years ago)
- Default Branch: master
- Last Pushed: 2021-04-15T14:45:24.000Z (over 3 years ago)
- Last Synced: 2024-11-16T08:15:40.793Z (about 2 months ago)
- Topics: adobe, analytics, analytics-providers, analytics-tracking, carthage, cocoapods, mparticle, podfile, protocol, protocol-oriented, providers-simcoe, subspecs, track-analytics
- Language: Swift
- Homepage:
- Size: 426 KB
- Stars: 19
- Watchers: 24
- Forks: 8
- Open Issues: 4
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
[](https://travis-ci.org/prolificinteractive/simcoe)
[](https://img.shields.io/cocoapods/v/Simcoe.svg)
[](http://cocoadocs.org/docsets/Simcoe)
[](http://cocoadocs.org/docsets/Simcoe)
[](https://github.com/Carthage/Carthage)
## Description
A light analytics wrapper aimed at making analytics implementation & debugging as simple and
streamlined as possible -- especially for projects utilizing multiple analytics providers.
## Requirements
Simcoe is written in Swift and utilizes dynamic frameworks for its implementation. As such, this
library requires:
* Xcode 8 or greater
* iOS 8 or greater
## Installation
Simcoe is made up of a core framework with additional plugins available for a variety of different analytics providers.
### CocoaPods
Simcoe is available through [CocoaPods](http://cocoapods.org). To install
it, simply add the following line to your `Podfile`:
```ruby
pod "Simcoe"
```
This will give you the core SDK with the default debugging capabilities right out of the box. However, you
will be responsible for creating the analytics provider. Simcoe comes with a variety of provider implementations
right out of the box, however, that can reduce the amount of work you need to do to get started. Simply include the relevant subspec in your Podfile; for instance, if your project was using Adobe Omniture to
track analytics, simply specify the subspec in your project's Podfile:
``
pod 'Simcoe', :subspecs => ['Adobe']
``
### Carthage
You can also add Simcoe to your project using [Carthage](https://github.com/Carthage/Carthage). Add the following to your `Cartfile`:
```ruby
github "prolificinteractive/Simcoe"
```
## Included Providers
Simcoe comes with default implementations for a wide-variety of providers right out of the box:
* [Adobe](Simcoe/Adobe/README.md)
* [mParticle](Simcoe/mParticle/README.md)
* [Mixpanel](Simcoe/Mixpanel/README.md)
## Usage
Using Simcoe is simple. At the start of your application's lifecycle, simply begin running Simcoe with the providers you wish to use:
`Simcoe.run(with: Adobe())`
If you do not yet know which analytics tool your project will be using, that's fine! Simply start Simcoe without arguments:
`Simcoe.run()`
By default, if Simcoe is not given any providers, it will automatically create a default provider to use as a placeholder. This allows you to implement, track, and debug analytics without a provider. Then, when your
provider changes, simply update your `run()` call with the providers and that's it!
To facilitate debugging when using multiple providers, Simcoe contains a few options for updating the information logged in the console:
* verbose
* simple
* none
By default, Simcoe will log all console outputs in detail (*verbose*) providing one line per item for **each** provider that was specified. *simple* will output one line per item regardless of how many providers were specified while *none* will disable all console logging. To update the *outputOption,* simply call (update this property after the `run()` command):
`Simcoe.engine.tracker.outputOption = .simple`
Simcoe providers a base function call for each major analytics action right out of the gate, giving a consistent API to all of your analytics tracking. For instance, to track page views:
``
Simcoe.track(pageView: "Home Screen")
``
That's it! Simcoe will automatically call all of your analytics providers and request that they log that page view. This same method is uniform and consistent, no matter what providers you are using.
### Creating an Analytics Provider
While Simcoe comes with some analytics implementations right out of the box, sometimes you will need to roll your own. The Simcoe API makes it easy for anyone to do.
#### AnalyticsTracking
First, all analytics trackers implement this base protocol: `AnalyticsTracking`. This protocol is the only that is needed for any object to be considered a valid analytics tracker to Simcoe. This protocol allows you to define a user-readable name for your provider as well as the ability to begin or handle any setup work that your tracker requires.
While simply implementing this protocol is all you need for your object to be a valid analytics tracker, you won't be able to do too much with it. This is because Simcoe utilizes an array of various different protocols, each one giving defining the functionality needed to handle that API event. These protocols are:
* `CartLogging`
* `CheckoutTracking`
* `ErrorLogging`
* `EventTracking`
* `LifetimeValueTracking`
* `LocationTracking`
* `PageViewTracking`
* `PurchaseTracking`
* `SuperPropertyTracking`
* `TimedEventTracking`
* `UserAttributeTracking`
* `ViewDetailLogging`
So for your analytics provider to be able to handle page views in the Simcoe framework, your provider should implement the `PageViewTracking` protocol. This plug-and-play API allows you to define what you want your provider to handle at a very granular level. If your provider only needs to implement location tracking and nothing else, then you need only implement the `LocationTracking` protocol (as well as the `AnalyticsTracking` protocol, of course); all other protocols are optional. This allows you full customization as to how your objects respond to Simcoe.
#### Additional Tracking
Each analytics implementation is different, and Simcoe doesn't expect to be the be-all, end-all of analytics implementations. What if you need to track something that is not included in the base SDK?
Ultimately, all tracking calls in `Simcoe` are forwarded to the default singleton: `Simcoe.engine` which publicly exposes the one tracking method: `write`. This function takes an array of all objects, a description
of the event, and a closure to actually do the write event. Using this method will allow you to handle any type of custom analytics work you may need to do while also continuing to utilize the powerful debug and logging
tools provided by the Simcoe framework.
Let's say, for example, you are using Sqweeblytics to track the amount of Sqweebles in your application. This is clearly unique behavior, but it's important analytics data.
All you would need to do is wrap your Sqweeblytics provider in the Simcoe engine:
```
Simcoe.engine.write(toProviders: [Sqweeblytics()],
description: "Tracks all of the user's sqweebles.",
action: { sqweeblytics in
sqweeblytics.track()
return .Success
})
```
That's it! You are now able to properly track your sqweebles while continuing to utilize the Simcoe engine.
## Contributing to Simcoe
To report a bug or enhancement request, feel free to file an issue under the respective heading.
If you wish to contribute to the project, fork this repo and submit a pull request. Code contributions should follow the standards specified in the [Prolific Swift Style Guide](https://github.com/prolificinteractive/swift-style-guide).
## License
Copyright (c) 2017 Prolific Interactive
Simcoe is maintained and sponsored by Prolific Interactive. It may be redistributed under the terms specified in the [LICENSE] file.
[LICENSE]: ./LICENSE