https://github.com/tpitale/staccato-ex
Google Analytics Collection API in Elixir
https://github.com/tpitale/staccato-ex
Last synced: over 1 year ago
JSON representation
Google Analytics Collection API in Elixir
- Host: GitHub
- URL: https://github.com/tpitale/staccato-ex
- Owner: tpitale
- Created: 2018-07-06T01:52:36.000Z (about 8 years ago)
- Default Branch: master
- Last Pushed: 2018-08-17T15:35:48.000Z (almost 8 years ago)
- Last Synced: 2025-03-24T09:21:17.895Z (over 1 year ago)
- Language: Elixir
- Size: 30.3 KB
- Stars: 5
- Watchers: 2
- Forks: 3
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
# Staccato
Elixir library to track into the official Google Analytics Measurement Protocol
https://developers.google.com/analytics/devguides/collection/protocol/v1/
**NOTE:** The Measurement Protocol is part of Universal Analytics, which is currently available in public beta. Data from the measurement protocol will only be processed in Universal Analytics enabled properties.
## Installation
If [available in Hex](https://hex.pm/docs/publish), the package can be installed
by adding `staccato` to your list of dependencies in `mix.exs`:
```elixir
def deps do
[
{:staccato, "~> 0.1.0"}
]
end
```
Documentation can be generated with [ExDoc](https://github.com/elixir-lang/ex_doc)
and published on [HexDocs](https://hexdocs.pm). Once published, the docs can
be found at [https://hexdocs.pm/staccato](https://hexdocs.pm/staccato).
## TODO: ##
* [x] Basic hit types
* [ ] Session control
* [ ] Measurements
* [ ] Handle boolean fields
* [ ] Timing w/ block
* [ ] Custom Dimensions and Metrics
* [ ] Global hit defaults
* [ ] HTTP Adapters
* [ ] Image URLs
## Usage ##
```elixir
tracker = Staccato.tracker('UA-XXXX-Y') # REQUIRED, your Google Analytics Tracking ID
```
`#tracker` optionally takes a second param for the `client_id` value.
By default, the `client_id` is set to a random UUID with `SecureRandom.uuid`
### Track some data ###
```elixir
import Staccato.Hit
# Track a Pageview (all values optional)
tracker
|> pageview(path: "/page-path", hostname: "mysite.com", title: "A Page!")
|> track!
# Track an Event (all values optional)
tracker
|> event(category: "video", action: "play", label: "cars", value: 1)
|> track!
# Track social activity (all values REQUIRED)
tracker
|> social(action: 'like', network: 'facebook', target: '/something')
|> track!
# Track exceptions (all values optional)
tracker
|> exception(description: 'RuntimeException', fatal: true)
|> track!
# Track timing (all values optional, but should include time)
tracker
|> timing(category: 'runtime', variable: 'db', label: 'query', time: 50) # time in milliseconds
|> track!
# Track transaction (transaction_id REQUIRED)
tracker
|> transaction(%{
transaction_id: 12345,
affiliation: 'clothing',
revenue: 17.98,
shipping: 2.00,
tax: 2.50,
currency: 'EUR'
})
|> track!
# Track transaction item (matching transaction_id and item name REQUIRED)
tracker
|> transaction_item(%{
transaction_id: 12345,
name: 'Shirt',
price: 8.99,
quantity: 2,
code: 'afhcka1230',
variation: 'red',
currency: 'EUR'
})
track!
```
### Setting SSL on a tracker ###
```elixir
# passing nil as the second argument lets Staccato build the client id, as the default
tracker = Staccato.tracker('UA-XXXX-Y', nil, ssl: true)
```
### "Global" Options ###
Any of the options on the parameters list (https://developers.google.com/analytics/devguides/collection/protocol/v1/parameters) that are accepted on ALL hit types can be set as options on any of the hits.
```elixir
tracker
|> pageview(path: '/video/1235', flash_version: 'v1.2.3')
```
`flash_version` is a **global option** in the example above.
The complete list at this time:
```elixir
Staccato::Hit::GLOBAL_OPTIONS.keys # =>
[:anonymize_ip,
:queue_time,
:data_source,
:cache_buster,
:user_id,
:user_ip,
:user_agent,
:referrer,
:campaign_name,
:campaign_source,
:campaign_medium,
:campaign_keyword,
:campaign_content,
:campaign_id,
:adwords_id,
:display_ads_id,
:screen_resolution,
:viewport_size,
:screen_colors,
:user_language,
:java_enabled,
:flash_version,
:document_location,
:document_encoding,
:document_hostname,
:document_path,
:document_title,
:link_id,
:application_name,
:application_version,
:application_id,
:application_installer_id,
:experiment_id,
:experiment_variant,
:product_action,
:product_action_list,
:promotion_action,
:geographical_id]
```
Boolean options like `anonymize_ip` will be converted from `true`/`false` into `1`/`0` as per the tracking API docs.
The `data_source` option can take any value, but note that hits sent from other Google tools will have specific values. Hits sent from analytics.js will have `data_source` set to `web`, and hits sent from one of the mobile SDKs will have `data_source` set to `app`.
#### Non-Interactive Hit ####
```elixir
# Track a Non-Interactive Hit
tracker
|> event(category: 'video', action: 'play', non_interactive: true)
|> track!
```
Non-Interactive events are useful for tracking things like emails sent, or other
events that are not directly the result of a user's interaction.
The option `non_interactive` is global, accepted for all hit types.
#### Session Control ####
```elixir
# start a session
tracker
|> pageview(path: '/blog', start_session: true)
|> track!
# end a session
tracker
|> pageview(path: '/blog', end_session: true)
|> track!
```
Other options are acceptable to start and end a session: `session_start`, `session_end`, and `stop_session`.
#### Content Experiment ####
```elixir
# Tracking an Experiment
# useful for tracking A/B or Multivariate testing
tracker
|> pageview(%{
path: '/blog',
experiment_id: 'a7a8d91df',
experiment_variant: 'a'
})
|> track!
```
### Screenview (as in mobile) ###
```elixir
tracker
|> screenview(screen_name: 'user1')
|> track!
```
## Google Documentation ##
https://developers.google.com/analytics/devguides/collection/protocol/v1/devguide
https://developers.google.com/analytics/devguides/collection/protocol/v1/reference
https://developers.google.com/analytics/devguides/collection/protocol/v1/parameters
## Contributing ##
1. Fork it
2. Create your feature branch (`git checkout -b my-new-feature`)
3. Commit your changes (`git commit -am 'Add some feature'`)
4. Push to the branch (`git push origin my-new-feature`)
5. Create new Pull Request