iOS SDK Usage & Integration

Learn how to initialize the DoorstepAI SDK and integrate delivery tracking into your iOS application.

SDK Initialization

Basic Setup

Initialize the SDK early in your app's lifecycle, typically in your App struct or AppDelegate:

MyApp.swift

import SwiftUI
import DoorstepDropoffSDK

@main
struct MyApp: App {
    init() {
        // Initialize DoorstepAI with your API key
        DoorstepAI.setApiKey(key: "YOUR_API_KEY_HERE")
    }

    var body: some Scene {
        WindowGroup {
            ContentView()
        }
    }
}

SwiftUI Integration

For SwiftUI applications, integrate the SDK root component:

ContentView.swift

import SwiftUI
import DoorstepDropoffSDK

struct ContentView: View {
    var body: some View {
        VStack {
            // Your app content
            Text("Welcome to My Delivery App")
            
            // DoorstepAI Root Component
            DoorstepAIRoot()
        }
    }
}

API Key Security

Store your API key securely using environment variables or a secure configuration service. Never hardcode API keys in production builds.

Core Functionality

Delivery IDs

Delivery IDs are designed to be unique identifiers for each delivery session. Use meaningful, unique identifiers that help you track and manage your deliveries effectively.

Starting Delivery Tracking

The SDK provides multiple methods to start delivery tracking based on different address formats:

1. Start by Place ID

Task {
    do {
        try await DoorstepAI.startDeliveryByPlaceID(
            placeID: "some_place_id",
            deliveryId: "delivery_12345"
        )
        print("✅ Delivery started successfully")
        // Handle successful start
    } catch {
        print("❌ Failed to start delivery: \(error.localizedDescription)")
        // Handle error
    }
}

2. Start by Plus Code

Task {
    do {
        try await DoorstepAI.startDeliveryByPlusCode(
            plusCode: "some_plus_code",
            deliveryId: "delivery_12345"
        )
        print("✅ Delivery started with Plus Code")
    } catch {
        print("❌ Plus Code delivery failed: \(error.localizedDescription)")
    }
}

3. Start by Address Components

let address = AddressType(
    streetNumber: "123",
    route: "Main Street",
    subPremise: "Apt 4B",
    locality: "San Francisco",
    administrativeAreaLevel1: "CA",
    postalCode: "94102"
)

Task {
    do {
        try await DoorstepAI.startDeliveryByAddressType(
            address: address,
            deliveryId: "delivery_12345"
        )
        print("✅ Address delivery started")
    } catch {
        print("❌ Address delivery failed: \(error.localizedDescription)")
    }
}

Delivery Events

Track important delivery milestones using event reporting:

Proof of Delivery (POD) Events

// When driver starts taking a photo for proof of delivery
Task {
    do {
        try await DoorstepAI.newEvent(
            eventName: "taking_pod",
            deliveryId: "delivery_12345"
        )
        print("POD capture initiated")
    } catch {
        print("POD capture failed: \(error.localizedDescription)")
    }
}

// When proof of delivery photo is captured
Task {
    do {
        try await DoorstepAI.newEvent(
            eventName: "pod_captured",
            deliveryId: "delivery_12345"
        )
        print("POD captured successfully")
    } catch {
        print("POD capture failed: \(error.localizedDescription)")
    }
}

Stopping Delivery Tracking

Stop tracking when the delivery is complete:

// Stop delivery tracking
Task {
    await DoorstepAI.stopDelivery(deliveryId: "delivery_12345")
    print("🛑 Delivery tracking stopped")
}

Address Types Reference

AddressType Structure

public struct AddressType {
    public let streetNumber: String
    public let route: String
    public let subPremise: String
    public let locality: String
    public let administrativeAreaLevel1: String
    public let postalCode: String
    
    public init(streetNumber: String, route: String, subPremise: String, locality: String, administrativeAreaLevel1: String, postalCode: String)
}

Usage Examples

// Minimal address
let simpleAddress = AddressType(
    streetNumber: "456",
    route: "Oak Avenue",
    subPremise: "",
    locality: "Oakland",
    administrativeAreaLevel1: "CA",
    postalCode: "94610"
)

// Complete address with apartment
let detailedAddress = AddressType(
    streetNumber: "789",
    route: "Pine Street",
    subPremise: "Suite 100",
    locality: "Berkeley",
    administrativeAreaLevel1: "California",
    postalCode: "94704"
)

Best Practices

1. Error Handling

Always implement proper error handling for SDK methods:

func startDeliveryWithErrorHandling(placeID: String, deliveryId: String) {
    Task {
        do {
            try await DoorstepAI.startDeliveryByPlaceID(
                placeID: placeID,
                deliveryId: deliveryId
            )
            // handle success
        } catch {
            // handle error
        }
    }
}

2. Lifecycle Management

Handle app lifecycle changes appropriately:

class DeliveryManager: ObservableObject {
    func startDelivery(placeID: String, deliveryId: String) {
        Task {
            do {
                try await DoorstepAI.startDeliveryByPlaceID(
                    placeID: placeID,
                    deliveryId: deliveryId
                )
                // Handle success
            } catch {
                // Handle error
            }
        }
    }
    
    func handleAppWillEnterBackground() {
        // SDK automatically handles background processing
        // No additional action required
    }
}

3. Thread Safety

Always update UI on the main thread:

private func handleDeliveryCallback() {
    Task {
        do {
            try await DoorstepAI.startDeliveryByPlaceID(
                placeID: placeID,
                deliveryId: deliveryId
            )
            // handle success
        } catch {
            // handle error
        }
    }
}

Next Steps

Now that you have the SDK installed and configured:

1. 📚 Learn SDK Usage - Initialize and use the SDK
2. 💡 View Examples - See complete implementation examples