{"id":3644,"url":"https://github.com/instacart/truetime-android","last_synced_at":"2025-05-15T21:04:23.981Z","repository":{"id":41113769,"uuid":"62934066","full_name":"instacart/truetime-android","owner":"instacart","description":"Android NTP time library. Get the true current time impervious to device clock time changes","archived":false,"fork":false,"pushed_at":"2023-06-12T05:55:17.000Z","size":719,"stargazers_count":1435,"open_issues_count":40,"forks_count":195,"subscribers_count":36,"default_branch":"master","last_synced_at":"2025-04-08T04:14:07.731Z","etag":null,"topics":["android","clock","mobile","ntp","ntp-server","rxjava","sntp","time","truetime"],"latest_commit_sha":null,"homepage":"https://tech.instacart.com/truetime/","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/instacart.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}},"created_at":"2016-07-09T05:34:37.000Z","updated_at":"2025-03-27T06:41:35.000Z","dependencies_parsed_at":"2022-07-16T05:30:50.166Z","dependency_job_id":"89b5b6d3-3952-4474-a0de-e254d240f806","html_url":"https://github.com/instacart/truetime-android","commit_stats":null,"previous_names":[],"tags_count":1,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/instacart%2Ftruetime-android","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/instacart%2Ftruetime-android/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/instacart%2Ftruetime-android/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/instacart%2Ftruetime-android/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/instacart","download_url":"https://codeload.github.com/instacart/truetime-android/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254422754,"owners_count":22068678,"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","clock","mobile","ntp","ntp-server","rxjava","sntp","time","truetime"],"created_at":"2024-01-05T20:16:47.313Z","updated_at":"2025-05-15T21:04:23.963Z","avatar_url":"https://github.com/instacart.png","language":"Kotlin","readme":"# TrueTime for Android\n\n![TrueTime](truetime.png \"TrueTime for Android\")\n\n*⚠️ See work in progress section below. TrueTime is undergoing some changes*\n\n----------------------------------------\n\n*Make sure to check out our counterpart too: [TrueTime](https://github.com/instacart/TrueTime.swift)\n, an NTP library for Swift.*\n\n# What is TrueTime?\n\nTrueTime is an (S)NTP client for Android. It helps you calculate the date and time \"now\" impervious\nto manual changes to device clock time.\n\n## Why do I need TrueTime?\n\nIn certain applications it becomes important to get the real or \"true\" date and time. On most\ndevices, if the clock has been changed manually, then a `Date()` instance gives you a time impacted\nby local settings.\n\nUsers may do this for a variety of reasons, like being in different timezones, trying to be punctual\nby setting their clocks 5 – 10 minutes early, etc. Your application or service may want a date that\nis unaffected by these changes and reliable as a source of truth. TrueTime gives you that.\n\nYou can read more about the use case in\nour [intro blog post](https://tech.instacart.com/offline-first-introducing-truetime-for-swift-and-android-15e5d968df96)\n.\n\n# How does TrueTime work?\n\nIn a [conference talk](https://vimeo.com/190922794), we explained how the full NTP implementation\nworks. Check the [video](https://vimeo.com/190922794#t=1466s)\nand [slides](https://speakerdeck.com/kaushikgopal/learning-rx-by-example-2?slide=31) out for\nimplementation details.\n\nTrueTime has since been migrated to Kotlin \u0026 Coroutines and no longer requires the additional Rx\ndependency. The concept hasn't changed but the above video is still a good explainer on the concept.\n\n# How do I use TrueTime?\n\n## Installation\n\nWe use [JitPack](https://jitpack.io) to host the library.\n\n[![](https://jitpack.io/v/instacart/truetime-android.svg)](https://jitpack.io/#instacart/truetime-android)\n\nAdd this to your application's `build.gradle` file:\n\n```groovy\nrepositories {\n    maven {\n        url \"https://jitpack.io\"\n    }\n}\n\ndependencies {\n    // ...\n    implementation 'com.github.instacart:truetime-android:\u003crelease-version\u003e'\n}\n```\n\n## Usage\n\nIn your application class start the TrueTime sync-er like so:\n\n```kt\n// App.kt\nclass App : Application() {\n\n    val trueTime = TrueTimeImpl()\n\n    override fun onCreate() {\n        super.onCreate()\n        trueTime.sync()\n    }\n}\n```\n\nOnce TrueTime gets a fix with an NTP time server, you can simply use:\n\n```kt\n(application as App).trueTime.now()\n```\n\n_Btw don't do ↑, inject TrueTime into your app and then just call `trueTime.now()`_\n\n# Installation\n\n## Usage\n\n```kt\nval trueTime = TrueTimeImpl()\ntrueTime.sync()\ntrueTime.now()\n```\n\n💥\n\n# ⚠️ Work in Progress 4.0\n\nWith the move to Kotlin \u0026 Coroutines TrueTime 4 was\na [major overhaul](https://github.com/instacart/truetime-android/pull/129). We still haven't ported\nsome of the additional bells \u0026 whistles. This section keeps track of those features (that will come\nin the near future). TrueTime is completely functional without these additional features, so feel\nfree to start using it.\n\nMost of these todos should have corresponding \"TODO\" comments within the code.\n\n- [ ] Introduce a Cache provider\n\n* Add an `interface CacheProvider` so folks can inject in their preferred caching mechanisms\n* Provide a default cache implementation (probably using the non-android version\n  of [DataStore](https://developer.android.com/topic/libraries/architecture/datastore#kts))\n* ? Provide example of using this with a Database like Realm\n\n- [ ] Algorithmic improvements\n\nThere are some exciting improvements that we have planned and use internally. Will have to upstream\nthese changes (with a cleaner api + implementation)\n\n- [ ] Move android dependency to separate package\n\nThere's no reason for TrueTime (with the move to coroutines) to be an \"android\" library. It can be a\npure kotlin lib.\n\nThe only remaining dependency is `SystemClock` (which we should just have a provider for).\n\n- [ ] Utilize all ntp pool addresses from `TrueTimeParameters.ntpHostPool`\n\nWe currently only take the first ntp host pool address from the supplied parameters. In the future,\nit would be nice to provide multiple ntp \"pool\" addresses like `time.google.com`, `time.apple.com`\nand utilize all of those to get the \"best\" value.\n\n- [ ] BootCompletedBroadcastReceiver sample\n\nEverytime a device is rebooted, the Truetime info is invalid. Previous libraries included an\nactual `BroadcastReceiver` but this is better handled by the application than the library. For safe\nmeasure, I'll include an example of how this can be done in case folks are curious.\n\n# License\n\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","funding_links":[],"categories":["Time","Libraries"],"sub_categories":["Date \u0026 Time"],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Finstacart%2Ftruetime-android","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Finstacart%2Ftruetime-android","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Finstacart%2Ftruetime-android/lists"}