react-native-qpush 0.0.0-stage → 1.0.0

package/android/src/main/java/com/qpush/reactnative/QPushEventBus.kt

@@ -0,0 +1,153 @@
+package com.qpush.reactnative
+
+import android.app.ActivityManager
+import android.content.Context
+import android.os.Handler
+import android.os.Looper
+import java.lang.ref.WeakReference
+import java.util.UUID
+import java.util.concurrent.ConcurrentHashMap
+import java.util.concurrent.ExecutorService
+import java.util.concurrent.Executors
+
+/**
+ * Bridge between native components (messaging service, trampoline activity)
+ * and the JS layer. Events are queued until JS subscribed (`setJsReady`), so
+ * a click that cold-starts the app is delivered once the bundle is running.
+ */
+internal object QPushEventBus {
+  const val EVENT_CLICK = "QPushPushClick"
+  const val EVENT_FOREGROUND_WILL_DISPLAY = "QPushPushForegroundWillDisplay"
+  const val EVENT_PUSH_TOKEN = "QPushPushToken"
+
+  /** JS must answer a foregroundWillDisplay event within this time, else the notification is shown. */
+  private const val FOREGROUND_RESPONSE_TIMEOUT_MS = 1_000L
+  /** After `preventDefault()`, JS may still call `display()` during this window. */
+  private const val PREVENTED_EXPIRY_MS = 25_000L
+  private const val MAX_PENDING_EVENTS = 50
+
+  private class PendingEvent(val name: String, val body: Map<String, Any?>)
+
+  private class PendingDisplay(val context: Context, val payload: QPushPayload) {
+    var timeout: Runnable? = null
+  }
+
+  private val lock = Any()
+  private val pendingEvents = ArrayList<PendingEvent>()
+  private val pendingDisplays = ConcurrentHashMap<String, PendingDisplay>()
+  private val mainHandler = Handler(Looper.getMainLooper())
+
+  /** Single thread for rendering (image downloads) outside the main thread. */
+  val worker: ExecutorService = Executors.newSingleThreadExecutor()
+
+  @Volatile
+  private var moduleRef: WeakReference<QPushPushModule>? = null
+
+  @Volatile
+  private var jsReady = false
+
+  @Volatile
+  var hostResumed = false
+
+  fun attach(module: QPushPushModule) {
+    moduleRef = WeakReference(module)
+    jsReady = false
+  }
+
+  fun detach(module: QPushPushModule) {
+    if (moduleRef?.get() === module) {
+      moduleRef = null
+      jsReady = false
+      hostResumed = false
+    }
+  }
+
+  /** Called by JS once it subscribed to the native events. */
+  fun setJsReady() {
+    val toSend: List<PendingEvent>
+    synchronized(lock) {
+      jsReady = true
+      toSend = ArrayList(pendingEvents)
+      pendingEvents.clear()
+    }
+    for (event in toSend) emit(event.name, event.body)
+  }
+
+  fun emit(name: String, body: Map<String, Any?>) {
+    val module = moduleRef?.get()
+    if (module != null && jsReady && module.canEmit()) {
+      try {
+        module.sendEvent(name, body)
+        return
+      } catch (e: Exception) {
+        QPushLog.w("Could not emit $name, queueing it", e)
+      }
+    }
+    synchronized(lock) {
+      pendingEvents.add(PendingEvent(name, body))
+      while (pendingEvents.size > MAX_PENDING_EVENTS) pendingEvents.removeAt(0)
+    }
+  }
+
+  fun emitClick(rawPayload: String, actionId: String?, url: String?) {
+    emit(EVENT_CLICK, mapOf("rawPayload" to rawPayload, "actionId" to actionId, "url" to url))
+  }
+
+  fun emitToken(token: String) {
+    emit(EVENT_PUSH_TOKEN, mapOf("token" to token))
+  }
+
+  /** True when the app UI is visible and JS can decide about foreground display. */
+  fun canHandleForeground(): Boolean {
+    val module = moduleRef?.get() ?: return false
+    return jsReady && hostResumed && module.canEmit() && isProcessInForeground()
+  }
+
+  private fun isProcessInForeground(): Boolean {
+    return try {
+      val info = ActivityManager.RunningAppProcessInfo()
+      ActivityManager.getMyMemoryState(info)
+      info.importance == ActivityManager.RunningAppProcessInfo.IMPORTANCE_FOREGROUND
+    } catch (e: Exception) {
+      false
+    }
+  }
+
+  /**
+   * Asks JS whether to display a notification received in the foreground.
+   * Returns false when JS cannot answer (caller renders directly).
+   */
+  fun requestForegroundDisplay(context: Context, payload: QPushPayload): Boolean {
+    if (!canHandleForeground()) return false
+    val displayId = UUID.randomUUID().toString()
+    val pending = PendingDisplay(context.applicationContext, payload)
+    pendingDisplays[displayId] = pending
+    val timeout = Runnable { display(displayId) }
+    pending.timeout = timeout
+    mainHandler.postDelayed(timeout, FOREGROUND_RESPONSE_TIMEOUT_MS)
+    emit(EVENT_FOREGROUND_WILL_DISPLAY, mapOf("displayId" to displayId, "rawPayload" to payload.raw))
+    return true
+  }
+
+  /** JS (or the timeout) decided to display. */
+  fun display(displayId: String) {
+    val pending = pendingDisplays.remove(displayId) ?: return
+    pending.timeout?.let { mainHandler.removeCallbacks(it) }
+    worker.execute {
+      try {
+        QPushNotificationRenderer.render(pending.context, pending.payload)
+      } catch (e: Exception) {
+        QPushLog.e("Failed to render notification", e)
+      }
+    }
+  }
+
+  /** JS called `preventDefault()`: keep the payload around in case `display()` is called later. */
+  fun prevent(displayId: String) {
+    val pending = pendingDisplays[displayId] ?: return
+    pending.timeout?.let { mainHandler.removeCallbacks(it) }
+    val expiry = Runnable { pendingDisplays.remove(displayId) }
+    pending.timeout = expiry
+    mainHandler.postDelayed(expiry, PREVENTED_EXPIRY_MS)
+  }
+}

package/android/src/main/java/com/qpush/reactnative/QPushFcm.kt

@@ -0,0 +1,108 @@
+package com.qpush.reactnative
+
+import android.content.Context
+import com.google.firebase.FirebaseApp
+import com.google.firebase.FirebaseOptions
+import com.google.firebase.messaging.FirebaseMessaging
+
+/** FCM params from `GET /apps/{app_id}/android_params.js`. */
+internal data class FcmParams(
+  val projectId: String,
+  val appId: String,
+  val apiKey: String,
+  val senderId: String,
+)
+
+internal data class PushRegistrationResult(
+  val token: String?,
+  val notificationTypes: Int?,
+  val error: String?,
+)
+
+/**
+ * Obtains the FCM registration token.
+ *
+ * With params from the QPush dashboard, a secondary FirebaseApp named
+ * `QPUSH_SDK_FCM_APP` is initialized programmatically, so the app needs
+ * neither google-services.json nor the google-services Gradle plugin (same
+ * approach as OneSignal). Without params the default FirebaseApp is used when
+ * the app has one.
+ */
+internal object QPushFcm {
+  const val FIREBASE_APP_NAME = "QPUSH_SDK_FCM_APP"
+  /** notification_types for token errors (protocol: -3 missing play services / FCM error). */
+  const val ERROR_NOTIFICATION_TYPES = -3
+
+  fun register(context: Context, params: FcmParams?, callback: (PushRegistrationResult) -> Unit) {
+    val appContext = context.applicationContext
+    val firebaseApp: FirebaseApp = try {
+      if (params != null) {
+        QPushStore.set(appContext, QPushStore.KEY_FCM_MODE, "secondary")
+        secondaryApp(appContext, params)
+      } else {
+        QPushStore.set(appContext, QPushStore.KEY_FCM_MODE, "default")
+        defaultApp(appContext) ?: run {
+          callback(
+            PushRegistrationResult(
+              null,
+              ERROR_NOTIFICATION_TYPES,
+              "No FCM configuration: add Android (FCM) credentials to the QPush app or google-services.json to the project",
+            ),
+          )
+          return
+        }
+      }
+    } catch (t: Throwable) {
+      QPushLog.e("Could not initialize Firebase", t)
+      callback(PushRegistrationResult(null, ERROR_NOTIFICATION_TYPES, t.message ?: t.javaClass.simpleName))
+      return
+    }
+
+    try {
+      val messaging = firebaseApp.get(FirebaseMessaging::class.java)
+      messaging.token.addOnCompleteListener { task ->
+        val token = if (task.isSuccessful) task.result else null
+        if (!token.isNullOrEmpty()) {
+          QPushLog.d("FCM token received")
+          callback(PushRegistrationResult(token, null, null))
+        } else {
+          val message = task.exception?.message ?: "FCM returned an empty token"
+          QPushLog.w("FCM token request failed: $message", task.exception)
+          callback(PushRegistrationResult(null, ERROR_NOTIFICATION_TYPES, message))
+        }
+      }
+    } catch (t: Throwable) {
+      QPushLog.e("FCM token request failed", t)
+      callback(PushRegistrationResult(null, ERROR_NOTIFICATION_TYPES, t.message ?: t.javaClass.simpleName))
+    }
+  }
+
+  private fun secondaryApp(context: Context, params: FcmParams): FirebaseApp {
+    val options = FirebaseOptions.Builder()
+      .setProjectId(params.projectId)
+      .setApplicationId(params.appId)
+      .setApiKey(params.apiKey)
+      .setGcmSenderId(params.senderId)
+      .build()
+    val existing = try {
+      FirebaseApp.getInstance(FIREBASE_APP_NAME)
+    } catch (e: IllegalStateException) {
+      null
+    }
+    if (existing != null) {
+      if (existing.options == options) return existing
+      // Credentials changed in the dashboard: recreate the app.
+      existing.delete()
+    }
+    return FirebaseApp.initializeApp(context, options, FIREBASE_APP_NAME)
+  }
+
+  private fun defaultApp(context: Context): FirebaseApp? {
+    FirebaseApp.getApps(context).firstOrNull { it.name == FirebaseApp.DEFAULT_APP_NAME }?.let { return it }
+    return try {
+      FirebaseApp.initializeApp(context)
+    } catch (e: Exception) {
+      null
+    }
+  }
+}

package/android/src/main/java/com/qpush/reactnative/QPushHttp.kt

@@ -0,0 +1,92 @@
+package com.qpush.reactnative
+
+import android.content.Context
+import android.net.Uri
+import org.json.JSONObject
+import java.io.IOException
+import java.net.HttpURLConnection
+import java.net.URL
+
+/**
+ * Native HTTP calls that must work while the JS runtime is not running
+ * (notification receipt and open). Must be called off the main thread.
+ */
+internal object QPushHttp {
+  const val SDK_VERSION = "qpush-react-native/1.0.0"
+  private const val DEVICE_TYPE_ANDROID = 1
+  private const val TIMEOUT_MS = 15_000
+  private const val MAX_ATTEMPTS = 3
+
+  /** `PUT /notifications/{id}/report_received` */
+  fun reportReceived(context: Context, notificationId: String): Boolean {
+    val body = baseBody(context) ?: return false
+    return send(context, "/notifications/${Uri.encode(notificationId)}/report_received", body)
+  }
+
+  /** `PUT /notifications/{id}` with `opened: true` (click). */
+  fun reportOpened(context: Context, notificationId: String, actionId: String?): Boolean {
+    val body = baseBody(context) ?: return false
+    body.put("opened", true)
+    if (!actionId.isNullOrEmpty()) body.put("action_id", actionId)
+    return send(context, "/notifications/${Uri.encode(notificationId)}", body)
+  }
+
+  private fun baseBody(context: Context): JSONObject? {
+    val appId = QPushStore.get(context, QPushStore.KEY_APP_ID)
+    if (appId.isNullOrEmpty()) {
+      QPushLog.w("Cannot report notification event: SDK was never initialized")
+      return null
+    }
+    val body = JSONObject()
+    body.put("app_id", appId)
+    QPushStore.get(context, QPushStore.KEY_SUBSCRIPTION_ID)?.let { body.put("subscription_id", it) }
+    body.put("device_type", DEVICE_TYPE_ANDROID)
+    return body
+  }
+
+  private fun send(context: Context, path: String, body: JSONObject): Boolean {
+    val base = QPushStore.get(context, QPushStore.KEY_SERVER_URL)
+    if (base.isNullOrEmpty()) return false
+    val url = base.trimEnd('/') + path
+    val payload = body.toString().toByteArray(Charsets.UTF_8)
+    val subscriptionId = QPushStore.get(context, QPushStore.KEY_SUBSCRIPTION_ID)
+
+    for (attempt in 1..MAX_ATTEMPTS) {
+      var connection: HttpURLConnection? = null
+      try {
+        connection = (URL(url).openConnection() as HttpURLConnection).apply {
+          requestMethod = "PUT"
+          doOutput = true
+          connectTimeout = TIMEOUT_MS
+          readTimeout = TIMEOUT_MS
+          setRequestProperty("Content-Type", "application/json")
+          setRequestProperty("Accept", "application/json")
+          setRequestProperty("SDK-Version", SDK_VERSION)
+          if (!subscriptionId.isNullOrEmpty()) setRequestProperty("QPush-Subscription-Id", subscriptionId)
+          setFixedLengthStreamingMode(payload.size)
+        }
+        connection.outputStream.use { it.write(payload) }
+        val status = connection.responseCode
+        try {
+          (if (status < 400) connection.inputStream else connection.errorStream)?.close()
+        } catch (ignored: IOException) {
+        }
+        QPushLog.d("PUT $path -> $status")
+        if (status in 200..299) return true
+        if (status != 429 && status < 500) return false
+      } catch (e: Exception) {
+        QPushLog.d("PUT $path failed: ${e.message}")
+      } finally {
+        connection?.disconnect()
+      }
+      if (attempt < MAX_ATTEMPTS) {
+        try {
+          Thread.sleep(1000L * attempt)
+        } catch (e: InterruptedException) {
+          return false
+        }
+      }
+    }
+    return false
+  }
+}

package/android/src/main/java/com/qpush/reactnative/QPushImages.kt

@@ -0,0 +1,103 @@
+package com.qpush.reactnative
+
+import android.content.Context
+import android.graphics.Bitmap
+import android.graphics.BitmapFactory
+import android.graphics.Canvas
+import androidx.core.content.ContextCompat
+import java.io.ByteArrayOutputStream
+import java.net.HttpURLConnection
+import java.net.URL
+
+/** Image helpers for notification rendering (blocking: call off the main thread). */
+internal object QPushImages {
+  private const val TIMEOUT_MS = 8_000
+  private const val MAX_BYTES = 5 * 1024 * 1024
+
+  fun isRemote(value: String): Boolean =
+    value.startsWith("http://", ignoreCase = true) || value.startsWith("https://", ignoreCase = true)
+
+  /** Downloads and decodes an image, downsampling it to at most `maxDimension` px. */
+  fun download(url: String, maxDimension: Int): Bitmap? {
+    var connection: HttpURLConnection? = null
+    return try {
+      connection = (URL(url).openConnection() as HttpURLConnection).apply {
+        connectTimeout = TIMEOUT_MS
+        readTimeout = TIMEOUT_MS
+        instanceFollowRedirects = true
+      }
+      if (connection.responseCode !in 200..299) return null
+      val bytes = connection.inputStream.use { input ->
+        val output = ByteArrayOutputStream()
+        val buffer = ByteArray(16 * 1024)
+        var total = 0
+        while (true) {
+          val read = input.read(buffer)
+          if (read < 0) break
+          total += read
+          if (total > MAX_BYTES) return null
+          output.write(buffer, 0, read)
+        }
+        output.toByteArray()
+      }
+      decode(bytes, maxDimension)
+    } catch (e: Exception) {
+      QPushLog.w("Could not download image $url", e)
+      null
+    } finally {
+      connection?.disconnect()
+    }
+  }
+
+  private fun decode(bytes: ByteArray, maxDimension: Int): Bitmap? {
+    val bounds = BitmapFactory.Options().apply { inJustDecodeBounds = true }
+    BitmapFactory.decodeByteArray(bytes, 0, bytes.size, bounds)
+    if (bounds.outWidth <= 0 || bounds.outHeight <= 0) return null
+    var sample = 1
+    while (bounds.outWidth / (sample * 2) >= maxDimension || bounds.outHeight / (sample * 2) >= maxDimension) {
+      sample *= 2
+    }
+    val options = BitmapFactory.Options().apply { inSampleSize = sample }
+    return BitmapFactory.decodeByteArray(bytes, 0, bytes.size, options)
+  }
+
+  /** Resolves a drawable/mipmap resource id by name (`ic_stat_x`, `drawable/ic_x`, `ic_x.png`). */
+  fun resourceId(context: Context, rawName: String?): Int {
+    if (rawName.isNullOrBlank()) return 0
+    val name = rawName.substringAfterLast('/').substringBeforeLast('.')
+    if (name.isEmpty()) return 0
+    val resources = context.resources
+    val packageName = context.packageName
+    for (type in arrayOf("drawable", "mipmap")) {
+      @Suppress("DiscouragedApi")
+      val id = resources.getIdentifier(name, type, packageName)
+      if (id != 0) return id
+    }
+    return 0
+  }
+
+  /** Loads a bitmap from a drawable resource name (bitmap or vector). */
+  fun fromResource(context: Context, name: String): Bitmap? {
+    val id = resourceId(context, name)
+    if (id == 0) return null
+    BitmapFactory.decodeResource(context.resources, id)?.let { return it }
+    return try {
+      val drawable = ContextCompat.getDrawable(context, id) ?: return null
+      val width = if (drawable.intrinsicWidth > 0) drawable.intrinsicWidth else 128
+      val height = if (drawable.intrinsicHeight > 0) drawable.intrinsicHeight else 128
+      val bitmap = Bitmap.createBitmap(width, height, Bitmap.Config.ARGB_8888)
+      val canvas = Canvas(bitmap)
+      drawable.setBounds(0, 0, canvas.width, canvas.height)
+      drawable.draw(canvas)
+      bitmap
+    } catch (e: Exception) {
+      null
+    }
+  }
+
+  /** Remote URL or drawable name. */
+  fun load(context: Context, value: String?, maxDimension: Int): Bitmap? {
+    if (value.isNullOrBlank()) return null
+    return if (isRemote(value)) download(value, maxDimension) else fromResource(context, value)
+  }
+}

package/android/src/main/java/com/qpush/reactnative/QPushLog.kt

@@ -0,0 +1,39 @@
+package com.qpush.reactnative
+
+import android.util.Log
+
+/** Leveled logger using the same numeric levels as the JS `LogLevel` enum. */
+internal object QPushLog {
+  private const val TAG = "QPush"
+
+  const val NONE = 0
+  const val FATAL = 1
+  const val ERROR = 2
+  const val WARN = 3
+  const val INFO = 4
+  const val DEBUG = 5
+  const val VERBOSE = 6
+
+  @Volatile
+  var level: Int = WARN
+
+  fun e(message: String, error: Throwable? = null) {
+    if (level >= ERROR) Log.e(TAG, message, error)
+  }
+
+  fun w(message: String, error: Throwable? = null) {
+    if (level >= WARN) Log.w(TAG, message, error)
+  }
+
+  fun i(message: String) {
+    if (level >= INFO) Log.i(TAG, message)
+  }
+
+  fun d(message: String) {
+    if (level >= DEBUG) Log.d(TAG, message)
+  }
+
+  fun v(message: String) {
+    if (level >= VERBOSE) Log.v(TAG, message)
+  }
+}

package/android/src/main/java/com/qpush/reactnative/QPushMessagingService.kt

@@ -0,0 +1,77 @@
+package com.qpush.reactnative
+
+import android.content.Context
+import com.google.firebase.messaging.FirebaseMessagingService
+import com.google.firebase.messaging.RemoteMessage
+
+/**
+ * Receives QPush data messages. Works with the JS runtime dead: rendering
+ * and the delivery receipt only need SharedPreferences.
+ *
+ * If your app already declares its own FirebaseMessagingService (only one
+ * service receives MESSAGING_EVENT), forward to QPush from it:
+ *
+ * ```kotlin
+ * override fun onMessageReceived(message: RemoteMessage) {
+ *   if (QPushMessagingService.handleMessage(this, message)) return
+ *   // your own handling
+ * }
+ * override fun onNewToken(token: String) { QPushMessagingService.handleNewToken(this, token) }
+ * ```
+ */
+class QPushMessagingService : FirebaseMessagingService() {
+
+  override fun onMessageReceived(message: RemoteMessage) {
+    handleMessage(applicationContext, message)
+  }
+
+  override fun onNewToken(token: String) {
+    handleNewToken(applicationContext, token)
+  }
+
+  companion object {
+    private const val DATA_KEY = "qpush"
+
+    /** Returns true when the message was a QPush notification. Blocking: call from the FCM thread. */
+    @JvmStatic
+    fun handleMessage(context: Context, message: RemoteMessage): Boolean {
+      val raw = message.data[DATA_KEY] ?: return false
+      processPayload(context.applicationContext, raw)
+      return true
+    }
+
+    /** Token refresh of the default FirebaseApp. */
+    @JvmStatic
+    fun handleNewToken(context: Context, token: String) {
+      QPushStore.set(context, QPushStore.KEY_DEFAULT_APP_TOKEN, token)
+      // With dashboard FCM params the token comes from the secondary app and is
+      // refreshed by JS on every cold start; only forward default-app tokens.
+      if (QPushStore.get(context, QPushStore.KEY_FCM_MODE) == "default") {
+        QPushEventBus.emitToken(token)
+      }
+    }
+
+    internal fun processPayload(context: Context, raw: String) {
+      val payload = QPushPayload.parse(raw)
+      if (payload == null) {
+        QPushLog.w("Ignoring malformed QPush payload")
+        return
+      }
+      if (QPushStore.markNotificationSeen(context, payload.id)) {
+        QPushLog.d("Duplicate notification ${payload.id} ignored")
+        return
+      }
+      QPushLog.d("Received notification ${payload.id}")
+
+      if (!payload.isSilent && !QPushEventBus.requestForegroundDisplay(context, payload)) {
+        try {
+          QPushNotificationRenderer.render(context, payload)
+        } catch (e: Exception) {
+          QPushLog.e("Failed to render notification ${payload.id}", e)
+        }
+      }
+      // Confirmed delivery (idempotent on the server).
+      QPushHttp.reportReceived(context, payload.id)
+    }
+  }
+}

package/android/src/main/java/com/qpush/reactnative/QPushNotificationOpenActivity.kt

@@ -0,0 +1,121 @@
+package com.qpush.reactnative
+
+import android.app.Activity
+import android.content.ActivityNotFoundException
+import android.content.Intent
+import android.net.Uri
+import android.os.Bundle
+
+/**
+ * Invisible activity started by the notification PendingIntent (body tap or
+ * action button). Starting an Activity directly from the notification is the
+ * Android 12+ compliant way (no service/receiver trampolines).
+ *
+ * It reports the open natively, queues the click for JS (delivered once a
+ * listener is attached, so cold-start clicks are not lost), opens the URL
+ * (button URL wins) unless disabled, brings the app to the front and finishes.
+ */
+class QPushNotificationOpenActivity : Activity() {
+
+  override fun onCreate(savedInstanceState: Bundle?) {
+    super.onCreate(savedInstanceState)
+    try {
+      val current: Intent? = intent
+      if (current == null) openApp() else handle(current)
+    } catch (e: Exception) {
+      QPushLog.e("Failed to handle notification open", e)
+      openApp()
+    }
+    finish()
+    overridePendingTransitionCompat()
+  }
+
+  private fun handle(intent: Intent) {
+    val raw = intent.getStringExtra(QPushNotificationRenderer.EXTRA_PAYLOAD)
+    val payload = QPushPayload.parse(raw)
+    if (raw == null || payload == null) {
+      // Group summary or unknown intent: just open the app.
+      openApp()
+      return
+    }
+    val actionId = intent.getStringExtra(QPushNotificationRenderer.EXTRA_ACTION_ID)
+
+    // Action buttons do not auto-cancel the notification.
+    if (actionId != null && intent.hasExtra(QPushNotificationRenderer.EXTRA_NOTIFICATION_ID)) {
+      val notificationId = intent.getIntExtra(QPushNotificationRenderer.EXTRA_NOTIFICATION_ID, 0)
+      QPushNotificationRenderer.cancel(applicationContext, notificationId)
+    }
+
+    val url = payload.buttonUrl(actionId) ?: payload.url
+    val appContext = applicationContext
+    Thread {
+      QPushHttp.reportOpened(appContext, payload.id, actionId)
+    }.start()
+
+    QPushEventBus.emitClick(raw, actionId, url)
+
+    if (url != null && QPushStore.autoOpenUrls(appContext)) {
+      openUrl(url)
+    } else {
+      openApp()
+    }
+  }
+
+  private fun launchIntent(): Intent? {
+    val launch = packageManager.getLaunchIntentForPackage(packageName) ?: return null
+    // Behave like the launcher icon: resume the existing task instead of
+    // stacking a new activity on top of it.
+    launch.setPackage(null)
+    launch.addFlags(Intent.FLAG_ACTIVITY_NEW_TASK or Intent.FLAG_ACTIVITY_RESET_TASK_IF_NEEDED)
+    return launch
+  }
+
+  private fun openApp() {
+    val launch = launchIntent() ?: return
+    try {
+      startActivity(launch)
+    } catch (e: Exception) {
+      QPushLog.e("Could not open the app", e)
+    }
+  }
+
+  private fun openUrl(url: String) {
+    val uri = try {
+      Uri.parse(url)
+    } catch (e: Exception) {
+      null
+    }
+    if (uri == null || uri.scheme.isNullOrEmpty()) {
+      QPushLog.w("Invalid notification URL: $url")
+      openApp()
+      return
+    }
+    val view = Intent(Intent.ACTION_VIEW, uri).addFlags(Intent.FLAG_ACTIVITY_NEW_TASK)
+    try {
+      // Deep link handled by this app: deliver it to the app itself
+      // (React Native Linking receives it).
+      val ownHandler = view.resolveActivity(packageManager)?.packageName == packageName
+      if (ownHandler) {
+        view.setPackage(packageName)
+        startActivity(view)
+        return
+      }
+      // External URL: open the app with the browser on top, so going back
+      // lands in the app (and JS receives the click event).
+      val launch = launchIntent()
+      if (launch != null) startActivities(arrayOf(launch, view)) else startActivity(view)
+    } catch (e: ActivityNotFoundException) {
+      QPushLog.w("No activity can open $url", e)
+      openApp()
+    }
+  }
+
+  @Suppress("DEPRECATION")
+  private fun overridePendingTransitionCompat() {
+    try {
+      overridePendingTransition(0, 0)
+    } catch (e: Exception) {
+      // ignore
+    }
+  }
+}