{"id":13604463,"url":"https://github.com/jonfinerty/Once","last_synced_at":"2025-04-12T02:30:43.427Z","repository":{"id":34445380,"uuid":"38379873","full_name":"jonfinerty/Once","owner":"jonfinerty","description":"A small Android library to manage one-off operations.","archived":false,"fork":false,"pushed_at":"2021-07-04T15:46:18.000Z","size":229,"stargazers_count":1198,"open_issues_count":3,"forks_count":81,"subscribers_count":25,"default_branch":"master","last_synced_at":"2024-08-02T19:34:25.369Z","etag":null,"topics":["android","android-library"],"latest_commit_sha":null,"homepage":"","language":"Java","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/jonfinerty.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE.txt","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2015-07-01T15:46:16.000Z","updated_at":"2024-07-27T23:32:13.000Z","dependencies_parsed_at":"2022-07-12T16:11:26.500Z","dependency_job_id":null,"html_url":"https://github.com/jonfinerty/Once","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/jonfinerty%2FOnce","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jonfinerty%2FOnce/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jonfinerty%2FOnce/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jonfinerty%2FOnce/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/jonfinerty","download_url":"https://codeload.github.com/jonfinerty/Once/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":223489549,"owners_count":17153780,"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","android-library"],"created_at":"2024-08-01T19:00:46.149Z","updated_at":"2024-11-07T09:30:22.995Z","avatar_url":"https://github.com/jonfinerty.png","language":"Java","funding_links":[],"categories":["Java"],"sub_categories":[],"readme":"# Once\n[![Android Weekly](http://img.shields.io/badge/Android%20Weekly-%23164-33B5E5.svg?style=flat)](http://androidweekly.net/issues/issue-164)\n[![Android Arsenal](https://img.shields.io/badge/Android%20Arsenal-Once-brightgreen.svg?style=flat)](http://android-arsenal.com/details/1/2206)\n[![Build Status](https://travis-ci.org/jonfinerty/Once.svg?branch=master)](https://travis-ci.org/jonfinerty/Once)\n\nA small Android library to manage one-off operations for API 14 and higher.\n\n----\n\nSome things should happen **once**.\n* Users should only get the guided tour _once_. \n* Release notes should only pop up _once every app upgrade_. \n* Your app should only phone home to update content _once every hour_.\n\n`Once` provides a simple API to track whether or not your app has already performed an action within a given scope.\n\n## Usage\n\nFirst things first, you'll need to initialise Once on start up. In your `Application` class's `onCreate()` override add the follow:\n\n```java\nOnce.initialise(this);\n```\n\n\n### Checking if something has been _done_\n\nNow you're ready to go. Say you wanted to navigate to a 'WhatsNew' Activity every time your app is upgraded:\n\n```java\nString showWhatsNew = \"showWhatsNewTag\";\n\nif (!Once.beenDone(Once.THIS_APP_VERSION, showWhatsNew)) {\n    startActivity(new Intent(this, WhatsNewActivity.class));\n    Once.markDone(showWhatsNew);\n}\n```\n\nOr if you want your app tour to be shown only when a user install, simply check the tag using the `THIS_APP_INSTALL` scope:\n\n```java\nif (!Once.beenDone(Once.THIS_APP_INSTALL, showAppTour)) {\n    ...\n    Once.markDone(showAppTour);\n}\n```\n\nYour app operations can also be rate-limited by time spans. So for example if you only want to phone back to your server a maximum of once per hour, you'd do the following: \n```java\nif (!Once.beenDone(TimeUnit.HOURS, 1, phonedHome) { ... }\n```\n\nIf checking by time bounds is not enough you can manually get the `Date` of last time a tag was marked done by:\n```java\nDate lastDone = Once.lastDone(brushedTeeth);\n```\nThis will return null if the tag has never been marked as done.\n\n### Marking something as _to do_\n\nSay one part of your app triggers functionality elsewhere. For example you might have some advanced feature onboarding to show on the main activity, but you only want to show it once the user has seen the basic functionality.\n\n```java\n\n// in the basic functionality activity\nOnce.toDo(Once.THIS_APP_INSTALL, \"show feature onboarding\");\n...\n\n// back in the home activity\nif (Once.needToDo(showAppTour)) {\n    // do some operations\n    ...\n\n    // after task has been done, mark it as done as normal\n    Once.markDone(showAppTour);\n}\n```\n\nWhen a task is marked done it is removed from the set of tasks 'to do' so subsequent `needToDo(tag)` calls will return `false`. To stop the tag from being added back to your todo list each time the user looks at the basic functionality task, we've added a scope to the todo call: `toDo(Once.THIS_APP_INSTALL, tag)`. You could also use the `THIS_APP_VERSION` scope for todo's which should happen once per app version, or leave off scope complete for tasks which should be repeated every time.\n\n### Doing something once per X events\n\nSometimes you need to keep track of how many times something has happened before you act on it. For example, you could prompt the user to rate your app after they've used the core functionality three times.\n\n```java\n// Once again in the basic functionality activity\nOnce.markDone(\"action\");\nif (Once.beenDone(\"action\", Amount.exactly(3))) {\n    showRateTheAppDialog();\n}\n```\n\nYou can also change the count checking from `exactly(int x)` times, to either `Amount.lessThan(int x)` times or `Amount.moreThan(int x)` times. When you don't specific a particular amount, Once will default to `Amount.moreThan(0)` i.e. checking if it's ever been done at all.\n\nTo de-noise your code a bit more you can also static-import the `Once` methods, so usage looks a bit cleaner\n\n```java\nimport static jonathanfinerty.once.Once.THIS_APP_INSTALL;\nimport static jonathanfinerty.once.Once.beenDone;\nimport static jonathanfinerty.once.Once.markDone;\n\n...\n...\n\nif (!beenDone(THIS_APP_VERSION, tagName)) {\n    ...\n    markDone(showWhatsNew);\n}\n```\n\n## Installation\n\nAdd a library dependency to your app module's `build.gradle`:\n\n```\ndependencies {\n    compile 'com.jonathanfinerty.once:once:1.3.1'\n}\n```\n\nYou'll need to have `mavenCentral()` in your list of repositories\n\n## Example\n\nTry out the sample app here: https://play.google.com/store/apps/details?id=jonathanfinerty.onceexample and have a look at it's source code in `once-example/` for more simple usage.\n\n## Contributing\n\n`Once` was made in '20%' time at [Huddle](https://talentcommunity.huddle.com/), where its used to help build our [Android apps](https://play.google.com/store/apps/details?id=com.huddle.huddle). [Pete O'Grady](https://twitter.com/peteog) and [Paul Simmons](https://twitter.com/slamminsoup) also provided invaluable feedback.\n\nPull requests and github issues are more than welcome and you can get in touch with me directly [@jonfinerty](https://twitter.com/jonfinerty).\n\n## License\n\n```\nCopyright 2021 Jon Finerty\n\nLicensed under the Apache License, Version 2.0 (the \"License\");\nyou may not use this file except in compliance with the License.\nYou may obtain a copy of the License at\n\n   http://www.apache.org/licenses/LICENSE-2.0\n\nUnless required by applicable law or agreed to in writing, software\ndistributed under the License is distributed on an \"AS IS\" BASIS,\nWITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\nSee the License for the specific language governing permissions and\nlimitations under the License.\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjonfinerty%2FOnce","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjonfinerty%2FOnce","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjonfinerty%2FOnce/lists"}