{"id":20682186,"url":"https://github.com/bluecadet/cinder-bluecadetanalytics","last_synced_at":"2025-04-22T12:13:31.550Z","repository":{"id":43812627,"uuid":"73521676","full_name":"bluecadet/Cinder-BluecadetAnalytics","owner":"bluecadet","description":"Cinder block with client implementation for Google Analaytics Measurement API v1","archived":false,"fork":false,"pushed_at":"2022-05-09T22:10:32.000Z","size":18327,"stargazers_count":10,"open_issues_count":2,"forks_count":0,"subscribers_count":10,"default_branch":"develop","last_synced_at":"2025-04-22T12:13:26.167Z","etag":null,"topics":["cinder","cpp","google-analytics"],"latest_commit_sha":null,"homepage":null,"language":"C++","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"bsd-3-clause","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/bluecadet.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2016-11-12T00:23:49.000Z","updated_at":"2021-11-26T23:16:20.000Z","dependencies_parsed_at":"2022-07-12T18:19:50.602Z","dependency_job_id":null,"html_url":"https://github.com/bluecadet/Cinder-BluecadetAnalytics","commit_stats":null,"previous_names":[],"tags_count":1,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bluecadet%2FCinder-BluecadetAnalytics","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bluecadet%2FCinder-BluecadetAnalytics/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bluecadet%2FCinder-BluecadetAnalytics/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bluecadet%2FCinder-BluecadetAnalytics/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/bluecadet","download_url":"https://codeload.github.com/bluecadet/Cinder-BluecadetAnalytics/tar.gz/refs/heads/develop","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":250237834,"owners_count":21397401,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["cinder","cpp","google-analytics"],"created_at":"2024-11-16T22:12:57.627Z","updated_at":"2025-04-22T12:13:31.496Z","avatar_url":"https://github.com/bluecadet.png","language":"C++","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Cinder-BluecadetAnalytics\n\nClient implementation for [Google Analaytics Measurement API v1](https://developers.google.com/analytics/devguides/collection/protocol/v1/). Built for interactive multiuser installations with long run times. Deployed to and optimized for highly trafficked installations at public spaces with 5,000+ tracked real world interactions per hour.\n\nTested in production on Windows 7, but also runs on MacOS and iOS. See [Google's dev guide](https://developers.google.com/analytics/devguides/collection/protocol/v1/devguide#event) for more API implementation info.\n\n## Features\n\n* Track events and screen views\n* Extendable to support more hit types\n* Multi-threaded HTTP requests using [Cinder-Asio](https://github.com/BanTheRewind/Cinder-Asio) and [Protocol](https://github.com/BanTheRewind/Cinder-Protocol)\n* Offline support with automatic retries at increasing intervals\n* Configured to stay within Google Analytics [quota limits](https://developers.google.com/analytics/devguides/collection/protocol/v1/limits-quotas)\n\t* Automatic session renewal\n\t* Automatic hit batching\n\t* Automatic cache busting\n\n## Dependencies\n\n[Cinder-Asio](https://github.com/BanTheRewind/Cinder-Asio) is a required dependency that needs to be installed in _Cinder/blocks_. [Protocol](https://github.com/BanTheRewind/Cinder-Protocol) is included in this repo since it's not set up as a Cinder block.\n\n## Usage\n\n```c++\nstring clientId = \"00000000-0000-0000-0000-000000000000\"; // required\nstring gaId = \"UA-00000000-0\"; // required\nstring appName = \"My App\"; // required\n\nAnalyticsClient::getInstance()-\u003esetup(clientId, gaId, appName);\nAnalyticsClient::getInstance()-\u003etrackScreenView(\"Test Screen\");\nAnalyticsClient::getInstance()-\u003etrackEvent(\"Test Category\", \"Test Action\");\n```\n\n## Notes on Client ID\n\nThe client ID is used to identify unique clients and measures as unique users in Google Analytics. The client ID is a UUID according to [RFC 4122 spec](http://www.ietf.org/rfc/rfc4122.txt), which can be pre-generated and hard coded into your app (e.g. using [online tools](https://www.guidgenerator.com/online-guid-generator.aspx)) or randomly generated at run time (e.g. using boost).\n\nExample UUID generation using boost:\n\n```c++\n#include \u003cboost/uuid/uuid.hpp\u003e\n#include \u003cboost/uuid/uuid_generators.hpp\u003e\n#include \u003cboost/uuid/uuid_io.hpp\u003e\n\n//...\n\nstring clientId = boost::uuids::to_string(boost::uuids::random_generator()());\n```\n\n### Single User Mode\n\nIf your app only tracks as a single user, you can just use  the shared instance with your GA ID and client ID. All hits sent to GA will track under the same unique user.\n\n```c++\nAnalyticsClient::getInstance()-\u003esetup(clientId, gaId, appName, appVersion);\nAnalyticsClient::getInstance()-\u003etrackEvent(\"Test Category\", \"Test Action\");\nAnalyticsClient::getInstance()-\u003etrackEvent(\"Test Category\", \"Test Action\");\nAnalyticsClient::getInstance()-\u003etrackEvent(\"Test Category\", \"Test Action\");\n```\n\nThis will create three event hits in total, each by the same user.\n\nSee the [AnalyticsSample](samples/AnalyticsSample) project for more details.\n\n### Multi User Mode\n\nIf your app should track multiple users individually, you can create one client per user, each with their own unique client ID:\n\n```c++\nmClientA = AnalyticsClientRef(new AnalyticsClient());\nmClientB = AnalyticsClientRef(new AnalyticsClient());\nmClientC = AnalyticsClientRef(new AnalyticsClient());\n\nmClientA-\u003esetup(clientIdA, gaId, appName, appVersion);\nmClientB-\u003esetup(clientIdB, gaId, appName, appVersion);\nmClientC-\u003esetup(clientIdC, gaId, appName, appVersion);\n\nmClientA-\u003etrackEvent(\"Test Category\", \"Test Action\");\nmClientB-\u003etrackEvent(\"Test Category\", \"Test Action\");\nmClientC-\u003etrackEvent(\"Test Category\", \"Test Action\");\n```\n\nThis will create three event hits in total, each by individual users.\n\nSee the [MultiUserSample](samples/MultiUserSample) project for more details.\n\n## Notes on Error Reporting\n\nThe Google Analytics API does not return any form of errors when reporting hits via HTTP. In fact, it returns `200 OK` for every request, regardless of its data and format, so make sure that your GA ID and client ID are correctly formatted.\n\nYou can test if events and screen views are coming in correctly by looking at the [Real Time](https://support.google.com/analytics/answer/1638635?hl=en) view in your GA dashboard.\n\nSee [Google's hit validation notes](https://developers.google.com/analytics/devguides/collection/protocol/v1/validating-hits) for more info.\n\n## Notes on Sessions and Quotas\n\nGoogle Analytics has a few [limitations](https://developers.google.com/analytics/devguides/collection/protocol/v1/limits-quotas) that make tracking of high amounts of hits on multi-user apps difficult. For example, each session is limited to 500 hits. This Cinder block automatically renews sessions once 400 hits have been reached to stay under this limit, but that means that session data in GA is not really meaningful.\n\nThis automatic renewal can be disabled using `setAutoSessionsEnabled(false)`.\n\n## Unimplemented Features\n\nThe following features are nice to have and would cover relatively rare edge cases (e.g. payload size with reasonable events/screen views should never reach the limits below).\n\n- Check for batch size limit of 16K bytes ([reference](https://developers.google.com/analytics/devguides/collection/protocol/v1/devguide#batch-limitations))\n- Check for hit size limit of 8K bytes ([reference](https://developers.google.com/analytics/devguides/collection/protocol/v1/devguide#batch-limitations))\n- Send remaining batches before app quits (currently all remaining batches will be discarded)\n\n## Version Notes\n\n* Version 1.0.0\n* Tested with Cinder `0.9.1dev` commit [0b24d643e3](https://github.com/cinder/Cinder/commit/0b24d643e3b19a4ae6875b92899bae9376f7a64a)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbluecadet%2Fcinder-bluecadetanalytics","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbluecadet%2Fcinder-bluecadetanalytics","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbluecadet%2Fcinder-bluecadetanalytics/lists"}