framework_specifications.md 10.5 KB

Raw Blame History Permalink



SwiftWarplyFramework Specifications


Overview

SwiftWarplyFramework is an iOS SDK that provides loyalty program functionality, including campaign management, coupon handling, analytics tracking, and user management. This document outlines the technical specifications of the completed Swift migration of the framework.


Technical Requirements


Platform Support


Minimum iOS Version: 17.0
Swift Version: 5.0+
Build System: CocoaPods
Framework Version: 2.0.1


Dependencies


RSBarcodes_Swift (~> 5.2.0) - Barcode scanning and generation
SwiftEventBus - Event handling and communication (backward compatibility)
No other external dependencies (SQLite.swift removed - using pure Swift implementation)


Framework Structure (Actual Implementation)

SwiftWarplyFramework/
├── Core/
│   └── WarplySDK.swift              # Main entry point - Pure Swift implementation
│
├── Network/
│   ├── NetworkService.swift        # URLSession-based networking
│   └── Endpoints.swift             # API endpoint definitions
│
├── Models/                          # Data models (Codable)
│   ├── Campaign.swift
│   ├── Coupon.swift
│   ├── Market.swift
│   ├── Merchant.swift
│   ├── Events.swift
│   ├── Gifts.swift
│   ├── Response.swift
│   ├── OfferModel.swift
│   ├── SectionModel.swift
│   └── CouponFilterModel.swift
│
├── Events/
│   └── EventDispatcher.swift       # Modern Swift event system
│
├── Screens/                        # UIKit ViewControllers
│   ├── CampaignViewController.swift
│   ├── CouponViewController/
│   ├── MyRewardsViewController/
│   └── ProfileViewController/
│
├── Cells/                          # UITableViewCells & UICollectionViewCells
│   ├── MyRewardsBannerOfferCollectionViewCell/
│   ├── MyRewardsBannerOffersScrollTableViewCell/
│   ├── MyRewardsOfferCollectionViewCell/
│   ├── MyRewardsOffersScrollTableViewCell/
│   ├── ProfileCouponFiltersTableViewCell/
│   ├── ProfileCouponTableViewCell/
│   ├── ProfileFilterCollectionViewCell/
│   ├── ProfileHeaderTableViewCell/
│   └── ProfileQuestionnaireTableViewCell/
│
├── Helpers/
│   ├── WarplyReactMethods.h        # React Native bridge header
│   └── WarplyReactMethods.m        # React Native bridge implementation
│
├── Extensions/
│   ├── UIColorExtensions.swift
│   ├── ViewControllerExtensions.swift
│   └── CopyableLabel.swift
│
├── Resources/
│   ├── Media.xcassets/             # Images and assets
│   ├── fonts/                      # Custom fonts
│   ├── Main.storyboard            # UI storyboard
│   └── Info.plist                 # Framework info
│
└── Documentation/
    └── SwiftWarplyFramework.docc/  # DocC documentation


Core Components (Actual Implementation)


WarplySDK.swift - Main Entry Point


Pattern: Singleton with dependency injection

Features:


Unified API interface for all framework functionality
Pure Swift implementation (no Objective-C dependencies)
Both completion handler and async/await support
Comprehensive state management
UserDefaults integration with property wrappers
Dual event system (EventDispatcher + SwiftEventBus compatibility)


Network Layer (NetworkService.swift)


Implementation: URLSession-based networking

Features:


Pure Swift async/await patterns
Token management (access + refresh tokens)
Network connectivity monitoring
Structured error handling with NetworkError enum
Type-safe endpoint definitions
Automatic JSON serialization/deserialization
Request/response validation


Event System (EventDispatcher.swift)


Implementation: Modern Swift event dispatcher

Features:


Type-safe event protocols
Thread-safe implementation
Memory-safe subscription management
SwiftEventBus compatibility layer
Automatic cleanup on deinit
Both string-based and type-safe event posting


Data Models (Models/ Directory)


Implementation: Pure Swift Codable models

Features:


10 domain-separated model files
Backward compatibility with existing model names
Computed properties for enhanced functionality
JSON serialization/deserialization
Optional property handling
Date formatting and conversion


Configuration Management


Implementation: Property wrappers for UserDefaults

Features:


Type-safe configuration storage
Environment switching (development/production)
Language localization support
Dark mode configuration
Analytics tracking preferences
Merchant and app UUID management


Authentication & Token Management


Implementation: Integrated into NetworkService

Features:


JWT token handling
Automatic token refresh
Secure token storage
Authentication state management
Login/logout functionality
Token validation and expiration handling


Feature Components


Campaign Management


Campaign listing and details
Features:


Campaign tracking
Interactive campaigns
Campaign analytics
Campaign filtering
Campaign categories


Coupon System


Coupon management
Features:


Coupon listing
Coupon redemption
QR code generation
Barcode scanning
Expiration handling
Favorite coupons
Coupon categories


Market Features


Market functionality
Features:


Store locator
Market pass
Offer tracking
Store details
Distance calculation
Store categories


Profile Management


User profile handling
Features:


User preferences
Settings management
Profile data
Authentication state
Data persistence


UI Components


Maintain existing UIKit implementations
Features:


Campaign screens
Coupon screens
Profile screens
Custom cells
Reusable components


Performance Requirements


Memory Management


Efficient memory usage
Proper cleanup of resources
Prevention of memory leaks
Optimization of image loading


Network Optimization


Efficient data transfer
Request caching
Data compression
Bandwidth optimization


Battery Usage


Efficient location updates
Background task optimization
Network request batching
Push notification optimization


Security Requirements


Data Security


Secure storage of sensitive data
Encryption of user data
Secure network communication
Certificate pinning
Token management


Privacy


User data protection
Location data handling
Push notification permissions
Data retention policies


Integration Requirements


Host App Integration


Simple initialization process
Clear documentation
Sample implementations
Migration guide from previous versions


Configuration


Environment switching (dev/prod)
Logging levels
Feature flags
API endpoints
Timeout settings
Error handling


Documentation Requirements


Technical Documentation


API reference
Integration guide
Migration guide
Best practices
Sample code
Architecture overview


User Documentation


Feature guides
UI components
Implementation examples
Troubleshooting guide
FAQ section


Testing Requirements


Unit Testing


Core functionality tests
Service layer tests
Model tests
Utility tests


Integration Testing


API integration tests
Database integration tests
Service integration tests


UI Testing


Screen navigation tests
User interaction tests
Visual regression tests


Version Control


Git Requirements


Feature branching
Semantic versioning
Release tagging
Changelog maintenance
Pull request guidelines


Build and Release


CocoaPods


Podspec maintenance
Version management
Dependency management
Release process


CI/CD


Automated builds
Test automation
Release automation
Documentation generation


Migration Status - COMPLETED ✅


Migration Achievements


100% Pure Swift Implementation (excluding React Native bridge)

Zero Breaking Changes for existing clients

Modern Swift Patterns throughout the codebase

Successful Build - All compilation errors resolved

Backward Compatibility maintained with SwiftEventBus

Enhanced Error Handling with structured Swift error types


Build Fixes Applied

During the migration completion, the following critical build issues were resolved:


CampaignViewController.swift - Fixed nested function syntax errors


Separated getCampaignsCallback from getCouponsCallback 
Corrected function scope and closing braces


WarplySDK.swift - Fixed NetworkService integration


Removed invalid networkService.configure() call
NetworkService now properly initialized with Configuration.baseURL


NetworkError.swift - Added missing error code property


Added code computed property to NetworkError enum
Proper error code mapping for all error types


NetworkService.swift - Added missing token access method


Added getRefreshToken() method alongside getAccessToken()

Consistent token management API


WarplyReactMethods.m - Fixed UIKit import


Added missing #import <UIKit/UIKit.h> statement
Resolved "Use of undeclared identifier 'UIDevice'" error


Migration Notes


From Objective-C to Pure Swift


Complete Swift rewrite of core networking and SDK logic

Maintained existing functionality with enhanced type safety

Improved architecture with modern Swift patterns

Added modern Swift features (async/await, property wrappers, structured concurrency)

Preserved UIKit implementations that were already modernized

Updated networking layer from AFNetworking to URLSession

Enhanced security features with structured error handling


Architectural Improvements


Dependency Injection: Clean separation of concerns

Property Wrappers: Type-safe UserDefaults access

Async/Await: Modern concurrency patterns alongside completion handlers

Event System: Dual system supporting both modern EventDispatcher and legacy SwiftEventBus

Error Handling: Structured Swift error types with localized descriptions

State Management: Centralized state management in WarplySDK


Future Considerations


Scalability


Module extensibility
Feature addition process
Performance monitoring
Analytics enhancement


Maintenance


Code review process
Documentation updates
Dependency updates
Security updates
Bug fixing process