Sovendus iOS SDK Integration Guide

Quick Integration Checklist

Step 1: Installation

Option A: Swift Package Manager (Recommended)

1. Open Xcode project
2. Go to File > Add Package Dependencies
3. Enter repository URL: https://github.com/Sovendus-GmbH/sovendus-sdk-ios
4. Select version and add to target

Option B: Local Drop-In

• iOS 16.0+
• Xcode 15.0+
• Swift 5.7+

Step 2: Get Your Credentials

• Traffic Source Number - (e.g. 1234)
• Traffic Medium Number - (e.g. 5678)

Step 3: Add the Component

let config = SovendusConfig(
    trafficSourceNumber: 1234,
    trafficMediumNumber: 5678,
    consumerData: nil,
    orderData: nil,
    sandbox: true, // Omit or set to false for production

SwiftUI

import SwiftUI
import SovendusSDK

struct ContentView: View {
    private let config = SovendusConfig(
        trafficSourceNumber: 1234,
        trafficMediumNumber:     
                    

UIKit

import UIKit
import SwiftUI
import SovendusSDK

class ViewController: UIViewController {
    private lazy var config = SovendusConfig(
        trafficSourceNumber:    
    
        
        
        
        
        
        
        

Theming & Gradient Backgrounds

• Linear - Directional gradients at any angle
• Radial - Circular gradients with configurable center and radius
• Angular - Sweep gradients around a center point

Layout Options

• The component renders whatever the API returns: banner only, list only, or both
• Each VoucherBenefitsView instance with a different SovendusConfig (unique trafficMediumNumber) triggers its own API call
• Sovendus controls content and layout per placement

Multiple Placements

// Placement 1 - e.g. checkout page
VoucherBenefitsView(
    config: SovendusConfig(
        trafficSourceNumber: 1234,
        trafficMediumNumber: 100,
        consumerData: consumerData,
        orderData: orderData
    )
)

Step 4: Add Personalization (Optional)

let consumerData = ConsumerData(
    salutation: .mr,
    firstName: "Max",
    lastName: "Mustermann", 
    email: "customer@example.com",
    country: "DE",
    zipCode

Step 5: Production Configuration

let productionConfig = SovendusConfig(
    trafficSourceNumber: 1234, // Your real TSN from Sovendus
    trafficMediumNumber: 5678, // Your real TMN from Sovendus
    consumerData: consumerData,
    orderData: orderData,
    sandbox: false,           

• Use real trafficSourceNumber and trafficMediumNumber from Sovendus
• Set sandbox: false for production behavior
• Set enableDebugLogs: false to disable debug output
• Both traffic parameters are required

Step 6: Handle State Changes

private func handleSovendusState(_ state: SovendusState) {
    switch state {
    case .loading:
        // Show loading indicator if needed
        print("Loading Sovendus content...")
    case

Step 7: Custom Link Handling (Optional)

let config = SovendusConfig(
    trafficSourceNumber: 1234,
    trafficMediumNumber: 5678,
    consumerData: consumerData,
    orderData: orderData,
    onLinkOpened: { url in
        // optional:  Custom link handling - useful for:

Common Use Cases

In-App Browser with SFSafariViewController

import SafariServices

let config = SovendusConfig(
    trafficSourceNumber: 1234,
    trafficMediumNumber: 5678,
    consumerData: consumerData,
    orderData: orderData,
    onLinkOpened: { url         

Step 8: Custom Font Configuration (Optional)

let config = SovendusConfig(
    trafficSourceNumber: 1234,
    trafficMediumNumber: 5678,
    consumerData: consumerData,
    orderData: orderData,
    customFont: UIFont(name: "YourCustomFont-Regular",

Bundling Custom Fonts in Your App

1. Add the font file (.ttf or .otf) to your Xcode project
2. Include in target - Ensure the font is added to your app target's "Copy Bundle Resources" build phase
3. Register in Info.plist - Add the font filename to UIAppFonts (Fonts provided by application):

<key>UIAppFonts</key>
<array>
    <string>YourCustomFont-Regular.ttf</string>
    <string>YourCustomFont-Bold.ttf</string>
</array>

Creating the UIFont

// Create a custom font with the PostScript name
let customFont = UIFont(name: "YourCustomFont-Regular", size: 14)

// You can also use font descriptors for more control
let descriptor = UIFontDescriptor(name: "YourCustomFont", size:

• Opening the font file in Font Book and checking "PostScript name" in the info panel
• Printing all available fonts: UIFont.familyNames.forEach { print(UIFont.fontNames(forFamilyName: $0)) }

Example with Multiple Font Weights

// Define font helpers
extension UIFont {
    static var appFontRegular: UIFont? {
        UIFont(name: "Poppins-Regular", size: 14)
    }

    

Error Handling & Debugging

Development Mode (enableDebugLogs = true, sandbox = true)

• Console logging for debugging
• Network error details
• Configuration validation
• Sandbox benefits for testing

Production Mode (enableDebugLogs = false, sandbox = false)

• Silent failures - no console spam
• Graceful degradation if SDK fails
• Real benefits from production API

# Check device logs for production errors
# Use Xcode Console or device logs
# Look for SovendusSDK related messages

• Missing traffic numbers in production
• Network connectivity issues
• Invalid customer data format

Modal Integration Example

SwiftUI

struct CheckoutSuccessView: View {
    @State private var showBenefitsModal = false
    
    var body: some View {
        VStack {
            Text(

UIKit

class CheckoutSuccessViewController: UIViewController {
    private var benefitsViewController: UIViewController?
    
    @IBAction func showBenefitsPressed(_ sender: UIButton) {
        let        
        
    

Troubleshooting

"Components don't render"

• Check console logs with enableDebugLogs: true
• Verify traffic source/medium numbers are correct
• Test network connectivity
• Try sandbox mode for testing

"No personalized content"

• Verify consumer data is provided correctly
• Check email format and validity
• Ensure order data is accurate

"Performance issues"

• Components load asynchronously
• Use state callbacks to show loading indicators
• Content appears when ready

"Integration errors"

• Import SovendusSDK in your files
• Verify minimum iOS version (16.0+)
• Check callback implementations are correct