feat(android): add configurable notification click behavior

Author: zeevenn

android/src/main/java/com/doublesymmetry/trackplayer/service/MusicService.kt

@@ -98,11 +98,19 @@ class MusicService : HeadlessJsMediaService() {
             }
         })
         fakePlayer = ExoPlayer.Builder(this).build()
+
+        val notificationClickBehavior = androidOptions?.getBundle(NOTIFICATION_CLICK_BEHAVIOR_KEY)
+        val enableUriData = notificationClickBehavior?.getBoolean(NOTIFICATION_CLICK_ENABLED_KEY, true) ?: true
+
         val openAppIntent = packageManager.getLaunchIntentForPackage(packageName)?.apply {
             flags = Intent.FLAG_ACTIVITY_CLEAR_TOP or Intent.FLAG_ACTIVITY_SINGLE_TOP
-            // Add the Uri data so apps can identify that it was a notification click
-            data = Uri.parse("trackplayer://notification.click")
-            action = Intent.ACTION_VIEW
+            if (enableUriData) {
+                val customUri = notificationClickBehavior?.getString(NOTIFICATION_CLICK_CUSTOM_URI_KEY)
+                data = Uri.parse(customUri ?: "trackplayer://notification.click")
+
+                val customAction = notificationClickBehavior?.getString(NOTIFICATION_CLICK_CUSTOM_ACTION_KEY)
+                action = customAction ?: Intent.ACTION_VIEW
+            }
         }
         mediaSession = MediaLibrarySession.Builder(this, fakePlayer,
             InnerMediaSessionCallback()
@@ -1022,6 +1030,12 @@ class MusicService : HeadlessJsMediaService() {
         const val IS_FOCUS_LOSS_PERMANENT_KEY = "permanent"
         const val IS_PAUSED_KEY = "paused"
 
+        // Notification click behavior keys
+        const val NOTIFICATION_CLICK_BEHAVIOR_KEY = "notificationClickBehavior"
+        const val NOTIFICATION_CLICK_ENABLED_KEY = "enabled"
+        const val NOTIFICATION_CLICK_CUSTOM_URI_KEY = "customUri"
+        const val NOTIFICATION_CLICK_CUSTOM_ACTION_KEY = "action"
+
         const val HANDLE_NOISY = "androidHandleAudioBecomingNoisy"
         const val ALWAYS_SHOW_NEXT = "androidAlwaysShowNext"
         const val SKIP_SILENCE = "androidSkipSilence"

docs/docs/api/objects/android-options.md

@@ -7,3 +7,4 @@ Options available for the android player. All options are optional.
 | `appKilledPlaybackBehavior` | [`AppKilledPlaybackBehavior`](../constants/app-killed-playback-behavior.md) | [`ContinuePlayback`](../constants/app-killed-playback-behavior.md#continueplayback-default) | Define how the audio playback should behave after removing the app from recents (killing it). |
 | `alwaysPauseOnInterruption` | `boolean` | `false` | Whether the `remote-duck` event will be triggered on every interruption |
 | `stopForegroundGracePeriod` | `number` | `5` | Time in seconds to wait once the player should transition to not considering the service as in the foreground. If playback resumes within this grace period, the service remains in the foreground state. |
+| `notificationClickBehavior` | [`NotificationClickBehavior`](./notification-click-behavior.md) | [`Default Value`](./notification-click-behavior.md) | Configuration for notification click behavior |

docs/docs/api/objects/notification-click-behavior.md

@@ -0,0 +1,69 @@
+# NotificationClickBehavior
+
+Configuration for notification click behavior on Android.
+
+| Param | Type  | Default | Description |
+|-------|-------|---------|-------------|
+| `enabled` | `boolean` | `true` | Whether to add URI data to the notification click intent. When disabled, the app will launch without any URI information. |
+| `customUri` | `string` | `"trackplayer://notification.click"` | Custom URI to use instead of the default. Only used when `enabled` is `true`. |
+| `action` | `string` | `"android.intent.action.VIEW"` | Custom action to use for the notification click intent. Only used when `enabled` is `true`. |
+
+## Default Value
+
+```typescript
+{
+  enabled: true,
+  customUri: "trackplayer://notification.click",
+  action: "android.intent.action.VIEW"
+}
+```
+
+## Examples
+
+### Disable URI data (launch app without notification click detection)
+```typescript
+await TrackPlayer.updateOptions({
+  android: {
+    notificationClickBehavior: {
+      enabled: false
+    }
+  }
+});
+```
+
+### Use custom URI
+```typescript
+await TrackPlayer.updateOptions({
+  android: {
+    notificationClickBehavior: {
+      enabled: true,
+      customUri: "myapp://notification.click"
+    }
+  }
+});
+```
+
+### Use custom action
+```typescript
+await TrackPlayer.updateOptions({
+  android: {
+    notificationClickBehavior: {
+      enabled: true,
+      action: "android.intent.action.MAIN"
+    }
+  }
+});
+```
+
+### Complete configuration
+```typescript
+await TrackPlayer.updateOptions({
+  android: {
+    notificationClickBehavior: {
+      enabled: true,
+      customUri: "myapp://player.notification",
+      action: "android.intent.action.VIEW"
+    }
+  }
+});
+``` 

example/android/app/src/main/AndroidManifest.xml

@@ -1,6 +1,7 @@
 <manifest xmlns:android="http://schemas.android.com/apk/res/android">
 
     <uses-permission android:name="android.permission.INTERNET" />
+    <uses-permission android:name="android.permission.POST_NOTIFICATIONS" />
     <uses-permission android:name="android.permission.SYSTEM_ALERT_WINDOW" />
 
     <application

example/src/services/SetupService.ts

@@ -22,6 +22,17 @@ export const SetupService = async () => {
     await TrackPlayer.updateOptions({
       android: {
         appKilledPlaybackBehavior: DefaultAudioServiceBehaviour,
+        // Example: Configure notification click behavior
+        // You can disable URI data to launch app without notification click detection
+        // notificationClickBehavior: {
+        //   enabled: false
+        // },
+        // Or use custom URI and action
+        // notificationClickBehavior: {
+        //   enabled: true,
+        //   customUri: "example://notification.click",
+        //   action: "android.intent.action.VIEW"
+        // }
       },
       capabilities: [
         Capability.Play,

src/interfaces/AndroidOptions.ts

@@ -1,5 +1,25 @@
 import type { AppKilledPlaybackBehavior } from '../constants';
 
+export interface NotificationClickBehavior {
+  /**
+   * Whether to add URI data to the notification click intent
+   * @default true
+   */
+  enabled?: boolean;
+
+  /**
+   * Custom URI to use instead of the default "trackplayer://notification.click"
+   * Only used when enabled is true
+   */
+  customUri?: string;
+
+  /**
+   * Custom action to use for the notification click intent
+   * @default "android.intent.action.VIEW"
+   */
+  action?: string;
+}
+
 export interface AndroidOptions {
   /**
    * Whether the audio playback notification is also removed when the playback
@@ -21,6 +41,11 @@ export interface AndroidOptions {
    */
   stopForegroundGracePeriod?: number;
 
+  /**
+   * Configuration for notification click behavior
+   */
+  notificationClickBehavior?: NotificationClickBehavior;
+
   /**
    * https://developer.android.com/media/media3/exoplayer/track-selection#audioOffload
    */