{"id":22122962,"url":"https://github.com/telemetrydeck/kotlinsdk","last_synced_at":"2025-07-25T14:31:21.039Z","repository":{"id":41970181,"uuid":"358612712","full_name":"TelemetryDeck/KotlinSDK","owner":"TelemetryDeck","description":"Kotlin SDK for TelemetryDeck, a privacy-conscious analytics service for apps and websites.","archived":false,"fork":false,"pushed_at":"2024-11-25T06:34:40.000Z","size":313,"stargazers_count":7,"open_issues_count":6,"forks_count":6,"subscribers_count":3,"default_branch":"main","last_synced_at":"2024-11-25T07:29:42.319Z","etag":null,"topics":["analytics","android","kotlin"],"latest_commit_sha":null,"homepage":"","language":"Kotlin","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/TelemetryDeck.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,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2021-04-16T13:43:49.000Z","updated_at":"2024-08-01T11:56:30.000Z","dependencies_parsed_at":"2024-06-25T12:57:53.393Z","dependency_job_id":"e95529f7-a79f-405c-adc4-86a172d0db28","html_url":"https://github.com/TelemetryDeck/KotlinSDK","commit_stats":null,"previous_names":[],"tags_count":8,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/TelemetryDeck%2FKotlinSDK","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/TelemetryDeck%2FKotlinSDK/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/TelemetryDeck%2FKotlinSDK/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/TelemetryDeck%2FKotlinSDK/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/TelemetryDeck","download_url":"https://codeload.github.com/TelemetryDeck/KotlinSDK/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":227584817,"owners_count":17789758,"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":["analytics","android","kotlin"],"created_at":"2024-12-01T15:28:33.746Z","updated_at":"2025-07-25T14:31:21.021Z","avatar_url":"https://github.com/TelemetryDeck.png","language":"Kotlin","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Kotlin SDK for TelemetryDeck\n\nThis package allows you to send signals to [TelemetryDeck](https://telemetrydeck.com) from your\nAndroid applications. Sign up for a free account at [telemetrydeck.com](https://telemetrydeck.com)\n\n* [Installation](#installation)\n    * [Dependencies](#dependencies)\n    * [Permission for internet access](#permission-for-internet-access)\n* [Getting Started](#getting-started)\n    * [Using the application manifest](#using-the-application-manifest)\n    * [Programmatic Usage](#programmatic-usage)\n* [Sending Signals](#sending-signals)\n* [User Identifiers](#user-identifiers)\n    * [Custom User Identifiers](#custom-user-identifiers)\n    * [Environment Parameters](#environment-parameters)\n* [Default Parameters](#default-parameters)\n* [Default Prefix](#default-prefix)\n* [Navigation Signals](#navigation-signals)\n* [Acquisition](#acquisition)\n* [Session Tracking](#session-tracking)\n* [Custom Telemetry](#custom-telemetry)\n* [Purchase Completed](#purchase-completed)\n* [Custom Logging](#custom-logging)\n* [Requirements](#requirements)\n* [Migrating providers to 5.0+](#migrating-providers-to-50)\n* [Migrating providers to 3.0+](#migrating-providers-to-30)\n\n## Installation\n\n### Dependencies\n\nThe Kotlin SDK for TelemetryDeck is available from Maven Central at the following coordinates:\n\n```groovy\n// `build.gradle`\ndependencies {\n    implementation 'com.telemetrydeck:kotlin-sdk:6.2.0'\n}\n```\n\n```kotlin\n// `build.gradle.kts`\ndependencies {\n    implementation(\"com.telemetrydeck:kotlin-sdk:6.2.0\")\n}\n```\n\nIf needed, update your `gradle.settings` to reference Kotlin version compatible with 2.0.20, e.g.:\n\n```\nid \"org.jetbrains.kotlin.android\" version \"2.0.20\" apply false\n```\n\n### Permission for internet access\n\nSending signals requires access to the internet so the following permission should be added to the\napp's `AndroidManifest.xml`\n\n```xml\n\n\u003cuses-permission android:name=\"android.permission.INTERNET\" /\u003e\n```\n\n## Getting Started\n\n### Using the application manifest\n\nA quick way to start is by adding your App ID to the `application` section of the app's\n`AndroidManifest.xml`:\n\n```xml\n\n\u003capplication\u003e\n    ...\n\n    \u003cmeta-data android:name=\"com.telemetrydeck.appID\"\n        android:value=\"XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX\" /\u003e\n\n\u003c/application\u003e\n```\n\nReplace `XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX` with your TelemetryDeck App ID.\n\nIn addition, the following optional properties are supported:\n\n- `com.telemetrydeck.showDebugLogs`\n- `com.telemetrydeck.apiBaseURL`\n- `com.telemetrydeck.sendNewSessionBeganSignal`\n- `com.telemetrydeck.testMode`\n- `com.telemetrydeck.defaultUser`\n\n### Programmatic Usage\n\nFor greater control you can set up and configure `TelemetryDeck` using the provided builder:\n\n```kotlin\nval builder = TelemetryDeck.Builder()\n    .appID(\"XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX\")\n    .showDebugLogs(true)\n    .defaultUser(\"Person\")\n\nTelemetryDeck.start(applicationContext, builder)\n```\n\n## Sending Signals\n\nTo send a signal immediately\n\n```kotlin\nTelemetryDeck.send(\"appLaunchedRegularly\")\n```\n\nTo enqueue a signal to be sent by TelemetryDeck at a later time\n\n```kotlin\nTelemetryDeck.signal(\"appLaunchedRegularly\")\n```\n\n## User Identifiers\n\nWhen `TelemetryDeck` is started for the first time, it will create a user identifier for the user\nthat is specific to the app installation.\n\n- The identity is stored within the application's file folder on the user's device.\n\n- The identifier will be removed when a user uninstalls an app. The KotlinSDK will not \"bridge\" the\n  user's identity between installations.\n\n- Users can reset the identifier at any time by using the \"Clear Data\" action in Settings of their\n  device.\n\nIf you have a better user identifier available, such as an email address or a username, you can use\nthat instead, by setting `defaultUser` (the identifier will be hashed before sending it) in\nconfiguration, or by passing the value when sending signals.\n\n### Custom User Identifiers\n\nIf you need a more robust mechanism for keep track of the user's identity, you can replace the\ndefault behaviour by providing your own implementation of `TelemetryDeckIdentityProvider`:\n\n```kotlin\nval builder = TelemetryDeck.Builder()\n    .appID(\"XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX\")\n    .showDebugLogs(true)\n    .defaultUser(\"Person\")\n    .identityProvider(YourIdentityProvider())\n\nTelemetryDeck.start(applicationContext, builder)\n```\n\n### Environment Parameters\n\nBy default, Kotlin SDK for TelemetryDeck will include the following environment parameters for each\noutgoing signal\n\n| Parameter name                                                | Provider                        | Description                                        |\n|---------------------------------------------------------------|---------------------------------|----------------------------------------------------|\n| `TelemetryDeck.AppInfo.buildNumber`                           | `EnvironmentParameterProvider`  |                                                    |\n| `TelemetryDeck.AppInfo.version`                               | `EnvironmentParameterProvider`  |                                                    |\n| `TelemetryDeck.AppInfo.versionAndBuildNumber`                 | `EnvironmentParameterProvider`  |                                                    |\n| `TelemetryDeck.Device.architecture`                           | `EnvironmentParameterProvider`  |                                                    |\n| `TelemetryDeck.Device.modelName`                              | `EnvironmentParameterProvider`  |                                                    |\n| `TelemetryDeck.Device.operatingSystem`                        | `EnvironmentParameterProvider`  |                                                    |\n| `TelemetryDeck.Device.platform`                               | `EnvironmentParameterProvider`  |                                                    |\n| `TelemetryDeck.Device.systemMajorMinorVersion`                | `EnvironmentParameterProvider`  |                                                    |\n| `TelemetryDeck.Device.systemMajorVersion`                     | `EnvironmentParameterProvider`  |                                                    |\n| `TelemetryDeck.Device.systemVersion`                          | `EnvironmentParameterProvider`  |                                                    |\n| `TelemetryDeck.Device.orientation`                            | `PlatformContextProvider`       |                                                    |\n| `TelemetryDeck.Device.screenDensity`                          | `PlatformContextProvider`       |                                                    |\n| `TelemetryDeck.Device.screenResolutionHeight`                 | `PlatformContextProvider`       |                                                    |\n| `TelemetryDeck.Device.screenResolutionWidth`                  | `PlatformContextProvider`       |                                                    |\n| `TelemetryDeck.Device.brand`                                  | `EnvironmentParameterProvider`  |                                                    |\n| `TelemetryDeck.Device.timeZone`                               | `PlatformContextProvider`       |                                                    |\n| `TelemetryDeck.AppInfo.buildNumber`                           | `EnvironmentParameterProvider`  |                                                    |\n| `TelemetryDeck.AppInfo.version`                               | `EnvironmentParameterProvider`  |                                                    |\n| `TelemetryDeck.AppInfo.versionAndBuildNumber`                 | `EnvironmentParameterProvider`  |                                                    |\n| `TelemetryDeck.SDK.name`                                      | `EnvironmentParameterProvider`  |                                                    |\n| `TelemetryDeck.SDK.version`                                   | `EnvironmentParameterProvider`  |                                                    |\n| `TelemetryDeck.SDK.nameAndVersion`                            | `EnvironmentParameterProvider`  |                                                    |\n| `TelemetryDeck.SDK.buildType`                                 | `EnvironmentParameterProvider`  |                                                    |\n| `TelemetryDeck.RunContext.locale`                             | `PlatformContextProvider`       |                                                    |\n| `TelemetryDeck.RunContext.targetEnvironment`                  | `PlatformContextProvider`       |                                                    |\n| `TelemetryDeck.RunContext.isSideLoaded`                       | `PlatformContextProvider`       |                                                    |\n| `TelemetryDeck.RunContext.sourceMarketplace`                  | `PlatformContextProvider`       |                                                    |\n| `TelemetryDeck.Accessibility.isBoldTextEnabled`               | `AccessibilityProvider`         | API 31 and above                                   |\n| `TelemetryDeck.Accessibility.fontWeightAdjustment`            | `AccessibilityProvider`         | API 31 and above                                   |\n| `TelemetryDeck.Accessibility.isDarkerSystemColorsEnabled`     | `AccessibilityProvider`         |                                                    |\n| `TelemetryDeck.Accessibility.fontScale`                       | `AccessibilityProvider`         | Mapped to iOS size categories                      |\n| `TelemetryDeck.Accessibility.isInvertColorsEnabled`           | `AccessibilityProvider`         |                                                    |\n| `TelemetryDeck.Accessibility.isReduceMotionEnabled`           | `AccessibilityProvider`         |                                                    |\n| `TelemetryDeck.Accessibility.isReduceTransparencyEnabled`     | `AccessibilityProvider`         |                                                    |\n| `TelemetryDeck.Accessibility.shouldDifferentiateWithoutColor` | `AccessibilityProvider`         |                                                    |\n| `TelemetryDeck.UserPreference.layoutDirection`                | `AccessibilityProvider`         | Possible values are \"rightToLeft\" or \"leftToRight\" |\n| `TelemetryDeck.UserPreference.region`                         | `AccessibilityProvider`         | Current device region in ISO 3166-1 alpha-2 format |\n| `TelemetryDeck.UserPreference.language`                       | `AccessibilityProvider`         | Current application language in ISO 639-1 format   |\n| `TelemetryDeck.UserPreference.colorScheme`                    | `AccessibilityProvider`         | \"Dark\" or \"Light\"                                  |\n| `TelemetryDeck.Session.started`                               | `SessionTrackingSignalProvider` |                                                    |\n| `TelemetryDeck.Acquisition.newInstallDetected`                | `SessionTrackingSignalProvider` |                                                    |\n| `TelemetryDeck.Acquisition.firstSessionDate`                  | `SessionTrackingSignalProvider` |                                                    |\n| `TelemetryDeck.Retention.averageSessionSeconds`               | `SessionTrackingSignalProvider` |                                                    |\n| `TelemetryDeck.Retention.distinctDaysUsed`                    | `SessionTrackingSignalProvider` |                                                    |\n| `TelemetryDeck.Retention.totalSessionsCount`                  | `SessionTrackingSignalProvider` |                                                    |\n| `TelemetryDeck.Retention.previousSessionSeconds`              | `SessionTrackingSignalProvider` |                                                    |\n| `TelemetryDeck.Retention.distinctDaysUsedLastMonth`           | `SessionTrackingSignalProvider` |                                                    |\n| `TelemetryDeck.Calendar.dayOfMonth`                           | `CalendarParameterProvider`     |                                                    |\n| `TelemetryDeck.Calendar.dayOfWeek`                            | `CalendarParameterProvider`     |                                                    |\n| `TelemetryDeck.Calendar.dayOfYear`                            | `CalendarParameterProvider`     |                                                    |\n| `TelemetryDeck.Calendar.weekOfYear`                           | `CalendarParameterProvider`     |                                                    |\n| `TelemetryDeck.Calendar.isWeekend`                            | `CalendarParameterProvider`     |                                                    |\n| `TelemetryDeck.Calendar.monthOfYear`                          | `CalendarParameterProvider`     |                                                    |\n| `TelemetryDeck.Calendar.quarterOfYear`                        | `CalendarParameterProvider`     |                                                    |\n| `TelemetryDeck.Calendar.hourOfDay`                            | `CalendarParameterProvider`     |                                                    |\n\n#### Notes\n\n- `TelemetryDeck.Acquisition.newInstallDetected`\n\nWe send this signal when a user starts the app for the first time on a given device.\n\n- Session data is stored locally on device as part of the application's files.\n- If the application is uninstalled or it's data cleared, the SDK will report a new installation\n  event (we do not bridge session data of any kind between installations).\n\nSee [Session Tracking](#session-tracking) on how sessions are tracked.\n\n- `TelemetryDeck.Accessibility.fontScale` - the value is mapped to better align with size categories\n  sent by other SDKs:\n\n```\nfontScale \u003c= 0.8f -\u003e                      XS\nfontScale \u003e 0.8f \u0026\u0026 fontScale \u003c 0.9f -\u003e   S\nfontScale \u003e= 0.9f \u0026\u0026 fontScale \u003c 1.0f -\u003e  M\nfontScale == 1.0f -\u003e                      L\nfontScale \u003e= 1.0f \u0026\u0026 fontScale \u003c 1.3f -\u003e  XL\nfontScale \u003e= 1.3f \u0026\u0026 fontScale \u003c 1.4f -\u003e  XXL\nfontScale \u003e= 1.4f \u0026\u0026 fontScale \u003c 1.5f -\u003e  XXXL\nfontScale \u003e= 1.5f \u0026\u0026 fontScale \u003c 1.6f -\u003e  AccessibilityM\nfontScale \u003e= 1.6f \u0026\u0026 fontScale \u003c 1.7f -\u003e  AccessibilityL\nfontScale \u003e= 1.7f \u0026\u0026 fontScale \u003c 1.8f -\u003e  AccessibilityXL\nfontScale \u003e= 1.8f \u0026\u0026 fontScale \u003c 1.9f -\u003e  AccessibilityXXL\nfontScale \u003e= 1.9f \u0026\u0026 fontScale \u003c 2.0f -\u003e  AccessibilityXXXL\nfontScale \u003e= 2.0f -\u003e                      AccessibilityXXXL\n```\n\nSee [Custom Telemetry](#custom-telemetry) on how to implement your own parameter enrichment.\n\n## Default Parameters\n\nIf there are parameters you would like to include with every outgoing signal, you can use\n`DefaultParameterProvider` instead of passing them with every call.\n\n```kotlin\n// create an instance of [DefaultParameterProvider] and pass the key value you wish to be appended to every signal\nval provider = DefaultParameterProvider(mapOf(\"key\" to \"value\"))\n\n// add the provider when configuring an instance of TelemetryDeck\n\nval builder = TelemetryDeck.Builder()\n    .appID(\"XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX\")\n    .addProvider(provider)\n```\n\n## Default Prefix\n\nIf you find yourself prepending the same prefix for to your custom signals or parameters,\nyou can optionally configure `TelemetryDeck` to do this for you by activating our\n`DefaultPrefixProvider`:\n\n```kotlin\n// create an instance of [DefaultPrefixProvider] with a signal or parameter prefix\nval provider = DefaultPrefixProvider(\"MyApp.\", \"MyApp.Params.\")\n\n// add the provider when configuring an instance of TelemetryDeck\n\nval builder = TelemetryDeck.Builder()\n    .appID(\"XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX\")\n    .addProvider(provider)\n```\n\n## Navigation Signals\n\nYou can make use\nof [Navigation Signals](https://telemetrydeck.com/docs/articles/navigation-signals/) to better\nunderstand how your users a moving through the app.\n\n```kotlin\n// track a navigation event e.g. when the user is moving from one screen to another:\nTelemetryDeck.navigate(sourcePath = \"/onboarding\", destinationPath = \"/home\")\n\n// let TelemetryDeck take care of tracking the user's route by calling navigate when the path changes\nTelemetryDeck.navigate(\"/onboarding\")\nTelemetryDeck.navigate(\"/home\")\n```\n\n## Acquisition\n\nThe following helper methods are available\n\n```kotlin\n/**\n * Send a `TelemetryDeck.Acquisition.userAcquired` signal with the provided channel.\n */\nfun acquiredUser(channel: String, ...)\n```\n\n```kotlin\n/**\n * Send a `TelemetryDeck.Acquisition.leadStarted` signal with the provided leadId.\n */\nfun leadStarted(leadId: String, ...)\n```\n\n```kotlin\n/**\n * Send a `TelemetryDeck.Acquisition.leadConverted` signal with the provided leadId.\n */\nfun leadConverted(leadId: String, ...)\n```\n\n## Session Tracking\n\nThe SDK uses session tracking detect when the app is launched for the first time (\n`TelemetryDeck.Acquisition.newInstallDetected`) and enrich signals with default parameters regarding\nuser retention like session duration, days used, number of sessions etc.\n\n- Session state is stored within the application's file folder on the user's device.\n\n- The session state will be removed when a user uninstalls an app. The SDK does not \"bridge\" state\n  between installations.\n\n- Users can reset the session state at any time by using the \"Clear Data\" action in Settings of\n  their device.\n\nThe SDK tracks sessions by means of a session manager. The default session manager is\n`SessionTrackingSignalProvider` and it is enabled by default.\n\nHere are some concepts on which the `SessionTrackingSignalProvider` is based:\n\n### Foreground/Active Time\n\nThis refers to the time during which the app is actively being used by the user.\nIt's the period when the app is in the foreground and interacting with the user.\n\n### Starting a session\n\nA session typically begins when the user opens the app or resumes interaction after a period of\ninactivity.\n\nNote: If `sendNewSessionBeganSignal` is set to `true`, the `TelemetryDeck.Session.started` is send\nfor every start of a new session.\n\n### Completed Session\n\nA completed session is defined as the time between two subsequent session starts.\nEssentially, it's the duration from when the app becomes active until it becomes active again after\na period of inactivity or closure.\n\n**Example:**\n\n- First Session Start\n  The user opens the app at 10:00. A new session is started.\n  The user actively uses the app until 10:15, then minimizes it or switches to another app.\n\n- Second Session Start\n  The user returns to the app at 10:30. A new session is started again.\n  The user uses the app until 10:45, then closes it.\n\n- Third Session Start\n  The user opens the app again at 11:00. A new session is started for the third time.\n  The user uses the app until 11:10.\n\n**Results**\n\n| Completed Session | Start Time | End Time | Duration |\n|-------------------|------------|----------|----------|\n| First             | 10:00      | 10:30    | 30 min   |\n| Second            | 10:30      | 11:00    | 30 min   |\n\nThe third session will not be counted until the next time the user opens the app.\n\n### Custom sessionID\n\nIn some situations, you may want to control the session identifier.\n\nSession IDs are UUIDs which the SDK would generate automatically but you can provide your own as\nfollows:\n\n* Retrieve the current session ID using `TelemetryDeck.sessionID`. If the value is `null`, the\n  session manager is disabled or no session has been started yet.\n\n* Start/end a session on demand by calling `TelemetryDeck.newSession()` and optionally passing a\n  custom sessionID.\n\n* Instruct the SDK to start with a custom sessionID using the builder:\n\n```kotlin\nval builder = TelemetryDeck.Builder()\n    .appID(\"XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX\")\n    .sessionID(UUID.fromString(\"00000000-0000-0000-0000-000000000000\"))\n```\n\n* Session tracking is optional and can be deactivated by disabling the session manager:\n\n```kotlin\nval builder = TelemetryDeck.Builder()\n    .appID(\"XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX\")\n    .sessionManager(null)\n```\n\n* You can provide your own logic for session tracking by adopting\n  `TelemetryDeckSessionManagerProvider` and setting it as the session manager.\n\n## Duration Signals\n\nThe SDK offers convenience methods to facilitate tracking the duration of specific objects or events.\n\nOnce started, a duration signal will be tracked internally by the SDK and upon completion, it will send the signal while also adding a `TelemetryDeck.Signal.durationInSeconds` parameter.\n\n```kotlin\n// start tracking, without sending a signal\nTelemetryDeck.startDurationSignal(\"wizard_step1\")\n\n// end tracking, sends the signal including the total duration (excluding background time) \nTelemetryDeck.stopAndSendDurationSignal(\"wizard_step1\")\n```\n\nDuration signals are provided by the `DurationSignalTrackerProvider` which is always enabled. \n\n\n## Calendar Parameters\n\nBy default, the KotlinSDK will append the following parameters to all outgoing signals:\n\n- `TelemetryDeck.Calendar.dayOfMonth`: The day-of-month (1..31) component of the date.\n- `TelemetryDeck.Calendar.dayOfWeek`: The ISO 8601 number of the given day of the week. Monday is 1, Sunday is 7.\n- `TelemetryDeck.Calendar.dayOfYear`: The 1-based day-of-year component of the date.\n- `TelemetryDeck.Calendar.weekOfYear`: The week number within the current year as defined by `getFirstDayOfWeek()` and `getMinimalDaysInFirstWeek()`.\n- `TelemetryDeck.Calendar.isWeekend`: `true` if the day of the week is Saturday or Sunday, `false` otherwise.\n- `TelemetryDeck.Calendar.monthOfYear`: The number-of-the-month (1..12) component of the date.\n- `TelemetryDeck.Calendar.quarterOfYear`: The the quarter-of-year (1..4). For API 26 and earlier, it's the number of the month divided by 3.\n- `TelemetryDeck.Calendar.hourOfDay`: The hour-of-day (0..23) time component of this time value.\n\n\n## Purchase Completed\n\nThe SDK offers a facility method `TelemetryDeck.purchaseCompleted()` that can be invoked in response to a user purchase.\nWith information from the marketplace where the user made a purchase, you can inform TelemetryDeck as follows:\n\n```kotlin\nTelemetryDeck.purchaseCompleted(\n            event = PurchaseEvent.PAID_PURCHASE,\n            countryCode = \"BE\",\n            productID = \"product1\",\n            purchaseType = PurchaseType.ONE_TIME_PURCHASE,\n            priceAmountMicros = 7990000,\n            currencyCode = \"EUR\",\n            offerID = \"offer1\"\n        )\n```\n\nDepending on the specified `PurchaseEvent`, one of the following signals will be sent:\n- `TelemetryDeck.Purchase.completed`\n- `TelemetryDeck.Purchase.freeTrialStarted`\n- `TelemetryDeck.Purchase.convertedFromTrial`\n\n\nThe `floatValue` of the signal will be set to the provided purchase amount, converted `USD`.\n\nThe following parameters are also included with the signal:\n\n| Parameter                             | Description                                                                   |\n|---------------------------------------|-------------------------------------------------------------------------------|\n| `TelemetryDeck.Purchase.type`         | `subscription` or `one-time-purchase`                                         |\n| `TelemetryDeck.Purchase.countryCode`  | The country code of the marketplace where the purchase was made               |\n| `TelemetryDeck.Purchase.currencyCode` | The ISO 4217 currency code (e.g., \"EUR\" for Euro) used for the purchase.      |\n| `TelemetryDeck.Purchase.priceMicros`  | The price of the product in micro-units of the currency                       |\n| `TelemetryDeck.Purchase.productID`    | The unique identifier of the purchased product                                |\n| `TelemetryDeck.Purchase.offerID`      | The specific offer identifier for subscription products or customized pricing |\n\n\n### Google Play\n\nWhen integrating with Google Play Billing Library, you can adopt the TelemetryDeck SDK with Google Play Services in order to let us determine the exact purchase parameters.\n\n1. Add the following package as a dependency to your app:\n\n```kotlin\n// `build.gradle.kts`\ndependencies {\n    implementation(\"com.telemetrydeck:kotlin-sdk-google-services:6.2.0\")\n}\n```\n\n2. You can now use the `purchaseCompleted` function optimized for Google Play Billing:\n\n```kotlin\nfun purchaseHandlerInYourApp(\n  billingConfig: BillingConfig,\n  purchase: Purchase,\n  productDetails: ProductDetails\n) {\n  TelemetryDeck.purchaseCompleted(\n    billingConfig = billingConfig,\n    purchase = purchase,\n    productDetails = productDetails\n  )\n}\n```\n\nBy default, this method assumes the purchase is a `PAID_PURCHASE`. To determine if the user is converting or starting a trial, you will have to implement your own [server-side validation](https://developer.android.com/google/play/billing/integrate) and inspect the `paymentState` of a subscription.\n\nTo make it easier to get started, the TelemetryDeck SDK offers a helper method which attempts to guess the purchase origin based on locally available data, so you could:\n\n```kotlin\nTelemetryDeck.purchaseCompleted(\n  billingConfig = billingConfig,\n  purchase = purchase,\n  productDetails = productDetails,\n  purchaseOrigin = purchase.toTelemetryDeckPurchaseEvent(setOf(\"TRIAL_SKU\"))\n)\n```\n\nNote that this approach is not exact and comes with a certain number of limitations, please check the doc notes on `com.telemetrydeck.sdk.googleservices.toTelemetryDeckPurchaseEvent` for more details.\n\n\n## Custom Telemetry\n\nAnother way to send signals is to implement a custom `TelemetryDeckProvider`.\nA provider uses the TelemetryDeck client in order to queue or send signals based on environment or\nother triggers.\n\nTo create a provider, implement the `TelemetryDeckProvider` interface:\n\n```kotlin\nclass CustomProvider : TelemetryDeckProvider {\n    override fun register(ctx: Context?, client: TelemetryDeckClient) {\n        // configure and start the provider\n        // you may retain a WeakReference to client\n    }\n\n    override fun stop() {\n        // deactivate the provider, perform cleanup work\n    }\n}\n```\n\nSetup and start the provider during the `register` method.\n\nTips:\n\n- Do not retain a strong reference to the application context or TelemetryDeckClient instance.\n- You can use `WeakReference\u003cTelemetryDeckClient\u003e` if you need to be able to call the TelemetryDeck\n  at a later time.\n\nTo use your custom provider, register it by calling `addProvider` using the\n`TelemetryDeck.Builder` :\n\n```kotlin\nval builder = TelemetryDeck.Builder()\n    //    ...\n    .addProvider(CustomProvider()) // \u003c-- Your custom provider\n```\n\nEvery time the SDK is about to send signals to our servers, the `enrich` method of every provider\nwill be invoked to give you the opportunity to append additional parameters.\n\nIn the implementation of your custom `TelemetryDeckProvider`, you can override the `enrich` method:\n\n```kotlin\noverride fun enrich(\n    signalType: String,\n    clientUser: String?,\n    additionalPayload: Map\u003cString, String\u003e\n): Map\u003cString, String\u003e {\n    // retrieve the payload of signal\n    val signalPayload = additionalPayload.toMutableMap()\n    // add additional attributes of your choice\n    val today = LocalDateTime.now().dayOfWeek\n    if (today == DayOfWeek.MONDAY) {\n        signalPayload[\"isMonday\"] = \"yes\"\n    }\n    // return the enriched payload\n    return signalPayload\n}\n```\n\nWe use providers internally to provide lifecycle and environment integration out of the box.\nFeel free to examine how they work and inspire your own implementations.\n\nYou can also completely disable or override the default providers with your own.\n\n- `SessionAppProvider` - Emits signals for application and activity lifecycle events. This provider\n  is tasked with resetting the sessionID when `sendNewSessionBeganSignal` is enabled.\n- `SessionActivityProvider` - Emits signals for application and activity lifecycle events. This\n  provider is not enabled by default.\n- `EnvironmentParameterProvider` - Adds environment and device information to outgoing Signals. This\n  provider overrides the `enrich` method in order to append additional metadata for all signals\n  before sending them.\n- `PlatformContextProvider` - Adds environment and device information which may change over time\n  like the current timezone and screen metrics.\n- `AccessibilityProvider` - Adds parameters describing the currently active accessibility options.\n- `SessionTrackingSignalProvider` - Reports when a new app installation has been detected.\n\nFor a complete list, check the `com.telemetrydeck.sdk.providers` package.\n\n```kotlin\n// Append a custom provider\nval builder = TelemetryDeck.Builder()\n    //    ...\n    .addProvider(CustomProvider())\n\n\n// Replace all default providers\nval builder = TelemetryDeck.Builder()\n    //    ...\n    .providers(listOf(CustomProvider(), AnotherProvider()))\n```\n\n## Custom Logging\n\nBy default, TelemetryDeck SDK uses a simple `println` to output internal diagnostic messages when\n`showDebugLogs` is set to `true` in configuration.\n\nIf your platform has custom logging needs, you can adopt the `DebugLogger` interface and provide it\nto the `TelemetryDeck` builder:\n\n```kotlin\nval builder = TelemetryDeck.Builder()\n    //    ...\n    .logger(CustomLogger())\n```\n\nPlease note that the logger implementation should be thread safe as it may be invoked in different\nqueues and contexts.\n\n## Requirements\n\n- Android API 21 or later\n- Kotlin 2.0.20\n- Gradle 6.8.3–8.8\\*\n- AGP 7.1.3–8.5\n\n## Migrating providers to 5.0+\n\n* The provider interface `TelemetryDeckProvider` has changed to accept a `Context` instance instead\n  of an `Application`.\n* The deprecated fallback provider callbacks are no longer used and the functionality has been\n  removed.\n* Providers can now optionally override the `transform` method in order to modify any component of\n  the signal.\n\n## Migrating providers to 3.0+\n\nIf you had Kotlin SDK for TelemetryDeck added to your app, you will notice that `TelemetryManager`\nand related classes have been deprecated.\nYou can read more about the motivation behind these\nchanges [here](https://telemetrydeck.com/docs/articles/grand-rename/).\n\nTo upgrade, please perform the following changes depending on how you use TelemetryDeck SDK.\n\n### If you're using the application manifest\n\n- Adapt the manifest of your app and rename all keys from `com.telemetrydeck.sdk.*` to\n  `com.telemetrydeck.*` for example:\n\nBefore:\n\n```xml\n\n\u003cmeta-data android:name=\"com.telemetrydeck.sdk.appID\"\n    android:value=\"XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX\" /\u003e\n```\n\nAfter:\n\n```xml\n\n\u003cmeta-data android:name=\"com.telemetrydeck.appID\"\n    android:value=\"XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX\" /\u003e\n```\n\n- In your app sourcecode, rename all uses of `TelemetryManager` to `TelemetryDeck`.\n- If you were using `send()` to send signals, no further changes are needed!\n- If you were using `queue()` to send signals, you will need to rename the method to\n  `TelemetryDeck.signal()`.\n\n### Programmatic Usage\n\n- In your app sourcecode, rename all uses of `TelemetryManager` to `TelemetryDeck`.\n- If you were using `send()` to send signals, no further changes are needed!\n- If you were using `queue()` to send signals, you will need to rename the method to\n  `TelemetryDeck.signal()`.\n- If you had a custom provider configuration, please replace the corresponding providers as follows:\n\n| Provider (old name)             | Provider (new, 3.0+)                                      |\n|---------------------------------|-----------------------------------------------------------|\n| `AppLifecycleTelemetryProvider` | `SessionAppProvider`, `SessionActivityProvider`           |\n| `SessionProvider`               | `SessionAppProvider`                                      |\n| `EnvironmentMetadataProvider`   | `EnvironmentParameterProvider`, `PlatformContextProvider` |\n\n\u003e [!TIP]\n\u003e You can rename all deprecated classes in your project using the Code Cleanup function in\n\u003e IntelliJ/Android Studio.\n\n\u003e [!WARNING]\n\u003e Do not mix usage of `TelemetryManager` and `TelemetryDeck`. Once you're ready to migrate, adapt\n\u003e all uses at the same time.\n\n### Custom Telemetry\n\nYour custom providers must replace `TelemetryProvider` with `TelemetryDeckProvider`.\n\nTo adopt the new interface:\n\n- Adapt the signature of the `register` method to\n  `register(ctx: Context?, client: TelemetryDeckSignalProcessor)`\n\nThe `TelemetryDeckSignalProcessor` interface offers a subset of the `TelemetryDeck` client API which\ngives you access to:\n\n- To access the logger, use can use `client.debugLogger`\n- To access the signal cache, use `client.signalCache`\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftelemetrydeck%2Fkotlinsdk","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftelemetrydeck%2Fkotlinsdk","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftelemetrydeck%2Fkotlinsdk/lists"}