code improvements suggested by Nick

Author: BrandonStalnaker

mParticle-Apple-SDK/MPRokt.m

@@ -12,6 +12,17 @@
 #import "MPIConstants.h"
 #import "MPIdentityDTO.h"
 
+// Constants for kit configuration keys
+static NSString * const kMPKitConfigurationIdKey = @"id";
+static NSString * const kMPAttributeMappingSourceKey = @"map";
+static NSString * const kMPAttributeMappingDestinationKey = @"value";
+
+// Rokt attribute keys
+static NSString * const kMPRoktAttributeKeySandbox = @"sandbox";
+
+// Rokt kit identifier
+static const NSInteger kMPRoktKitId = 181;
+
 @interface MParticle ()
 
 + (dispatch_queue_t)messageQueue;
@@ -29,11 +40,25 @@ @implementation MPRoktConfig
 
 @implementation MPRokt
 
+/// Displays a Rokt ad placement with the specified identifier and user attributes.
+/// This is a convenience method that calls the full selectPlacements method with nil for optional parameters.
+/// - Parameters:
+///   - identifier: The Rokt placement identifier configured in the Rokt dashboard (e.g., "checkout_confirmation")
+///   - attributes: Optional dictionary of user attributes to pass to Rokt (e.g., email, firstName, etc.)
 - (void)selectPlacements:(NSString *)identifier
               attributes:(NSDictionary<NSString *, NSString *> * _Nullable)attributes {
     [self selectPlacements:identifier attributes:attributes embeddedViews:nil config:nil callbacks:nil];
 }
 
+/// Displays a Rokt ad placement with full configuration options.
+/// This method handles user identity synchronization, attribute mapping, and forwards the request to the Rokt Kit.
+/// Device identifiers (IDFA/IDFV) are automatically added if available.
+/// - Parameters:
+///   - identifier: The Rokt placement identifier configured in the Rokt dashboard
+///   - attributes: Optional dictionary of user attributes (email, firstName, etc.). Attributes will be mapped according to dashboard configuration.
+///   - embeddedViews: Optional dictionary mapping placement identifiers to embedded view containers for inline placements
+///   - config: Optional Rokt configuration object (e.g., for dark mode or custom styling)
+///   - callbacks: Optional callback handlers for Rokt events (selection, display, completion, etc.)
 - (void)selectPlacements:(NSString *)identifier
               attributes:(NSDictionary<NSString *, NSString *> * _Nullable)attributes
            embeddedViews:(NSDictionary<NSString *, MPRoktEmbeddedView *> * _Nullable)embeddedViews
@@ -49,16 +74,16 @@ - (void)selectPlacements:(NSString *)identifier
         if (attributeMap) {
             NSMutableDictionary *mappedAttributes = attributes.mutableCopy;
             for (NSDictionary<NSString *, NSString *> *map in attributeMap) {
-                NSString *mapFrom = map[@"map"];
-                NSString *mapTo = map[@"value"];
+                NSString *mapFrom = map[kMPAttributeMappingSourceKey];
+                NSString *mapTo = map[kMPAttributeMappingDestinationKey];
                 if (mappedAttributes[mapFrom]) {
                     NSString * value = mappedAttributes[mapFrom];
                     [mappedAttributes removeObjectForKey:mapFrom];
                     mappedAttributes[mapTo] = value;
                 }
             }
             for (NSString *key in mappedAttributes) {
-                if (![key isEqual:@"sandbox"]) {
+                if (![key isEqual:kMPRoktAttributeKeySandbox]) {
                     [resolvedUser setUserAttribute:key value:mappedAttributes[key]];
                 }
             }
@@ -86,6 +111,12 @@ - (void)selectPlacements:(NSString *)identifier
     }];
 }
 
+/// Notifies Rokt that a purchase from a placement offer has been finalized.
+/// Call this method to inform Rokt about the completion status of an offer purchase initiated from a placement.
+/// - Parameters:
+///   - placementId: The identifier of the placement where the offer was displayed
+///   - catalogItemId: The identifier of the catalog item that was purchased
+///   - success: Whether the purchase was successful (YES) or failed (NO)
 - (void)purchaseFinalized:(NSString * _Nonnull)placementId catalogItemId:(NSString * _Nonnull)catalogItemId success:(BOOL)success {
     dispatch_async(dispatch_get_main_queue(), ^{
         // Forwarding call to kits
@@ -103,6 +134,11 @@ - (void)purchaseFinalized:(NSString * _Nonnull)placementId catalogItemId:(NSStri
     });
 }
 
+/// Registers a callback to receive events from a specific Rokt placement.
+/// Use this to listen for events like placement shown, offer selected, placement closed, etc.
+/// - Parameters:
+///   - identifier: The Rokt placement identifier to listen for events from
+///   - onEvent: Callback block that receives MPRoktEvent objects when placement events occur
 - (void)events:(NSString * _Nonnull)identifier onEvent:(void (^ _Nullable)(MPRoktEvent * _Nonnull))onEvent {
     dispatch_async(dispatch_get_main_queue(), ^{
         // Forwarding call to kits
@@ -120,6 +156,8 @@ - (void)events:(NSString * _Nonnull)identifier onEvent:(void (^ _Nullable)(MPRok
     });
 }
 
+/// Closes any currently displayed Rokt placement.
+/// Call this method to programmatically dismiss an active Rokt overlay or embedded placement.
 - (void)close {
     dispatch_async(dispatch_get_main_queue(), ^{
         // Forwarding call to kits
@@ -132,17 +170,28 @@ - (void)close {
     });
 }
 
-- (NSArray<NSDictionary<NSString *, NSString *> *> *)getRoktPlacementAttributesMapping {
-    NSArray<NSDictionary<NSString *, NSString *> *> *attributeMap = nil;
-    
-    // Get the kit configuration
+#pragma mark - Private Helper Methods
+
+/// Retrieves the Rokt Kit configuration from the kit container.
+/// @return The Rokt Kit configuration dictionary, or nil if Rokt Kit is not configured.
+- (NSDictionary * _Nullable)getRoktKitConfiguration {
     NSArray<NSDictionary *> *kitConfigs = [MParticle sharedInstance].kitContainer_PRIVATE.originalConfig.copy;
-    NSDictionary *roktKitConfig;
     for (NSDictionary *kitConfig in kitConfigs) {
-        if (kitConfig[@"id"] != nil && [kitConfig[@"id"] integerValue] == 181) {
-            roktKitConfig = kitConfig;
+        if ([kitConfig[kMPKitConfigurationIdKey] integerValue] == kMPRoktKitId) {
+            return kitConfig;
         }
     }
+    return nil;
+}
+
+/// Retrieves the attribute mapping configuration for the Rokt Kit from the mParticle dashboard settings.
+/// The mapping defines how attribute keys should be renamed before being sent to Rokt (e.g., "userEmail" → "email").
+/// @return An array of mapping dictionaries with "map" (source key) and "value" (destination key), or nil if Rokt Kit is not configured.
+- (NSArray<NSDictionary<NSString *, NSString *> *> *)getRoktPlacementAttributesMapping {
+    NSArray<NSDictionary<NSString *, NSString *> *> *attributeMap = nil;
+    
+    // Get the kit configuration
+    NSDictionary *roktKitConfig = [self getRoktKitConfiguration];
 
     // Return nil if no Rokt Kit configuration found
     if (!roktKitConfig) {
@@ -181,15 +230,12 @@ - (void)close {
     return attributeMap;
 }
 
+/// Retrieves the configured identity type to use for hashed email from the Rokt Kit configuration.
+/// The hashed email identity type is determined by dashboard settings and may vary (e.g., CustomerId, Other, etc.).
+/// @return The NSNumber representing the MPIdentity type for hashed email, or nil if not configured.
 - (NSNumber *)getRoktHashedEmailUserIdentityType {
     // Get the kit configuration
-    NSArray<NSDictionary *> *kitConfigs = [MParticle sharedInstance].kitContainer_PRIVATE.originalConfig.copy;
-    NSDictionary *roktKitConfig;
-    for (NSDictionary *kitConfig in kitConfigs) {
-        if (kitConfig[@"id"] != nil && [kitConfig[@"id"] integerValue] == 181) {
-            roktKitConfig = kitConfig;
-        }
-    }
+    NSDictionary *roktKitConfig = [self getRoktKitConfiguration];
 
     // Get the string representing which identity to use and convert it to the key (NSNumber)
     NSString *hashedIdentityTypeString = roktKitConfig[kMPRemoteConfigKitConfigurationKey][kMPHashedEmailUserIdentityType];
@@ -198,25 +244,36 @@ - (NSNumber *)getRoktHashedEmailUserIdentityType {
     return hashedIdentityTypeNumber;
 }
 
+/// Ensures the "sandbox" attribute is present in the attributes dictionary.
+/// If not already set by the caller, the sandbox value is automatically determined based on the current mParticle environment
+/// (MPEnvironmentDevelopment → "true", production → "false"). This tells Rokt whether to show test or production ads.
+/// - Parameter attributes: The input attributes dictionary to validate
+/// @return A dictionary with the sandbox attribute guaranteed to be present
 - (NSDictionary<NSString *, NSString *> *)confirmSandboxAttribute:(NSDictionary<NSString *, NSString *> * _Nullable)attributes {
     NSMutableDictionary<NSString *, NSString *> *finalAttributes = attributes.mutableCopy;
-    NSString *sandboxKey = @"sandbox";
 
     // Determine the value of the sandbox attribute based off the current environment
     NSString *sandboxValue = ([[MParticle sharedInstance] environment] == MPEnvironmentDevelopment) ? @"true" : @"false";
 
     if (finalAttributes != nil) {
         // Only set sandbox if it`s not set by the client
-        if (![finalAttributes.allKeys containsObject:sandboxKey]) {
-            finalAttributes[sandboxKey] = sandboxValue;
+        if (![finalAttributes.allKeys containsObject:kMPRoktAttributeKeySandbox]) {
+            finalAttributes[kMPRoktAttributeKeySandbox] = sandboxValue;
         }
     } else {
-        finalAttributes = [[NSMutableDictionary alloc] initWithDictionary:@{sandboxKey: sandboxValue}];
+        finalAttributes = [[NSMutableDictionary alloc] initWithDictionary:@{kMPRoktAttributeKeySandbox: sandboxValue}];
     }
 
     return finalAttributes;
 }
 
+/// Synchronizes user identity with mParticle if email or hashed email is provided in attributes.
+/// If the email or hashed email in attributes differs from the current user's identity, this method performs
+/// an identity API call to update the user before proceeding. This ensures Rokt has the most current user identity.
+/// - Parameters:
+///   - attributes: Dictionary that may contain "email" or "emailsha256" keys
+///   - user: The current mParticle user
+///   - completion: Completion handler called with the resolved (possibly updated) user
 - (void)confirmUser:(NSDictionary<NSString *, NSString *> * _Nullable)attributes user:(MParticleUser * _Nullable)user completion:(void (^)(MParticleUser *_Nullable))completion {
     NSString *email = attributes[@"email"];
     NSString *hashedEmail = attributes[@"emailsha256"];