{"id":21820340,"url":"https://github.com/trademe/plunge","last_synced_at":"2025-04-14T02:46:32.091Z","repository":{"id":37983343,"uuid":"175732781","full_name":"TradeMe/Plunge","owner":"TradeMe","description":"An Android Library for building and testing Deep Link handling","archived":false,"fork":false,"pushed_at":"2022-08-22T01:39:30.000Z","size":272,"stargazers_count":10,"open_issues_count":5,"forks_count":3,"subscribers_count":8,"default_branch":"master","last_synced_at":"2025-03-27T16:50:42.212Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Kotlin","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/TradeMe.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2019-03-15T02:16:00.000Z","updated_at":"2023-09-08T17:51:35.000Z","dependencies_parsed_at":"2022-09-06T20:01:52.677Z","dependency_job_id":null,"html_url":"https://github.com/TradeMe/Plunge","commit_stats":null,"previous_names":[],"tags_count":3,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/TradeMe%2FPlunge","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/TradeMe%2FPlunge/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/TradeMe%2FPlunge/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/TradeMe%2FPlunge/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/TradeMe","download_url":"https://codeload.github.com/TradeMe/Plunge/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248813064,"owners_count":21165533,"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-11-27T16:31:53.287Z","updated_at":"2025-04-14T02:46:32.073Z","avatar_url":"https://github.com/TradeMe.png","language":"Kotlin","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Plunge\n\n### _Simple, easily testable deep link handling – the way it should be._\n\n\n## Installation\n\nAdd the dependencies to your module-level `build.gradle` file:\n\n```groovy\nbuildscript {\n  dependencies {\n    classpath \"nz.co.trademe.plunge:plunge-gradle-plugin:current_version\"\n  }\n}\n\napply plugin: 'nz.co.trademe.plunge'\n\ndependencies {\n  implementation 'nz.co.trademe.plunge:plunge:current_version'\n\n  testImplementation 'nz.co.trademe.plunge:plunge-test:current_version'\n  testImplementation 'nz.co.trademe.plunge:plunge-parsing:current_version'\n}\n```\n\nThe `current_version` is: [ ![Download](https://api.bintray.com/packages/trademe/Plunge/plunge/images/download.svg) ](https://bintray.com/trademe/Plunge/plunge/_latestVersion)\n\n\n## Better deep linking in 7 easy steps!\n\n1. Add link-handling support to the `AndroidManifest.xml` file, as per usual:\n\n```xml\n\u003cintent-filter\u003e\n  ...\n  \u003cdata android:scheme=\"https\"\n        android:host=\"plunge.example.com\"\n        android:pathPattern=\"/submarines/.*/buy\"\n  ...\n\u003c/intent-filter\u003e\n```\n\n2. Implement a `UrlSchemeHandler`:\n\n```kotlin\nclass PlungeExampleSchemeHandler(private val router: DeepLinkRouter): UrlSchemeHandler() {\n    override fun hostMatches(host: String): Boolean = host.contains(\"plunge.example.com\")\n\n    override val matchers by patterns {\n        pattern(\"/submarines/{d|id}/buy\") { result -\u003e router.launchBuyPage(result.params[\"id\"]) }\n    }\n}\n\ninterface DeepLinkRouter {\n  fun launchBuyPage(id: String) // Note: parameters are always Strings\n}\n```\n\n3. Forward your links from your intent filter `Activity`:\n\n```kotlin\nclass PlungeActivity : AppCompatActivity(), DeepLinkRouter {\n  val linkHandler = DeepLinkHandler.withSchemeHandlers(\n    PlungeExampleSchemeHandler(this)\n  )\n\n  fun onDeepLinkCaught() {\n    val link = Uri.parse(getIntent().getData())\n\n    val handled = linkHandler.processUri(link)\n    if (!handled) {\n        // ... Some kind of default fallback\n    }\n  }\n\n  fun launchBuyPage(id: String) {\n    // ...\n  }\n}\n```\n\n4. Add the path to your test cases to your module-level `build.gradle` file:\n\n```groovy\nplunge {\n    testDirectory = file(\"$projectDir/src/test/test-cases\")\n}\n```\n\n5. Write some test cases to ensure the links you want to handle will be handled:\n\n```json\n{\n  \"url\": \"https://plunge.example.com/submarines/12345/buy\",\n  \"description\": \"The page for buying a submarine\",\n  \"params\": [\n    {\n      \"name\": \"id\",\n      \"value\": \"12345\"\n    }\n  ]\n}\n```\n\n6. Write some more test cases to ensure the links you _don't_ want to handle won't launch your app:\n\n```json\n{\n  \"url\": \"https://plunge.example.com/submarines/sell\",\n  \"description\": \"The page for selling a submarine. We don't support this in the app yet, so users will have to use the desktop site.\",\n  \"handled\": false\n}\n```\n\n7. Finally, write a JUnit test case for executing Plunge tests:\n\n```kotlin\n@RunWith(ParameterizedRobolectricTestRunner::class)\n@Config(manifest = Config.NONE)\nclass PlungeExampleTests {\n  companion object {\n\n    @JvmStatic\n    private val pathToTests = System.getProperty(\"user.dir\") + \"/src/test/test-cases\"\n\n    @JvmStatic\n    @ParameterizedRobolectricTestRunner.Parameters(name = \"{0}\")\n    fun parameters() = PlungeTestRunner.testCases(pathToTests)\n\n  }\n\n  val linkHandler = DeepLinkHandler.withSchemeHandlers(\n    PlungeExampleSchemeHandler(Mockito.mock(DeepLinkRouter::class.java))\n  )\n\n  @ParameterizedRobolectricTestRunner.Parameter(0)\n  lateinit var testCase: PlungeTestCase\n\n  @Test\n  fun runTest() = PlungeTestRunner.assertPlungeTest(testCase, linkHandler)\n}\n```\n\n## Running tests\n\nPlunge unit tests can be easily run in the same way you'd run any other unit tests; however, a Gradle plugin is included to execute the verification tests. To run these tests, look for the appropriate `plungeTest` Gradle task for your build variant in the `verification` group. This task will build and install the app on the device or emulator currently connected to your machine, and execute your tests against it. The task will fail if any links are not correctly handled by the app (or links **are** handled by the app when they shouldn't be).\n\nIntegrate the task into your CI pipeline for an even better time!\n\n## More info\n\nSee [the wiki](https://github.com/TradeMe/Plunge/wiki) for more in-depth information about how to do better deep linking with Plunge.\n\n## License\n\nPlunge is made available under the MIT licence.\n\n## Contributing\n\nWe love contributions, but make sure to check out [CONTRIBUTING.MD](CONTRIBUTING.MD) first!\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftrademe%2Fplunge","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftrademe%2Fplunge","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftrademe%2Fplunge/lists"}