Once


Source link: https://github.com/jonfinerty/Once

Once

A small Android library to manage one-off operations for API 9 and higher.


Some things should happen once.

  • Users should only get the guided tour once.
  • Release notes should only pop up once every app upgrade.
  • Your app should only phone home to update content once every hour.

Once provides a simple API to track whether or not your app has already performed an action within a given scope.

Usage

First things first, you'll need to initialise Once on start up. In your Application class's onCreate() override add the follow:

Once.initialise(this);

Checking if something has been done

Now you're ready to go. Say you wanted to navigate to a 'WhatsNew' Activity every time your app is upgraded:

String showWhatsNew = "showWhatsNewTag";  if (!Once.beenDone(Once.THIS_APP_VERSION, showWhatsNew)) {

  startActivity(new Intent(this, WhatsNewActivity.class));

  Once.markDone(showWhatsNew);
 
}

Or if you want your app tour to be shown only when a user install, simply check the tag using the THIS_APP_INSTALL scope:

if (!Once.beenDone(Once.THIS_APP_INSTALL, showAppTour)) {

  ...
  Once.markDone(showAppTour);
 
}

Your app operations can also be rate-limited by time spans. So for example if you only want to phone back to your a maximum of server once per hour, you'd do the following:

if (!Once.beenDone(TimeUnit.HOURS, 1, phonedHome) {
 ... 
}

If checking by time bounds is not enough you can manually get the Date of last time a tag was marked done by:

Date lastDone = Once.lastDone(brushedTeeth);

This will return null if the tag has never been marked as done.

Marking something as to do

Say 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.

// in the basic functionality activity Once.toDo(Once.THIS_APP_INSTALL, "show feature onboarding");
 ...  // back in the home activity if (Once.needToDo(showAppTour)) {

  // do some operations
  ...

// after task has been done, mark it as done as normal
  Once.markDone(showAppTour);
 
}

When 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.

Doing something once per X events

Sometimes 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.

// Once again in the basic functionality activity Once.markDone("action");
 if (Once.beenDone("action", Amount.exactly(3))) {

  showRateTheAppDialog();
 
}

You 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.

To de-noise your code a bit more you can also static-import the Once methods, so usage looks a bit cleaner

import static jonathanfinerty.once.Once.THIS_APP_INSTALL; import static jonathanfinerty.once.Once.beenDone; import static jonathanfinerty.once.Once.markDone;  ... ...  if (!beenDone(THIS_APP_VERSION, tagName)) {

  ...
  markDone(showWhatsNew);
 
}

Installation

Add a library dependency to your app module's build.gradle:

dependencies {

  compile 'com.jonathanfinerty.once:once:1.2.2' 
}
 

You'll need to have jcenter() in your list of repositories

Example

Try 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.

Contributing

Once was made in '20%' time at Huddle, where its used to help build our Android apps. Pete O'Grady and Paul Simmons also provided invaluable feedback.

Pull requests and github issues are more than welcome and you can get in touch with me directly @jonfinerty.

License

Copyright 2017 Jon Finerty  Licensed under the Apache License, Version 2.0 (the "License");
 you may not use this file except in compliance with the License. You may obtain a copy of the License at
  http://www.apache.org/licenses/LICENSE-2.0  Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License. 

Resources

Useful library for selecting images and videos from sd-card. The library can be used to display images & videos in file view or folder view. File view shows all files whereas Folder view shows files categorized. All items are sorted according to date-time with latest item showing first.

Gmail like pull to refresh implementation.

You can see Teleport as an Android Wear "plugin" you can add to your Activities and Services.

Teleport provides you commodity classes to easily establish a communication between a mobile handheld device and an Android Wear device.

BlurBehind is a library to add blur effect for your Android views.

Before API level 14 there was a Window flag called FLAG_BLUR_BEHIND. It was used for "blurring everything behind a window" and is no longer supported by Android.

BlurBehind provides an easy way to have that effect, with customization, for your window without API level restrictions.

A library for creating Data Access Objects from Android Cursors and converting them back into ContentValues.

Burst is a set of test runners which rely on enums for varying both the instantiation of test classes and the methods inside of them.

Topics


2D Engines   3D Engines   9-Patch   Action Bars   Activities   ADB   Advertisements   Analytics   Animations   ANR   AOP   API   APK   APT   Architecture   Audio   Autocomplete   Background Processing   Backward Compatibility   Badges   Bar Codes   Benchmarking   Bitmaps   Bluetooth   Blur Effects   Bread Crumbs   BRMS   Browser Extensions   Build Systems   Bundles   Buttons   Caching   Camera   Canvas   Cards   Carousels   Changelog   Checkboxes   Cloud Storages   Color Analysis   Color Pickers   Colors   Comet/Push   Compass Sensors   Conferences   Content Providers   Continuous Integration   Crash Reports   Credit Cards   Credits   CSV   Curl/Flip   Data Binding   Data Generators   Data Structures   Database   Database Browsers   Date &   Debugging   Decompilers   Deep Links   Dependency Injections   Design   Design Patterns   Dex   Dialogs   Distributed Computing   Distribution Platforms   Download Managers   Drawables   Emoji   Emulators   EPUB   Equalizers &   Event Buses   Exception Handling   Face Recognition   Feedback &   File System   File/Directory   Fingerprint   Floating Action   Fonts   Forms   Fragments   FRP   FSM   Functional Programming   Gamepads   Games   Geocaching   Gestures   GIF   Glow Pad   Gradle Plugins   Graphics   Grid Views   Highlighting   HTML   HTTP Mocking   Icons   IDE   IDE Plugins   Image Croppers   Image Loaders   Image Pickers   Image Processing   Image Views   Instrumentation   Intents   Job Schedulers   JSON   Keyboard   Kotlin   Layouts   Library Demos   List View   List Views   Localization   Location   Lock Patterns   Logcat   Logging   Mails   Maps   Markdown   Mathematics   Maven Plugins   MBaaS   Media   Menus   Messaging   MIME   Mobile Web   Native Image   Navigation   NDK   Networking   NFC   NoSQL   Number Pickers   OAuth   Object Mocking   OCR Engines   OpenGL   ORM   Other Pickers   Parallax List   Parcelables   Particle Systems   Password Inputs   PDF   Permissions   Physics Engines   Platforms   Plugin Frameworks   Preferences   Progress Indicators   ProGuard   Properties   Protocol Buffer   Pull To   Purchases   Push/Pull   QR Codes   Quick Return   Radio Buttons   Range Bars   Ratings   Recycler Views   Resources   REST   Ripple Effects   RSS   Screenshots   Scripting   Scroll Views   SDK   Search Inputs   Security   Sensors   Services   Showcase Views   Signatures   Sliding Panels   Snackbars   SOAP   Social Networks   Spannable   Spinners   Splash Screens   SSH   Static Analysis   Status Bars   Styling   SVG   System   Tags   Task Managers   TDD &   Template Engines   Testing   Testing Tools   Text Formatting   Text Views   Text Watchers   Text-to   Toasts   Toolkits For   Tools   Tooltips   Trainings   TV   Twitter   Updaters   USB   User Stories   Utils   Validation   Video   View Adapters   View Pagers   Views   Watch Face   Wearable Data   Wearables   Weather   Web Tools   Web Views   WebRTC   WebSockets   Wheel Widgets   Wi-Fi   Widgets   Windows   Wizards   XML   XMPP   YAML   ZIP Codes