{"id":24449136,"url":"https://github.com/codeniko/fitbit-ga4","last_synced_at":"2025-08-01T07:39:35.637Z","repository":{"id":57686341,"uuid":"482146853","full_name":"codeniko/fitbit-ga4","owner":"codeniko","description":"Google Analytics 4 (GA4) for Fitbit OS apps, clockfaces, and companions","archived":false,"fork":false,"pushed_at":"2022-04-22T01:49:42.000Z","size":597,"stargazers_count":1,"open_issues_count":1,"forks_count":0,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-07-20T11:20:16.379Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/codeniko.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","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":"2022-04-16T03:40:15.000Z","updated_at":"2022-10-26T06:21:44.000Z","dependencies_parsed_at":"2022-09-18T23:23:18.946Z","dependency_job_id":null,"html_url":"https://github.com/codeniko/fitbit-ga4","commit_stats":null,"previous_names":[],"tags_count":7,"template":false,"template_full_name":null,"purl":"pkg:github/codeniko/fitbit-ga4","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/codeniko%2Ffitbit-ga4","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/codeniko%2Ffitbit-ga4/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/codeniko%2Ffitbit-ga4/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/codeniko%2Ffitbit-ga4/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/codeniko","download_url":"https://codeload.github.com/codeniko/fitbit-ga4/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/codeniko%2Ffitbit-ga4/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":268185570,"owners_count":24209396,"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","status":"online","status_checked_at":"2025-08-01T02:00:08.611Z","response_time":67,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"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":[],"created_at":"2025-01-21T00:37:17.202Z","updated_at":"2025-08-01T07:39:35.591Z","avatar_url":"https://github.com/codeniko.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Fitbit Google Analytics 4 (GA4)\n[![NPM version](https://img.shields.io/npm/v/fitbit-ga4.svg)](https://npmjs.org/package/fitbit-ga4)\n[![License](https://img.shields.io/badge/license-MIT-blue.svg)](https://github.com/codeniko/fitbit-ga4/blob/master/LICENSE)\n\nGoogle Analytics 4 (GA4) for Fitbit OS apps, clockfaces, and companions. This uses the new measurement protocol for GA4. Note that GA4 differs from the previous Universal Analytics as it's changed to be event based instead of sessions based.\n\n## Installation\nThis module assumes you're using the [Fitbit CLI](https://dev.fitbit.com/build/guides/command-line-interface/) in your workflow, which allows you to manage packages using [npm](https://docs.npmjs.com/about-npm/). You can't include modules if you're using Fitbit Studio.\n\n```\nnpm install --save fitbit-ga4\n```\n\n#### Permissions\nYou'll also need to add permissions for `access_internet` in your `package.json` file.\n```\n\"requestedPermissions\": [\n  \"access_internet\"\n]\n```\n\n## Configuration\nFitbit Google Analytics 4 requires an import in the companion in order to configure GA4.\nYou'll need to provide your [Measurement ID and API Secret](https://developers.google.com/analytics/devguides/collection/protocol/ga4/sending-events?client_type=gtag).\n#### Companion\n```javascript\nimport ga from 'fitbit-ga4/companion'\n\nga.configure({\n    measurementId: 'G-S2JKS12JK1',\n    apiSecret: 'coWInB_MTmOaQ3AXhR12_g',\n})\n```\n\n## Sending events\nYou can send events from both the app and companion. We provide a convenience function to send events for app loading, unloading, and display turning on. This is optional.\n#### App\n```javascript\nimport ga from 'fitbit-ga4/app'\n\nga.sendLoadAndDisplayOnEvents(true)\nga.send({ name: 'event_name' })\n```\n\n#### Companion\n```javascript\nimport ga from 'fitbit-ga4/companion'\n\nga.send({ name: 'event_name' })\n```\n\n## Events with parameters\nEvents sent from the app and companion all support parameter similar to the GA4 spec. Additionally, you can send one event at a time, or multiple at once as an array of events.\n```javascript\n// single event with params\nga.send({\n  name: 'event_name',\n  params: {\n    some_param1: 'value1',\n    some_param2: 'value2',\n  }\n})\n\n// multiple events with params per event\nga.send([\n    { name: 'event_name1' },\n    {\n        name: 'event_name2',\n        params: {\n            some_param1: 'value1',\n            some_param2: 'value2',\n        }\n    },\n])\n```\n\n## User properties\nYou can set and clear user properties from both the app and companion. New user properties get appended alongside existing ones. If you want to change an existing user property, use the same key.\nUser properties are persisted in companion's local storage to be restored whenever companion reloads. Note, user property values are stored as Strings.\n#### App/Companion\n```javascript\n// Set user properties\nga.setUserProperties({\n    my_user_property: 'property_value'\n})\n\n// Clear persisted user properties\nga.clearUserProperties()\n\n// View persisted user properties, NOTE only available in companion!\nga.getUserProperties()\n```\n\nAfter you integrate fitbit-ga4 into your fitbit app, verify events were successfully sent from your app in the `Realtime Overview` page, under the `Event count by Event name` section.\n\n## Other notes\n### Read if you use `file-transfer` in your fitbit project\nFitbit-ga4's companion uses `file-transfer` internally. By default, fitbit-ga4 is configured to auto process all file transfers.\nThis can conflict with your companion's file transfer processing. Fitbit SDK does a poor job here and doesn't allow modules to handle their own queues.\nRegardless which of our companions processes first, the other will not receive its expected files.\nIn order to not interfere with each other's processing, you can disable fitbit-ga4's auto handling and forward unknown files to us to process manually instead.\nNote: identify a file is yours based off the filename first before consuming it with `arrayBuffer()`, `cbor{}`, `json()`, or `text()`.\nIf you invoke one of those functions, fitbit-ga4 wont be able to consume that file's content after you.\n\n#### Example companion disabling auto file transfer processing\n```javascript\nimport { inbox } from 'file-transfer'\nimport ga from 'fitbit-ga4/companion'\n\nga.configure({\n    // ... other options\n    autoFileTransferProcessing: false\n})\n\nasync function processAllFiles() {\n    let file\n    while ((file = await inbox.pop())) {\n        if (file.name.startsWith('MY_FILE')) {\n            // your processing logic\n        } else {\n            // unknown file, proxy to fitbit-ga4 for processing\n            ga.processFileTransfer(file)\n        }\n    }\n}\n```\n\n#### Client ID\nUpon installation, a persistent client ID is created to anonymously identify the device. This is required by the Measurement Protocol API.\n\n#### Automatic Load, Unload and Display events\nWe provide a convenience function to send events for app loading, unloading, and display turning on. You can enable this from the app side by invoking `ga.sendLoadAndDisplayOnEvents()`:\n* `load` is emitted each time the app is loaded.\n* `display_on` is emitted each time the device display turns on.\n* `unload` is emitted each time the app is unloaded.\n\n## Setting up GA4 on Google\n1) Create new GA4 property (no need to create the UA property alongside it).\n2) In Data Streams, choose the \"Web\" platform. Enter any URL and stream name. You can disable Enhanced measurements as those are tied to webpages and are irrelevant for fitbit apps.\n3) Copy the Measurement ID at the top right; it starts with `G-`\n4) On the same Data Stream page, scroll down and open `Measurement Protocol API secrets`. Create and copy the generated secret value.\n\n## Debug logs\nYou can enable debug logs in both the app and companion. Companion's `ga.configure` function allows for an optional `debug` field. Similarly, App exposes a `ga.setDebug(true)` function.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcodeniko%2Ffitbit-ga4","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcodeniko%2Ffitbit-ga4","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcodeniko%2Ffitbit-ga4/lists"}