ios

Imported from initialcodess/LogDrop-LLM-integration-kit (ios/AGENTS.md). Install upstream with npx skills add initialcodess/LogDrop-LLM-integration-kit --skill ios. Copyright stays with the author.

LogDrop iOS Integration Instructions for Coding Agents

Use these instructions when a user asks to integrate LogDrop into an iOS project. You can also refer directly to the official LogDrop Developer Documentation at https://developer.logdrop.io/ for reference.

Goal

Integrate the LogDrop iOS SDK with the smallest safe change set.

Business and runtime logging is handled by the global logging instructions in ../logging/AGENTS.md after the iOS SDK integration builds.

Required Behavior

1. Detect whether the app uses CocoaPods, Swift Package Manager, or a manually embedded framework.
2. Resolve the latest published stable LogDrop iOS SDK version from the package source before adding or updating the dependency.
3. Add the LogDrop dependency using the app's existing dependency style.
4. Do not copy a local SDK repository into the client app.
5. Do not use a local :path pod dependency in client apps.
6. Do not hardcode sample API keys, secret keys, base URLs, user IDs, card data, or sample log messages.
7. Find the app startup entry point: AppDelegate, SwiftUI App, or the app's existing composition root.
8. Initialize LogDrop exactly once during app launch.
9. Do not call setBaseUrl(...) during SDK initialization.
10. Use placeholder config values only when the client has not provided real LogDrop credentials, and call out the placeholders in the final response.
11. Enable LogDrop logging only for debug/development builds unless the user explicitly requests production logging.
12. Enable crash tracking only when the app already accepts the SDK's crash tracking behavior or the user asks for it.
13. Skip APNS/push integration unless the app already has remote notification registration or the user explicitly asks for LogDrop push handling.
14. Preserve existing notification delegate behavior when adding APNS hooks.
15. Build the app and confirm the LogDrop SDK compiles with the client app.
16. Do not add business/runtime logs during the SDK integration phase.
17. If the user also asks for logging, hand off to ../logging/AGENTS.md after the iOS build gate passes.
18. Never log secrets, tokens, passwords, OTPs, card data, raw personal data, raw request/response bodies, or arbitrary user-entered text.
19. Never change original app logic, control flow, validation, state handling, data handling, navigation, or user-visible behavior, even if it appears incorrect, incomplete, or missing.
20. When crash tracking is enabled or requested, configure a Run Script build phase in Xcode to upload dSYM files.

Required Workflow

Work in separate phases:

1. SDK integration phase: add the dependency, initialize LogDrop, and wire only approved lifecycle/config/push hooks.
2. Build gate: run the iOS build before adding any LogDrop.i, LogDrop.d, LogDrop.w, LogDrop.e, LogDrop.updateUser, or LogDrop.sendLogs calls outside SDK initialization or approved push wiring.
3. Logging handoff: only if the user asks for logging work, use ../logging/AGENTS.md after the build gate passes.
4. Final verification: run the iOS build after SDK integration, and run it again after logging changes if a logging phase is performed.

If the build gate fails, fix the SDK integration first. Do not start adding logs until the app builds with the LogDrop SDK.

Do not fix unrelated app bugs or missing behavior while integrating LogDrop. Report any suspicious existing logic in the final response instead of changing it.

Dependency Rules

Read docs/dependencies-and-versions.md before editing dependency files.

Prefer the dependency manager already used by the project.

For CocoaPods projects, add or update the pod using the official LogDrop iOS SDK source and an exact stable version:

pod 'LogDrop', :git => 'https://github.com/initialcodess/LogDrop-iOS.git', :tag => '<latest-stable-version>'

Do not add a local :path dependency.

For Swift Package Manager projects, add the current official package URL and an exact stable version or an existing-version-rule-compatible stable range:

https://github.com/initialcodess/LogDrop-iOS.git

The package product is LogDropSDK.

For manually embedded framework projects, only use manual embedding when the project already uses that style or the user explicitly asks for it. Prefer CocoaPods or Swift Package Manager when the app already uses one of them.

Default SDK Initialization

Prefer this pattern in an AppDelegate app:

import LogDropSDK
import UIKit

@main
class AppDelegate: UIResponder, UIApplicationDelegate {
    func application(
        _ application: UIApplication,
        didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?
    ) -> Bool {
        let config = LogDropConfig.Builder()
            .setAppId("TODO_REPLACE_WITH_LOGDROP_APP_ID")
            .setLoggingEnabled(isDebugBuild)
            .build()

        LogDrop.initialize(with: config)
        return true
    }

    private var isDebugBuild: Bool {
        #if DEBUG
        return true
        #else
        return false
        #endif
    }
}

For SwiftUI lifecycle apps, initialize in the app initializer:

import LogDropSDK
import SwiftUI

@main
struct ClientApp: App {
    init() {
        let config = LogDropConfig.Builder()
            .setAppId("TODO_REPLACE_WITH_LOGDROP_APP_ID")
            .setLoggingEnabled(isDebugBuild)
            .build()

        LogDrop.initialize(with: config)
    }

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

private var isDebugBuild: Bool {
    #if DEBUG
    return true
    #else
    return false
    #endif
}

If the client app already has configuration infrastructure, prefer reading the App ID from that existing config mechanism instead of hardcoding source literals. Do not commit real secrets unless the client project already stores equivalent non-secret configuration in source and the user explicitly provides the value.

Config Rules

Before adding any iOS LogDrop SDK call, import, callback implementation, builder method, or model usage, confirm the exact declaration against this integration kit's public sdk/platforms/ios/logdrop-ios-public-api.md. If the client app uses a different installed SDK version, inspect that installed SDK source or generated declarations and prefer the installed version.

The current iOS SDK requires explicit configuration through LogDropConfig.Builder.

Use:

• setAppId(...) with a real user-provided ID or TODO_REPLACE_WITH_LOGDROP_APP_ID
• setLoggingEnabled(isDebugBuild) by default

Do not add setSecretKey(...) by default. Do not call setBaseUrl(...) during SDK initialization.

Do not add these APIs by default:

• setDefaultSDKDisabledValue(...)
• setFrameworkType(...)
• setPushCallbacks(...)
• setPushDeeplinkHandler(...)
• setInAppLifecycleCallbacks(...)
• setInternalBrowserLifecycleCallbacks(...)
• setPushAppGroupSuiteName(...)
• URLSession.enableSessionInitSwizzle()
• LogDrop.requestPushNotificationAuthorization()
• LogDrop.showPendingPushPopup()
• LogDrop.setPushCallbacks(...)
• LogDrop.setPushDeeplinkHandler(...)
• LogDrop.setInAppLifecycleCallbacks(...)
• LogDrop.setInternalBrowserLifecycleCallbacks(...)
• LogDrop.sendLogs() (except immediately after a core flow/transaction completes, as described in logging/AGENTS.md)
• LogDrop.saveHttpLog(...)
• LogDrop.saveCustomCrashReport(...)

Only add them when the user explicitly requests that feature or the app already has an equivalent integration point that clearly needs it.

Crash Tracking Rules

Do not enable crash tracking blindly.

Only add setCrashTrackingEnabled(true) if the installed SDK version exposes it and one of these is true:

• the user explicitly asks for crash tracking
• the client app already uses LogDrop crash tracking
• the client confirms the SDK should install crash handling

If the SDK version does not expose setCrashTrackingEnabled, do not invent an equivalent API.

dSYM Upload Build Script

When crash tracking is enabled, or when the user requests it, a Run Script build phase must be added to the Xcode project to upload dSYM files for crash symbolication.

Add a new Run Script build phase to the Xcode target (with default shell /bin/sh) using the following script:

export LOGDROP_BASE_URL="https://server.logdrop.io/api/"

# Resolve API Key dynamically from LogDrop-Services.plist
SERVICES_PLIST="${PROJECT_DIR}/TokenMobile/LogDrop-Services.plist"
if [ -f "$SERVICES_PLIST" ]; then
  export LOGDROP_APP_ID=$(/usr/libexec/PlistBuddy -c "Print :projects:${PRODUCT_BUNDLE_IDENTIFIER}:app_id" "$SERVICES_PLIST" 2>/dev/null)
fi

if [ -z "$LOGDROP_APP_ID" ]; then
  export LOGDROP_APP_ID="TODO_REPLACE_WITH_LOGDROP_APP_ID"
fi

# Locate script (CocoaPods or SPM)
SCRIPT=""
if [ -f "${PODS_ROOT}/LogDrop/upload_dsym.sh" ]; then
  SCRIPT="${PODS_ROOT}/LogDrop/upload_dsym.sh"
else
  SCRIPT=$(find "${BUILD_DIR%/Build/*}/SourcePackages/checkouts/LogDrop-iOS" -name "upload_dsym.sh" 2>/dev/null | head -n 1)
fi

if [ -n "$SCRIPT" ] && [ -f "$SCRIPT" ]; then
  /bin/sh "$SCRIPT"
else
  echo "LogDrop - upload_dsym.sh not found."
  exit 1
fi

Push Rules

Read docs/push-integration.md before changing push or notification code.

LogDrop push integration is optional. Only wire LogDrop into APNS handling if the target app already registers for remote notifications or the user explicitly asks for LogDrop push handling.

If the app has no push setup, skip LogDrop push integration entirely. Do not add push entitlements, notification permissions, Firebase, APNS registration, notification delegates, app groups, or background modes just for LogDrop.

When APNS handling already exists, preserve the app's current behavior and add LogDrop hooks alongside it:

func application(
    _ application: UIApplication,
    didRegisterForRemoteNotificationsWithDeviceToken deviceToken: Data
) {
    LogDrop.onNewApnsToken(apnsToken: deviceToken)
    // Existing app token handling continues here.
}

func application(
    _ application: UIApplication,
    didReceiveRemoteNotification userInfo: [AnyHashable: Any],
    fetchCompletionHandler completionHandler: @escaping (UIBackgroundFetchResult) -> Void
) {
    LogDrop.onRemoteMessageReceived(userInfo)
    // Existing app remote notification handling continues here.
}

If UNUserNotificationCenter.current().delegate is already assigned, do not replace it without preserving existing delegate callbacks.

Logging Handoff

Do not add business/runtime logs as part of iOS SDK integration.

After the iOS build gate passes, use ../logging/AGENTS.md only when the user asks to add, improve, audit, or review LogDrop logs.

For Swift log syntax with the current SDK:

LogDrop.i("Auth login succeeded")
LogDrop.w("Auth login blocked")
LogDrop.e("Sync failed")
LogDrop.d("Network retry scheduled")

The verified current iOS SDK log signature is:

LogDrop.w(_ message: String, logFlow: LogFlow? = nil, file: String = #file, line: Int = #line)

The same signature shape applies to LogDrop.i, LogDrop.d, and LogDrop.e. Before adding any error, code, or metadata parameter to a LogDrop warning or error call, inspect the installed iOS SDK declarations or client-local LogDrop wrapper. Do not invent an error: parameter and do not interpolate error.localizedDescription into the LogDrop message.

When the installed SDK supports LogFlow(name:id:), pass a LogFlow for logs that belong to a clear runtime or business journey. Use a stable, low-cardinality flow name and a non-sensitive id for that specific flow instance. Reuse the same name for every log in the same journey so the LogDrop panel can group the logs by flow name:

LogDrop.i("Registration started", logFlow: LogFlow(name: "Registration", id: registrationDetails.uuid))
LogDrop.i("Registration completed", logFlow: LogFlow(name: "Registration", id: registrationDetails.uuid))

LogDrop.i("Checkout started", logFlow: LogFlow(name: "Checkout", id: checkoutDetails.uuid))
LogDrop.w("Checkout blocked: missing required state", logFlow: LogFlow(name: "Checkout", id: checkoutDetails.uuid))
LogDrop.e("Payment failed", logFlow: LogFlow(name: "Checkout", id: checkoutDetails.uuid))
LogDrop.i("Order completed", logFlow: LogFlow(name: "Checkout", id: checkoutDetails.uuid))

LogDrop.e("Crash captured", logFlow: LogFlow(name: "Crash", id: crashDetails.uuid))
LogDrop.e("Crash upload failed", logFlow: LogFlow(name: "Crash", id: crashDetails.uuid))

Current iOS identity syntax is:

LogDrop.updateUser(userUuid: userId)

Only add identity updates when the app exposes a stable internal user id approved for LogDrop identity. Do not use email, phone, name, device id, advertising id, access token, refresh token, or third-party identifier unless the client explicitly confirms it is approved.

Verification

After the SDK integration phase, run the most appropriate concrete build command before any separate logging phase.

For CocoaPods projects, build the workspace:

xcodebuild -workspace <App>.xcworkspace -scheme <Scheme> -destination 'generic/platform=iOS Simulator' build

For non-CocoaPods projects, build the project:

xcodebuild -project <App>.xcodeproj -scheme <Scheme> -destination 'generic/platform=iOS Simulator' build

If the project has shared schemes, detect them with:

xcodebuild -list

If the simulator destination is unavailable in the local environment, try a generic iOS destination:

xcodebuild -project <App>.xcodeproj -scheme <Scheme> -destination 'generic/platform=iOS' build

Run the same build command again after logging changes if a separate logging phase is performed.

Review ios/docs/verification-checklist.md before finalizing. Do not ask clients to run executable files from the integration kit.

Final Response

Summarize:

• changed files
• where LogDrop is initialized
• dependency manager and LogDrop SDK version used
• whether the dSYM upload build script phase was added for crash tracking
• whether APNS/push hooks were added or intentionally skipped
• verification command and result for SDK integration
• if logging was requested, the global logging summary from ../logging/AGENTS.md
• if logging was not requested, state that no business/runtime logs were added in the integration phase
• any remaining client-side config required
• if placeholder API keys were added, that the user must replace them with valid LogDrop API keys before release