{"id":13611444,"url":"https://github.com/savepopulation/gadget","last_synced_at":"2025-04-13T04:34:33.022Z","repository":{"id":100183359,"uuid":"361980800","full_name":"savepopulation/gadget","owner":"savepopulation","description":"Gadget is a library that makes analytics tracking easier for android apps","archived":false,"fork":false,"pushed_at":"2022-10-11T05:49:30.000Z","size":382,"stargazers_count":54,"open_issues_count":0,"forks_count":0,"subscribers_count":2,"default_branch":"master","last_synced_at":"2024-08-01T19:57:33.322Z","etag":null,"topics":["android","enhanced-ecommerce","google-analytics","kotlin","kotlin-android","kotlin-library"],"latest_commit_sha":null,"homepage":"","language":"Kotlin","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/savepopulation.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,"governance":null,"roadmap":null,"authors":null}},"created_at":"2021-04-27T04:33:15.000Z","updated_at":"2024-06-27T13:00:52.000Z","dependencies_parsed_at":"2023-03-30T05:50:39.179Z","dependency_job_id":null,"html_url":"https://github.com/savepopulation/gadget","commit_stats":null,"previous_names":[],"tags_count":13,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/savepopulation%2Fgadget","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/savepopulation%2Fgadget/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/savepopulation%2Fgadget/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/savepopulation%2Fgadget/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/savepopulation","download_url":"https://codeload.github.com/savepopulation/gadget/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":223568224,"owners_count":17166622,"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":["android","enhanced-ecommerce","google-analytics","kotlin","kotlin-android","kotlin-library"],"created_at":"2024-08-01T19:01:55.378Z","updated_at":"2024-11-07T18:30:31.057Z","avatar_url":"https://github.com/savepopulation.png","language":"Kotlin","funding_links":[],"categories":["Kotlin"],"sub_categories":[],"readme":"# Gadget\n**Gadget** is a library that aims to _make analytics event tracking_ **more reliable** and **configurable**.\u003cbr\u003e\n\n### Problems to solve\nHere're a few problems that **Gadget** tries to solve.\n\n1. Managing the tracking of the events to n platforms from a single point.\n2. Adding or removing an analytics plafrom easily\n3. Configuring of event tracking for different screens or conditions.\n4. Google Enhanced Ecommerce implementation easier.  \n\n### How to use?\nFirst you need to setup **Gadget** in your **application**.\n```KOTLIN\nclass MyAwesomeApp : Application() {\n\n    override fun onCreate() {\n        super.onCreate()\n        Gadget.setup(this)\n    \t// .. other stuff\n    }\n}\n```\nBy default **Gadget** uses it's own tracker which is called ```DefaultEventTracker``` and tracks to **Firebase Analytics** by default.\n```KOTLIN\nopen class DefaultEventTracker(private val firebaseEventTracker: EventTracker) : EventTracker {\n```\nTo customize the event tracking in your app, you can define your own tracker by implementing **EventTracker**\n```KOTLIN\ninterface EventTracker {\n    /*\n     * Tracking function\n     * Tracks the given event\n     */\n    fun track(event: Event)\n}\n```\n\nAfter creating your custom event tracker, you can pass it to Gadget and use **your own tracker**.\n```KOTLIN\nGadget.setup(this,myAwesomeCustomEventTracker)\n```\n\nSecondly, you should create **your own events** or you can use directly **Gadget's pre-defined events**. Your own events should impement Gadget's ```Event``` interface.\n```KOTLIN\n/*\n * Event\n * Generic Event interface\n * Every event has a name and params\n */\ninterface Event\n```\nIf this event will be tracked to Firebase Analytics as well, you should implementd Gadget's ```FirebaseEvent``` interface. This interface has a default ```bundle``` implementation and you can override this bundle conversion anytime you want in your own event. (You can notice that some predefined **EEC events** has different ```bundle``` conversions.)\n```KOTLIN\n/*\n * Firebase Event\n * Defines the events that will be tracked to Firebase Analytics\n */\ninterface FirebaseEvent : Event {\n    /*\n     * Converts the event to bundle to track Firebase Analytics\n     */\n    fun toBundle(): Bundle {\n        val bundle = Bundle()\n        if (params.isNotEmpty()) {\n            for (param in this.params) {\n                bundle.put(param.key, param.value)\n            }\n        }\n\n        return bundle\n    }\n} \n```\n\nInstead of implementing your own events, you can directly use **Gadget's** ```CustomEvent``` for event tracking.\n```KOTLIN\nval addEvent = CustomEvent(\"content_add\")\naddEvent.putParam(\"type\", \"message\")\n```\n\nAnd finally, you can track your event with ```Gadget```\n```KOTLIN\nGadget.track(addEvent)\n```\n\nIF you want to change the event tracking strategy for a single event specifically **Gadget's track method** takes ```EventTracker``` as parameter and if you pass a different event tracker, your event will be tracked with that implementation.\n\n### Gadget's Google Analytics Enhanced Ecommerce Support\nGoogle Analytics Enhanced Ecommerce reporting allows you to collect data related to ecommerce transactions: item data, impression data, product data, promotion data, and action data. This information gives you a snapshot of your company’s health by providing an overarching view of how visitors interact with your ecommerce website. [Source and more information here](https://thegood.com/insights/google-analytics-enhanced-ecommerce/)\n\nGadget has it's own impression trackers can be used for EEC impression tracking. You can use ```EecProductImpressionTracker``` for product impression tracking and \n```EecPromotionImpressionTracker``` for tracking your promotions. These trackers both implements **Gadget's** ```ListItemImpressionTracker\u003cT\u003e``` and ```LifecycleEventTracker``` implements to handle impression tracking in a with **lifecycle events**.\n\nTo collect the impressions, you can use ```addImpression``` method of ```ListItemImpressionTracker```\n```KOTLIN\n    /*\n     * Function to track item impression\n     * Call when item is viewed\n     */\n    fun addImpression(item: T) {\n        viewedItems.add(item)\n    }\n\n    /*\n     * Function to track item impression with a mapper\n     * Call when item is viewed\n     */\n    fun addImpression(item: Any?, mapper: Function\u003cAny, T\u003e) {\n        item?.let {\n            viewedItems.add(mapper.apply(it))\n        }\n    }\n```\n\nTo track an item selection, you can use ```trackItemSelection``` method of ```ListItemImpressionTracker```\n```KOTLIN\n/*\n * Tracks selection of an item in a list\n * Measure product clicks by logging a SELECT_CONTENT event\n * with an item (i.e. product) defined with the relevant fields:\n */\n fun trackItemSelection(item: T)\n```\n\nAnd finally, **Gadget's** ```EecProductImpressionTracker``` will track the collected impressions ```@OnLifecycleEvent(Lifecycle.Event.ON_PAUSE)```\n\n**Note:** You can notice that there're some out dated classes and implementations for **EEC support**. **Google Analytics 4 migration** is still on going and i'm trying to understand and replace these deprecated classes with the GA 4 implementations.\n\n### Dependency\u003cbr\u003e\n```\nallprojects {\n\t\trepositories {\n\t\t\t...\n\t\t\tmaven { url 'https://jitpack.io' }\n\t\t}\n\t}\n  ```\n  ```\n  dependencies {\n\t        implementation 'com.github.savepopulation:gadget:1.0.2'\n\t}\n  ```\n  \n### Apps Using Gadget on Production\n[Phone Box](https://play.google.com/store/apps/details?id=com.raqun.phonebox)\u003cbr\u003e\n  \n  * __Please send me an email if you're using Gaget on production and want to be in the list.__\n\n### WHere Gadget comes from?\n![alt text](/art/gadget.jpeg)\u003cbr\u003e\u003cbr\u003e\n[Inspector Gadget](https://en.wikipedia.org/wiki/Inspector_Gadget)\u003cbr\u003e\n[Watch this](https://www.youtube.com/watch?v=rIc13VjeAw8)\n\n### License\n```\n  Copyright 2021 Taylan SABIRCAN\n\n   Licensed under the Apache License, Version 2.0 (the \"License\");\n   you may not use this file except in compliance with the License.\n   You may obtain a copy of the License at\n\n       http://www.apache.org/licenses/LICENSE-2.0\n\n   Unless required by applicable law or agreed to in writing, software\n   distributed under the License is distributed on an \"AS IS\" BASIS,\n   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n   See the License for the specific language governing permissions and\n   limitations under the License.\n```\n\n  \n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsavepopulation%2Fgadget","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsavepopulation%2Fgadget","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsavepopulation%2Fgadget/lists"}