TrueTime for Android

⚠️ See work in progress section below. TrueTime is undergoing some changes

Make sure to check out our counterpart too: TrueTime
, an NTP library for Swift.

What is TrueTime?

TrueTime is an (S)NTP client for Android. It helps you calculate the date and time “now” impervious
to manual changes to device clock time.

Why do I need TrueTime?

In certain applications it becomes important to get the real or “true” date and time. On most
devices, if the clock has been changed manually, then a Date() instance gives you a time impacted
by local settings.

Users may do this for a variety of reasons, like being in different timezones, trying to be punctual
by setting their clocks 5 – 10 minutes early, etc. Your application or service may want a date that
is unaffected by these changes and reliable as a source of truth. TrueTime gives you that.

You can read more about the use case in
our intro blog post
.

How does TrueTime work?

In a conference talk, we explained how the full NTP implementation
works. Check the video
and slides out for
implementation details.

TrueTime has since been migrated to Kotlin & Coroutines and no longer requires the additional Rx
dependency. The concept hasn’t changed but the above video is still a good explainer on the concept.

How do I use TrueTime?

Installation

We use JitPack to host the library.

Add this to your application’s build.gradle file:

repositories {
    maven {
        url "https://jitpack.io"
    }
}
dependencies {
    // ...
    implementation 'com.github.instacart:truetime-android:<release-version>'
}

Usage

In your application class start the TrueTime sync-er like so:

// App.kt
class App : Application() {
    val trueTime = TrueTimeImpl()
    override fun onCreate() {
        super.onCreate()
        trueTime.sync()
    }
}

Once TrueTime gets a fix with an NTP time server, you can simply use:

(application as App).trueTime.now()

Btw don’t do ↑, inject TrueTime into your app and then just call trueTime.now()

Installation

Usage

val trueTime = TrueTimeImpl()
trueTime.sync()
trueTime.now()

💥

⚠️ Work in Progress 4.0

With the move to Kotlin & Coroutines TrueTime 4 was
a major overhaul. We still haven’t ported
some of the additional bells & whistles. This section keeps track of those features (that will come
in the near future). TrueTime is completely functional without these additional features, so feel
free to start using it.

Most of these todos should have corresponding “TODO” comments within the code.

• Introduce a Cache provider

• Add an interface CacheProvider so folks can inject in their preferred caching mechanisms
• Provide a default cache implementation (probably using the non-android version
  of DataStore)
• ? Provide example of using this with a Database like Realm

• Algorithmic improvements

There are some exciting improvements that we have planned and use internally. Will have to upstream
these changes (with a cleaner api + implementation)

• Move android dependency to separate package

There’s no reason for TrueTime (with the move to coroutines) to be an “android” library. It can be a
pure kotlin lib.

The only remaining dependency is SystemClock (which we should just have a provider for).

• Utilize all ntp pool addresses from TrueTimeParameters.ntpHostPool

We currently only take the first ntp host pool address from the supplied parameters. In the future,
it would be nice to provide multiple ntp “pool” addresses like time.google.com, time.apple.com
and utilize all of those to get the “best” value.

• BootCompletedBroadcastReceiver sample

Everytime a device is rebooted, the Truetime info is invalid. Previous libraries included an
actual BroadcastReceiver but this is better handled by the application than the library. For safe
measure, I’ll include an example of how this can be done in case folks are curious.

License

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.