Skip to main content
SDK Version

Troubleshooting

The following article cover the most common issues encountered when integrating and using the Actito SDK.

Because the Ionic Native SDK relies on native platform integrations, troubleshooting steps can differ between Android and iOS. To make issues easier to identify and resolve, the troubleshooting guide is organized by platform.

Choose the platform you're targeting to find the most relevant solutions.

Android Troubleshooting​

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 AndroidManifest.xml file:

<?xml version="1.0" encoding="utf-8"?>
<manifest>
    <application>
        <meta-data
            android:name="com.actito.debug_logging_enabled"
            android:value="true" />
    </application>
</manifest>

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

Problem sending notifications​

If notifications are not being delivered as expected, the most common cause is an environment mismatch. This typically occurs when the application is targeting the wrong environment (for example, sending from production to a development build) or when incorrect FCM credentials are configured for that environment.

You can verify in your Actito app that your Push service configurations and your application’s configuration are aligned in terms of environment, application keys, and Firebase credentials.

You can also check the documentation on Notification Provider Environments for more information on environment configuration.

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.

Google Maps Key on Android​

The Actito Push UI module requires access to the Google Maps API when rendering notifications containing map content. A common issue is neglecting to obtain or configure the required Google Maps API Key.

Ensure you have properly generated and enabled a Google Maps Key for your project. You can find detailed setup instructions in the Setting Up Google Maps Guide.

iOS Troubleshooting​

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.

Problems sending notifications​

If notifications are not being delivered as expected, the most common cause is an environment mismatch. This typically occurs when the application is targeting the wrong environment (for example, sending from production to a development build) or when incorrect APNS credentials are configured for that environment.

Contact Actito Support to verify that the Push service configurations and your application’s configuration are aligned in terms of environment, application keys, and APNS credentials.

You can also check the documentation on Notification Provider Environments for more information on environment configuration.

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.

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>