Background Sync The ContactsManager SDK allows you to synchronize contacts even when your app is in the background. This ensures that your app always has the most up-to-date contact information, even if the user hasn’t opened the app recently.
Background sync is completely optional. Your app will work perfectly well without it, with contacts syncing when the app is in the foreground. Enable background sync only if you need real-time contact updates when your app isn’t actively being used.
Enabling Background Sync To enable background sync, you need to:
Configure your app with the proper capabilities and settings
Call the enableBackgroundSync() method during app initialization
Swift
React Native
Kotlin
Objective-C
// In your AppDelegate or App initialization code ContactsService. shared . enableBackgroundSync ()
iOS Configuration For iOS, you need to:
Add the “Background Processing” capability to your app in Xcode:
Open your app target’s “Signing & Capabilities” tab
Click the ”+” button to add a capability
Select “Background Processing” from the list
Register the background task identifier in your Info.plist:
< key > BGTaskSchedulerPermittedIdentifiers </ key > < array > < string > com.contactsmanager.contact-sync </ string > </ array >
Implement background task scheduling in your AppDelegate:
import UIKit import BackgroundTasks import ContactsManager @main class AppDelegate : UIResponder , UIApplicationDelegate { func application ( _ application : UIApplication, didFinishLaunchingWithOptions launchOptions : [UIApplication.LaunchOptionsKey: Any ] ? ) -> Bool { // Initialize ContactsManager and enable background sync Task { do { try await ContactsService. shared . initialize ( withAPIKey : "your-api-key" , token : "user-token" , userInfo : userInfo ) // Enable background sync ContactsService. shared . enableBackgroundSync () // Schedule the first background task scheduleBackgroundSync () } catch { print ( "Failed to initialize ContactsManager: \( error ) " ) } } return true } func applicationDidEnterBackground ( _ application : UIApplication) { scheduleBackgroundSync () } private func scheduleBackgroundSync () { let request = BGProcessingTaskRequest ( identifier : "com.contactsmanager.contact-sync" ) request. earliestBeginDate = Date ( timeIntervalSinceNow : 15 * 60 ) // 15 minutes from now request. requiresNetworkConnectivity = true do { try BGTaskScheduler. shared . submit (request) print ( "Background sync scheduled successfully" ) } catch { print ( "Could not schedule background sync: \( error ) " ) } } } iOS Configuration For iOS, you need to:
Add the “Background Processing” capability to your app in Xcode:
Open your app target’s “Signing & Capabilities” tab
Click the ”+” button to add a capability
Select “Background Processing” from the list
Register the background task identifier in your Info.plist:
< key > BGTaskSchedulerPermittedIdentifiers </ key > < array > < string > com.contactsmanager.contact-sync </ string > </ array >
Implement background task scheduling in your AppDelegate:
import UIKit import BackgroundTasks import ContactsManager @main class AppDelegate : UIResponder , UIApplicationDelegate { func application ( _ application : UIApplication, didFinishLaunchingWithOptions launchOptions : [UIApplication.LaunchOptionsKey: Any ] ? ) -> Bool { // Initialize ContactsManager and enable background sync Task { do { try await ContactsService. shared . initialize ( withAPIKey : "your-api-key" , token : "user-token" , userInfo : userInfo ) // Enable background sync ContactsService. shared . enableBackgroundSync () // Schedule the first background task scheduleBackgroundSync () } catch { print ( "Failed to initialize ContactsManager: \( error ) " ) } } return true } func applicationDidEnterBackground ( _ application : UIApplication) { scheduleBackgroundSync () } private func scheduleBackgroundSync () { let request = BGProcessingTaskRequest ( identifier : "com.contactsmanager.contact-sync" ) request. earliestBeginDate = Date ( timeIntervalSinceNow : 15 * 60 ) // 15 minutes from now request. requiresNetworkConnectivity = true do { try BGTaskScheduler. shared . submit (request) print ( "Background sync scheduled successfully" ) } catch { print ( "Could not schedule background sync: \( error ) " ) } } } Android Configuration Android support is coming soon.
The implementation will likely involve:
Setting up WorkManager for periodic background tasks
Configuring network permissions
Handling battery optimization exceptions
Check back for detailed instructions.
React Native Configuration For React Native apps, you’ll need to configure both iOS and Android platforms:
iOS Setup
Add the Background Processing capability to your iOS project:
Open your .xcodeproj file in Xcode
Select your target and go to “Signing & Capabilities”
Add the “Background Processing” capability
Add the background task identifier to your Info.plist:
< key > BGTaskSchedulerPermittedIdentifiers </ key > < array > < string > com.contactsmanager.contact-sync </ string > </ array >
Update your AppDelegate.m or AppDelegate.swift to register the background task
AppDelegate.swift Example: import BackgroundTasks @UIApplicationMain class AppDelegate : UIResponder , UIApplicationDelegate { // ... existing code func application ( _ application : UIApplication, didFinishLaunchingWithOptions launchOptions : [UIApplication.LaunchOptionsKey: Any ] ? ) -> Bool { // ... other initialization // Register background task BGTaskScheduler. shared . register ( forTaskWithIdentifier : "com.contactsmanager.contact-sync" , using : nil ) { task in // This will be handled by the native module self . handleBackgroundSync ( task : task as! BGProcessingTask) } return true } func applicationDidEnterBackground ( _ application : UIApplication) { scheduleBackgroundSync () } func handleBackgroundSync ( task : BGProcessingTask) { // The ContactsManager React Native module will handle this // This is just a placeholder to avoid task expiration task. expirationHandler = { // Clean up if task expires } } func scheduleBackgroundSync () { let request = BGProcessingTaskRequest ( identifier : "com.contactsmanager.contact-sync" ) request. earliestBeginDate = Date ( timeIntervalSinceNow : 15 * 60 ) // 15 minutes from now request. requiresNetworkConnectivity = true do { try BGTaskScheduler. shared . submit (request) } catch { print ( "Could not schedule background sync: \( error ) " ) } } } Android Setup Android background sync capability is coming soon. It will utilize WorkManager to schedule periodic background tasks while respecting Android’s battery optimization constraints.
How Background Sync Works When background sync is enabled, the ContactsManager SDK will:
Register a background task with the system
Periodically wake up in the background (based on system constraints and heuristics)
Check for updated contacts on the device
Synchronize any changes with the server
Schedule the next background task
Background operations are designed to be efficient with minimal battery and data usage:
Only changed contacts are synchronized
Sync frequency is managed by the operating system based on usage patterns
Network operations are batched to minimize battery impact
Background tasks respect system constraints for memory and CPU usage
Limitations Be aware of these platform-specific limitations:
iOS: Background tasks are scheduled at the system’s discretion based on app usage patterns, network conditions, and battery status
Android: Background operations may be restricted on some devices with aggressive battery optimization
Best Practices For optimal background sync performance:
Enable background sync early in your app’s lifecycle
Handle initialization errors gracefully
Don’t rely on exact timing of background operations
Test background behavior thoroughly in real-world conditions
Consider providing a manual sync option for users who want immediate updates
