Installation Guide

Complete installation guide for the Kasookoo iOS SDK, from package installation to push notification setup.

Table of Contents

1. System Requirements
2. SDK Installation
3. Xcode Project Configuration
4. Apple Developer Setup
5. Firebase Setup (for Push Notifications)
6. Verify Installation

System Requirements

Development Environment

Target Environment

Account Requirements

• ✅ Paid Apple Developer Program account ($99/year) — required for push notifications
• ✅ Kasookoo account with publishable key — sign up at kasookoo.ai
• ✅ Firebase account (free) — required for push notifications

SDK Installation

Method 1: Swift Package Manager (Recommended)

Via Xcode UI

1. In Xcode, open your project
2. Select File → Add Package Dependencies
3. Enter the repository URL:

   https://github.com/kasookoo/ios-sdk.git

4. Select Dependency Rule: Up to Next Major Version from 1.0.0
5. Click Add Package
6. Select your app target
7. Click Add Package

Via Package.swift

// swift-tools-version: 5.9
import PackageDescription

let package = Package(
    name: "YourApp",
    platforms: [.iOS(.v15)],
    dependencies: [
        .package(
            url: "https://github.com/kasookoo/ios-sdk.git",
            from: "1.0.0"
        )
    ],
    targets: [
        .target(
            name: "YourApp",
            dependencies: [
                .product(name: "KasookooSDK", package: "ios-sdk")
            ]
        )
    ]
)

Method 2: CocoaPods

Add to your Podfile:

platform :ios, '15.0'

target 'YourApp' do
  use_frameworks!
  pod 'KasookooSDK', '~> 1.0'
end

Then run:

pod install

Open the .xcworkspace file going forward.

Xcode Project Configuration

1. Enable Required Capabilities

1. Select your project in Xcode
2. Select your app target
3. Go to Signing & Capabilities tab
4. Click + Capability and add:

Background Modes

• ✅ Voice over IP — Required for VoIP push notifications
• ✅ Audio, AirPlay, and Picture in Picture — Required for call audio

Push Notifications

• ✅ Add Push Notifications capability — Required for incoming calls

2. Configure Info.plist

Add these entries to your Info.plist:

<!-- Microphone permission for voice calls -->
<key>NSMicrophoneUsageDescription</key>
<string>This app needs microphone access to make voice calls.</string>

<!-- Camera permission (for future video support) -->
<key>NSCameraUsageDescription</key>
<string>This app needs camera access for video calls.</string>

<!-- Required background modes -->
<key>UIBackgroundModes</key>
<array>
    <string>voip</string>
    <string>audio</string>
</array>

3. Bundle Identifier

Make sure your Bundle Identifier is set:

1. Select project → target → General tab
2. Note your Bundle Identifier (e.g., com.yourcompany.yourapp)
3. You'll need this for Firebase and Apple Developer setup

Apple Developer Setup

1. Register App ID

1. Go to Apple Developer Portal
2. Navigate to Certificates, Identifiers & Profiles
3. Select Identifiers → Click +
4. Select App IDs → Continue
5. Choose App → Continue
6. Fill in:
   • Description: Your app name
   • Bundle ID: Explicit, e.g., com.yourcompany.yourapp
7. Under Capabilities, enable:
   • ✅ Push Notifications
   • ✅ Background Modes (Voice over IP)
8. Click Continue → Register

2. Create APNs Authentication Key

This key allows Firebase to send pushes to iOS devices via Apple.

1. In Apple Developer Portal → Keys → Click +
2. Fill in:
   • Key Name: "Kasookoo Push Key" (or any descriptive name)
3. Check ✅ Apple Push Notifications service (APNs)
4. Click Continue → Register
5. Download the .p8 file — save it carefully!

   ⚠️

   This file can only be downloaded ONCE

6. Note these values from the key details:
   • Key ID (10 characters, e.g., ABC123DEFG)
   • Team ID (visible in top-right corner of Apple Developer)

Firebase Setup (for Push Notifications)

Note: If you're using Kasookoo's hosted Firebase project, skip this section and use the GoogleService-Info.plist provided during onboarding.

1. Create a Firebase Project

1. Go to Firebase Console
2. Click Add project
3. Enter project name (e.g., "MyApp-iOS")
4. Disable Google Analytics for now (you can enable later)
5. Click Create project

2. Add iOS App to Firebase

1. In Firebase project dashboard, click iOS icon
2. Fill in:
   • Apple bundle ID: Same as your Xcode project (e.g., com.yourcompany.yourapp)
   • App nickname: "MyApp iOS"
   • App Store ID: Leave blank
3. Click Register app

3. Download GoogleService-Info.plist

1. Click Download GoogleService-Info.plist
2. Drag this file into your Xcode project
3. In Xcode dialog:
   • ✅ Check Copy items if needed
   • ✅ Check Add to targets: Your app target
4. Click Finish

4. Upload APNs Key to Firebase

1. In Firebase Console → Project Settings → Cloud Messaging tab
2. Scroll to Apple app configuration
3. Find your iOS app
4. Under APNs Authentication Key, click Upload
5. Fill in:
   • APNs auth key file (.p8): Select your downloaded .p8 file
   • Key ID: The 10-character Key ID from Apple Developer
   • Team ID: The 10-character Team ID from Apple Developer
6. Click Upload

5. Install Firebase iOS SDK

Add Firebase to your Package.swift or via Xcode:

https://github.com/firebase/firebase-ios-sdk.git

Select these libraries:

• ✅ FirebaseCore
• ✅ FirebaseMessaging

6. Initialize Firebase in Your App

In your AppDelegate.swift:

import UIKit
import FirebaseCore
import FirebaseMessaging
import KasookooSDK

class AppDelegate: NSObject, UIApplicationDelegate {
    
    func application(
        _ application: UIApplication,
        didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]? = nil
    ) -> Bool {
        // 1. Configure Firebase
        FirebaseApp.configure()
        
        // 2. Set messaging delegate
        Messaging.messaging().delegate = self
        
        // 3. Request notification permissions
        UNUserNotificationCenter.current().delegate = self
        UNUserNotificationCenter.current().requestAuthorization(
            options: [.alert, .badge, .sound]
        ) { granted, _ in
            if granted {
                DispatchQueue.main.async {
                    application.registerForRemoteNotifications()
                }
            }
        }
        
        return true
    }
    
    // Called when APNs token received
    func application(
        _ application: UIApplication,
        didRegisterForRemoteNotificationsWithDeviceToken deviceToken: Data
    ) {
        Messaging.messaging().apnsToken = deviceToken
    }
}

// MARK: - Firebase Messaging Delegate
extension AppDelegate: MessagingDelegate {
    func messaging(_ messaging: Messaging, didReceiveRegistrationToken fcmToken: String?) {
        guard let fcmToken = fcmToken else { return }
        
        // Pass FCM token to Kasookoo SDK
        Task {
            try await KasookooSDK.shared.notifications.registerDevice(
                fcmToken: fcmToken,
                userType: .customer
            )
        }
    }
}

// MARK: - Notification Center Delegate
extension AppDelegate: UNUserNotificationCenterDelegate {
    func userNotificationCenter(
        _ center: UNUserNotificationCenter,
        didReceive response: UNNotificationResponse,
        withCompletionHandler completionHandler: @escaping () -> Void
    ) {
        let userInfo = response.notification.request.content.userInfo
        
        // Forward to Kasookoo SDK
        Task {
            try await KasookooSDK.shared.notifications.handlePush(payload: userInfo)
        }
        
        completionHandler()
    }
}

Verify Installation

1. Build the Project

In Xcode: Cmd + B

You should see: Build Succeeded ✅

2. Test SDK Import

Create a test file or use existing one:

import KasookooSDK

let testSDK = KasookooSDK()
print("SDK loaded: \(testSDK)")

If this compiles, the SDK is correctly installed.

3. Run on Device

1. Connect your iPhone via USB
2. Select your device in Xcode scheme
3. Press Cmd + R

First-time deployment:

• iPhone will ask to trust developer: Go to Settings → General → VPN & Device Management → Trust your developer certificate

4. Check Logs

After launching the app, you should see in Xcode console:

[KasookooSDK] SDK initialized
[FirebaseMessaging] FCM token received: ...

If FCM token is received, Firebase is correctly configured.

Troubleshooting Installation

Build fails with "No such module 'KasookooSDK'"

Solutions:

1. Clean build folder: Cmd + Shift + K
2. Reset package caches: File → Packages → Reset Package Caches
3. Quit Xcode, delete ~/Library/Developer/Xcode/DerivedData, restart Xcode

"No such module 'FirebaseCore'"

Solutions:

1. Make sure you added FirebaseCore and FirebaseMessaging to your target
2. In Xcode: File → Add Package Dependencies → re-add Firebase

Push notifications not working

Common causes:

1. ❌ Using simulator (use real device)
2. ❌ Free Apple Developer account (need paid)
3. ❌ .p8 key not uploaded to Firebase
4. ❌ Bundle ID mismatch between Xcode and Firebase
5. ❌ Push capability not enabled in Apple Developer

See Push Notifications Guide for detailed troubleshooting.

"Invalid publishable key" error

Solutions:

1. Verify key format: starts with pk_test_ (sandbox) or pk_live_ (production)
2. Check key in your Kasookoo Dashboard
3. Make sure you're using the right environment (.sandbox vs .production)

Next Steps

✅ Installation complete? Continue with:

• 🚀 Quick Start Guide — Make your first call
• 📞 Making Calls Guide — Outgoing call patterns
• 📱 Receiving Calls Guide — Handle incoming calls
• 🔔 Push Notifications Guide — Detailed push setup

Need Help?

• 📧 [email protected]
• 📖 Full Documentation
• 💬 Discord Community