Add trackClickAndReturnOriginal method

Developers call the `OneSignal.LiveActivities.trackClickAndReturnOriginal(url)` method to provide OneSignal the click tracking metadata. This method returns the intended original URL, with which they use to navigate their users.

Author: nan-li

iOS_SDK/OneSignalSDK/OneSignalLiveActivities/Source/OneSignalLiveActivitiesManagerImpl.swift

@@ -175,6 +175,54 @@ public class OneSignalLiveActivitiesManagerImpl: NSObject, OSLiveActivities {
         }
     }
 
+    @objc
+    public static func trackClickAndReturnOriginal(_ url: URL) -> URL? {
+        // Check if this is a OneSignal click tracking URL
+        guard url.scheme == LiveActivityConstants.Tracking.scheme,
+              url.host == LiveActivityConstants.Tracking.host,
+              url.path == LiveActivityConstants.Tracking.clickPath,
+              let components = URLComponents(url: url, resolvingAgainstBaseURL: false),
+              let queryItems = components.queryItems else
+        {
+            OneSignalLog.onesignalLog(.LL_VERBOSE, message: "trackClickAndReturnOriginal:\(url) is not a tracking URL")
+            return url
+        }
+
+        /// Helper function to extract redirect URL
+        func getRedirectURL() -> URL? {
+            guard let redirectString = queryItems.first(where: { $0.name == LiveActivityConstants.Tracking.redirect })?.value,
+                  let redirectURL = URL(string: redirectString)
+            else {
+                return nil
+            }
+            return redirectURL
+        }
+
+        // Extract metadata
+        guard let clickId = queryItems.first(where: { $0.name == LiveActivityConstants.Tracking.clickId })?.value,
+              let activityId = queryItems.first(where: { $0.name == LiveActivityConstants.Tracking.activityId })?.value,
+              let activityType = queryItems.first(where: { $0.name == LiveActivityConstants.Tracking.activityType })?.value else
+        {
+            OneSignalLog.onesignalLog(.LL_ERROR, message: "Missing required parameters in tracking URL: \(url)")
+            return getRedirectURL()
+        }
+
+        trackClick(clickId: clickId, activityType: activityType, activityId: activityId)
+
+        return getRedirectURL()
+    }
+
+    /**
+     Track the click event.
+     - Parameters:
+        - clickId: UUID representing the unique click event, as it is possible for this click to be tracked multiple times.
+     */
+    private static func trackClick(clickId: String, activityType: String, activityId: String) {
+        OneSignalLog.onesignalLog(.LL_VERBOSE, message: "OneSignal.LiveActivities trackClick called with clickId: \(clickId), activityType: \(activityType), activityId: \(activityId)")
+        let req = OSRequestLiveActivityClicked(key: clickId, activityType: activityType, activityId: activityId)
+        _executor.append(req)
+    }
+
     @available(iOS 17.2, *)
     private static func listenForPushToStart<Attributes: OneSignalLiveActivityAttributes>(_ activityType: Attributes.Type, options: LiveActivitySetupOptions? = nil) {
         if options == nil || options!.enablePushToStart {

iOS_SDK/OneSignalSDK/OneSignalOSCore/Source/OSLiveActivities.swift

@@ -34,7 +34,7 @@ import OneSignalCore
 public protocol OSLiveActivities {
     /**
      Indicate this device has entered a live activity, identified within OneSignal by the `activityId`.
-     - Parameters
+     - Parameters:
         - activityId: The activity identifier the live activity on this device will receive updates for.
         - withToken: The live activity's update token to receive the updates.
      */
@@ -43,7 +43,7 @@ public protocol OSLiveActivities {
     /**
      Indicate this device has entered a live activity, identified within OneSignal by the `activityId`. This method is deprecated since
      the request to enter a live activity will always succeed.
-     - Parameters
+     - Parameters:
         - activityId: The activity identifier the live activity on this device will receive updates for.
         - withToken: The live activity's update token to receive the updates.
         - withSuccess: A success callback that will be called when the live activity enter request has been queued.
@@ -54,19 +54,29 @@ public protocol OSLiveActivities {
 
     /**
      Indicate this device has exited a live activity, identified within OneSignal by the `activityId`.
-     - Parameters
+     - Parameters:
         - activityId: The activity identifier the live activity on this device will no longer receive updates for.
      */
     static func exit(_ activityId: String)
 
     /**
      Indicate this device has exited a live activity, identified within OneSignal by the `activityId`. This method is deprecated since
      the request to enter a live activity will always succeed.
-     - Parameters
+     - Parameters:
         - activityId: The activity identifier the live activity on this device will no longer receive updates for.
         - withSuccess: A success callback that will be called when the live activity exit request has been queued.
         - withFailure: A failure callback that will be called when the live activity enter exit was not successfully queued.
      */
     @available(*, deprecated)
     static func exit(_ activityId: String, withSuccess: OSResultSuccessBlock?, withFailure: OSFailureBlock?)
+
+    /**
+     Use in conjunction with the `onesignalWidgetURL` modifier. Handle a URL opened in the app to track Live Activity clicks. Call this method from your app's URL handling code
+     (e.g., `application(_:open:options:)` in AppDelegate or `onOpenURL` in SwiftUI).
+
+     - Parameters:
+        - url: The URL that was opened, which may be a OneSignal Live Activity click tracking URL.
+     - Returns: The intended original nullable URL.
+     */
+    static func trackClickAndReturnOriginal(_ url: URL) -> URL?
 }

iOS_SDK/OneSignalSDK/OneSignalOSCore/Source/OSStubLiveActivities.swift

@@ -31,4 +31,8 @@ public class OSStubLiveActivities: NSObject, OSLiveActivities {
         OneSignalLog.onesignalLog(.LL_ERROR, message: "OneSignalLiveActivities not found. In order to use OneSignal's LiveActivities features the OneSignalLiveActivities module must be added.")
     }
 
+    public static func trackClickAndReturnOriginal(_ url: URL) -> URL? {
+        OneSignalLog.onesignalLog(.LL_ERROR, message: "OneSignalLiveActivities not found. In order to use OneSignal's LiveActivities features the OneSignalLiveActivities module must be added.")
+        return url
+    }
 }