{"id":23511197,"url":"https://github.com/percolate/foam","last_synced_at":"2025-04-18T15:03:11.450Z","repository":{"id":29770792,"uuid":"33314734","full_name":"percolate/foam","owner":"percolate","description":"A library to quickly and easily enable multiple monitoring \u0026 support platforms for your mobile apps","archived":false,"fork":false,"pushed_at":"2015-06-09T15:54:01.000Z","size":582,"stargazers_count":65,"open_issues_count":4,"forks_count":8,"subscribers_count":67,"default_branch":"master","last_synced_at":"2025-03-29T06:23:18.212Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"Java","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/percolate.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":"2015-04-02T14:57:32.000Z","updated_at":"2024-08-27T16:15:59.000Z","dependencies_parsed_at":"2022-09-07T00:41:34.596Z","dependency_job_id":null,"html_url":"https://github.com/percolate/foam","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/percolate%2Ffoam","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/percolate%2Ffoam/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/percolate%2Ffoam/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/percolate%2Ffoam/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/percolate","download_url":"https://codeload.github.com/percolate/foam/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":249509410,"owners_count":21283576,"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":[],"created_at":"2024-12-25T12:13:43.462Z","updated_at":"2025-04-18T15:03:11.432Z","avatar_url":"https://github.com/percolate.png","language":"Java","funding_links":[],"categories":["Libs"],"sub_categories":["\u003cA NAME=\"Utility\"\u003e\u003c/A\u003eUtility"],"readme":"You have a small team.  Setting up crash reporting tools, event tracking tools, and log management services\nis not what you want to spend your hours doing.  You know these are important to the health of your application,\nbut you just want to code.\n\nThat's where Foam comes into play.  Want to use Flurry and Papertrail in your app?  No problem:\n\u003cpre\u003e\n\u003cb\u003e@FoamApiKeys\u003c/b\u003e(\n    \u003cb\u003eflurry\u003c/b\u003e = \"S6S7S8S9S0S1S2S3S4S5\", // API Key\n    \u003cb\u003epapertrail\u003c/b\u003e = \"logs2.papertrailapp.com:49999\" // Server URL\n)\npublic class MyApplication extends \u003cb\u003eFoamApplication\u003c/b\u003e {\n}\n\u003c/pre\u003e\n\nWant to use Google Analytics, PagerDuty, and Logentries?  Sure...\n```java\n@FoamApiKeys(\n    googleAnalytics = \"UA-00000000-1\", // Tracking ID\n    pagerDuty = \"3a3b3c3d3e3f3g3h3i3j3k3l3m3n3o3p\", // API Key\n    logentries = \"data.logentries.com:12345\" // Server URL\n)\npublic class MyApplication extends FoamApplication {\n}\n```\n\nYou add your API Keys, we'll do the rest.\n\n## Supported Services\n\n| Crash Reporting    | Event Tracking   | Log Management |\n|--------------------|------------------|----------------|\n| PagerDuty          | Flurry           | Papertrail     |\n| Papertrail         | Mixpanel         | Logentries     |\n| HockeyApp          | Google Analytics |                |\n| Flurry             | Graphite         |                |\n\n**Crash Reporting:** Unhandled exceptions will be reported.\n\n**Event Tracking:** Activity launches will be tracked.\n\n**Log management:** Error logs from devices will be reported.\n\n## Setup All The Things\n\n```java\n@FoamApiKeys(\n    pagerDuty = \"3a3b3c3d3e3f3g3h3i3j3k3l3m3n3o3p\",\n    papertrail = \"logs2.papertrailapp.com:49999\",\n    hockeyApp = \"b2044c3055d4066e5077f6088g7099h8\",\n    flurry = \"S6S7S8S9S0S1S2S3S4S5\"\n    mixpanel = \"221b331c441d551e661f771g881h991i\",\n    googleAnalytics = \"UA-00000000-1\",\n    logentries = \"data.logentries.com:12345\",\n    graphite = \"[api-key@]graphite.myhost.com:2003\"\n)\npublic class MyApplication extends FoamApplication {\n}\n```\n\nThat's it.  You've just enabled all of these services for your application.  Well, almost.  Make sure you also have the following set:\n\n1. Internet permission in your `AndroidManifest.xml`:\n\n        \u003cuses-permission android:name=\"android.permission.INTERNET\" /\u003e\n\n1. SDK level 14 or higher in `build.gradle`:\n\n        minSdkVersion 14\n\n1. Define your custom Application class in your `AndroidManifest.xml`:\n\n        \u003capplication\n            android:name=\"com.your.app.MyApplication\"\n\n1. Add dependencies for Foam, Retrofit, and Gson in `build.gradle`:\n\n        compile 'com.percolate:foam:0.9.4'\n        compile 'com.squareup.retrofit:retrofit:1.9.0'\n        compile 'com.google.code.gson:gson:2.3'\n\n## Where to find your API Keys:\n\n**HockeyApp**: Click your name (top right) -\u003e API Tokens -\u003e Create an API token. _(permissions can be set to \"Read Only\")_\n\n**Mixpanel**: Your project 'Token' can be found under \"Update project settings\" (gear icon on the bottom left).\n\n**PagerDuty**: Configuration -\u003e API Access -\u003e Create API Key\n\n**Papertrail**: Add a system.  You'll see \"Your systems will log to \u0026lt;url\u0026gt;\".  Use this URL.\n\n**Logentries**: Add a new log -\u003e Select Manual (Gear icon) -\u003e Change \"How are the logs sent?\" to \"Plain TCP, UDP - logs are sent via syslog.\" -\u003e Click create.  You will get back \"Start sending logs to \u0026lt;url\u0026gt;\".  Use this URL.\n\n**Google Analytics**: Create a new Property -\u003e Select \"Mobile App\" -\u003e Click \"Get Tracking ID\".\n\n**Flurry**: Create an application in Flurry then add your application key. _(FlurryAnalytics-x.x.x.jar must be added manually to your project {TODO document in wiki})_\n\n**Graphite**: Provided by the maintainer of your graphite host.\n\n## Notes:\n\n- It takes time for some services to process incoming data.  There may be a delay of few hours before anything shows up.  Be patient.\n- Like other crash reporting tools, crashes are sent when the user reopens the app after a crash.  Keeping an app open to send data during a crash would lead to other problems, such as ANRs.\n- Does you application currently extend MultiDexApplication?  No problem, just use our `FoamMultiDexApplication` version instead.\n- Can't extend `FoamApplication` or `FoamMultiDexApplication` for some reason?  That's fine too.  Make your application class implement our `FoamApp` interface, and create an instance of `FoamMain` in `onCreate`.  See [FoamApplication.java](https://github.com/percolate/foam/blob/master/Foam/foam/src/main/java/com/percolate/foam/FoamApplication.java) for an example.\n- If your application may be sending lots of data, you may want to set `wifiOnly = true` on the `@FoamApiKeys` annotation.\n- You can use `FoamEvent#track(Activity activity, String event)` to track custom events.\n- You can use `FoamDisabler#disable()` to disable Foam, and `FoamDisabler#reenable()` to turn it back on.  Useful to hook up to a \"Do not track\" user setting.\n\n**Why no Crashlytics?**\n\n  We had it.  Then we removed it.  \n  Crashlytics requires some [custom setup](https://crashlytics.com/downloads).  There is no way around this.  \n  After which, enabling crashlytics is a single line of code `Crashlytics.start(this)`.  \n  This tool would not lessen setup, configuration, or required coding coding as it does with the other services we support.  \n  If Crashlytics were to ever support manual configuration or provide an API to submit crashes, we will add it.  \n  In the meantime, if you wish to use Crashlytics in your application, instructions can be found [here](https://crashlytics.com/downloads).\n\n## TODO\n\n**iOS version:** Coming soon  \n**Services to add:** Loggly\n\nIf you would like to add a new service please create a pull request.  A good example of what is required is contained in our [Adding Graphite PR]( https://github.com/percolate/foam/pull/3).\n\nFeel free to open a [new issue](https://github.com/percolate/foam/issues) for platforms you would like to see added.\n\n## License\n\nOpen source.  Distributed under the BSD 3 license.  See [LICENSE](https://github.com/percolate/foam/blob/master/LICENSE) for details.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpercolate%2Ffoam","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fpercolate%2Ffoam","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpercolate%2Ffoam/lists"}