SwiftWarplyFramework Quick Reference

🚀 Essential Guide for Developers

Version: 2.1.0 | iOS: 17.0+ | Swift: 5.0+

---

📦 Installation

# Podfile
pod 'SwiftWarplyFramework', :git => 'https://git@git.warp.ly/open-source/warply_sdk_framework.git', :tag => ‘2.1.0’

---

⚡ Setup (AppDelegate)

import SwiftWarplyFramework

// Configure & Initialize
WarplySDK.shared.configure(webId: "your-web-id", merchantId: "your-merchant-id", environment: .production)
WarplySDK.shared.initialize { success in
    print("SDK Ready: \(success)")
}

---

🔐 Authentication

// Login
WarplySDK.shared.verifyTicket(guid: "user-guid", ticket: "user-ticket") { response in
    if response?.getStatus == 1 { /* Success */ }
}

// Async/Await
let response = try await WarplySDK.shared.verifyTicket(guid: "guid", ticket: "ticket")

// Logout
WarplySDK.shared.logout { response in /* Handle logout */ }

---

🎯 Campaigns

// Get Campaigns
WarplySDK.shared.getCampaigns(language: "en") { campaigns in
    // Handle campaigns array
}

// Async/Await
let campaigns = try await WarplySDK.shared.getCampaigns(language: "en")

// Personalized Campaigns
let personalizedCampaigns = try await WarplySDK.shared.getCampaignsPersonalized(language: "en")

// Supermarket Campaign
WarplySDK.shared.getSupermarketCampaign(language: "en") { campaign in
    // Handle supermarket campaign
}

---

🎫 Coupons

// Get Coupons
WarplySDK.shared.getCoupons(language: "en", completion: { coupons in
    // Handle coupons
}, failureCallback: { errorCode in
    // Handle error
})

// Async/Await
let coupons = try await WarplySDK.shared.getCoupons(language: "en")

// Coupon Sets
let couponSets = try await WarplySDK.shared.getCouponSets()

// Availability
WarplySDK.shared.getAvailableCoupons { availability in
    // Handle availability data
}

---

🏪 Market Pass

// Market Pass Details
WarplySDK.shared.getMarketPassDetails(completion: { marketPass in
    print("Balance: \(marketPass?.balance ?? 0)")
}, failureCallback: { errorCode in
    // Handle error
})

// Async/Await
let marketPass = try await WarplySDK.shared.getMarketPassDetails()

// Supermarket History
let history = try await WarplySDK.shared.getRedeemedSMHistory(language: "en")

---

📡 Events

Modern EventDispatcher (Recommended)

class ViewController: UIViewController {
    private var eventSubscriptions: [EventSubscription] = []

    override func viewDidLoad() {
        super.viewDidLoad()

        // Subscribe to events
        let subscription = WarplySDK.shared.subscribe(CampaignsRetrievedEvent.self) { event in
            DispatchQueue.main.async {
                // Update UI
            }
        }
        eventSubscriptions.append(subscription)
    }

    deinit {
        eventSubscriptions.removeAll() // Auto cleanup
    }
}

Legacy SwiftEventBus

// Subscribe
SwiftEventBus.onMainThread(self, name: "campaigns_retrieved") { result in
    // Handle event
}

// Cleanup
deinit {
    SwiftEventBus.unregister(self)
}

---

⚠️ Error Handling

// Async/Await Error Handling
Task {
    do {
        let campaigns = try await WarplySDK.shared.getCampaigns(language: "en")
        // Success
    } catch let error as WarplyError {
        switch error {
        case .networkError: // Handle network error
        case .authenticationFailed: // Handle auth error
        case .invalidResponse: // Handle invalid response
        case .dataParsingError: // Handle parsing error
        case .unknownError(let code): // Handle unknown error
        }
    }
}

---

📱 Push Notifications

// AppDelegate
func application(_ application: UIApplication, didRegisterForRemoteNotificationsWithDeviceToken deviceToken: Data) {
    let tokenString = deviceToken.map { String(format: "%02.2hhx", $0) }.joined()
    WarplySDK.shared.updateDeviceToken(tokenString)
}

func application(_ application: UIApplication, didReceiveRemoteNotification userInfo: [AnyHashable: Any]) {
    if WarplySDK.shared.checkForLoyaltySDKNotification(userInfo) {
        // Warply notification handled
    }
}

---

⚙️ Configuration Properties

// Language
WarplySDK.shared.applicationLocale = "en" // or "el"

// Dark Mode
WarplySDK.shared.isDarkModeEnabled = true

// Analytics
WarplySDK.shared.trackersEnabled = true

// Network Status
let status = WarplySDK.shared.getNetworkStatus() // 1=connected, 0=disconnected, -1=unknown

---

🎯 State Management

// Campaigns
let campaigns = WarplySDK.shared.getCampaignList()
let allCampaigns = WarplySDK.shared.getAllCampaignList()
let carouselCampaigns = WarplySDK.shared.getCarouselList()

// Coupons
let activeCoupons = WarplySDK.shared.getCouponList()
let usedCoupons = WarplySDK.shared.getOldCouponList()

// Market Pass
let marketPass = WarplySDK.shared.getMarketPassDetails()

// Merchants
let merchants = WarplySDK.shared.getMerchantList()

---

🔧 Utilities

// Campaign URLs
let url = WarplySDK.shared.constructCampaignUrl(campaign)
let params = WarplySDK.shared.constructCampaignParams(campaign)

// UI Helpers
WarplySDK.shared.openSupermarketsMap(self) // Open map
WarplySDK.shared.openSuperMarketsFlow(self) // Open flow
WarplySDK.shared.showDialog(self, "Title", "Message") // Show alert

---

🚨 Common Patterns

Loading Data with Cache

func loadCampaigns() {
    // Show cached data first
    let cached = WarplySDK.shared.getCampaignList()
    if !cached.isEmpty {
        updateUI(with: cached)
    }

    // Fetch fresh data
    Task {
        do {
            let fresh = try await WarplySDK.shared.getCampaigns(language: "en")
            updateUI(with: fresh)
        } catch {
            // Keep cached data on error
        }
    }
}

Batch API Calls

Task {
    async let campaigns = WarplySDK.shared.getCampaigns(language: "en")
    async let coupons = WarplySDK.shared.getCoupons(language: "en")
    async let marketPass = WarplySDK.shared.getMarketPassDetails()

    do {
        let (campaignData, couponData, marketData) = try await (campaigns, coupons, marketPass)
        // Update UI with all data
    } catch {
        // Handle errors
    }
}

Network Check Before API

func safeAPICall() {
    guard WarplySDK.shared.getNetworkStatus() == 1 else {
        showOfflineMessage()
        return
    }

    // Proceed with API call
    Task {
        let campaigns = try await WarplySDK.shared.getCampaigns(language: "en")
        // Handle success
    }
}

---

📋 Available Events

Event	Type	Description
campaigns_retrieved	CampaignsRetrievedEvent	Campaigns loaded
coupons_fetched	CouponsRetrievedEvent	Coupons loaded
market_pass_details_fetched	MarketPassDetailsEvent	Market pass loaded
ccms_retrieved	CCMSRetrievedEvent	CCMS campaigns loaded
seasonals_retrieved	SeasonalsRetrievedEvent	Seasonal campaigns loaded
dynatrace	DynatraceEvent	Analytics events

---

🔍 Debug Info

print("SDK Version: 2.1.0")
print("App UUID: \(WarplySDK.shared.appUuid)")
print("Merchant ID: \(WarplySDK.shared.merchantId)")
print("Language: \(WarplySDK.shared.applicationLocale)")
print("Network: \(WarplySDK.shared.getNetworkStatus())")
print("Dark Mode: \(WarplySDK.shared.isDarkModeEnabled)")

---

💡 Best Practices

✅ Initialize in AppDelegate
✅ Use async/await for new code
✅ Handle errors properly
✅ Check network status
✅ Use weak self in closures
✅ Clean up event subscriptions
✅ Cache data when possible

❌ Don't ignore errors
❌ Don't initialize in ViewControllers
❌ Don't create retain cycles
❌ Don't forget to unregister events

---

For detailed documentation, see CLIENT_DOCUMENTATION.md