add documentation across all methods in file

Author: nickolas-dimitrakas

mParticle-Apple-SDK/MPRokt.m

@@ -34,11 +34,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
@@ -97,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
@@ -114,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
@@ -131,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
@@ -143,6 +170,9 @@ - (void)close {
     });
 }
 
+/// 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;
 
@@ -190,6 +220,9 @@ - (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;
@@ -207,6 +240,11 @@ - (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;
 
@@ -225,6 +263,13 @@ - (NSNumber *)getRoktHashedEmailUserIdentityType {
     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"];