Troubleshooting

Quick fixes for the most common integration issues. Can't find your issue here? Enable debug logging first — it usually points straight to the cause.

Symptom	Likely cause	Fix
Notifications aren't delivered at all	Environment mismatch — app is built against dev but Actito is sending to prod (or vice versa), or APNs credentials don't match the environment	Check your Actito app to confirm the Push service config and your app's ActitoServices.plist point to the same environment, keys, and APNs credentials. See Notification Provider Environments
SDK crashes or can't be configured when using SwiftUI's App lifecycle	AppDelegate isn't accessible — SwiftUI apps don't have one by default	Bridge it in with @UIApplicationDelegateAdaptor (see below)
Notification Service Extension fails to build, or the lock screen image doesn't show	ActitoNotificationServiceExtensionKit added via CocoaPods with dynamic linking, but only to one target	Add the dependency to both the app and the extension target, or switch to Swift Package Manager (see below)
File access errors while the device is locked	Data Protection capability set to Complete app-wide, blocking the SDK's background database access	Override the file protection level for the SDK's database (see below)
Not enough detail in logs to diagnose an issue	Default logging level is too low	Enable debug logging (see below)

Enabling debug logging

In some cases, the default logging level may not provide enough detail to diagnose an issue. You can enable debug logging by adding the following entry to your ActitoOptions.plist file:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
	<key>DEBUG_LOGGING_ENABLED</key>
	<true/>
</dict>
</plist>

This enables verbose logging, allowing you to better trace initialization and runtime behavior across SDK modules.

SwiftUI

When using the new SwiftUI App Lifecycle, the AppDelegate is not directly accessible unless explicitly defined. Since the Actito SDK must be configured within the application(_:didFinishLaunchingWithOptions:) method, you need to add an interceptor to expose the AppDelegate.

In your app’s main entry point, declare a UIApplicationDelegateAdaptor to bridge the SwiftUI lifecycle with UIKit:

@main
struct SampleApp: App {
    // Register the AppDelegate
    @UIApplicationDelegateAdaptor(AppDelegate.self) var appDelegate

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

Then, create an AppDelegate.swift file to configure the SDK:

import ActitoKit

class AppDelegate: NSObject, UIApplicationDelegate {
    func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey : Any]? = nil) -> Bool {
        // Configure Actito
        Actito.shared.configure()

        // Additional setup...
        return true
    }
}

Notification Service Extension

When including the ActitoNotificationServiceExtensionKit via CocoaPods, the integration works as expected if you use use_frameworks! in your Podfile.

However, when using dynamic linking, two potential issues may occur:

• The app fails to build if the framework is added only to the main target and not the extension target.
• The lock screen image fails to display if the framework is added only to the extension target (since it is not embedded in the app).

Currently, CocoaPods cannot correctly link the XCFramework dynamically across both targets. To avoid these issues, we recommend using Swift Package Manager (SPM) to include ActitoNotificationServiceExtensionKit in your application and extension targets.

Data Protection capability

Enabling the Data Protection capability in your app sets the default File Protection Level to Complete. This restricts database access while the device is locked, which can interfere with the SDK’s background operations (such as processing incoming notifications).

Apple recommends enabling file protection only for sensitive data rather than for the entire application. If you enable it globally, you may encounter file access errors due to the SDK’s need to operate while the device is locked.

To override this behavior and ensure reliable access, you can adjust the database file protection level by enabling the following option in your ActitoOptions.plist file:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
	<key>OVERRIDE_DATABASE_FILE_PROTECTION</key>
	<true/>
</dict>
</plist>

Managing Application State

The Actito SDK stores essential application data — such as the current device information, registration details, and push notification state — in the system’s shared preferences.

It is important not to manually delete or modify these files or properties. Doing so may lead to inconsistent behavior, including partial resets or desynchronization with Actito.

If you need to clear or reset specific aspects of the SDK’s state, always use the appropriate public APIs that safely handle cleanup operations. For example:

• Use disableRemoteNotifications() to stop receiving push notifications.
• Use unlaunch() to fully unregister the SDK and remove all device-related data.

These methods ensure that both local and remote data remain consistent and that the SDK continues to operate as expected.