Add Documentation

Author: deepone

.gitignore

@@ -1,5 +1,6 @@
 # OS X
 .DS_Store
+__MACOSX
 # Xcode
 #
 build/
@@ -32,4 +33,4 @@ Pods/
 Podfile.lock
 
 # SwiftPM
-.build
+.build

DeepOneSDK/DeepOne.swift

@@ -7,17 +7,24 @@ import UIKit
 import Cocoa
 #endif
 
+/// DeepOne provides comprehensive deep linking and deferred deep linking capabilities for iOS and macOS applications.
+/// This modern SDK offers attribution tracking, link generation, and seamless user experience management.
 @objcMembers
 public class DeepOne: NSObject {
 
+    // MARK: - Attribution Parameters
+    /// Parameter keys for routing and attribution information (Objective-C compatible)
     @objc public static let AttributionParameterOriginURL = "origin_url"
     @objc public static let AttributionParameterRoutePath = "route_path"
     @objc public static let AttributionParameterQueryParameters = "query_params"
     @objc public static let AttributionParameterIsFirstSession = "is_first_session"
     @objc public static let AttributionParameterAttributionData = "attribution_data"
 
+    // MARK: - Error Constants
+    /// Error domain for DeepOne operations
     @objc public static let DeepOneErrorDomain = "DeepOneErrorDomain"
 
+    /// Error codes for DeepOne operations
     @objc public enum DeepOneErrorCode: Int {
         case invalidConfiguration = 1001
         case networkError = 1002
@@ -26,20 +33,26 @@ public class DeepOne: NSObject {
         case missingCredentials = 1005
     }
 
+    // MARK: - Type Aliases
+    /// Handler for processing incoming deep link attribution with type-safe data model
     public typealias AttributionHandler = (_ attributionData: DeepOneAttributionData?, _ error: NSError?) -> Void
 
+    // MARK: - Singleton Instance
     public static let shared = DeepOne()
 
+    // MARK: - Properties
     private var isDevelopmentMode = false
     private var attributionHandler: AttributionHandler?
 
+    /// API credentials for link verification and generation
     private var apiKey: String? {
         guard
             let keys = Bundle.main.object(forInfoDictionaryKey: "DeepOne.keys") as? [String: Any],
             let key = keys[isDevelopmentMode ? "test" : "live"] as? String else { return nil }
         return key
     }
 
+    /// Tracks if this is the first session ever (persists across reinstalls via keychain)
     private var isFirstSession: Bool {
         didSet {
             if !isFirstSession {
@@ -59,19 +72,36 @@ public class DeepOne: NSObject {
     }
 
 #if canImport(UIKit)
+    /// Configures the DeepOne SDK with application launch context and attribution handling.
+    ///
+    /// - Parameters:
+    ///   - launchOptions: The launch options from the application delegate
+    ///   - developmentMode: Enable development mode for testing. Default is `false`.
+    ///   - attributionHandler: Closure to handle incoming attribution data
     public func configure(launchOptions: [UIApplication.LaunchOptionsKey: Any]?, 
                          developmentMode: Bool = false,  
                          attributionHandler: AttributionHandler?) {
         _configure(developmentMode: developmentMode, attributionHandler: attributionHandler)
     }
 #elseif canImport(Cocoa)
+    /// Configures the DeepOne SDK with macOS application context and attribution handling.
+    ///
+    /// - Parameters:
+    ///   - notification: The application launch notification
+    ///   - developmentMode: Enable development mode for testing. Default is `false`.
+    ///   - attributionHandler: Closure to handle incoming attribution data
     public func configure(notification: Notification, 
                          developmentMode: Bool = false,  
                          attributionHandler: AttributionHandler?) {
         _configure(developmentMode: developmentMode, attributionHandler: attributionHandler)
     }
 #endif
 
+    /// Creates a new attributed link with the specified configuration
+    ///
+    /// - Parameters:
+    ///   - configuration: Link configuration containing routing and attribution parameters
+    ///   - completion: Completion handler with the generated URL or error
     @objc public func createAttributedLink(configuration: DeepOneCreateLinkBuilder, completion: @escaping (URL?, NSError?) -> Void) {
         guard let parameters = configuration.buildParameters() else { 
             let error = NSError(domain: DeepOne.DeepOneErrorDomain, 
@@ -110,6 +140,10 @@ public class DeepOne: NSObject {
         }
     }
 
+    /// Processes universal link user activity for attribution
+    ///
+    /// - Parameter activity: The NSUserActivity from universal link handling
+    /// - Returns: Boolean indicating successful attribution processing
     @objc(continueUserActivity:)
     @discardableResult public func processUniversalLink(_ activity: NSUserActivity) -> Bool {
         guard
@@ -118,10 +152,15 @@ public class DeepOne: NSObject {
         return processAttributionData(from: url)
     }
 
+    /// Clears all persisted attribution data (resets first session tracking)
     @objc public func clearAttributionData() {
         DeepOneCoreAPI.deleteKeychainData(key: "first_session_marker")
     }
 
+    /// Processes an incoming URL for attribution tracking
+    ///
+    /// - Parameter url: The URL to process for attribution
+    /// - Returns: Boolean indicating successful processing
     @objc @discardableResult
     public func trackAttributionURL(_ url: URL) -> Bool {
         return processAttributionData(from: url)
@@ -181,6 +220,7 @@ public class DeepOne: NSObject {
         }
     }
 
+    /// Extracts marketing attribution parameters from query parameters
     private func extractMarketingAttribution(from queryParams: [String: Any]) -> [String: Any] {
         var marketingData = [String: Any]()
 
@@ -205,9 +245,12 @@ public class DeepOne: NSObject {
     }
 }
 
+// MARK: - Swift Convenience Methods
+
 #if swift(>=5.5)
 extension DeepOne {
 
+    /// Swift-specific link creation with Result type and async/await
     @available(iOS 13.0, macOS 10.15, *)
     public func createAttributedLink(configuration: DeepOneCreateLinkBuilder) async -> Result<URL, DeepOneSwiftError> {
         return await withCheckedContinuation { continuation in
@@ -224,6 +267,7 @@ extension DeepOne {
     }
 }
 
+/// Swift-specific error enum for modern error handling
 public enum DeepOneSwiftError: Error, LocalizedError {
     case invalidConfiguration
     case networkError(Error)

DeepOneSDK/DeepOneAttributionData.swift

@@ -1,41 +1,66 @@
 import Foundation
 
+/// Attribution data model providing type-safe access to attribution information
 @objcMembers
 public class DeepOneAttributionData: NSObject {
 
+    // MARK: - Core Attribution Properties
+    
+    /// The original URL that triggered the attribution
     public let originURL: String?
 
+    /// The path component of the attribution URL
     public let routePath: String?
 
+    /// Whether this is the user's first session ever (persists across app reinstalls)
     public let isFirstSession: Bool
 
+    /// All query parameters from the attribution URL
     public let queryParameters: [String: String]
 
+    // MARK: - Marketing Attribution Properties
+    
+    /// UTM source parameter
     public let marketingSource: String?
 
+    /// UTM medium parameter  
     public let marketingMedium: String?
 
+    /// UTM campaign parameter
     public let marketingCampaign: String?
 
+    /// UTM term parameter
     public let marketingTerm: String?
 
+    /// UTM content parameter
     public let marketingContent: String?
 
+    /// Custom referrer parameter
     public let referrer: String?
 
+    /// Campaign identifier
     public let campaignIdentifier: String?
-
+    
+    // MARK: - Additional Properties
+    
+    /// Raw attribution data dictionary (for custom parameters)
     public let rawData: [String: Any]
-
+    
+    // MARK: - Initialization
+    
+    /// Internal initializer from dictionary data
     internal init(from dictionary: [String: Any]) {
         self.rawData = dictionary
 
+        // Core attribution data
         self.originURL = dictionary[DeepOne.AttributionParameterOriginURL] as? String
         self.routePath = dictionary[DeepOne.AttributionParameterRoutePath] as? String
         self.isFirstSession = (dictionary[DeepOne.AttributionParameterIsFirstSession] as? Bool) ?? false
 
+        // Query parameters
         self.queryParameters = (dictionary[DeepOne.AttributionParameterQueryParameters] as? [String: String]) ?? [:]
 
+        // Marketing attribution data
         let marketingData = dictionary[DeepOne.AttributionParameterAttributionData] as? [String: Any] ?? [:]
 
         self.marketingSource = marketingData["utm_source"] as? String
@@ -49,22 +74,29 @@ public class DeepOneAttributionData: NSObject {
         super.init()
     }
 
+    // MARK: - Convenience Methods
+    
+    /// Checks if this attribution contains marketing data
     @objc public var hasMarketingData: Bool {
         return marketingSource != nil || marketingMedium != nil || marketingCampaign != nil
     }
 
+    /// Checks if this attribution contains UTM parameters
     @objc public var hasUTMParameters: Bool {
         return marketingSource != nil || marketingMedium != nil || marketingCampaign != nil || marketingTerm != nil || marketingContent != nil
     }
 
+    /// Gets a custom parameter value
     @objc public func customParameter(for key: String) -> Any? {
         return rawData[key]
     }
 
+    /// Gets a custom string parameter
     @objc public func customStringParameter(for key: String) -> String? {
         return rawData[key] as? String
     }
 
+    /// Gets all UTM parameters as a dictionary
     @objc public var utmParameters: [String: String] {
         var utm: [String: String] = [:]
         if let source = marketingSource { utm["utm_source"] = source }
@@ -75,6 +107,8 @@ public class DeepOneAttributionData: NSObject {
         return utm
     }
 
+    // MARK: - Debug Description
+    
     public override var description: String {
         var components: [String] = []
 
@@ -99,22 +133,28 @@ public class DeepOneAttributionData: NSObject {
     }
 }
 
+// MARK: - Swift Convenience Extensions
+
 #if swift(>=5.5)
 extension DeepOneAttributionData {
 
+    /// URL of the attributed link
     public var url: URL? {
         guard let originURL = originURL else { return nil }
         return URL(string: originURL)
     }
 
+    /// Checks if the attribution indicates a specific route
     public func matches(route: String) -> Bool {
         return routePath == route
     }
 
+    /// Checks if the attribution has a route with a specific prefix
     public func hasRoute(withPrefix prefix: String) -> Bool {
         return routePath?.hasPrefix(prefix) ?? false
     }
 
+    /// Extracts an ID from a route path (e.g., "/product/123" -> "123")
     public func extractID(fromRoute routePrefix: String) -> String? {
         guard let path = routePath, path.hasPrefix(routePrefix) else { return nil }
         let idStartIndex = path.index(path.startIndex, offsetBy: routePrefix.count)

DeepOneSDK/DeepOneCreateLinkBuilder.swift

@@ -1,5 +1,6 @@
 import Foundation
 
+/// Configuration builder for creating attributed deep links with marketing parameters
 @objcMembers
 public class DeepOneCreateLinkBuilder: NSObject {
     // MARK: - Core Properties
@@ -19,14 +20,20 @@ public class DeepOneCreateLinkBuilder: NSObject {
     var marketingTerm: String?
     var marketingContent: String?
 
+    // MARK: - Custom Parameters
     private var customParameters: [String: Any] = [:]
 
+    /// Creates a link builder with basic routing information
+    /// - Parameters:
+    ///   - destinationPath: The deep link path for routing
+    ///   - linkIdentifier: Unique identifier for this link
     public init(destinationPath: String, linkIdentifier: String) {
         self.destinationPath = destinationPath
         self.linkIdentifier = linkIdentifier
         super.init()
     }
 
+    /// Creates a link builder with comprehensive configuration
     public init(destinationPath: String,
                 linkIdentifier: String,
                 linkDescription: String? = nil,
@@ -53,13 +60,21 @@ public class DeepOneCreateLinkBuilder: NSObject {
     }
 }
 
+// MARK: - Builder Methods
+
 extension DeepOneCreateLinkBuilder {
+    /// Adds a custom parameter to the link configuration
+    /// - Parameters:
+    ///   - key: Parameter key
+    ///   - value: Parameter value
+    /// - Returns: Self for method chaining
     @objc @discardableResult
     public func addCustomParameter(key: String, value: Any) -> Self {
         customParameters[key] = value
         return self
     }
 
+    /// Sets social media preview content
     @objc @discardableResult
     public func setSocialPreview(title: String, description: String, imageURL: String?) -> Self {
         socialTitle = title
@@ -68,12 +83,15 @@ extension DeepOneCreateLinkBuilder {
         return self
     }
 
+    /// Sets social media preview content (Objective-C convenience method)
     @objc @discardableResult
     public func setSocialPreviewWithTitle(_ title: String, description: String) -> Self {
         return setSocialPreview(title: title, description: description, imageURL: nil)
     }
 }
 
+// MARK: - Parameter Building
+
 extension DeepOneCreateLinkBuilder: Encodable {
     enum CodingKeys: String, CodingKey {
         case destinationPath = "path"
@@ -89,6 +107,8 @@ extension DeepOneCreateLinkBuilder: Encodable {
         case marketingContent = "utmContent"
     }
 
+    /// Builds the parameter dictionary for API submission
+    /// - Returns: Dictionary containing all link parameters, or nil if invalid
     @objc public func buildParameters() -> [String: Any]? {
         guard let data = try? JSONEncoder().encode(self) else { return nil }
         guard var parameters = try? JSONSerialization.jsonObject(with: data) as? [String: Any] else { return nil }
@@ -101,6 +121,7 @@ extension DeepOneCreateLinkBuilder: Encodable {
         return parameters
     }
 
+    /// Legacy method for backward compatibility
     @objc public func toDic() -> [String: Any]? {
         return buildParameters()
     }